effect 4.0.0-beta.67 → 4.0.0-beta.69

package/dist/Effect.js

@@ -15,13 +15,13 @@ 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** (Usage)
+ * **Example** (Checking whether a value is an Effect)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -30,7 +30,7 @@ export const TypeId = core.EffectTypeId;
  * console.log(Effect.isEffect("hello")) // false
  * ```
  *
- * @category Guards
+ * @category guards
  * @since 2.0.0
  */
 export const isEffect = core.isEffect;
@@ -52,7 +52,7 @@ export const isEffect = core.isEffect;
  * `Result` in the same output shape. Use `discard: true` to ignore successful
  * values and return `void`.
  *
- * **Example** (Combining Effects in Tuples)
+ * **Example** (Collecting tuple results in order)
  *
  * ```ts
  * import { Console, Effect } from "effect"
@@ -73,7 +73,7 @@ export const isEffect = core.isEffect;
  * // [ 42, 'Hello' ]
  * ```
  *
- * **Example** (Combining Effects in Iterables)
+ * **Example** (Collecting iterable results in order)
  *
  * ```ts
  * import { Console, Effect } from "effect"
@@ -94,7 +94,7 @@ export const isEffect = core.isEffect;
  * // [ 1, 2, 3 ]
  * ```
  *
- * **Example** (Combining Effects in Structs)
+ * **Example** (Collecting struct results by key)
  *
  * ```ts
  * import { Console, Effect } from "effect"
@@ -115,7 +115,7 @@ export const isEffect = core.isEffect;
  * // { a: 42, b: 'Hello' }
  * ```
  *
- * **Example** (Combining Effects in Records)
+ * **Example** (Collecting record results by key)
  *
  * ```ts
  * import { Console, Effect } from "effect"
@@ -136,7 +136,7 @@ export const isEffect = core.isEffect;
  * // { key1: 1, key2: 2 }
  * ```
  *
- * **Example** (Short-Circuiting Behavior)
+ * **Example** (Stopping on the first failure)
  *
  * ```ts
  * import { Console, Effect } from "effect"
@@ -176,7 +176,7 @@ export const all = internal.all;
  * This function runs every effect and never fails. Use `concurrency` to control
  * parallelism.
  *
- * **Example** (Usage)
+ * **Example** (Separating successes and failures)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -190,7 +190,7 @@ export const all = internal.all;
  * ```
  *
  * @category Collecting
- * @since 3.0.0
+ * @since 2.0.0
  */
 export const partition = internal.partition;
 /**
@@ -203,7 +203,7 @@ export const partition = internal.partition;
  * Use `discard: true` to ignore successful values while still validating all
  * elements.
  *
- * **Example** (Usage)
+ * **Example** (Validating every element)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -227,7 +227,7 @@ export const partition = internal.partition;
  * ```
  *
  * @category Error Accumulation
- * @since 4.0.0
+ * @since 2.0.0
  */
 export const validate = internal.validate;
 /**
@@ -236,7 +236,7 @@ export const validate = internal.validate;
  * The predicate receives the element and its index. Evaluation short-circuits
  * as soon as an element matches.
  *
- * **Example** (Usage)
+ * **Example** (Finding the first successful match)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -284,11 +284,10 @@ export const findFirstFilter = internal.findFirstFilter;
  *
  * @see {@link all} for combining multiple effects into one.
  *
- * **Example** (Applying Effects to Iterable Elements)
+ * **Example** (Mapping over an iterable with effects)
  *
  * ```ts
- * import { Effect } from "effect"
- * import { Console } from "effect"
+ * import { Console, Effect } from "effect"
  *
  * const result = Effect.forEach(
  *   [1, 2, 3, 4, 5],
@@ -306,11 +305,10 @@ export const findFirstFilter = internal.findFirstFilter;
  * // [ 2, 4, 6, 8, 10 ]
  * ```
  *
- * **Example** (Using discard to Ignore Results)
+ * **Example** (Running effects without collecting results)
  *
  * ```ts
- * import { Effect } from "effect"
- * import { Console } from "effect"
+ * import { Console, Effect } from "effect"
  *
  * // Apply effects but discard the results
  * const result = Effect.forEach(
@@ -337,7 +335,7 @@ export const forEach = internal.forEach;
 /**
  * Executes a body effect repeatedly while a condition holds true.
  *
- * **Example** (Usage)
+ * **Example** (Repeating an effectful loop)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -382,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**
  *
@@ -391,7 +389,7 @@ export const whileLoop = internal.whileLoop;
  *
  * @see {@link tryPromise} for a version that can handle failures.
  *
- * **Example** (Delayed Message)
+ * **Example** (Wrapping a non-rejecting Promise)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -441,7 +439,7 @@ 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** (Wrapping a fetch request that may fail)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -457,7 +455,7 @@ export const promise = internal.promise;
  * const program = getTodo(1)
  * ```
  *
- * **Example** (Custom Error Handling)
+ * **Example** (Mapping Promise rejections to a tagged error)
  *
  * ```ts
  * import { Data, Effect } from "effect"
@@ -492,7 +490,7 @@ export const tryPromise = internal.tryPromise;
  *
  * @see {@link fail} to create an effect that represents a failure.
  *
- * **Example** (Creating a Successful Effect)
+ * **Example** (Creating a successful effect)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -511,7 +509,7 @@ export const succeed = internal.succeed;
 /**
  * Returns an effect which succeeds with `None`.
  *
- * **Example** (Usage)
+ * **Example** (Succeeding with Option.none)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -529,7 +527,7 @@ export const succeedNone = internal.succeedNone;
 /**
  * Returns an effect which succeeds with the value wrapped in a `Some`.
  *
- * **Example** (Usage)
+ * **Example** (Succeeding with Option.some)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -558,7 +556,7 @@ 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** (Lazy Evaluation with Side Effects)
+ * **Example** (Lazily evaluating side effects)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -576,7 +574,7 @@ export const succeedSome = internal.succeedSome;
  * console.log(Effect.runSync(good)) // Output: 2
  * ```
  *
- * **Example** (Recursive Fibonacci)
+ * **Example** (Suspending recursive Fibonacci evaluation)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -602,7 +600,7 @@ export const succeedSome = internal.succeedSome;
  * // Output: 3524578
  * ```
  *
- * **Example** (Using Effect.suspend to Help TypeScript Infer Types)
+ * **Example** (Helping TypeScript infer recursive effect types)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -646,11 +644,11 @@ 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** (Logging a Message)
+ * **Example** (Capturing synchronous logging in an Effect)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -698,13 +696,7 @@ undefined_ as undefined };
  * Use `Effect.callback` when integrating APIs that complete through callbacks
  * instead of returning a `Promise`.
  *
- * **Previously Known As**
- *
- * This API replaces the following from Effect 3.x:
- *
- * - `Effect.async`
- *
- * **Example** (Usage)
+ * **Example** (Integrating callback APIs)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -722,14 +714,14 @@ undefined_ as undefined };
  * ```
  *
  * @category Creating Effects
- * @since 2.0.0
+ * @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** (Usage)
+ * **Example** (Creating a never-ending effect)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -752,11 +744,10 @@ export const never = internal.never;
  * An `Effect` containing an empty record `{}`, used as the starting point for
  * do notation chains.
  *
- * **Example** (Usage)
+ * **Example** (Starting do notation)
  *
  * ```ts
- * import { Effect } from "effect"
- * import { pipe } from "effect/Function"
+ * import { Effect, pipe } from "effect"
  *
  * const program = pipe(
  *   Effect.Do,
@@ -767,7 +758,7 @@ export const never = internal.never;
  * ```
  *
  * @category Do notation
- * @since 4.0.0
+ * @since 2.0.0
  */
 export const Do = internal.Do;
 /**
@@ -775,7 +766,7 @@ export const Do = internal.Do;
  * record used in do notation pipelines.
  *
  * @category Do notation
- * @since 4.0.0
+ * @since 2.0.0
  */
 export const bindTo = internal.bindTo;
 const let_ = internal.let;
@@ -784,14 +775,14 @@ export {
  * Adds a computed plain value to the do notation record.
  *
  * @category Do notation
- * @since 4.0.0
+ * @since 2.0.0
  */
 let_ as let };
 /**
  * Adds an `Effect` value to the do notation record under a given name.
  *
  * @category Do notation
- * @since 4.0.0
+ * @since 2.0.0
  */
 export const bind = internal.bind;
 /**
@@ -809,7 +800,7 @@ 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** (Usage)
+ * **Example** (Sequencing effects with generators)
  *
  * ```ts
  * import { Data, Effect } from "effect"
@@ -853,11 +844,11 @@ 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** (Creating a Failed Effect)
+ * **Example** (Creating a failed effect)
  *
  * ```ts
  * import { Data, Effect } from "effect"
@@ -881,7 +872,7 @@ 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** (Usage)
+ * **Example** (Lazily creating failures)
  *
  * ```ts
  * import { Data, Effect } from "effect"
@@ -904,7 +895,7 @@ 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** (Usage)
+ * **Example** (Failing with a full Cause)
  *
  * ```ts
  * import { Cause, Effect } from "effect"
@@ -927,7 +918,7 @@ 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** (Usage)
+ * **Example** (Lazily creating a Cause)
  *
  * ```ts
  * import { Cause, Effect } from "effect"
@@ -961,10 +952,9 @@ 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** (Failing when division by zero)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -1013,7 +1003,7 @@ export {
  * @see {@link sync} if the effectful computation is synchronous and does not
  * throw errors.
  *
- * **Example** (Basic Usage with Default Error Handling)
+ * **Example** (Parsing JSON with typed error mapping)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -1033,7 +1023,7 @@ export {
  * // Output: Exit.failure with Error
  * ```
  *
- * **Example** (Custom Error Handling)
+ * **Example** (Mapping synchronous exceptions to a tagged error)
  *
  * ```ts
  * import { Data, Effect } from "effect"
@@ -1057,7 +1047,7 @@ try_ as try };
 /**
  * Yields control back to the Effect runtime, allowing other fibers to execute.
  *
- * **Example** (Usage)
+ * **Example** (Yielding to other fibers)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -1078,7 +1068,7 @@ export const yieldNow = internal.yieldNow;
 /**
  * Yields control back to the Effect runtime with a specified priority, allowing other fibers to execute.
  *
- * **Example** (Usage)
+ * **Example** (Yielding with priority)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -1093,13 +1083,13 @@ export const yieldNow = internal.yieldNow;
  * ```
  *
  * @category Creating Effects
- * @since 2.0.0
+ * @since 4.0.0
  */
 export const yieldNowWith = internal.yieldNowWith;
 /**
  * Provides access to the current fiber within an effect computation.
  *
- * **Example** (Usage)
+ * **Example** (Reading the current fiber)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -1113,7 +1103,7 @@ export const yieldNowWith = internal.yieldNowWith;
  * ```
  *
  * @category Creating Effects
- * @since 2.0.0
+ * @since 4.0.0
  */
 export const withFiber = core.withFiber;
 // -----------------------------------------------------------------------------
@@ -1122,7 +1112,7 @@ export const withFiber = core.withFiber;
 /**
  * Converts a `Result` to an `Effect`.
  *
- * **Example** (Usage)
+ * **Example** (Converting a Result into an Effect)
  *
  * ```ts
  * import { Effect, Result } from "effect"
@@ -1138,7 +1128,7 @@ export const withFiber = core.withFiber;
  * // { _id: 'Exit', _tag: 'Failure', cause: { _id: 'Cause', _tag: 'Fail', failure: 'Something went wrong' } }
  * ```
  *
- * @category Conversions
+ * @category converting
  * @since 4.0.0
  */
 export const fromResult = internal.fromResult;
@@ -1148,7 +1138,7 @@ export const fromResult = internal.fromResult;
  * `Option.some` becomes a successful effect with the contained value, while
  * `Option.none` becomes a failed effect with `NoSuchElementError`.
  *
- * **Example** (Usage)
+ * **Example** (Converting an Option into an Effect)
  *
  * ```ts
  * import { Effect, Option } from "effect"
@@ -1164,7 +1154,7 @@ export const fromResult = internal.fromResult;
  * // { _id: 'Exit', _tag: 'Failure', cause: { _id: 'Cause', _tag: 'Fail', failure: { _id: 'NoSuchElementError' } } }
  * ```
  *
- * @category Conversions
+ * @category converting
  * @since 4.0.0
  */
 export const fromOption = internal.fromOption;
@@ -1172,7 +1162,7 @@ export const fromOption = internal.fromOption;
  * Converts a nullable value to an `Effect`, failing with a `NoSuchElementError`
  * when the value is `null` or `undefined`.
  *
- * **Example** (Usage)
+ * **Example** (Failing on nullish values)
  *
  * ```ts
  * import { Console, Effect } from "effect"
@@ -1190,7 +1180,7 @@ export const fromOption = internal.fromOption;
  * // Output: hello
  * ```
  *
- * @category Conversions
+ * @category converting
  * @since 4.0.0
  */
 export const fromNullishOr = internal.fromNullishOr;
@@ -1227,7 +1217,7 @@ export const fromNullishOr = internal.fromNullishOr;
  * step produces a new `Effect` while flattening any nested effects that may
  * occur.
  *
- * **Example** (Usage)
+ * **Example** (Sequencing dependent effects)
  *
  * ```ts
  * import { Data, Effect, pipe } from "effect"
@@ -1258,14 +1248,14 @@ export const fromNullishOr = internal.fromNullishOr;
  *
  * @see {@link tap} for a version that ignores the result of the effect.
  *
- * @category Sequencing
+ * @category sequencing
  * @since 2.0.0
  */
 export const flatMap = internal.flatMap;
 /**
  * Flattens an `Effect` that produces another `Effect` into a single effect.
  *
- * **Example** (Usage)
+ * **Example** (Flattening nested effects)
  *
  * ```ts
  * import { Console, Effect } from "effect"
@@ -1279,7 +1269,7 @@ export const flatMap = internal.flatMap;
  * })
  * ```
  *
- * @category Sequencing
+ * @category sequencing
  * @since 2.0.0
  */
 export const flatten = internal.flatten;
@@ -1312,13 +1302,7 @@ export const flatten = internal.flatten;
  * Failures or requirements from either effect are preserved in the returned
  * effect.
  *
- * **Previously Known As**
- *
- * This API replaces the following from Effect 3.x:
- *
- * - `Effect.zipRight`
- *
- * **Example** (Applying a Discount Based on Fetched Amount)
+ * **Example** (Sequencing a discount calculation after fetching a total)
  *
  * ```ts
  * import { Data, Effect, pipe } from "effect"
@@ -1358,7 +1342,7 @@ export const flatten = internal.flatten;
  * // Output: 190
  * ```
  *
- * @category Sequencing
+ * @category sequencing
  * @since 2.0.0
  */
 export const andThen = internal.andThen;
@@ -1379,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)
  *
  * ```ts
- * import { Data, Effect, pipe } from "effect"
- * import { Console } from "effect"
+ * import { Console, Data, Effect, pipe } from "effect"
  *
  * class DiscountRateError extends Data.TaggedError("DiscountRateError")<{}> {}
  *
@@ -1419,7 +1396,7 @@ export const andThen = internal.andThen;
  * // 95
  * ```
  *
- * @category Sequencing
+ * @category sequencing
  * @since 2.0.0
  */
 export const tap = internal.tap;
@@ -1446,13 +1423,7 @@ 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:
- *
- * - `Effect.either`
- *
- * **Example** (Usage)
+ * **Example** (Capturing success or failure as Result)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -1485,7 +1456,7 @@ export const result = internal.result;
  * Success values become `Option.some`, recoverable failures become
  * `Option.none`, and defects still fail the effect.
  *
- * **Example** (Usage)
+ * **Example** (Capturing success or failure as Option)
  *
  * ```ts
  * import { Console, Effect, Option } from "effect"
@@ -1523,7 +1494,7 @@ 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** (Usage)
+ * **Example** (Capturing completion as Exit)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -1570,7 +1541,7 @@ 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"
@@ -1592,7 +1563,7 @@ 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
+ * @category mapping
  * @since 2.0.0
  */
 export const map = internal.map;
@@ -1602,7 +1573,7 @@ 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** (Replacing a Value)
+ * **Example** (Replacing a success value)
  *
  * ```ts
  * import { Effect, pipe } from "effect"
@@ -1614,7 +1585,7 @@ export const map = internal.map;
  * // Output: "new value"
  * ```
  *
- * @category Mapping
+ * @category mapping
  * @since 2.0.0
  */
 export const as = internal.as;
@@ -1623,7 +1594,7 @@ export const as = internal.as;
  * in an `Option` value. If the original `Effect` value fails, the returned
  * `Effect` value will also fail.
  *
- * **Example** (Usage)
+ * **Example** (Wrapping success in Option.some)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -1634,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;
@@ -1644,7 +1615,7 @@ export const asSome = internal.asSome;
  * succeed. If the original `Effect` value fails, the returned `Effect` value
  * will fail with the same error.
  *
- * **Example** (Usage)
+ * **Example** (Discarding success values)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -1655,7 +1626,7 @@ export const asSome = internal.asSome;
  * // undefined (void)
  * ```
  *
- * @category Mapping
+ * @category mapping
  * @since 2.0.0
  */
 export const asVoid = internal.asVoid;
@@ -1668,7 +1639,7 @@ 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** (Usage)
+ * **Example** (Swapping success and failure channels)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -1682,7 +1653,7 @@ export const asVoid = internal.asVoid;
  * const flipped = Effect.flip(program)
  * ```
  *
- * @category Mapping
+ * @category mapping
  * @since 2.0.0
  */
 export const flip = internal.flip;
@@ -1703,7 +1674,7 @@ 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** (Combining Two Effects Sequentially)
+ * **Example** (Combining two effects sequentially)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -1730,7 +1701,7 @@ export const flip = internal.flip;
  * // [ 1, 'hello' ]
  * ```
  *
- * **Example** (Combining Two Effects Concurrently)
+ * **Example** (Combining two effects concurrently)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -1754,7 +1725,7 @@ export const flip = internal.flip;
  * // [ 1, 'hello' ]
  * ```
  *
- * @category Zipping
+ * @category zipping
  * @since 2.0.0
  */
 export const zip = internal.zip;
@@ -1773,7 +1744,7 @@ export const zip = internal.zip;
  * By default, the effects are run sequentially. To execute them concurrently,
  * use the `{ concurrent: true }` option.
  *
- * **Example** (Combining Effects with a Custom Function)
+ * **Example** (Combining two success values with a function)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -1801,7 +1772,7 @@ export const zip = internal.zip;
  * // 6
  * ```
  *
- * @category Zipping
+ * @category zipping
  * @since 2.0.0
  */
 export const zipWith = internal.zipWith;
@@ -1825,13 +1796,7 @@ 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
+ * @category error handling
  * @since 4.0.0
  */
 catch_ as catch };
@@ -1849,7 +1814,7 @@ 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** (Usage)
+ * **Example** (Handling a tagged error)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -1873,7 +1838,7 @@ catch_ as catch };
  * )
  * ```
  *
- * @category Error Handling
+ * @category error handling
  * @since 2.0.0
  */
 export const catchTag = internal.catchTag;
@@ -1892,7 +1857,7 @@ 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** (Usage)
+ * **Example** (Handling multiple tagged errors)
  *
  * ```ts
  * import { Data, Effect } from "effect"
@@ -1917,7 +1882,7 @@ export const catchTag = internal.catchTag;
  * })
  * ```
  *
- * @category Error Handling
+ * @category error handling
  * @since 2.0.0
  */
 export const catchTags = internal.catchTags;
@@ -1927,7 +1892,7 @@ 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** (Usage)
+ * **Example** (Handling an error reason)
  *
  * ```ts
  * import { Data, Effect } from "effect"
@@ -1954,14 +1919,14 @@ export const catchTags = internal.catchTags;
  * )
  * ```
  *
- * @category Error Handling
+ * @category error handling
  * @since 4.0.0
  */
 export const catchReason = internal.catchReason;
 /**
  * Catches multiple reasons within a tagged error using an object of handlers.
  *
- * **Example** (Usage)
+ * **Example** (Handling multiple error reasons)
  *
  * ```ts
  * import { Data, Effect } from "effect"
@@ -1990,7 +1955,7 @@ export const catchReason = internal.catchReason;
  * )
  * ```
  *
- * @category Error Handling
+ * @category error handling
  * @since 4.0.0
  */
 export const catchReasons = internal.catchReasons;
@@ -1998,7 +1963,7 @@ export const catchReasons = internal.catchReasons;
  * Promotes nested reason errors into the Effect error channel, replacing
  * the parent error.
  *
- * **Example** (Usage)
+ * **Example** (Extracting the reason from a tagged error)
  *
  * ```ts
  * import { Data, Effect } from "effect"
@@ -2022,7 +1987,7 @@ export const catchReasons = internal.catchReasons;
  * const unwrapped = program.pipe(Effect.unwrapReason("AiError"))
  * ```
  *
- * @category Error Handling
+ * @category error handling
  * @since 4.0.0
  */
 export const unwrapReason = internal.unwrapReason;
@@ -2043,13 +2008,7 @@ 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:
- *
- * - `Effect.catchAllCause`
- *
- * **Example** (Usage)
+ * **Example** (Recovering from full failure causes)
  *
  * ```ts
  * import { Cause, Console, Effect } from "effect"
@@ -2068,7 +2027,7 @@ export const unwrapReason = internal.unwrapReason;
  * })
  * ```
  *
- * @category Error Handling
+ * @category error handling
  * @since 4.0.0
  */
 export const catchCause = internal.catchCause;
@@ -2091,13 +2050,7 @@ export const catchCause = internal.catchCause;
  * they often indicate serious issues. In some cases, such as dynamically loaded
  * plugins, controlled recovery may be needed.
  *
- * **Previously Known As**
- *
- * This API replaces the following from Effect 3.x:
- *
- * - `Effect.catchAllDefect`
- *
- * **Example** (Usage)
+ * **Example** (Recovering from defects)
  *
  * ```ts
  * import { Console, Effect } from "effect"
@@ -2115,7 +2068,7 @@ export const catchCause = internal.catchCause;
  * })
  * ```
  *
- * @category Error Handling
+ * @category error handling
  * @since 4.0.0
  */
 export const catchDefect = internal.catchDefect;
@@ -2129,14 +2082,7 @@ 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** (Recovering when a predicate matches)
  *
  * ```ts
  * import { Data, Effect, Filter } from "effect"
@@ -2162,14 +2108,14 @@ export const catchDefect = internal.catchDefect;
  * )
  * ```
  *
- * @category Error Handling
+ * @category error handling
  * @since 2.0.0
  */
 export const catchIf = internal.catchIf;
 /**
  * Recovers from specific errors using a `Filter`.
  *
- * @category Error Handling
+ * @category error handling
  * @since 4.0.0
  */
 export const catchFilter = internal.catchFilter;
@@ -2179,7 +2125,7 @@ export const catchFilter = internal.catchFilter;
  * Success values become `Option.some`, `NoSuchElementError` becomes
  * `Option.none`, and all other errors are preserved.
  *
- * **Example** (Usage)
+ * **Example** (Recovering from missing Option values)
  *
  * ```ts
  * import { Effect, Option } from "effect"
@@ -2191,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`
- *
- * @category Error Handling
- * @since 2.0.0
+ * @category error handling
+ * @since 4.0.0
  */
 export const catchNoSuchElement = internal.catchNoSuchElement;
 /**
@@ -2208,13 +2148,7 @@ 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** (Recovering from selected causes)
  *
  * ```ts
  * import { Cause, Console, Effect } from "effect"
@@ -2237,14 +2171,14 @@ export const catchNoSuchElement = internal.catchNoSuchElement;
  * // Then: "Fallback response"
  * ```
  *
- * @category Error Handling
+ * @category error handling
  * @since 4.0.0
  */
 export const catchCauseIf = internal.catchCauseIf;
 /**
  * Recovers from specific failures based on a `Filter`.
  *
- * @category Error Handling
+ * @category error handling
  * @since 4.0.0
  */
 export const catchCauseFilter = internal.catchCauseFilter;
@@ -2259,9 +2193,9 @@ 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** (Transforming the error channel)
  *
  * ```ts
  * import { Data, Effect } from "effect"
@@ -2280,7 +2214,7 @@ export const catchCauseFilter = internal.catchCauseFilter;
  * )
  * ```
  *
- * @category Error Handling
+ * @category error handling
  * @since 2.0.0
  */
 export const mapError = internal.mapError;
@@ -2294,7 +2228,7 @@ export const mapError = internal.mapError;
  * the error and the success values without altering the overall success or
  * failure status of the effect.
  *
- * **Example** (Usage)
+ * **Example** (Transforming success and failure channels)
  *
  * ```ts
  * import { Data, Effect } from "effect"
@@ -2316,7 +2250,7 @@ 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
+ * @category mapping
  * @since 2.0.0
  */
 export const mapBoth = internal.mapBoth;
@@ -2329,9 +2263,9 @@ export const mapBoth = internal.mapBoth;
  * Use `orDie` when a typed failure represents an unrecoverable bug or invalid
  * state and should not be handled as a recoverable error.
  *
- * @see {@link orDieWith} if you need to customize the error.
+ * @see {@link mapError} to transform the error before converting it into a defect with {@link orDie}.
  *
- * **Example** (Propagating an Error as a Defect)
+ * **Example** (Converting typed failures into defects)
  *
  * ```ts
  * import { Data, Effect } from "effect"
@@ -2367,7 +2301,7 @@ export const orDie = internal.orDie;
  * operation passed to `tapError` fails, that error is also represented in the
  * returned effect's error channel.
  *
- * **Example** (Usage)
+ * **Example** (Running effects on failure)
  *
  * ```ts
  * import { Console, Effect } from "effect"
@@ -2386,7 +2320,7 @@ export const orDie = internal.orDie;
  * // expected error: NetworkError
  * ```
  *
- * @category Sequencing
+ * @category sequencing
  * @since 2.0.0
  */
 export const tapError = internal.tapError;
@@ -2397,7 +2331,7 @@ export const tapError = internal.tapError;
  * 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** (Running effects for tagged failures)
  *
  * ```ts
  * import { Console, Data, Effect } from "effect"
@@ -2422,7 +2356,7 @@ export const tapError = internal.tapError;
  * // expected error: 504
  * ```
  *
- * @category Sequencing
+ * @category sequencing
  * @since 2.0.0
  */
 export const tapErrorTag = internal.tapErrorTag;
@@ -2436,13 +2370,7 @@ export const tapErrorTag = internal.tapErrorTag;
  * the operation succeeds, the original cause is preserved. If the operation
  * fails, its error is also represented in the returned effect.
  *
- * **Previously Known As**
- *
- * This API replaces the following from Effect 3.x:
- *
- * - `Effect.tapErrorCause`
- *
- * **Example** (Usage)
+ * **Example** (Observing full failure causes)
  *
  * ```ts
  * import { Cause, Console, Effect } from "effect"
@@ -2459,8 +2387,8 @@ export const tapErrorTag = internal.tapErrorTag;
  * // Then: { _id: 'Exit', _tag: 'Failure', cause: ... }
  * ```
  *
- * @category Sequencing
- * @since 2.0.0
+ * @category sequencing
+ * @since 4.0.0
  */
 export const tapCause = internal.tapCause;
 /**
@@ -2470,7 +2398,7 @@ 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** (Usage)
+ * **Example** (Observing selected failure causes)
  *
  * ```ts
  * import { Cause, Console, Effect } from "effect"
@@ -2489,14 +2417,14 @@ export const tapCause = internal.tapCause;
  * // Then: { _id: 'Exit', _tag: 'Failure', cause: ... }
  * ```
  *
- * @category Sequencing
+ * @category sequencing
  * @since 4.0.0
  */
 export const tapCauseIf = internal.tapCauseIf;
 /**
  * Conditionally executes a side effect based on the cause of a failed effect.
  *
- * @category Sequencing
+ * @category sequencing
  * @since 4.0.0
  */
 export const tapCauseFilter = internal.tapCauseFilter;
@@ -2510,7 +2438,7 @@ export const tapCauseFilter = internal.tapCauseFilter;
  * operation succeeds, the original defect is preserved; if the operation fails,
  * its error is also represented in the returned effect.
  *
- * **Example** (Usage)
+ * **Example** (Observing defects)
  *
  * ```ts
  * import { Console, Effect } from "effect"
@@ -2544,7 +2472,7 @@ export const tapCauseFilter = internal.tapCauseFilter;
  * //   ... stack trace ...
  * ```
  *
- * @category Sequencing
+ * @category sequencing
  * @since 2.0.0
  */
 export const tapDefect = internal.tapDefect;
@@ -2553,7 +2481,7 @@ export const tapDefect = internal.tapDefect;
  *
  * Yields between attempts so other fibers can run.
  *
- * **Example** (Usage)
+ * **Example** (Retrying until success)
  *
  * ```ts
  * import { Console, Effect } from "effect"
@@ -2600,7 +2528,7 @@ export const eventually = internal.eventually;
  * Use `retry` when typed failures may be transient, such as network issues or
  * temporary resource unavailability.
  *
- * **Example** (Usage)
+ * **Example** (Retrying with a schedule)
  *
  * ```ts
  * import { Data, Effect, Schedule } from "effect"
@@ -2627,7 +2555,7 @@ 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
+ * @category error handling
  * @since 2.0.0
  */
 export const retry = internalSchedule.retry;
@@ -2649,7 +2577,7 @@ export const retry = internalSchedule.retry;
  *
  * @see {@link retry} for a version that does not run a fallback effect.
  *
- * **Example** (Usage)
+ * **Example** (Falling back after retries are exhausted)
  *
  * ```ts
  * import { Console, Data, Effect, Schedule } from "effect"
@@ -2685,7 +2613,7 @@ export const retry = internalSchedule.retry;
  * // Network data
  * ```
  *
- * @category Error Handling
+ * @category error handling
  * @since 2.0.0
  */
 export const retryOrElse = internalSchedule.retryOrElse;
@@ -2698,7 +2626,7 @@ export const retryOrElse = internalSchedule.retryOrElse;
  * failures, defects, and interruptions. Use `unsandbox` to restore the original
  * typed error channel after cause-level handling.
  *
- * **Example** (Usage)
+ * **Example** (Exposing failures as causes)
  *
  * ```ts
  * import { Cause, Effect } from "effect"
@@ -2715,9 +2643,9 @@ 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
+ * @category error handling
  * @since 2.0.0
  */
 export const sandbox = internal.sandbox;
@@ -2733,7 +2661,7 @@ 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** (Using Effect.ignore to Discard Values)
+ * **Example** (Discarding success and failure values)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -2758,13 +2686,7 @@ 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
+ * @category error handling
  * @since 2.0.0
  */
 export const ignore = internal.ignore;
@@ -2774,7 +2696,7 @@ 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** (Usage)
+ * **Example** (Ignoring failures and logging causes)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -2785,7 +2707,7 @@ export const ignore = internal.ignore;
  * const programLog = task.pipe(Effect.ignoreCause({ log: true, message: "Ignoring failure cause" }))
  * ```
  *
- * @category Error Handling
+ * @category error handling
  * @since 4.0.0
  */
 export const ignoreCause = internal.ignoreCause;
@@ -2797,10 +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** (Usage)
+ * **Example** (Retrying with an execution plan)
  *
  * ```ts
- * import { Effect, ExecutionPlan, Layer, Context } from "effect"
+ * import { Context, Effect, ExecutionPlan, Layer } from "effect"
  *
  * const Endpoint = Context.Service<{ url: string }>("Endpoint")
  *
@@ -2830,7 +2752,7 @@ 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
+ * @category error handling
  * @since 4.0.0
  */
 export const withErrorReporting = internal.withErrorReporting;
@@ -2848,7 +2770,7 @@ export const withErrorReporting = internal.withErrorReporting;
  *
  * Defects and interruptions are not recovered by this operator.
  *
- * **Example** (Usage)
+ * **Example** (Replacing failures with a value)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -2894,7 +2816,7 @@ export const orElseSucceed = internal.orElseSucceed;
  * attempting multiple APIs, reading configuration from several sources, or
  * trying alternative resource locations in order.
  *
- * **Example** (Usage)
+ * **Example** (Trying alternatives until one succeeds)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -2932,11 +2854,9 @@ 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** (Failing when work takes too long)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -2982,11 +2902,9 @@ export const timeout = internal.timeout;
  * 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** (Returning None on timeout)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -3024,7 +2942,7 @@ 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** (Usage)
+ * **Example** (Falling back on timeout)
  *
  * ```ts
  * import { Console, Effect } from "effect"
@@ -3053,14 +2971,14 @@ export const timeoutOption = internal.timeoutOption;
  * ```
  *
  * @category Delays & Timeouts
- * @since 3.1.0
+ * @since 4.0.0
  */
 export const timeoutOrElse = internal.timeoutOrElse;
 /**
  * Returns an effect that is delayed from this effect by the specified
  * `Duration`.
  *
- * **Example** (Usage)
+ * **Example** (Delaying an effect)
  *
  * ```ts
  * import { Console, Effect } from "effect"
@@ -3082,7 +3000,7 @@ export const delay = internal.delay;
  * Returns an effect that suspends the current fiber for the specified duration
  * without blocking a JavaScript thread.
  *
- * **Example** (Usage)
+ * **Example** (Pausing without blocking)
  *
  * ```ts
  * import { Console, Effect } from "effect"
@@ -3108,7 +3026,7 @@ export const sleep = internal.sleep;
  * The original success, failure, or interruption is preserved; only the success
  * value is paired with the duration.
  *
- * **Example** (Usage)
+ * **Example** (Measuring execution time)
  *
  * ```ts
  * import { Console, Duration, Effect } from "effect"
@@ -3143,7 +3061,7 @@ export const timed = internal.timed;
  *
  * @see {@link race} for a version that handles only two effects.
  *
- * **Example** (Usage)
+ * **Example** (Racing many effects)
  *
  * ```ts
  * import { Duration, Effect } from "effect"
@@ -3173,7 +3091,7 @@ export const raceAll = internal.raceAll;
  * `raceAll` when early failures should be ignored until a success occurs or
  * all effects fail.
  *
- * **Example** (Usage)
+ * **Example** (Taking the first settled result)
  *
  * ```ts
  * import { Duration, Effect } from "effect"
@@ -3199,7 +3117,7 @@ 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** (Usage)
+ * **Example** (Racing two effects)
  *
  * ```ts
  * import { Console, Duration, Effect } from "effect"
@@ -3226,7 +3144,7 @@ export const race = internal.race;
  *
  * The losing effect is interrupted, and `onWinner` can observe the winning fiber.
  *
- * **Example** (Usage)
+ * **Example** (Observing the winning fiber)
  *
  * ```ts
  * import { Console, Duration, Effect } from "effect"
@@ -3257,7 +3175,7 @@ export const raceFirst = internal.raceFirst;
  * Filters elements of an iterable using a predicate, refinement, or effectful
  * predicate.
  *
- * **Example** (Usage)
+ * **Example** (Filtering success values)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -3271,21 +3189,21 @@ export const raceFirst = internal.raceFirst;
  * // Use Effect.filterMapEffect for effectful Filter.Filter callbacks
  * ```
  *
- * @category Filtering
+ * @category filtering
  * @since 2.0.0
  */
 export const filter = internal.filter;
 /**
  * Filters and maps elements of an iterable with a `Filter`.
  *
- * @category Filtering
- * @since 4.0.0
+ * @category filtering
+ * @since 2.0.0
  */
 export const filterMap = internal.filterMap;
 /**
  * Effectfully filters and maps elements of an iterable with a `FilterEffect`.
  *
- * @category Filtering
+ * @category filtering
  * @since 4.0.0
  */
 export const filterMapEffect = internal.filterMapEffect;
@@ -3299,7 +3217,7 @@ export const filterMapEffect = internal.filterMapEffect;
  * `orElse` effect can produce an alternative value or perform additional
  * computations.
  *
- * **Example** (Usage)
+ * **Example** (Filtering with a fallback effect)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -3317,14 +3235,14 @@ export const filterMapEffect = internal.filterMapEffect;
  * // Result: "Number 5 is odd" (since 5 is not even)
  * ```
  *
- * @category Filtering
+ * @category filtering
  * @since 2.0.0
  */
 export const filterOrElse = internal.filterOrElse;
 /**
  * Filters an effect with a `Filter`, providing an alternative effect on failure.
  *
- * @category Filtering
+ * @category filtering
  * @since 4.0.0
  */
 export const filterMapOrElse = internal.filterMapOrElse;
@@ -3337,7 +3255,7 @@ 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** (Usage)
+ * **Example** (Filtering with a custom failure)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -3355,14 +3273,14 @@ export const filterMapOrElse = internal.filterMapOrElse;
  * // Result: Effect.fail("Expected even number, got 5")
  * ```
  *
- * @category Filtering
+ * @category filtering
  * @since 2.0.0
  */
 export const filterOrFail = internal.filterOrFail;
 /**
  * Filters an effect with a `Filter`, failing when the filter fails.
  *
- * @category Filtering
+ * @category filtering
  * @since 4.0.0
  */
 export const filterMapOrFail = internal.filterMapOrFail;
@@ -3385,7 +3303,7 @@ export const filterMapOrFail = internal.filterMapOrFail;
  * Use this when an effectful check decides whether to run another effect while
  * representing the skipped case explicitly.
  *
- * **Example** (Usage)
+ * **Example** (Conditionally running an effect)
  *
  * ```ts
  * import { Console, Effect } from "effect"
@@ -3402,8 +3320,7 @@ 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.
  *
  * @category Conditional Operators
  * @since 2.0.0
@@ -3430,7 +3347,7 @@ export const when = internal.when;
  *
  * @see {@link matchEffect} if you need to perform side effects in the handlers.
  *
- * **Example** (Handling Both Success and Failure Cases)
+ * **Example** (Matching success and failure values)
  *
  * ```ts
  * import { Data, Effect } from "effect"
@@ -3483,7 +3400,7 @@ 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** (Usage)
+ * **Example** (Pattern matching eagerly when possible)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -3501,7 +3418,7 @@ export const match = internal.match;
  * @see {@link matchEffect} if you need to perform side effects in the handlers.
  *
  * @category Pattern Matching
- * @since 2.0.0
+ * @since 4.0.0
  */
 export const matchEager = internal.matchEager;
 /**
@@ -3518,7 +3435,7 @@ 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** (Usage)
+ * **Example** (Matching on success or failure causes)
  *
  * ```ts
  * import { Cause, Effect } from "effect"
@@ -3557,7 +3474,7 @@ 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** (Usage)
+ * **Example** (Eagerly matching already completed effects)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -3569,7 +3486,7 @@ export const matchCause = internal.matchCause;
  * ```
  *
  * @category Pattern Matching
- * @since 3.8.0
+ * @since 4.0.0
  */
 export const matchCauseEager = internal.matchCauseEager;
 /**
@@ -3594,7 +3511,7 @@ export const matchCauseEffectEager = internal.matchCauseEffectEager;
  * you to respond accordingly while performing side effects (like logging or
  * other operations).
  *
- * **Example** (Usage)
+ * **Example** (Effectfully matching on causes)
  *
  * ```ts
  * import { Cause, Console, Data, Effect, Result } from "effect"
@@ -3653,7 +3570,7 @@ export const matchCauseEffect = internal.matchCauseEffect;
  * @see {@link match} if you don't need side effects and only want to handle the
  * result or failure.
  *
- * **Example** (Handling Both Success and Failure Cases with Side Effects)
+ * **Example** (Matching success and failure with effectful handlers)
  *
  * ```ts
  * import { Data, Effect } from "effect"
@@ -3762,10 +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** (Usage)
+ * **Example** (Reading the full context)
  *
  * ```ts
- * import { Console, Effect, Option, Context } from "effect"
+ * import { Console, Context, Effect, Option } from "effect"
  *
  * const Logger = Context.Service<{
  *   log: (msg: string) => void
@@ -3802,10 +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** (Usage)
+ * **Example** (Deriving values from the context)
  *
  * ```ts
- * import { Console, Effect, Option, Context } from "effect"
+ * import { Console, Context, Effect, Option } from "effect"
  *
  * const Logger = Context.Service<{
  *   log: (msg: string) => void
@@ -3846,10 +3763,10 @@ export const contextWith = internal.contextWith;
  * to build the layer every time; by default, layers are shared between provide
  * calls.
  *
- * **Example** (Usage)
+ * **Example** (Providing dependencies with a layer)
  *
  * ```ts
- * import { Effect, Layer, Context } from "effect"
+ * import { Context, Effect, Layer } from "effect"
  *
  * interface Database {
  *   readonly query: (sql: string) => Effect.Effect<string>
@@ -3885,10 +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** (Usage)
+ * **Example** (Providing a complete context)
  *
  * ```ts
- * import { Effect, Context } from "effect"
+ * import { Context, Effect } from "effect"
  *
  * // Define service keys
  * const Logger = Context.Service<{
@@ -3914,16 +3831,16 @@ export const provide = internalLayer.provide;
  * ```
  *
  * @category Environment
- * @since 2.0.0
+ * @since 4.0.0
  */
 export const provideContext = internal.provideContext;
 /**
  * Accesses a service from the context.
  *
- * **Example** (Usage)
+ * **Example** (Accessing a required service)
  *
  * ```ts
- * import { Effect, Context } from "effect"
+ * import { Context, Effect } from "effect"
  *
  * interface Database {
  *   readonly query: (sql: string) => Effect.Effect<string>
@@ -3951,10 +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** (Usage)
+ * **Example** (Accessing an optional service)
  *
  * ```ts
- * import { Effect, Option, Context } from "effect"
+ * import { Context, Effect, Option } from "effect"
  *
  * // Define a service key
  * const Logger = Context.Service<{
@@ -3985,10 +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** (Usage)
+ * **Example** (Updating the context before running)
  *
  * ```ts
- * import { Effect, Context } from "effect"
+ * import { Context, Effect } from "effect"
  *
  * // Define services
  * const Logger = Context.Service<{
@@ -4026,10 +3943,10 @@ export const updateContext = internal.updateContext;
  * 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** (Replacing a service for one effect)
  *
  * ```ts
- * import { Console, Effect, Context } from "effect"
+ * import { Console, Context, Effect } from "effect"
  *
  * // Define a counter service
  * const Counter = Context.Service<{ count: number }>("Counter")
@@ -4065,10 +3982,10 @@ export const updateService = internal.updateService;
  *
  * @see {@link provide} for providing multiple layers to an effect.
  *
- * **Example** (Usage)
+ * **Example** (Providing a service value)
  *
  * ```ts
- * import { Console, Effect, Context } from "effect"
+ * import { Console, Context, Effect } from "effect"
  *
  * // Define a service for configuration
  * const Config = Context.Service<{
@@ -4110,10 +4027,10 @@ export const provideService = internal.provideService;
  * and leaves any other requirements to be provided later. Acquisition failures
  * are included in the returned effect's error channel.
  *
- * **Example** (Usage)
+ * **Example** (Providing a service with an effect)
  *
  * ```ts
- * import { Console, Effect, Context } from "effect"
+ * import { Console, Context, Effect } from "effect"
  *
  * // Define a database connection service
  * interface DatabaseConnection {
@@ -4160,7 +4077,7 @@ export const provideServiceEffect = internal.provideServiceEffect;
 /**
  * Sets the concurrency level for parallel operations within an effect.
  *
- * **Example** (Usage)
+ * **Example** (Setting local concurrency)
  *
  * ```ts
  * import { Console, Effect } from "effect"
@@ -4186,7 +4103,7 @@ export const provideServiceEffect = internal.provideServiceEffect;
  * // [1, 2, 3, 4, 5]
  * ```
  *
- * @category References
+ * @category references
  * @since 2.0.0
  */
 export const withConcurrency = internal.withConcurrency;
@@ -4196,7 +4113,7 @@ export const withConcurrency = internal.withConcurrency;
 /**
  * Returns the current scope for resource management.
  *
- * **Example** (Usage)
+ * **Example** (Accessing the current scope)
  *
  * ```ts
  * import { Console, Effect } from "effect"
@@ -4222,7 +4139,7 @@ export const withConcurrency = internal.withConcurrency;
  * // Releasing resource
  * ```
  *
- * @category Resource Management & Finalization
+ * @category resource management
  * @since 2.0.0
  */
 export const scope = internal.scope;
@@ -4231,7 +4148,7 @@ 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** (Usage)
+ * **Example** (Running a scoped acquisition)
  *
  * ```ts
  * import { Console, Effect } from "effect"
@@ -4255,14 +4172,14 @@ export const scope = internal.scope;
  * // Output: "Releasing resource"
  * ```
  *
- * @category Resource Management & Finalization
+ * @category resource management
  * @since 2.0.0
  */
 export const scoped = internal.scoped;
 /**
  * Creates a scoped effect by providing access to the scope.
  *
- * **Example** (Usage)
+ * **Example** (Working with an explicit scope)
  *
  * ```ts
  * import { Console, Effect, Scope } from "effect"
@@ -4295,8 +4212,8 @@ export const scoped = internal.scoped;
  * // Manual finalizer
  * ```
  *
- * @category Resource Management & Finalization
- * @since 2.0.0
+ * @category resource management
+ * @since 3.11.0
  */
 export const scopedWith = internal.scopedWith;
 /**
@@ -4312,7 +4229,7 @@ export const scopedWith = internal.scopedWith;
  * By default, acquisition is protected by an uninterruptible region. Pass
  * `{ interruptible: true }` to allow the acquisition effect to be interrupted.
  *
- * **Example** (Usage)
+ * **Example** (Acquiring and releasing a resource)
  *
  * ```ts
  * import { Console, Effect, Exit } from "effect"
@@ -4350,7 +4267,7 @@ export const scopedWith = internal.scopedWith;
  * )
  * ```
  *
- * @category Resource Management & Finalization
+ * @category resource management
  * @since 2.0.0
  */
 export const acquireRelease = internal.acquireRelease;
@@ -4367,13 +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** (Acquiring a disposable resource)
  *
  * ```ts
  * import sqlite from "node:sqlite";
- * import { Effect } from "effect";
+ * import { Effect } from "effect"
  *
  * const program = Effect.scoped(
  *   Effect.gen(function* () {
@@ -4389,7 +4306,7 @@ export const acquireRelease = internal.acquireRelease;
  * )
  * ```
  *
- * @category Resource Management & Finalization
+ * @category resource management
  * @since 4.0.0
  */
 export const acquireDisposable = internal.acquireDisposable;
@@ -4416,7 +4333,7 @@ export const acquireDisposable = internal.acquireDisposable;
  * is not desired, errors produced by the `release` `Effect` value can be caught
  * and ignored.
  *
- * **Example** (Usage)
+ * **Example** (Using a resource with cleanup)
  *
  * ```ts
  * import { Console, Effect, Exit } from "effect"
@@ -4462,7 +4379,7 @@ export const acquireDisposable = internal.acquireDisposable;
  * // Closing connection to db://localhost:5432 (success)
  * ```
  *
- * @category Resource Management & Finalization
+ * @category resource management
  * @since 2.0.0
  */
 export const acquireUseRelease = internal.acquireUseRelease;
@@ -4475,7 +4392,7 @@ 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** (Usage)
+ * **Example** (Registering scope finalizers)
  *
  * ```ts
  * import { Console, Effect, Exit } from "effect"
@@ -4505,7 +4422,7 @@ export const acquireUseRelease = internal.acquireUseRelease;
  * // operation result
  * ```
  *
- * @category Resource Management & Finalization
+ * @category resource management
  * @since 2.0.0
  */
 export const addFinalizer = internal.addFinalizer;
@@ -4520,7 +4437,7 @@ 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** (Usage)
+ * **Example** (Always running cleanup)
  *
  * ```ts
  * import { Console, Effect } from "effect"
@@ -4546,7 +4463,7 @@ export const addFinalizer = internal.addFinalizer;
  * // 42
  * ```
  *
- * @category Resource Management & Finalization
+ * @category resource management
  * @since 2.0.0
  */
 export const ensuring = internal.ensuring;
@@ -4554,10 +4471,10 @@ 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** (Usage)
+ * **Example** (Running cleanup on failure)
  *
  * ```ts
- * import { Cause, Data, Console, Effect } from "effect"
+ * import { Cause, Console, Data, Effect } from "effect"
  *
  * class TaskError extends Data.TaggedError("TaskError")<{ readonly message: string }> {}
  *
@@ -4574,7 +4491,7 @@ export const ensuring = internal.ensuring;
  * // TaskError: Something went wrong
  * ```
  *
- * @category Resource Management & Finalization
+ * @category resource management
  * @since 2.0.0
  */
 export const onError = internal.onError;
@@ -4582,7 +4499,7 @@ export const onError = internal.onError;
  * Runs the finalizer only when this effect fails and the `Cause` matches the
  * provided predicate.
  *
- * **Example** (Usage)
+ * **Example** (Running cleanup for selected failures)
  *
  * ```ts
  * import { Cause, Console, Effect } from "effect"
@@ -4599,14 +4516,14 @@ export const onError = internal.onError;
  * )
  * ```
  *
- * @category Resource Management & Finalization
+ * @category resource management
  * @since 4.0.0
  */
 export const onErrorIf = internal.onErrorIf;
 /**
  * Runs the finalizer only when this effect fails and the cause matches the provided `Filter`.
  *
- * @category Resource Management & Finalization
+ * @category resource management
  * @since 4.0.0
  */
 export const onErrorFilter = internal.onErrorFilter;
@@ -4619,15 +4536,15 @@ export const onErrorFilter = internal.onErrorFilter;
  * This low-level operator preserves the source effect's result unless the
  * finalizer fails. Prefer `onExit` for normal cleanup logic.
  *
- * @category Resource Management & Finalization
- * @since 2.0.0
+ * @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** (Usage)
+ * **Example** (Observing every exit)
  *
  * ```ts
  * import { Console, Effect, Exit } from "effect"
@@ -4647,7 +4564,7 @@ export const onExitPrimitive = internal.onExitPrimitive;
  * // 42
  * ```
  *
- * @category Resource Management & Finalization
+ * @category resource management
  * @since 2.0.0
  */
 export const onExit = internal.onExit;
@@ -4655,7 +4572,7 @@ export const onExit = internal.onExit;
  * Runs the cleanup effect only when the `Exit` satisfies the provided
  * predicate.
  *
- * **Example** (Usage)
+ * **Example** (Observing selected exits)
  *
  * ```ts
  * import { Console, Effect, Exit } from "effect"
@@ -4670,14 +4587,14 @@ export const onExit = internal.onExit;
  * )
  * ```
  *
- * @category Resource Management & Finalization
+ * @category resource management
  * @since 4.0.0
  */
 export const onExitIf = internal.onExitIf;
 /**
  * Runs the cleanup effect only when the `Exit` matches the provided `Filter`.
  *
- * @category Resource Management & Finalization
+ * @category resource management
  * @since 4.0.0
  */
 export const onExitFilter = internal.onExitFilter;
@@ -4707,7 +4624,7 @@ export const onExitFilter = internal.onExitFilter;
  * @see {@link cachedInvalidateWithTTL} for a similar function that includes an
  * additional effect for manually invalidating the cached value.
  *
- * **Example** (Usage)
+ * **Example** (Memoizing an effect until invalidated)
  *
  * ```ts
  * import { Console, Effect } from "effect"
@@ -4781,7 +4698,7 @@ export const cached = internal.cached;
  * @see {@link cachedInvalidateWithTTL} for a similar function that includes an
  * additional effect for manually invalidating the cached value.
  *
- * **Example** (Usage)
+ * **Example** (Memoizing an effect with TTL)
  *
  * ```ts
  * import { Console, Effect } from "effect"
@@ -4849,7 +4766,7 @@ 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** (Usage)
+ * **Example** (Memoizing with TTL and invalidation)
  *
  * ```ts
  * import { Console, Effect } from "effect"
@@ -4894,7 +4811,7 @@ export const cachedInvalidateWithTTL = internal.cachedInvalidateWithTTL;
 /**
  * Returns an effect that is immediately interrupted.
  *
- * **Example** (Usage)
+ * **Example** (Creating an interrupted effect)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -4915,7 +4832,7 @@ export const interrupt = internal.interrupt;
 /**
  * Returns a new effect that allows the effect to be interruptible.
  *
- * **Example** (Usage)
+ * **Example** (Allowing interruption)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -4936,7 +4853,7 @@ export const interruptible = internal.interruptible;
 /**
  * Runs the specified finalizer effect if this effect is interrupted.
  *
- * **Example** (Usage)
+ * **Example** (Running cleanup on interruption)
  *
  * ```ts
  * import { Console, Effect, Fiber } from "effect"
@@ -4961,7 +4878,7 @@ export const onInterrupt = internal.onInterrupt;
 /**
  * Returns a new effect that disables interruption for the given effect.
  *
- * **Example** (Usage)
+ * **Example** (Preventing interruption)
  *
  * ```ts
  * import { Console, Effect, Fiber } from "effect"
@@ -4987,7 +4904,7 @@ export const uninterruptible = internal.uninterruptible;
  * Disables interruption and provides a restore function to restore the
  * interruptible state within the effect.
  *
- * **Example** (Usage)
+ * **Example** (Restoring interruption in protected regions)
  *
  * ```ts
  * import { Console, Effect } from "effect"
@@ -5019,7 +4936,7 @@ export const uninterruptibleMask = internal.uninterruptibleMask;
  * `restore` function. This function can be used to restore the interruptibility
  * of any specific region of code.
  *
- * **Example** (Usage)
+ * **Example** (Controlling interruptibility locally)
  *
  * ```ts
  * import { Console, Effect } from "effect"
@@ -5056,7 +4973,7 @@ export const abortSignal = internal.abortSignal;
 /**
  * Repeats this effect forever (until the first error).
  *
- * **Example** (Usage)
+ * **Example** (Repeating forever)
  *
  * ```ts
  * import { Console, Effect, Fiber } from "effect"
@@ -5106,13 +5023,11 @@ export const forever = internal.forever;
  * delays, limiting recursions, or dynamically adjusting based on the outcome of
  * each execution.
  *
- * **Example** (Usage)
+ * **Example** (Repeating successful effects with a schedule)
  *
  * ```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"))
@@ -5121,12 +5036,11 @@ export const forever = internal.forever;
  * // Effect.runPromise(program).then((n) => console.log(`repetitions: ${n}`))
  * ```
  *
- * **Example** (Usage)
+ * **Example** (Stopping repetition on failure)
  *
  * ```ts
  * // Failure Example
- * import { Effect } from "effect"
- * import { Schedule } from "effect"
+ * import { Effect, Schedule } from "effect"
  *
  * let count = 0
  *
@@ -5163,11 +5077,10 @@ export const repeat = internalSchedule.repeat;
  * otherwise it receives `None`. If the schedule completes normally, the
  * returned effect succeeds with the schedule's output.
  *
- * **Example** (Usage)
+ * **Example** (Recovering after repetition stops)
  *
  * ```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*() {
@@ -5210,7 +5123,7 @@ export const replicate = internal.replicate;
  *
  * Use `concurrency` to control parallelism and `discard: true` to ignore results.
  *
- * **Example** (Usage)
+ * **Example** (Replicating an effect)
  *
  * ```ts
  * import { Console, Effect } from "effect"
@@ -5237,7 +5150,7 @@ export const replicateEffect = internal.replicateEffect;
  * fails, and otherwise succeeds with the schedule output when the schedule
  * completes.
  *
- * **Example** (Usage)
+ * **Example** (Scheduling repeated execution)
  *
  * ```ts
  * import { Console, Effect, Schedule } from "effect"
@@ -5280,7 +5193,7 @@ export const schedule = /*#__PURE__*/dual(2, (self, schedule) => scheduleFrom(se
  * succeeds with the schedule output when the schedule completes and fails if
  * the effect or schedule fails.
  *
- * **Example** (Usage)
+ * **Example** (Scheduling from an initial value)
  *
  * ```ts
  * import { Console, Effect, Schedule } from "effect"
@@ -5312,7 +5225,7 @@ export const scheduleFrom = internalSchedule.scheduleFrom;
 /**
  * Returns the current tracer from the context.
  *
- * **Example** (Usage)
+ * **Example** (Accessing the current tracer)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -5324,14 +5237,14 @@ export const scheduleFrom = internalSchedule.scheduleFrom;
  * })
  * ```
  *
- * @category Tracing
+ * @category tracing
  * @since 2.0.0
  */
 export const tracer = internal.tracer;
 /**
  * Provides a tracer to an effect.
  *
- * **Example** (Usage)
+ * **Example** (Providing a tracer)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -5345,7 +5258,7 @@ export const tracer = internal.tracer;
  * // const traced = Effect.withTracer(program, customTracer)
  * ```
  *
- * @category Tracing
+ * @category tracing
  * @since 2.0.0
  */
 export const withTracer = internal.withTracer;
@@ -5357,7 +5270,7 @@ export const withTracer = internal.withTracer;
  * 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** (Enabling or disabling tracing)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -5369,14 +5282,14 @@ export const withTracer = internal.withTracer;
  * )
  * ```
  *
- * @category Tracing
+ * @category tracing
  * @since 2.0.0
  */
 export const withTracerEnabled = internal.withTracerEnabled;
 /**
  * Enables or disables tracer timing for the given Effect.
  *
- * **Example** (Usage)
+ * **Example** (Enabling or disabling tracing timing)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -5388,14 +5301,14 @@ export const withTracerEnabled = internal.withTracerEnabled;
  * )
  * ```
  *
- * @category Tracing
+ * @category tracing
  * @since 2.0.0
  */
 export const withTracerTiming = internal.withTracerTiming;
 /**
  * Adds an annotation to each span in this effect.
  *
- * **Example** (Usage)
+ * **Example** (Annotating all spans)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -5416,14 +5329,14 @@ export const withTracerTiming = internal.withTracerTiming;
  * })
  * ```
  *
- * @category Tracing
+ * @category tracing
  * @since 2.0.0
  */
 export const annotateSpans = internal.annotateSpans;
 /**
  * Adds an annotation to the current span if available.
  *
- * **Example** (Usage)
+ * **Example** (Annotating the current span)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -5441,7 +5354,7 @@ export const annotateSpans = internal.annotateSpans;
  * const traced = Effect.withSpan(program, "user-operation")
  * ```
  *
- * @category Tracing
+ * @category tracing
  * @since 2.0.0
  */
 export const annotateCurrentSpan = internal.annotateCurrentSpan;
@@ -5453,7 +5366,7 @@ export const annotateCurrentSpan = internal.annotateCurrentSpan;
  * The effect fails with `NoSuchElementError` when there is no active local
  * `Span`.
  *
- * **Example** (Usage)
+ * **Example** (Reading the current span)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -5467,7 +5380,7 @@ export const annotateCurrentSpan = internal.annotateCurrentSpan;
  * const traced = Effect.withSpan(program, "my-span")
  * ```
  *
- * @category Tracing
+ * @category tracing
  * @since 2.0.0
  */
 export const currentSpan = internal.currentSpan;
@@ -5480,7 +5393,7 @@ export const currentSpan = internal.currentSpan;
  * present, and fails with `NoSuchElementError` when no parent span is
  * available.
  *
- * **Example** (Usage)
+ * **Example** (Reading the parent span)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -5499,7 +5412,7 @@ export const currentSpan = internal.currentSpan;
  * const traced = Effect.withSpan(program, "parent-span")
  * ```
  *
- * @category Tracing
+ * @category tracing
  * @since 2.0.0
  */
 export const currentParentSpan = internal.currentParentSpan;
@@ -5511,7 +5424,7 @@ export const currentParentSpan = internal.currentParentSpan;
  * These annotations are applied to spans created inside the context, such as
  * spans created by `withSpan`, `useSpan`, or `makeSpan`.
  *
- * **Example** (Usage)
+ * **Example** (Providing span annotations)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -5532,7 +5445,7 @@ export const currentParentSpan = internal.currentParentSpan;
  * // Output: Current span annotations: { userId: "123", operation: "data-processing" }
  * ```
  *
- * @category Tracing
+ * @category tracing
  * @since 2.0.0
  */
 export const spanAnnotations = internal.spanAnnotations;
@@ -5544,7 +5457,7 @@ export const spanAnnotations = internal.spanAnnotations;
  * These links are attached to spans created inside the context. Span links
  * connect related spans without making one span the parent of another.
  *
- * **Example** (Usage)
+ * **Example** (Providing span links)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -5557,7 +5470,7 @@ export const spanAnnotations = internal.spanAnnotations;
  * })
  * ```
  *
- * @category Tracing
+ * @category tracing
  * @since 2.0.0
  */
 export const spanLinks = internal.spanLinks;
@@ -5568,7 +5481,7 @@ 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** (Usage)
+ * **Example** (Linking one span to another span)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -5591,7 +5504,7 @@ export const spanLinks = internal.spanLinks;
  * })
  * ```
  *
- * **Example** (Usage)
+ * **Example** (Linking multiple spans at once)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -5610,7 +5523,7 @@ export const spanLinks = internal.spanLinks;
  * })
  * ```
  *
- * @category Tracing
+ * @category tracing
  * @since 2.0.0
  */
 export const linkSpans = internal.linkSpans;
@@ -5623,7 +5536,7 @@ export const linkSpans = internal.linkSpans;
  * automatically. Use `withSpan`, `useSpan`, or `makeSpanScoped` when the span
  * should be installed as context or closed automatically.
  *
- * **Example** (Usage)
+ * **Example** (Creating a span manually)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -5635,7 +5548,7 @@ export const linkSpans = internal.linkSpans;
  * })
  * ```
  *
- * @category Tracing
+ * @category tracing
  * @since 2.0.0
  */
 export const makeSpan = internal.makeSpan;
@@ -5646,7 +5559,7 @@ 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** (Usage)
+ * **Example** (Creating a scoped standalone span)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -5661,7 +5574,7 @@ export const makeSpan = internal.makeSpan;
  * )
  * ```
  *
- * @category Tracing
+ * @category tracing
  * @since 2.0.0
  */
 export const makeSpanScoped = internal.makeSpanScoped;
@@ -5672,7 +5585,7 @@ 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** (Usage)
+ * **Example** (Running an effect with a standalone span)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -5687,14 +5600,14 @@ export const makeSpanScoped = internal.makeSpanScoped;
  * )
  * ```
  *
- * @category Tracing
+ * @category tracing
  * @since 2.0.0
  */
 export const useSpan = internal.useSpan;
 /**
  * Wraps the effect with a new span for tracing.
  *
- * **Example** (Usage)
+ * **Example** (Wrapping an effect in a child span)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -5709,7 +5622,7 @@ export const useSpan = internal.useSpan;
  * })
  * ```
  *
- * @category Tracing
+ * @category tracing
  * @since 2.0.0
  */
 export const withSpan = internal.withSpan;
@@ -5718,7 +5631,7 @@ export const withSpan = internal.withSpan;
  *
  * The span is ended when the Scope is finalized.
  *
- * **Example** (Usage)
+ * **Example** (Creating a scoped child span)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -5732,14 +5645,14 @@ export const withSpan = internal.withSpan;
  * )
  * ```
  *
- * @category Tracing
+ * @category tracing
  * @since 2.0.0
  */
 export const withSpanScoped = internal.withSpanScoped;
 /**
  * Adds the provided span to the current span stack.
  *
- * **Example** (Usage)
+ * **Example** (Setting a parent span)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -5752,7 +5665,7 @@ export const withSpanScoped = internal.withSpanScoped;
  * })
  * ```
  *
- * @category Tracing
+ * @category tracing
  * @since 2.0.0
  */
 export const withParentSpan = internal.withParentSpan;
@@ -5765,7 +5678,7 @@ export const withParentSpan = internal.withParentSpan;
  * @category Requests & Batching
  * @since 2.0.0
  *
- * **Example** (Usage)
+ * **Example** (Executing a request through a resolver)
  *
  * ```ts
  * import { Console, Effect, Exit, Request, RequestResolver } from "effect"
@@ -5825,7 +5738,7 @@ 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** (Usage)
+ * **Example** (Forking a child fiber)
  *
  * ```ts
  * import { Effect, Fiber } from "effect"
@@ -5856,7 +5769,7 @@ export const forkChild = internal.forkChild;
  * Forks the effect in the specified scope. The fiber will be interrupted
  * when the scope is closed.
  *
- * **Example** (Usage)
+ * **Example** (Forking into a supplied scope)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -5884,7 +5797,7 @@ export const forkIn = internal.forkIn;
 /**
  * Forks the fiber in a `Scope`, interrupting it when the scope is closed.
  *
- * **Example** (Usage)
+ * **Example** (Forking into the current scope)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -5920,7 +5833,7 @@ 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** (Usage)
+ * **Example** (Forking a detached fiber)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -5946,7 +5859,7 @@ export const forkScoped = internal.forkScoped;
  * ```
  *
  * @category Supervision & Fibers
- * @since 2.0.0
+ * @since 4.0.0
  */
 export const forkDetach = internal.forkDetach;
 /**
@@ -5960,7 +5873,7 @@ export const awaitAllChildren = internal.awaitAllChildren;
 /**
  * Access the fiber currently executing the effect.
  *
- * **Example** (Usage)
+ * **Example** (Accessing the current fiber)
  *
  * ```ts
  * import { Console, Effect } from "effect"
@@ -5978,7 +5891,7 @@ export const fiber = internal.fiber;
 /**
  * Access the current fiber id executing the effect.
  *
- * **Example** (Usage)
+ * **Example** (Accessing the current fiber id)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -5995,7 +5908,7 @@ export const fiber = internal.fiber;
  * ```
  *
  * @category Supervision & Fibers
- * @since 4.0.0
+ * @since 2.0.0
  */
 export const fiberId = internal.fiberId;
 /**
@@ -6011,13 +5924,10 @@ export const fiberId = internal.fiberId;
  * Unless you specifically need a `Promise` or synchronous operation,
  * `runFork` is a good default choice.
  *
- * **Example** (Running an Effect in the Background)
+ * **Example** (Running an effect in the background)
  *
  * ```ts
- * 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>
  * //      ▼
@@ -6042,10 +5952,10 @@ export const runFork = internal.runFork;
 /**
  * Runs an effect in the background with the provided services.
  *
- * **Example** (Usage)
+ * **Example** (Running with services in the background)
  *
  * ```ts
- * import { Effect, Context } from "effect"
+ * import { Context, Effect } from "effect"
  *
  * interface Logger {
  *   log: (message: string) => void
@@ -6075,10 +5985,10 @@ export const runForkWith = internal.runForkWith;
  *
  * The returned interruptor calls `fiber.interruptUnsafe`, optionally with an interruptor id.
  *
- * **Example** (Usage)
+ * **Example** (Running with services and a callback)
  *
  * ```ts
- * import { Console, Effect, Exit, Context } from "effect"
+ * import { Console, Context, Effect, Exit } from "effect"
  *
  * interface Logger {
  *   log: (message: string) => Effect.Effect<void>
@@ -6119,7 +6029,7 @@ export const runCallbackWith = internal.runCallbackWith;
  * The interruptor calls `fiber.interruptUnsafe` with the optional interruptor
  * id.
  *
- * **Example** (Usage)
+ * **Example** (Running with a callback)
  *
  * ```ts
  * import { Console, Effect, Exit } from "effect"
@@ -6148,7 +6058,7 @@ export const runCallbackWith = internal.runCallbackWith;
  * ```
  *
  * @category Running Effects
- * @since 4.0.0
+ * @since 2.0.0
  */
 export const runCallback = internal.runCallback;
 /**
@@ -6165,7 +6075,7 @@ export const runCallback = internal.runCallback;
  *
  * @see {@link runPromiseExit} for a version that returns an `Exit` type instead of rejecting.
  *
- * **Example** (Running a Successful Effect as a Promise)
+ * **Example** (Running a successful effect as a Promise)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -6174,7 +6084,7 @@ export const runCallback = internal.runCallback;
  * // Output: 1
  * ```
  *
- * **Example** (Usage)
+ * **Example** (Running effects as promises)
  *
  * ```ts
  * //Example: Handling a Failing Effect as a Rejected Promise
@@ -6192,10 +6102,10 @@ export const runPromise = internal.runPromise;
 /**
  * Executes an effect as a Promise with the provided services.
  *
- * **Example** (Usage)
+ * **Example** (Running with services as a promise)
  *
  * ```ts
- * import { Effect, Context } from "effect"
+ * import { Context, Effect } from "effect"
  *
  * interface Config {
  *   apiUrl: string
@@ -6235,7 +6145,7 @@ export const runPromiseWith = internal.runPromiseWith;
  * - If it fails, the failure information is provided as a `Failure` containing
  *   a `Cause` type.
  *
- * **Example** (Handling Results as Exit)
+ * **Example** (Observing promise results as Exit)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -6270,10 +6180,10 @@ export const runPromiseExit = internal.runPromiseExit;
 /**
  * Runs an effect and returns a Promise of Exit with provided services.
  *
- * **Example** (Usage)
+ * **Example** (Running with services as an Exit promise)
  *
  * ```ts
- * import { Effect, Exit, Context } from "effect"
+ * import { Context, Effect, Exit } from "effect"
  *
  * interface Database {
  *   query: (sql: string) => string
@@ -6317,7 +6227,7 @@ export const runPromiseExitWith = internal.runPromiseExitWith;
  * @see {@link runSyncExit} for a version that returns an `Exit` type instead of
  * throwing an error.
  *
- * **Example** (Synchronous Logging)
+ * **Example** (Running a synchronous effect)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -6334,7 +6244,7 @@ export const runPromiseExitWith = internal.runPromiseExitWith;
  * // Output: 1
  * ```
  *
- * **Example** (Incorrect Usage with Failing or Async Effects)
+ * **Example** (Throwing for failed or async effects)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -6365,10 +6275,10 @@ export const runSync = internal.runSync;
 /**
  * Executes an effect synchronously with provided services.
  *
- * **Example** (Usage)
+ * **Example** (Running synchronously with services)
  *
  * ```ts
- * import { Effect, Context } from "effect"
+ * import { Context, Effect } from "effect"
  *
  * interface MathService {
  *   add: (a: number, b: number) => number
@@ -6413,7 +6323,7 @@ export const runSyncWith = internal.runSyncWith;
  * return an `Failure` with a `Die` cause, indicating that the effect cannot be
  * resolved synchronously.
  *
- * **Example** (Handling Results as Exit)
+ * **Example** (Observing synchronous results as Exit)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -6439,7 +6349,7 @@ export const runSyncWith = internal.runSyncWith;
  * // }
  * ```
  *
- * **Example** (Asynchronous Operation Resulting in Die)
+ * **Example** (Capturing async work as a Die cause)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -6468,10 +6378,10 @@ export const runSyncExit = internal.runSyncExit;
 /**
  * Runs an effect synchronously with provided services, returning an Exit result.
  *
- * **Example** (Usage)
+ * **Example** (Running synchronously with services as Exit)
  *
  * ```ts
- * import { Effect, Exit, Context } from "effect"
+ * import { Context, Effect, Exit } from "effect"
  *
  * // Define a logger service
  * const Logger = Context.Service<{
@@ -6510,7 +6420,7 @@ export const runSyncExitWith = internal.runSyncExitWith;
  *
  * `Effect.fnUntraced` also acts as a `pipe` function, so you can append transforms after the body.
  *
- * **Example** (Usage)
+ * **Example** (Defining untraced effect functions)
  *
  * ```ts
  * import { Console, Effect } from "effect"
@@ -6532,7 +6442,7 @@ export const fnUntraced = internal.fnUntraced;
  *
  * Pipeable functions run after the body and can transform the resulting Effect.
  *
- * **Example** (Usage)
+ * **Example** (Defining traced effect functions)
  *
  * ```ts
  * import { Console, Effect } from "effect"
@@ -6553,7 +6463,7 @@ export const fnUntraced = internal.fnUntraced;
  * ```
  *
  * @category Function
- * @since 3.12.0
+ * @since 3.11.0
  */
 export const fn = internal.fn;
 // ========================================================================
@@ -6563,7 +6473,7 @@ export const fn = internal.fn;
  * Retrieves the `Clock` service from the context and provides it to the
  * specified effectful function.
  *
- * **Example** (Usage)
+ * **Example** (Accessing the Clock service)
  *
  * ```ts
  * import { Console, Effect } from "effect"
@@ -6593,7 +6503,7 @@ 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** (Usage)
+ * **Example** (Logging at a dynamic level)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -6605,14 +6515,14 @@ export const clockWith = internal.clockWith;
  * })
  * ```
  *
- * @category Logging
+ * @category logging
  * @since 2.0.0
  */
 export const logWithLevel = internal.logWithLevel;
 /**
  * Logs one or more messages using the default log level.
  *
- * **Example** (Usage)
+ * **Example** (Logging at the default level)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -6633,14 +6543,14 @@ export const logWithLevel = internal.logWithLevel;
  * // 4
  * ```
  *
- * @category Logging
+ * @category logging
  * @since 2.0.0
  */
 export const log = /*#__PURE__*/internal.logWithLevel();
 /**
  * Logs one or more messages at the FATAL level.
  *
- * **Example** (Usage)
+ * **Example** (Logging fatal messages)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -6662,14 +6572,14 @@ export const log = /*#__PURE__*/internal.logWithLevel();
  * // timestamp=2023-... level=FATAL message="System shutting down"
  * ```
  *
- * @category Logging
+ * @category logging
  * @since 2.0.0
  */
 export const logFatal = /*#__PURE__*/internal.logWithLevel("Fatal");
 /**
  * Logs one or more messages at the WARNING level.
  *
- * **Example** (Usage)
+ * **Example** (Logging warnings)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -6692,14 +6602,14 @@ export const logFatal = /*#__PURE__*/internal.logWithLevel("Fatal");
  * // timestamp=2023-... level=WARN message="Using deprecated API endpoint"
  * ```
  *
- * @category Logging
+ * @category logging
  * @since 2.0.0
  */
 export const logWarning = /*#__PURE__*/internal.logWithLevel("Warn");
 /**
  * Logs one or more messages at the ERROR level.
  *
- * **Example** (Usage)
+ * **Example** (Logging errors)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -6725,14 +6635,14 @@ export const logWarning = /*#__PURE__*/internal.logWithLevel("Warn");
  * // timestamp=2023-... level=ERROR message="Caught error: Something went wrong"
  * ```
  *
- * @category Logging
+ * @category logging
  * @since 2.0.0
  */
 export const logError = /*#__PURE__*/internal.logWithLevel("Error");
 /**
  * Logs one or more messages at the INFO level.
  *
- * **Example** (Usage)
+ * **Example** (Logging information)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -6753,14 +6663,14 @@ export const logError = /*#__PURE__*/internal.logWithLevel("Error");
  * // timestamp=2023-... level=INFO message="Application version: 1.2.3"
  * ```
  *
- * @category Logging
+ * @category logging
  * @since 2.0.0
  */
 export const logInfo = /*#__PURE__*/internal.logWithLevel("Info");
 /**
  * Logs one or more messages at the DEBUG level.
  *
- * **Example** (Usage)
+ * **Example** (Logging debug messages)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -6782,14 +6692,14 @@ export const logInfo = /*#__PURE__*/internal.logWithLevel("Info");
  * // timestamp=2023-... level=DEBUG message="Variable state: x=10 y=20 z=30"
  * ```
  *
- * @category Logging
+ * @category logging
  * @since 2.0.0
  */
 export const logDebug = /*#__PURE__*/internal.logWithLevel("Debug");
 /**
  * Logs one or more messages at the TRACE level.
  *
- * **Example** (Usage)
+ * **Example** (Logging trace messages)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -6814,14 +6724,14 @@ export const logDebug = /*#__PURE__*/internal.logWithLevel("Debug");
  * // timestamp=2023-... level=TRACE message="Exiting function processData"
  * ```
  *
- * @category Logging
+ * @category logging
  * @since 2.0.0
  */
 export const logTrace = /*#__PURE__*/internal.logWithLevel("Trace");
 /**
  * Adds a logger to the set of loggers which will output logs for this effect.
  *
- * **Example** (Usage)
+ * **Example** (Adding a logger to an effect)
  *
  * ```ts
  * import { Effect, Logger } from "effect"
@@ -6843,14 +6753,14 @@ export const logTrace = /*#__PURE__*/internal.logWithLevel("Trace");
  * // Output includes both default and custom log outputs
  * ```
  *
- * @category Logging
- * @since 2.0.0
+ * @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** (Usage)
+ * **Example** (Adding log annotations)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -6874,7 +6784,7 @@ export const withLogger = /*#__PURE__*/dual(2, (effect, logger) => internal.upda
  * // All log messages will include the userId and operation annotations
  * ```
  *
- * @category Logging
+ * @category logging
  * @since 2.0.0
  */
 export const annotateLogs = /*#__PURE__*/dual(args => isEffect(args[0]), (effect, ...args) => internal.updateService(effect, CurrentLogAnnotations, annotations => {
@@ -6895,7 +6805,7 @@ 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** (Usage)
+ * **Example** (Adding scoped log annotations)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -6911,14 +6821,14 @@ export const annotateLogs = /*#__PURE__*/dual(args => isEffect(args[0]), (effect
  * Effect.runPromise(program)
  * ```
  *
- * @category Logging
- * @since 4.0.0
+ * @category logging
+ * @since 3.1.0
  */
 export const annotateLogsScoped = internal.annotateLogsScoped;
 /**
  * Adds a span to each log line in this effect.
  *
- * **Example** (Usage)
+ * **Example** (Adding a log span)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -6943,7 +6853,7 @@ export const annotateLogsScoped = internal.annotateLogsScoped;
  * // All log messages will include span information showing the nested operation context
  * ```
  *
- * @category Logging
+ * @category logging
  * @since 2.0.0
  */
 export const withLogSpan = /*#__PURE__*/dual(2, (effect, label) => internal.flatMap(internal.currentTimeMillis, now => internal.updateService(effect, CurrentLogSpans, spans => {
@@ -6959,7 +6869,7 @@ 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** (Usage)
+ * **Example** (Incrementing a metric for each execution)
  *
  * ```ts
  * import { Effect, Metric } from "effect"
@@ -6979,7 +6889,7 @@ export const withLogSpan = /*#__PURE__*/dual(2, (effect, label) => internal.flat
  * )
  * ```
  *
- * **Example** (Usage)
+ * **Example** (Mapping exits before updating a metric)
  *
  * ```ts
  * import { Effect, Exit, Metric } from "effect"
@@ -7014,7 +6924,7 @@ 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** (Usage)
+ * **Example** (Counting successful results)
  *
  * ```ts
  * import { Effect, Metric } from "effect"
@@ -7033,7 +6943,7 @@ export const track = /*#__PURE__*/dual(args => isEffect(args[0]), (self, metric,
  * )
  * ```
  *
- * **Example** (Usage)
+ * **Example** (Mapping successes before tracking)
  *
  * ```ts
  * import { Effect, Metric } from "effect"
@@ -7065,7 +6975,7 @@ 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** (Usage)
+ * **Example** (Counting expected failures)
  *
  * ```ts
  * import { Effect, Metric } from "effect"
@@ -7084,7 +6994,7 @@ export const trackSuccesses = /*#__PURE__*/dual(args => isEffect(args[0]), (self
  * )
  * ```
  *
- * **Example** (Usage)
+ * **Example** (Mapping errors before tracking)
  *
  * ```ts
  * import { Data, Effect, Metric } from "effect"
@@ -7118,7 +7028,7 @@ 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** (Usage)
+ * **Example** (Counting defects)
  *
  * ```ts
  * import { Effect, Metric } from "effect"
@@ -7137,7 +7047,7 @@ export const trackErrors = /*#__PURE__*/dual(args => isEffect(args[0]), (self, m
  * )
  * ```
  *
- * **Example** (Usage)
+ * **Example** (Mapping defects before tracking)
  *
  * ```ts
  * import { Effect, Metric } from "effect"
@@ -7173,7 +7083,7 @@ 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** (Usage)
+ * **Example** (Recording execution duration)
  *
  * ```ts
  * import { Effect, Metric } from "effect"
@@ -7190,7 +7100,7 @@ export const trackDefects = /*#__PURE__*/dual(args => isEffect(args[0]), (self,
  * )
  * ```
  *
- * **Example** (Usage)
+ * **Example** (Mapping duration before tracking)
  *
  * ```ts
  * import { Duration, Effect, Metric } from "effect"
@@ -7229,7 +7139,7 @@ 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** (Usage)
+ * **Example** (Building transactions)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -7264,7 +7174,7 @@ 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** (Usage)
+ * **Example** (Running a transaction)
  *
  * ```ts
  * import { Effect, TxRef } from "effect"
@@ -7373,7 +7283,7 @@ function clearTransaction(state) {
  * @category Transactions
  * @since 4.0.0
  *
- * **Example** (Usage)
+ * **Example** (Retrying transactions)
  *
  * ```ts
  * import { Effect, TxRef } from "effect"
@@ -7418,7 +7328,7 @@ export const txRetry = /*#__PURE__*/flatMap(Transaction, state => {
  * callback errors and `onSyncError` to turn synchronous throws into typed
  * failures; otherwise synchronous throws become defects.
  *
- * **Example** (Basic Usage)
+ * **Example** (Converting callbacks to effects)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -7434,7 +7344,7 @@ export const txRetry = /*#__PURE__*/flatMap(Transaction, state => {
  * // Output: contents of package.json
  * ```
  *
- * **Example** (Custom Error Handling)
+ * **Example** (Mapping callback errors to typed failures)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -7476,7 +7386,7 @@ 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** (Usage)
+ * **Example** (Constraining the success type)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -7503,7 +7413,7 @@ 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** (Usage)
+ * **Example** (Constraining the error type)
  *
  * ```ts
  * import { Data, Effect } from "effect"
@@ -7532,7 +7442,7 @@ 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** (Usage)
+ * **Example** (Constraining the services type)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -7569,7 +7479,7 @@ 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** (Usage)
+ * **Example** (Mapping already completed effects)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -7603,7 +7513,7 @@ 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** (Usage)
+ * **Example** (Mapping errors eagerly when possible)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -7640,7 +7550,7 @@ 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** (Usage)
+ * **Example** (Mapping both channels eagerly when possible)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -7679,7 +7589,7 @@ 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** (Usage)
+ * **Example** (Flat mapping eagerly when possible)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -7716,7 +7626,7 @@ 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** (Usage)
+ * **Example** (Catching failures eagerly when possible)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -7753,7 +7663,7 @@ 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** (Usage)
+ * **Example** (Defining eager untraced effect functions)
  *
  * ```ts
  * import { Effect } from "effect"