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

package/src/Cause.ts

@@ -32,7 +32,7 @@
  *
  * ## Gotchas
  *
- * - `findError`/`findDefect` return `Filter.fail` (not `Option.none`) when no match is
+ * - `findError`/`findDefect` return `Result.fail` (not `Option.none`) when no match is
  *   found. Use {@link findErrorOption} if you need an `Option`.
  * - `squash` picks the first `Fail` error, then the first `Die` defect, then falls back
  *   to a generic "interrupted" / "empty" error. It is lossy — use `prettyErrors` or
@@ -59,22 +59,20 @@
  *   const errors = cause.reasons
  *     .filter(Cause.isFailReason)
  *     .map((r) => r.error)
+ *     .sort()
  *
  *   const defects = cause.reasons
  *     .filter(Cause.isDieReason)
- *     .map((r) => r.defect)
+ *     .map((r) => String(r.defect))
+ *     .sort()
  *
- *   console.log(errors)  // ["err1", "err2"]  (order may vary)
- *   console.log(defects) // ["defect"]
+ *   console.log(errors.join(",")) // "err1,err2"
+ *   console.log(defects.join(",")) // "defect"
  * })
  *
  * Effect.runPromise(program)
  * ```
  *
- * @see {@link Cause} — the core interface
- * @see {@link Reason} — the union of failure kinds
- * @see {@link pretty} — human-readable rendering
- *
  * @since 2.0.0
  */
 import * as Context from "./Context.ts"
@@ -93,7 +91,7 @@ import type * as Types from "./Types.ts"
 /**
  * Unique brand for `Cause` values, used for runtime type checks via {@link isCause}.
  *
- * @category symbols
+ * @category type IDs
  * @since 4.0.0
  */
 export const TypeId: "~effect/Cause" = core.CauseTypeId
@@ -101,7 +99,7 @@ export const TypeId: "~effect/Cause" = core.CauseTypeId
 /**
  * Unique brand for `Reason` values, used for runtime type checks via {@link isReason}.
  *
- * @category symbols
+ * @category type IDs
  * @since 4.0.0
  */
 export const ReasonTypeId: "~effect/Cause/Reason" = core.CauseReasonTypeId
@@ -109,6 +107,11 @@ export const ReasonTypeId: "~effect/Cause/Reason" = core.CauseReasonTypeId
 /**
  * A structured representation of how an Effect failed.
  *
+ * **When to use**
+ *
+ * Use to preserve the full structured failure information for an effect instead
+ * of collapsing it to a single error value.
+ *
  * **Details**
  *
  * Access the individual failure entries through the `reasons` array, then
@@ -134,8 +137,6 @@ export const ReasonTypeId: "~effect/Cause/Reason" = core.CauseReasonTypeId
  * console.log(Cause.isFailReason(cause.reasons[0])) // true
  * ```
  *
- * @see {@link Reason} — the union type stored in `reasons`
- *
  * @category models
  * @since 2.0.0
  */
@@ -145,7 +146,7 @@ export interface Cause<out E> extends Pipeable, Inspectable, Equal {
 }
 
 /**
- * Tests if an arbitrary value is a {@link Cause}.
+ * Checks whether an arbitrary value is a `Cause`.
  *
  * **Example** (runtime type check)
  *
@@ -162,7 +163,7 @@ export interface Cause<out E> extends Pipeable, Inspectable, Equal {
 export const isCause: (self: unknown) => self is Cause<unknown> = core.isCause
 
 /**
- * Tests if an arbitrary value is a {@link Reason} (`Fail`, `Die`, or `Interrupt`).
+ * Checks whether an arbitrary value is a `Reason` (`Fail`, `Die`, or `Interrupt`).
  *
  * **Example** (runtime type check)
  *
@@ -180,7 +181,7 @@ export const isCause: (self: unknown) => self is Cause<unknown> = core.isCause
 export const isReason: (self: unknown) => self is Reason<unknown> = core.isCauseReason
 
 /**
- * A single entry inside a {@link Cause}'s `reasons` array.
+ * A single entry inside a `Cause`'s `reasons` array.
  *
  * **Details**
  *
@@ -205,21 +206,18 @@ export const isReason: (self: unknown) => self is Reason<unknown> = core.isCause
  * }
  * ```
  *
- * @see {@link Fail} — typed error reason
- * @see {@link Die} — untyped defect reason
- * @see {@link Interrupt} — interruption reason
- *
  * @category models
  * @since 4.0.0
  */
 export type Reason<E> = Fail<E> | Die | Interrupt
 
 /**
- * Narrows a {@link Reason} to {@link Fail}.
+ * Narrows a `Reason` to `Fail`.
  *
  * **When to use**
  *
- * Useful as a predicate for `Array.filter` when iterating over `cause.reasons`.
+ * Use as a predicate for `Array.filter` to pick out typed `Fail` reasons when
+ * iterating over `cause.reasons`.
  *
  * **Example** (filtering fail reasons)
  *
@@ -240,11 +238,12 @@ export type Reason<E> = Fail<E> | Die | Interrupt
 export const isFailReason: <E>(self: Reason<E>) => self is Fail<E> = core.isFailReason
 
 /**
- * Narrows a {@link Reason} to {@link Die}.
+ * Narrows a `Reason` to `Die`.
  *
  * **When to use**
  *
- * Useful as a predicate for `Array.filter` when iterating over `cause.reasons`.
+ * Use as a predicate for `Array.filter` to pick out `Die` (defect) reasons when
+ * iterating over `cause.reasons`.
  *
  * **Example** (filtering die reasons)
  *
@@ -265,11 +264,12 @@ export const isFailReason: <E>(self: Reason<E>) => self is Fail<E> = core.isFail
 export const isDieReason: <E>(self: Reason<E>) => self is Die = core.isDieReason
 
 /**
- * Narrows a {@link Reason} to {@link Interrupt}.
+ * Narrows a `Reason` to `Interrupt`.
  *
  * **When to use**
  *
- * Useful as a predicate for `Array.filter` when iterating over `cause.reasons`.
+ * Use as a predicate for `Array.filter` to pick out `Interrupt` reasons when
+ * iterating over `cause.reasons`.
  *
  * **Example** (filtering interrupt reasons)
  *
@@ -290,7 +290,7 @@ export const isDieReason: <E>(self: Reason<E>) => self is Die = core.isDieReason
 export const isInterruptReason: <E>(self: Reason<E>) => self is Interrupt = core.isInterruptReason
 
 /**
- * Companion namespace for the {@link Cause} interface.
+ * Companion namespace for the `Cause` interface.
  *
  * @since 2.0.0
  */
@@ -313,8 +313,7 @@ export declare namespace Cause {
   export type Error<T> = T extends Cause<infer E> ? E : never
 
   /**
-   * Base interface shared by all reason types ({@link Fail}, {@link Die},
-   * {@link Interrupt}).
+   * Base interface shared by all reason types (`Fail`, `Die`, `Interrupt`).
    *
    * **Details**
    *
@@ -337,7 +336,7 @@ export declare namespace Cause {
 }
 
 /**
- * Companion namespace for the {@link Reason} type.
+ * Companion namespace for the `Reason` type.
  *
  * @since 4.0.0
  */
@@ -363,10 +362,15 @@ export declare namespace Reason {
 /**
  * An untyped defect — typically a programming error or an uncaught exception.
  *
+ * **When to use**
+ *
+ * Use when inspecting `Cause` reasons that represent defects instead of typed
+ * failures or interruptions.
+ *
  * **Details**
  *
  * The `defect` property is `unknown` because defects are not part of the
- * typed error channel. Use {@link isDieReason} to narrow a {@link Reason}
+ * typed error channel. Use {@link isDieReason} to narrow a `Reason`
  * to this type.
  *
  * **Example** (accessing the defect)
@@ -374,15 +378,15 @@ export declare namespace Reason {
  * ```ts
  * import { Cause } from "effect"
  *
- * const cause = Cause.die(new Error("Unexpected"))
+ * const cause = Cause.die("Unexpected")
  * const reason = cause.reasons[0]
  * if (Cause.isDieReason(reason)) {
- *   console.log(reason.defect) // Error: Unexpected
+ *   console.log(reason.defect) // "Unexpected"
  * }
  * ```
  *
- * @see {@link die} — create a `Cause` containing a single `Die`
- * @see {@link isDieReason} — type guard
+ * @see {@link die} for constructing a cause with a single `Die` reason
+ * @see {@link isDieReason} for narrowing a `Reason` to `Die`
  *
  * @category models
  * @since 2.0.0
@@ -394,10 +398,15 @@ export interface Die extends Cause.ReasonProto<"Die"> {
 /**
  * A typed, expected error produced by `Effect.fail`.
  *
+ * **When to use**
+ *
+ * Use when inspecting `Cause` reasons that represent expected failures from the
+ * typed error channel.
+ *
  * **Details**
  *
  * The `error` property carries the typed value `E`. Use {@link isFailReason}
- * to narrow a {@link Reason} to this type.
+ * to narrow a `Reason` to this type.
  *
  * **Example** (accessing the error)
  *
@@ -411,8 +420,8 @@ export interface Die extends Cause.ReasonProto<"Die"> {
  * }
  * ```
  *
- * @see {@link fail} — create a `Cause` containing a single `Fail`
- * @see {@link isFailReason} — type guard
+ * @see {@link fail} for constructing a cause with a single `Fail` reason
+ * @see {@link isFailReason} for narrowing a `Reason` to `Fail`
  *
  * @category models
  * @since 2.0.0
@@ -427,7 +436,7 @@ export interface Fail<out E> extends Cause.ReasonProto<"Fail"> {
  *
  * **Details**
  *
- * Use {@link isInterruptReason} to narrow a {@link Reason} to this type.
+ * Use {@link isInterruptReason} to narrow a `Reason` to this type.
  *
  * **Example** (accessing the fiber ID)
  *
@@ -441,9 +450,6 @@ export interface Fail<out E> extends Cause.ReasonProto<"Fail"> {
  * }
  * ```
  *
- * @see {@link interrupt} — create a `Cause` containing a single `Interrupt`
- * @see {@link isInterruptReason} — type guard
- *
  * @category models
  * @since 2.0.0
  */
@@ -452,18 +458,23 @@ export interface Interrupt extends Cause.ReasonProto<"Interrupt"> {
 }
 
 /**
- * Creates a {@link Cause} from an array of {@link Reason} values.
+ * Creates a `Cause` from an array of `Reason` values.
  *
  * **When to use**
  *
- * Use this when you already have individual reasons (e.g. from filtering or
+ * Use when you already have individual reasons (e.g. from filtering or
  * transforming another cause's `reasons` array) and need to wrap them back
  * into a `Cause`.
  *
  * **Details**
  *
- * - Returns a new `Cause`; does not mutate the input array.
- * - An empty array produces a cause equivalent to {@link empty}.
+ * - Returns a new `Cause`.
+ * - An empty array produces a cause equivalent to `empty`.
+ *
+ * **Gotchas**
+ *
+ * The `reasons` array is stored as provided. Treat the array as immutable
+ * after passing it to this function.
  *
  * **Example** (building a cause from reasons)
  *
@@ -488,14 +499,30 @@ export const fromReasons: <E>(
 ) => Cause<E> = core.causeFromReasons
 
 /**
- * A {@link Cause} with an empty `reasons` array.
+ * Represents a `Cause` with an empty `reasons` array.
+ *
+ * **When to use**
+ *
+ * Use to represent the absence of failure when constructing or combining
+ * causes.
  *
  * **Details**
  *
  * Represents the absence of failure. Combining any cause with `empty` via
  * {@link combine} returns the original cause unchanged.
  *
- * @see {@link combine}
+ * **Example** (combining with the empty cause)
+ *
+ * ```ts
+ * import { Cause } from "effect"
+ *
+ * const cause = Cause.combine(Cause.empty, Cause.fail("boom"))
+ *
+ * console.log(cause.reasons.length) // 1
+ * console.log(Cause.hasFails(cause)) // true
+ * ```
+ *
+ * @see {@link combine} for merging causes where `empty` acts as the identity
  *
  * @category constructors
  * @since 2.0.0
@@ -503,9 +530,13 @@ export const fromReasons: <E>(
 export const empty: Cause<never> = core.causeEmpty
 
 /**
- * Creates a {@link Cause} containing a single {@link Fail} reason with the
+ * Creates a `Cause` containing a single `Fail` reason with the
  * given typed error.
  *
+ * **When to use**
+ *
+ * Use to construct a cause from an expected typed error.
+ *
  * **Example** (creating a fail cause)
  *
  * ```ts
@@ -525,15 +556,19 @@ export const empty: Cause<never> = core.causeEmpty
 export const fail: <E>(error: E) => Cause<E> = core.causeFail
 
 /**
- * Creates a {@link Cause} containing a single {@link Die} reason with the
+ * Creates a `Cause` containing a single `Die` reason with the
  * given defect.
  *
+ * **When to use**
+ *
+ * Use to construct a cause from an untyped defect or unexpected thrown value.
+ *
  * **Example** (creating a die cause)
  *
  * ```ts
  * import { Cause } from "effect"
  *
- * const cause = Cause.die(new Error("Unexpected"))
+ * const cause = Cause.die("Unexpected")
  * console.log(cause.reasons.length) // 1
  * console.log(Cause.isDieReason(cause.reasons[0])) // true
  * ```
@@ -547,7 +582,7 @@ export const fail: <E>(error: E) => Cause<E> = core.causeFail
 export const die: (defect: unknown) => Cause<never> = core.causeDie
 
 /**
- * Creates a {@link Cause} containing a single {@link Interrupt} reason,
+ * Creates a `Cause` containing a single `Interrupt` reason,
  * optionally carrying the interrupting fiber's ID.
  *
  * **Example** (creating an interrupt cause)
@@ -569,12 +604,12 @@ export const die: (defect: unknown) => Cause<never> = core.causeDie
 export const interrupt: (fiberId?: number | undefined) => Cause<never> = effect.causeInterrupt
 
 /**
- * Creates a standalone {@link Fail} reason (not wrapped in a {@link Cause}).
+ * Creates a standalone `Fail` reason (not wrapped in a `Cause`).
  *
  * **When to use**
  *
- * Use this when you need to construct individual reasons for
- * {@link fromReasons} or for direct comparison.
+ * Use when constructing a standalone typed failure reason for
+ * {@link fromReasons} or direct comparison.
  *
  * **Example** (creating a Fail reason)
  *
@@ -595,15 +630,21 @@ export const interrupt: (fiberId?: number | undefined) => Cause<never> = effect.
 export const makeFailReason = <E>(error: E): Fail<E> => new core.Fail(error)
 
 /**
- * Creates a standalone {@link Die} reason (not wrapped in a {@link Cause}).
+ * Creates a standalone `Die` reason (not wrapped in a `Cause`).
+ *
+ * **When to use**
+ *
+ * Use when constructing a standalone defect reason for {@link fromReasons} or
+ * direct comparison.
  *
  * **Example** (creating a Die reason)
  *
  * ```ts
  * import { Cause } from "effect"
  *
- * const reason = Cause.makeDieReason(new Error("bug"))
+ * const reason = Cause.makeDieReason("bug")
  * console.log(reason._tag) // "Die"
+ * console.log(reason.defect) // "bug"
  * ```
  *
  * @see {@link makeFailReason} — create a `Fail` reason
@@ -615,9 +656,14 @@ export const makeFailReason = <E>(error: E): Fail<E> => new core.Fail(error)
 export const makeDieReason = (defect: unknown): Die => new core.Die(defect)
 
 /**
- * Creates a standalone {@link Interrupt} reason (not wrapped in a {@link Cause}),
+ * Creates a standalone `Interrupt` reason (not wrapped in a `Cause`),
  * optionally carrying the interrupting fiber's ID.
  *
+ * **When to use**
+ *
+ * Use when constructing a standalone interrupt reason for {@link fromReasons}
+ * or direct comparison.
+ *
  * **Example** (creating an Interrupt reason)
  *
  * ```ts
@@ -637,12 +683,12 @@ export const makeDieReason = (defect: unknown): Die => new core.Die(defect)
 export const makeInterruptReason: (fiberId?: number | undefined) => Interrupt = effect.makeInterruptReason
 
 /**
- * Returns `true` if every reason in the cause is an {@link Interrupt} (and
+ * Returns `true` if every reason in the cause is an `Interrupt` (and
  * there is at least one reason).
  *
  * **When to use**
  *
- * Useful for deciding whether a failure was entirely due to interruption and
+ * Use when deciding whether a failure was entirely due to interruption and
  * can be silently discarded.
  *
  * **Example** (checking interrupt-only causes)
@@ -663,13 +709,20 @@ export const makeInterruptReason: (fiberId?: number | undefined) => Interrupt =
 export const hasInterruptsOnly: <E>(self: Cause<E>) => boolean = effect.hasInterruptsOnly
 
 /**
- * Transforms the typed error values inside a {@link Cause} using the
- * provided function. Only {@link Fail} reasons are affected; {@link Die}
- * and {@link Interrupt} reasons pass through unchanged.
+ * Transforms the typed error values inside a `Cause` using the
+ * provided function. Only `Fail` reasons are affected; `Die` and `Interrupt`
+ * reasons pass through unchanged.
+ *
+ * **When to use**
+ *
+ * Use to transform expected typed failures while preserving defects and
+ * interruptions unchanged.
  *
  * **Details**
  *
- * Returns a new `Cause`; does not mutate the original.
+ * If at least one `Fail` reason exists, this returns a new `Cause`
+ * containing the mapped failures. If the cause has no `Fail` reasons, the
+ * original cause is returned unchanged.
  *
  * **Example** (mapping errors to uppercase)
  *
@@ -689,13 +742,20 @@ export const hasInterruptsOnly: <E>(self: Cause<E>) => boolean = effect.hasInter
  */
 export const map: {
   /**
-   * Transforms the typed error values inside a {@link Cause} using the
-   * provided function. Only {@link Fail} reasons are affected; {@link Die}
-   * and {@link Interrupt} reasons pass through unchanged.
+   * Transforms the typed error values inside a `Cause` using the
+   * provided function. Only `Fail` reasons are affected; `Die` and `Interrupt`
+   * reasons pass through unchanged.
+   *
+   * **When to use**
+   *
+   * Use to transform expected typed failures while preserving defects and
+   * interruptions unchanged.
    *
    * **Details**
    *
-   * Returns a new `Cause`; does not mutate the original.
+   * If at least one `Fail` reason exists, this returns a new `Cause`
+   * containing the mapped failures. If the cause has no `Fail` reasons, the
+   * original cause is returned unchanged.
    *
    * **Example** (mapping errors to uppercase)
    *
@@ -715,13 +775,20 @@ export const map: {
    */
   <E, E2>(f: (error: Types.NoInfer<E>) => E2): (self: Cause<E>) => Cause<E2>
   /**
-   * Transforms the typed error values inside a {@link Cause} using the
-   * provided function. Only {@link Fail} reasons are affected; {@link Die}
-   * and {@link Interrupt} reasons pass through unchanged.
+   * Transforms the typed error values inside a `Cause` using the
+   * provided function. Only `Fail` reasons are affected; `Die` and `Interrupt`
+   * reasons pass through unchanged.
+   *
+   * **When to use**
+   *
+   * Use to transform expected typed failures while preserving defects and
+   * interruptions unchanged.
    *
    * **Details**
    *
-   * Returns a new `Cause`; does not mutate the original.
+   * If at least one `Fail` reason exists, this returns a new `Cause`
+   * containing the mapped failures. If the cause has no `Fail` reasons, the
+   * original cause is returned unchanged.
    *
    * **Example** (mapping errors to uppercase)
    *
@@ -746,9 +813,13 @@ export const map: {
  * Merges two causes into a single cause whose `reasons` array is the union
  * of both inputs (de-duplicated by value equality).
  *
+ * **When to use**
+ *
+ * Use to merge independent causes into one structured failure value.
+ *
  * **Details**
  *
- * - Combining with {@link empty} returns the other cause unchanged.
+ * - Combining with `empty` returns the other cause unchanged.
  * - If the result is structurally equal to `self`, `self` is returned
  *   (referential shortcut).
  *
@@ -764,6 +835,7 @@ export const map: {
  * ```
  *
  * @see {@link fromReasons} — build a cause from an array of reasons
+ * @see {@link empty} for the identity cause used when combining
  *
  * @category combining
  * @since 4.0.0
@@ -773,9 +845,13 @@ export const combine: {
    * Merges two causes into a single cause whose `reasons` array is the union
    * of both inputs (de-duplicated by value equality).
    *
+   * **When to use**
+   *
+   * Use to merge independent causes into one structured failure value.
+   *
    * **Details**
    *
-   * - Combining with {@link empty} returns the other cause unchanged.
+   * - Combining with `empty` returns the other cause unchanged.
    * - If the result is structurally equal to `self`, `self` is returned
    *   (referential shortcut).
    *
@@ -791,6 +867,7 @@ export const combine: {
    * ```
    *
    * @see {@link fromReasons} — build a cause from an array of reasons
+   * @see {@link empty} for the identity cause used when combining
    *
    * @category combining
    * @since 4.0.0
@@ -800,9 +877,13 @@ export const combine: {
    * Merges two causes into a single cause whose `reasons` array is the union
    * of both inputs (de-duplicated by value equality).
    *
+   * **When to use**
+   *
+   * Use to merge independent causes into one structured failure value.
+   *
    * **Details**
    *
-   * - Combining with {@link empty} returns the other cause unchanged.
+   * - Combining with `empty` returns the other cause unchanged.
    * - If the result is structurally equal to `self`, `self` is returned
    *   (referential shortcut).
    *
@@ -818,6 +899,7 @@ export const combine: {
    * ```
    *
    * @see {@link fromReasons} — build a cause from an array of reasons
+   * @see {@link empty} for the identity cause used when combining
    *
    * @category combining
    * @since 4.0.0
@@ -826,15 +908,20 @@ export const combine: {
 } = effect.causeCombine
 
 /**
- * Collapses a {@link Cause} into a single `unknown` value, picking the "most
+ * Collapses a `Cause` into a single `unknown` value, picking the "most
  * important" failure in this order:
  *
+ * **When to use**
+ *
+ * Use to collapse a structured cause to the single value that synchronous and
+ * promise runners would throw.
+ *
  * **Details**
  *
- * 1. First {@link Fail} error (the `E` value)
- * 2. First {@link Die} defect
+ * 1. First `Fail` error (the `E` value)
+ * 2. First `Die` defect
  * 3. A generic `Error("All fibers interrupted without error")` for interrupt-only causes
- * 4. A generic `Error("Empty cause")` for {@link empty}
+ * 4. A generic `Error("Empty cause")` for `empty`
  *
  * This is the function used by `Effect.runPromise` and `Effect.runSync` to
  * decide what to throw.
@@ -862,7 +949,12 @@ export const combine: {
 export const squash: <E>(self: Cause<E>) => unknown = effect.causeSquash
 
 /**
- * Returns `true` if the cause contains at least one {@link Fail} reason.
+ * Returns `true` if the cause contains at least one `Fail` reason.
+ *
+ * **When to use**
+ *
+ * Use to check whether a cause includes typed failures before extracting,
+ * mapping, or rendering them.
  *
  * **Example** (checking for typed errors)
  *
@@ -882,14 +974,14 @@ export const squash: <E>(self: Cause<E>) => unknown = effect.causeSquash
 export const hasFails: <E>(self: Cause<E>) => boolean = effect.hasFails
 
 /**
- * Returns a `Result` whose success value is the first {@link Fail} reason in
+ * Returns a `Result` whose success value is the first `Fail` reason in
  * the cause, including its annotations. If the cause has no `Fail` reason, the
  * failure value is the original cause narrowed to `Cause<never>`, because it
  * contains no typed error reasons.
  *
  * **When to use**
  *
- * Use {@link findError} if you only need the unwrapped error value `E`.
+ * Use when you use {@link findError} if you only need the unwrapped error value `E`.
  *
  * **Example** (extracting the first Fail reason)
  *
@@ -905,20 +997,20 @@ export const hasFails: <E>(self: Cause<E>) => boolean = effect.hasFails
  * @see {@link findError} — extract the unwrapped `E` value
  * @see {@link findDie} — extract the first `Die` reason
  *
- * @category filters
+ * @category filtering
  * @since 4.0.0
  */
 export const findFail: <E>(self: Cause<E>) => Result.Result<Fail<E>, Cause<never>> = effect.findFail
 
 /**
  * Returns a `Result` whose success value is the first typed error value `E`
- * from a {@link Fail} reason in the cause. If the cause has no `Fail` reason,
+ * from a `Fail` reason in the cause. If the cause has no `Fail` reason,
  * the failure value is the original cause narrowed to `Cause<never>`, because
  * it contains no typed error reasons.
  *
  * **When to use**
  *
- * Use {@link findFail} if you need the full {@link Fail} reason (including
+ * Use when you use {@link findFail} if you need the full `Fail` reason (including
  * annotations). Use {@link findErrorOption} if you prefer an `Option`.
  *
  * **Example** (extracting the first error value)
@@ -935,18 +1027,18 @@ export const findFail: <E>(self: Cause<E>) => Result.Result<Fail<E>, Cause<never
  * @see {@link findFail} — extract the full `Fail` reason
  * @see {@link findErrorOption} — `Option`-based variant
  *
- * @category filters
+ * @category filtering
  * @since 4.0.0
  */
 export const findError: <E>(self: Cause<E>) => Result.Result<E, Cause<never>> = effect.findError
 
 /**
  * Returns the first typed error value `E` from a cause wrapped in
- * `Option.some`, or `Option.none` if no {@link Fail} reason exists.
+ * `Option.some`, or `Option.none` if no `Fail` reason exists.
  *
  * **When to use**
  *
- * This is the `Option`-returning variant of {@link findError} for code that
+ * Use when this is the `Option`-returning variant of {@link findError} for code that
  * does not need the original cause returned in a failed `Result`.
  *
  * **Example** (extracting an error as Option)
@@ -961,15 +1053,20 @@ export const findError: <E>(self: Cause<E>) => Result.Result<E, Cause<never>> =
  * console.log(Option.isNone(none)) // true
  * ```
  *
- * @see {@link findError} — `Filter`-based variant
+ * @see {@link findError} — `Result`-based variant
  *
- * @category filters
+ * @category filtering
  * @since 4.0.0
  */
 export const findErrorOption: <E>(input: Cause<E>) => Option<E> = effect.findErrorOption
 
 /**
- * Returns `true` if the cause contains at least one {@link Die} reason.
+ * Returns `true` if the cause contains at least one `Die` reason.
+ *
+ * **When to use**
+ *
+ * Use to check whether a cause includes defects before extracting or rendering
+ * them.
  *
  * **Example** (checking for defects)
  *
@@ -989,13 +1086,13 @@ export const findErrorOption: <E>(input: Cause<E>) => Option<E> = effect.findErr
 export const hasDies: <E>(self: Cause<E>) => boolean = effect.hasDies
 
 /**
- * Returns a `Result` whose success value is the first {@link Die} reason in
+ * Returns a `Result` whose success value is the first `Die` reason in
  * the cause, including its annotations. If the cause has no `Die` reason, the
  * failure value is the original cause.
  *
  * **When to use**
  *
- * Use {@link findDefect} if you only need the unwrapped defect value.
+ * Use when you use {@link findDefect} if you only need the unwrapped defect value.
  *
  * **Example** (extracting the first Die reason)
  *
@@ -1011,19 +1108,19 @@ export const hasDies: <E>(self: Cause<E>) => boolean = effect.hasDies
  * @see {@link findDefect} — extract the unwrapped defect value
  * @see {@link findFail} — extract the first `Fail` reason
  *
- * @category filters
+ * @category filtering
  * @since 4.0.0
  */
 export const findDie: <E>(self: Cause<E>) => Result.Result<Die, Cause<E>> = effect.findDie
 
 /**
  * Returns a `Result` whose success value is the first defect value from a
- * {@link Die} reason in the cause. If the cause has no `Die` reason, the
+ * `Die` reason in the cause. If the cause has no `Die` reason, the
  * failure value is the original cause.
  *
  * **When to use**
  *
- * Use {@link findDie} if you need the full `Die` reason (including
+ * Use when you use {@link findDie} if you need the full `Die` reason (including
  * annotations).
  *
  * **Example** (extracting the first defect)
@@ -1040,13 +1137,13 @@ export const findDie: <E>(self: Cause<E>) => Result.Result<Die, Cause<E>> = effe
  * @see {@link findDie} — extract the full `Die` reason
  * @see {@link findError} — extract the first typed error
  *
- * @category filters
+ * @category filtering
  * @since 4.0.0
  */
 export const findDefect: <E>(self: Cause<E>) => Result.Result<unknown, Cause<E>> = effect.findDefect
 
 /**
- * Returns `true` if the cause contains at least one {@link Interrupt} reason.
+ * Returns `true` if the cause contains at least one `Interrupt` reason.
  *
  * **Example** (checking for interruptions)
  *
@@ -1067,10 +1164,15 @@ export const findDefect: <E>(self: Cause<E>) => Result.Result<unknown, Cause<E>>
 export const hasInterrupts: <E>(self: Cause<E>) => boolean = effect.hasInterrupts
 
 /**
- * Returns a `Result` whose success value is the first {@link Interrupt} reason
+ * Returns a `Result` whose success value is the first `Interrupt` reason
  * in the cause, including its annotations. If the cause has no `Interrupt`
  * reason, the failure value is the original cause.
  *
+ * **When to use**
+ *
+ * Use to extract the first interruption reason when you need its fiber ID and
+ * annotations.
+ *
  * **Example** (extracting the first interrupt)
  *
  * ```ts
@@ -1084,19 +1186,19 @@ export const hasInterrupts: <E>(self: Cause<E>) => boolean = effect.hasInterrupt
  *
  * @see {@link interruptors} — collect all interrupting fiber IDs as a `Set`
  *
- * @category filters
+ * @category filtering
  * @since 4.0.0
  */
 export const findInterrupt: <E>(self: Cause<E>) => Result.Result<Interrupt, Cause<E>> = effect.findInterrupt
 
 /**
- * Collects the defined fiber IDs from all {@link Interrupt} reasons in the
+ * Collects the defined fiber IDs from all `Interrupt` reasons in the
  * cause into a `ReadonlySet`. Interrupt reasons without a `fiberId` are
  * ignored. Returns an empty set when the cause has no interrupting fiber IDs.
  *
  * **When to use**
  *
- * This always succeeds. Use {@link filterInterruptors} when you want a
+ * Use when this always succeeds. Use {@link filterInterruptors} when you want a
  * `Result` that fails with the original cause if there are no `Interrupt`
  * reasons.
  *
@@ -1109,10 +1211,11 @@ export const findInterrupt: <E>(self: Cause<E>) => Result.Result<Interrupt, Caus
  *   Cause.interrupt(1),
  *   Cause.interrupt(2)
  * )
- * console.log(Cause.interruptors(cause)) // Set { 1, 2 }
+ *
+ * console.log(Cause.interruptors(cause)) // Set(2) { 1, 2 }
  * ```
  *
- * @see {@link filterInterruptors} — `Filter`-based variant
+ * @see {@link filterInterruptors} — `Result`-based variant
  *
  * @category accessors
  * @since 2.0.0
@@ -1121,40 +1224,51 @@ export const interruptors: <E>(self: Cause<E>) => ReadonlySet<number> = effect.c
 
 /**
  * Returns a `Result` whose success value is the set of defined fiber IDs from
- * the cause's {@link Interrupt} reasons. If the cause has no `Interrupt`
+ * the cause's `Interrupt` reasons. If the cause has no `Interrupt`
  * reason, the failure value is the original cause.
  *
  * **When to use**
  *
- * Use {@link interruptors} if you always want a `Set` without `Result`
+ * Use when you use {@link interruptors} if you always want a `Set` without `Result`
  * wrapping.
  *
- * **Example** (extracting interruptors with Filter)
+ * **Gotchas**
+ *
+ * Interrupt reasons without a `fiberId` still count as interrupts, so the
+ * function succeeds with an empty `Set` when every interrupt reason has an
+ * undefined fiber ID.
+ *
+ * **Example** (extracting interruptors with Result)
  *
  * ```ts
  * import { Cause, Result } from "effect"
  *
  * const result = Cause.filterInterruptors(Cause.interrupt(1))
  * if (!Result.isFailure(result)) {
- *   console.log(result.success) // Set { 1 }
+ *   console.log(result.success) // Set(1) { 1 }
  * }
  * ```
  *
  * @see {@link interruptors} — always-succeeding variant
  *
- * @category filters
+ * @category filtering
  * @since 4.0.0
  */
 export const filterInterruptors: <E>(self: Cause<E>) => Result.Result<Set<number>, Cause<E>> =
   effect.causeFilterInterruptors
 
 /**
- * Converts a {@link Cause} into an `Array<Error>` suitable for logging or
+ * Converts a `Cause` into an `Array<Error>` suitable for logging or
  * rethrowing.
  *
+ * **When to use**
+ *
+ * Use to convert every renderable failure in a cause into individual `Error`
+ * values before logging or rethrowing.
+ *
  * **Details**
  *
- * Each {@link Fail} and {@link Die} reason is converted into a standard
+ * Each `Fail` and `Die` reason is converted into a standard
  * `Error`:
  *
  * - **Objects / Error instances** — `message`, `name`, `stack`, and `cause`
@@ -1164,10 +1278,12 @@ export const filterInterruptors: <E>(self: Cause<E>) => Result.Result<Set<number
  * - **Other primitives** (`null`, `undefined`, numbers, …) — wrapped in an
  *   `Error` with message `"Unknown error: <value>"`.
  *
- * {@link Interrupt} reasons are collected separately. If the cause contains
+ * `Interrupt` reasons are collected separately. If the cause contains
  * **only** interrupts (no `Fail` or `Die`), a single `InterruptError` is
  * returned whose `cause` lists the interrupting fiber IDs.
  *
+ * An empty cause returns an empty array.
+ *
  * **Example** (converting a cause to errors)
  *
  * ```ts
@@ -1187,8 +1303,12 @@ export const filterInterruptors: <E>(self: Cause<E>) => Result.Result<Set<number
 export const prettyErrors: <E>(self: Cause<E>) => Array<Error> = effect.causePrettyErrors
 
 /**
- * Renders a {@link Cause} as a human-readable string for logging or
- * debugging.
+ * Formats a `Cause` as a human-readable string for logging or debugging.
+ *
+ * **When to use**
+ *
+ * Use to render a whole cause as one human-readable string for logs or
+ * diagnostics.
  *
  * **Details**
  *
@@ -1207,15 +1327,18 @@ export const prettyErrors: <E>(self: Cause<E>) => Array<Error> = effect.causePre
  *
  * Span annotations are appended to the relevant stack frames when available.
  *
+ * **Gotchas**
+ *
+ * Rendering an empty cause produces an empty string because there are no
+ * errors to render.
+ *
  * **Example** (rendering a cause)
  *
  * ```ts
  * import { Cause } from "effect"
  *
- * const cause = Cause.fail("something went wrong")
- * console.log(Cause.pretty(cause))
- * // Error: something went wrong
- * //     at ...
+ * const rendered = Cause.pretty(Cause.fail("something went wrong"))
+ * console.log(rendered.includes("something went wrong")) // true
  * ```
  *
  * @see {@link prettyErrors} — get the individual `Error` instances
@@ -1232,10 +1355,9 @@ export const pretty: <E>(cause: Cause<E>) => string = effect.causePretty
  *
  * **Details**
  *
- * All built-in error classes in this module ({@link NoSuchElementError},
- * {@link TimeoutError}, {@link IllegalArgumentError},
- * {@link ExceededCapacityError}, {@link AsyncFiberError}, and
- * {@link UnknownError}) implement this interface.
+ * All built-in error classes in this module (`NoSuchElementError`,
+ * `TimeoutError`, `IllegalArgumentError`, `ExceededCapacityError`,
+ * `AsyncFiberError`, and `UnknownError`) implement this interface.
  *
  * **Example** (yielding an error in Effect.gen)
  *
@@ -1258,7 +1380,7 @@ export interface YieldableError extends Error, Pipeable, Inspectable {
 }
 
 /**
- * Tests if an arbitrary value is a {@link NoSuchElementError}.
+ * Checks whether an arbitrary value is a `NoSuchElementError`.
  *
  * **Example** (runtime type check)
  *
@@ -1275,9 +1397,9 @@ export interface YieldableError extends Error, Pipeable, Inspectable {
 export const isNoSuchElementError: (u: unknown) => u is NoSuchElementError = core.isNoSuchElementError
 
 /**
- * Unique brand for {@link NoSuchElementError}.
+ * Unique brand for `NoSuchElementError`.
  *
- * @category symbols
+ * @category type IDs
  * @since 4.0.0
  */
 export const NoSuchElementErrorTypeId: "~effect/Cause/NoSuchElementError" = core.NoSuchElementErrorTypeId
@@ -1285,16 +1407,21 @@ export const NoSuchElementErrorTypeId: "~effect/Cause/NoSuchElementError" = core
 /**
  * An error indicating that an expected value was absent.
  *
+ * **When to use**
+ *
+ * Use to model APIs that intentionally turn absence into an error.
+ *
  * **Details**
  *
  * Used by APIs that convert absence into an exception or effect failure, such
- * as `Option.getOrThrow`. Implements {@link YieldableError} so it can be
+ * as `Option.getOrThrow`. Implements `YieldableError` so it can be
  * yielded directly in `Effect.gen`.
  *
  * **Gotchas**
  *
- * Safe lookup APIs that return `Option` should document the `None` case rather
- * than describing it as a thrown `NoSuchElementError`.
+ * Prefer APIs that return `Option` or a typed failure when absence is an
+ * expected case. This error is mainly for APIs that intentionally turn absence
+ * into a thrown value or failed effect.
  *
  * **Example** (creating and checking)
  *
@@ -1306,9 +1433,6 @@ export const NoSuchElementErrorTypeId: "~effect/Cause/NoSuchElementError" = core
  * console.log(error.message) // "Element not found"
  * ```
  *
- * @see {@link isNoSuchElementError} — type guard
- * @see {@link NoSuchElementError:var | NoSuchElementError constructor}
- *
  * @category errors
  * @since 4.0.0
  */
@@ -1318,7 +1442,12 @@ export interface NoSuchElementError extends YieldableError {
 }
 
 /**
- * Constructs a {@link NoSuchElementError} with an optional message.
+ * Constructs a `NoSuchElementError` with an optional message.
+ *
+ * **When to use**
+ *
+ * Use to create the error value for APIs that intentionally fail when an
+ * expected element is absent.
  *
  * **Example** (creating a NoSuchElementError)
  *
@@ -1329,13 +1458,15 @@ export interface NoSuchElementError extends YieldableError {
  * console.log(error.message) // "Element not found"
  * ```
  *
+ * @see {@link isNoSuchElementError} for checking unknown values
+ *
  * @category constructors
  * @since 4.0.0
  */
 export const NoSuchElementError: new(message?: string) => NoSuchElementError = core.NoSuchElementError
 
 /**
- * Tests if an arbitrary value is a {@link Done} signal.
+ * Checks whether an arbitrary value is a `Done` signal.
  *
  * **Example** (runtime type check)
  *
@@ -1352,9 +1483,9 @@ export const NoSuchElementError: new(message?: string) => NoSuchElementError = c
 export const isDone: (u: unknown) => u is Done<any> = core.isDone
 
 /**
- * Unique brand for {@link Done} values.
+ * Unique brand for `Done` values.
  *
- * @category symbols
+ * @category type IDs
  * @since 4.0.0
  */
 export const DoneTypeId: "~effect/Cause/Done" = core.DoneTypeId
@@ -1362,6 +1493,11 @@ export const DoneTypeId: "~effect/Cause/Done" = core.DoneTypeId
 /**
  * A graceful completion signal for queues and streams.
  *
+ * **When to use**
+ *
+ * Use to model normal producer completion through a stream or queue error
+ * channel.
+ *
  * **Details**
  *
  * `Done` indicates that a producer has finished normally — no more elements
@@ -1384,9 +1520,6 @@ export const DoneTypeId: "~effect/Cause/Done" = core.DoneTypeId
  * })
  * ```
  *
- * @see {@link isDone} — type guard
- * @see {@link done} — create a failing Effect with `Done`
- *
  * @category errors
  * @since 4.0.0
  */
@@ -1397,7 +1530,7 @@ export interface Done<A = void> {
 }
 
 /**
- * Companion namespace for the {@link Done} interface.
+ * Companion namespace for the `Done` interface.
  *
  * @since 4.0.0
  */
@@ -1421,7 +1554,12 @@ export declare namespace Done {
 }
 
 /**
- * Creates a {@link Done} signal with an optional value.
+ * Creates a `Done` signal with an optional value.
+ *
+ * **When to use**
+ *
+ * Use when you need the completion signal value itself. Use {@link done}
+ * when you need an `Effect` that fails with the signal.
  *
  * @see {@link done} — create a failing `Effect` with `Done`
  *
@@ -1431,10 +1569,27 @@ export declare namespace Done {
 export const Done: <A = void>(value?: A) => Done<A> = core.Done
 
 /**
- * Creates an Effect that fails with a {@link Done} error. Shorthand for
+ * Creates an Effect that fails with a `Done` error. Shorthand for
  * `Effect.fail(Cause.Done(value))`.
  *
- * @see {@link Done:var | Done} — create the signal value without an Effect
+ * **When to use**
+ *
+ * Use when you use this in effect workflows that model stream or queue completion through
+ * the error channel.
+ *
+ * **Example** (failing with Done)
+ *
+ * ```ts
+ * import { Cause, Effect } from "effect"
+ *
+ * const program = Cause.done("finished")
+ *
+ * Effect.runPromiseExit(program).then((exit) => {
+ *   console.log(exit._tag) // "Failure"
+ * })
+ * ```
+ *
+ * @see {@link Done} — create the signal value without an Effect
  *
  * @category constructors
  * @since 4.0.0
@@ -1442,15 +1597,15 @@ export const Done: <A = void>(value?: A) => Done<A> = core.Done
 export const done: <A = void>(value?: A) => Effect.Effect<never, Done<A>> = core.done
 
 /**
- * Unique brand for {@link TimeoutError}.
+ * Unique brand for `TimeoutError`.
  *
- * @category symbols
+ * @category type IDs
  * @since 4.0.0
  */
 export const TimeoutErrorTypeId: "~effect/Cause/TimeoutError" = effect.TimeoutErrorTypeId
 
 /**
- * Tests if an arbitrary value is a {@link TimeoutError}.
+ * Checks whether an arbitrary value is a `TimeoutError`.
  *
  * **Example** (runtime type check)
  *
@@ -1472,7 +1627,7 @@ export const isTimeoutError: (u: unknown) => u is TimeoutError = effect.isTimeou
  * **Details**
  *
  * Produced by `Effect.timeout` and related APIs. Implements
- * {@link YieldableError}.
+ * `YieldableError`.
  *
  * **Example** (creating and checking)
  *
@@ -1484,8 +1639,6 @@ export const isTimeoutError: (u: unknown) => u is TimeoutError = effect.isTimeou
  * console.log(error.message) // "Operation timed out"
  * ```
  *
- * @see {@link isTimeoutError} — type guard
- *
  * @category errors
  * @since 4.0.0
  */
@@ -1495,7 +1648,7 @@ export interface TimeoutError extends YieldableError {
 }
 
 /**
- * Constructs a {@link TimeoutError} with an optional message.
+ * Constructs a `TimeoutError` with an optional message.
  *
  * **Example** (creating a TimeoutError)
  *
@@ -1512,15 +1665,15 @@ export interface TimeoutError extends YieldableError {
 export const TimeoutError: new(message?: string) => TimeoutError = effect.TimeoutError
 
 /**
- * Unique brand for {@link IllegalArgumentError}.
+ * Unique brand for `IllegalArgumentError`.
  *
- * @category symbols
+ * @category type IDs
  * @since 4.0.0
  */
 export const IllegalArgumentErrorTypeId: "~effect/Cause/IllegalArgumentError" = effect.IllegalArgumentErrorTypeId
 
 /**
- * Tests if an arbitrary value is an {@link IllegalArgumentError}.
+ * Checks whether an arbitrary value is an `IllegalArgumentError`.
  *
  * **Example** (runtime type check)
  *
@@ -1542,7 +1695,7 @@ export const isIllegalArgumentError: (u: unknown) => u is IllegalArgumentError =
  *
  * **Details**
  *
- * Implements {@link YieldableError}.
+ * Implements `YieldableError`.
  *
  * **Example** (creating and checking)
  *
@@ -1554,8 +1707,6 @@ export const isIllegalArgumentError: (u: unknown) => u is IllegalArgumentError =
  * console.log(error.message) // "Expected positive number"
  * ```
  *
- * @see {@link isIllegalArgumentError} — type guard
- *
  * @category errors
  * @since 4.0.0
  */
@@ -1565,7 +1716,7 @@ export interface IllegalArgumentError extends YieldableError {
 }
 
 /**
- * Constructs an {@link IllegalArgumentError} with an optional message.
+ * Constructs an `IllegalArgumentError` with an optional message.
  *
  * **Example** (creating an IllegalArgumentError)
  *
@@ -1582,7 +1733,7 @@ export interface IllegalArgumentError extends YieldableError {
 export const IllegalArgumentError: new(message?: string) => IllegalArgumentError = effect.IllegalArgumentError
 
 /**
- * Tests if an arbitrary value is an {@link ExceededCapacityError}.
+ * Checks whether an arbitrary value is an `ExceededCapacityError`.
  *
  * **Example** (runtime type check)
  *
@@ -1599,9 +1750,9 @@ export const IllegalArgumentError: new(message?: string) => IllegalArgumentError
 export const isExceededCapacityError: (u: unknown) => u is ExceededCapacityError = effect.isExceededCapacityError
 
 /**
- * Unique brand for {@link ExceededCapacityError}.
+ * Unique brand for `ExceededCapacityError`.
  *
- * @category symbols
+ * @category type IDs
  * @since 4.0.0
  */
 export const ExceededCapacityErrorTypeId: "~effect/Cause/ExceededCapacityError" = effect.ExceededCapacityErrorTypeId
@@ -1610,9 +1761,14 @@ export const ExceededCapacityErrorTypeId: "~effect/Cause/ExceededCapacityError"
  * An error indicating that a bounded resource (queue, pool, semaphore, etc.)
  * has exceeded its capacity.
  *
+ * **When to use**
+ *
+ * Use to model bounded-resource failures where an operation cannot proceed
+ * because capacity has been exhausted.
+ *
  * **Details**
  *
- * Implements {@link YieldableError}.
+ * Implements `YieldableError`.
  *
  * **Example** (creating and checking)
  *
@@ -1624,8 +1780,6 @@ export const ExceededCapacityErrorTypeId: "~effect/Cause/ExceededCapacityError"
  * console.log(error.message) // "Queue full"
  * ```
  *
- * @see {@link isExceededCapacityError} — type guard
- *
  * @category errors
  * @since 4.0.0
  */
@@ -1635,7 +1789,11 @@ export interface ExceededCapacityError extends YieldableError {
 }
 
 /**
- * Constructs an {@link ExceededCapacityError} with an optional message.
+ * Constructs an `ExceededCapacityError` with an optional message.
+ *
+ * **When to use**
+ *
+ * Use to create the error value for bounded-resource capacity failures.
  *
  * **Example** (creating an ExceededCapacityError)
  *
@@ -1646,21 +1804,37 @@ export interface ExceededCapacityError extends YieldableError {
  * console.log(error.message) // "Queue full"
  * ```
  *
+ * @see {@link isExceededCapacityError} for checking unknown values
+ *
  * @category constructors
  * @since 4.0.0
  */
 export const ExceededCapacityError: new(message?: string) => ExceededCapacityError = effect.ExceededCapacityError
 
 /**
- * Unique brand for {@link AsyncFiberError}.
+ * Unique brand present on `AsyncFiberError` values and used by
+ * `isAsyncFiberError` for runtime checks.
  *
- * @category symbols
+ * @category type IDs
  * @since 4.0.0
  */
 export const AsyncFiberErrorTypeId: "~effect/Cause/AsyncFiberError" = effect.AsyncFiberErrorTypeId
 
 /**
- * Tests if an arbitrary value is an {@link AsyncFiberError}.
+ * Checks whether an arbitrary value is an `AsyncFiberError`.
+ *
+ * **Example** (runtime type check)
+ *
+ * ```ts
+ * import { Cause } from "effect"
+ * import type { Fiber } from "effect"
+ *
+ * declare const fiber: Fiber.Fiber<unknown, unknown>
+ *
+ * const error = new Cause.AsyncFiberError(fiber)
+ * console.log(Cause.isAsyncFiberError(error)) // true
+ * console.log(Cause.isAsyncFiberError("nope")) // false
+ * ```
  *
  * @category guards
  * @since 4.0.0
@@ -1670,6 +1844,29 @@ export const isAsyncFiberError: (u: unknown) => u is AsyncFiberError = effect.is
 /**
  * An error that occurs when trying to run an async fiber with Effect.runSync.
  *
+ * **When to use**
+ *
+ * Use to inspect failures produced when synchronous runners encounter an effect
+ * that cannot complete synchronously.
+ *
+ * **Details**
+ *
+ * The `fiber` property stores the fiber that could not be synchronously
+ * resolved. This error implements `YieldableError`.
+ *
+ * **Example** (accessing the fiber)
+ *
+ * ```ts
+ * import { Cause } from "effect"
+ * import type { Fiber } from "effect"
+ *
+ * declare const fiber: Fiber.Fiber<unknown, unknown>
+ *
+ * const error = new Cause.AsyncFiberError(fiber)
+ * console.log(error._tag) // "AsyncFiberError"
+ * console.log(error.fiber === fiber) // true
+ * ```
+ *
  * @category errors
  * @since 4.0.0
  */
@@ -1680,7 +1877,27 @@ export interface AsyncFiberError extends YieldableError {
 }
 
 /**
- * An error that occurs when trying to run an async fiber with Effect.runSync.
+ * Constructs an `AsyncFiberError` for a fiber that could not be resolved
+ * synchronously.
+ *
+ * **When to use**
+ *
+ * Use to create the error value for a fiber that could not be completed by a
+ * synchronous runner.
+ *
+ * **Example** (creating an AsyncFiberError)
+ *
+ * ```ts
+ * import { Cause } from "effect"
+ * import type { Fiber } from "effect"
+ *
+ * declare const fiber: Fiber.Fiber<unknown, unknown>
+ *
+ * const error = new Cause.AsyncFiberError(fiber)
+ * console.log(error.message) // "An asynchronous Effect was executed with Effect.runSync"
+ * ```
+ *
+ * @see {@link isAsyncFiberError} for checking unknown values
  *
  * @category constructors
  * @since 4.0.0
@@ -1688,15 +1905,15 @@ export interface AsyncFiberError extends YieldableError {
 export const AsyncFiberError: new(fiber: Fiber<unknown, unknown>) => AsyncFiberError = effect.AsyncFiberError
 
 /**
- * Unique brand for {@link UnknownError}.
+ * Unique brand for `UnknownError`.
  *
- * @category symbols
+ * @category type IDs
  * @since 4.0.0
  */
 export const UnknownErrorTypeId: "~effect/Cause/UnknownError" = effect.UnknownErrorTypeId
 
 /**
- * Tests if an arbitrary value is an {@link UnknownError}.
+ * Checks whether an arbitrary value is an `UnknownError`.
  *
  * **Example** (runtime type check)
  *
@@ -1717,9 +1934,9 @@ export const isUnknownError: (u: unknown) => u is UnknownError = effect.isUnknow
  *
  * **Details**
  *
- * Produced by the runtime when an effect throws a non-`Error` value.
- * The original thrown value is stored in the `cause` property (inherited
- * from `Error`). Implements {@link YieldableError}.
+ * Used when a thrown or rejected value is not represented by a more specific
+ * typed error. The original value is stored in the `cause` property inherited
+ * from `Error`. Implements `YieldableError`.
  *
  * **Example** (creating and checking)
  *
@@ -1731,8 +1948,6 @@ export const isUnknownError: (u: unknown) => u is UnknownError = effect.isUnknow
  * console.log(error.message) // "Something unknown"
  * ```
  *
- * @see {@link isUnknownError} — type guard
- *
  * @category errors
  * @since 4.0.0
  */
@@ -1742,7 +1957,7 @@ export interface UnknownError extends YieldableError {
 }
 
 /**
- * Constructs an {@link UnknownError}. The first argument is the original
+ * Constructs an `UnknownError`. The first argument is the original
  * cause (stored in `Error.cause`); the second is an optional human-readable
  * message.
  *
@@ -1761,7 +1976,11 @@ export interface UnknownError extends YieldableError {
 export const UnknownError: new(cause: unknown, message?: string) => UnknownError = effect.UnknownError
 
 /**
- * Attaches metadata to every reason in a {@link Cause}.
+ * Attaches metadata to every reason in a `Cause`.
+ *
+ * **When to use**
+ *
+ * Use to attach diagnostic metadata to every reason in a cause.
  *
  * **Details**
  *
@@ -1769,7 +1988,7 @@ export const UnknownError: new(cause: unknown, message?: string) => UnknownError
  * retrieved later via {@link reasonAnnotations} or {@link annotations}.
  * The runtime uses this to attach stack traces and spans.
  *
- * - Returns a new `Cause`; does not mutate the input.
+ * - Returns a new `Cause`.
  * - By default, existing keys are preserved. Pass `{ overwrite: true }` to
  *   replace them.
  *
@@ -1778,19 +1997,27 @@ export const UnknownError: new(cause: unknown, message?: string) => UnknownError
  * ```ts
  * import { Cause, Context } from "effect"
  *
+ * class RequestId extends Context.Service<RequestId, string>()("RequestId") {}
+ *
  * const cause = Cause.fail("error")
- * const annotated = Cause.annotate(cause, Context.empty())
+ * const annotated = Cause.annotate(cause, Context.make(RequestId, "req-1"))
+ *
+ * console.log(Context.getOrUndefined(Cause.annotations(annotated), RequestId)) // "req-1"
  * ```
  *
- * @see {@link annotations} — read merged annotations from a cause
- * @see {@link reasonAnnotations} — read annotations from a single reason
+ * @see {@link annotations} for reading merged annotations from a cause
+ * @see {@link reasonAnnotations} for reading annotations from a single reason
  *
  * @category annotations
  * @since 4.0.0
  */
 export const annotate: {
   /**
-   * Attaches metadata to every reason in a {@link Cause}.
+   * Attaches metadata to every reason in a `Cause`.
+   *
+   * **When to use**
+   *
+   * Use to attach diagnostic metadata to every reason in a cause.
    *
    * **Details**
    *
@@ -1798,7 +2025,7 @@ export const annotate: {
    * retrieved later via {@link reasonAnnotations} or {@link annotations}.
    * The runtime uses this to attach stack traces and spans.
    *
-   * - Returns a new `Cause`; does not mutate the input.
+   * - Returns a new `Cause`.
    * - By default, existing keys are preserved. Pass `{ overwrite: true }` to
    *   replace them.
    *
@@ -1807,12 +2034,16 @@ export const annotate: {
    * ```ts
    * import { Cause, Context } from "effect"
    *
+   * class RequestId extends Context.Service<RequestId, string>()("RequestId") {}
+   *
    * const cause = Cause.fail("error")
-   * const annotated = Cause.annotate(cause, Context.empty())
+   * const annotated = Cause.annotate(cause, Context.make(RequestId, "req-1"))
+   *
+   * console.log(Context.getOrUndefined(Cause.annotations(annotated), RequestId)) // "req-1"
    * ```
    *
-   * @see {@link annotations} — read merged annotations from a cause
-   * @see {@link reasonAnnotations} — read annotations from a single reason
+   * @see {@link annotations} for reading merged annotations from a cause
+   * @see {@link reasonAnnotations} for reading annotations from a single reason
    *
    * @category annotations
    * @since 4.0.0
@@ -1822,7 +2053,11 @@ export const annotate: {
    options?: { readonly overwrite?: boolean | undefined }
   ): <E>(self: Cause<E>) => Cause<E>
   /**
-   * Attaches metadata to every reason in a {@link Cause}.
+   * Attaches metadata to every reason in a `Cause`.
+   *
+   * **When to use**
+   *
+   * Use to attach diagnostic metadata to every reason in a cause.
    *
    * **Details**
    *
@@ -1830,7 +2065,7 @@ export const annotate: {
    * retrieved later via {@link reasonAnnotations} or {@link annotations}.
    * The runtime uses this to attach stack traces and spans.
    *
-   * - Returns a new `Cause`; does not mutate the input.
+   * - Returns a new `Cause`.
    * - By default, existing keys are preserved. Pass `{ overwrite: true }` to
    *   replace them.
    *
@@ -1839,12 +2074,16 @@ export const annotate: {
    * ```ts
    * import { Cause, Context } from "effect"
    *
+   * class RequestId extends Context.Service<RequestId, string>()("RequestId") {}
+   *
    * const cause = Cause.fail("error")
-   * const annotated = Cause.annotate(cause, Context.empty())
+   * const annotated = Cause.annotate(cause, Context.make(RequestId, "req-1"))
+   *
+   * console.log(Context.getOrUndefined(Cause.annotations(annotated), RequestId)) // "req-1"
    * ```
    *
-   * @see {@link annotations} — read merged annotations from a cause
-   * @see {@link reasonAnnotations} — read annotations from a single reason
+   * @see {@link annotations} for reading merged annotations from a cause
+   * @see {@link reasonAnnotations} for reading annotations from a single reason
    *
    * @category annotations
    * @since 4.0.0
@@ -1857,15 +2096,27 @@ export const annotate: {
 } = core.causeAnnotate
 
 /**
- * Reads the annotations from a single {@link Reason} as a `Context`.
+ * Reads the annotations from a single `Reason` as a `Context`.
  *
  * **When to use**
  *
- * Use this when you need tracing metadata (e.g. {@link StackTrace}) from
+ * Use when you need tracing metadata (e.g. `StackTrace`) from
  * a specific reason rather than the whole cause.
  *
+ * **Example** (reading reason annotations)
+ *
+ * ```ts
+ * import { Cause, Context } from "effect"
+ *
+ * class RequestId extends Context.Service<RequestId, string>()("RequestId") {}
+ *
+ * const reason = Cause.makeFailReason("error")
+ * const annotated = reason.annotate(Context.make(RequestId, "req-1"))
+ *
+ * console.log(Context.getOrUndefined(Cause.reasonAnnotations(annotated), RequestId)) // "req-1"
+ * ```
+ *
  * @see {@link annotations} — merged annotations from all reasons in a cause
- * @see {@link annotate} — attach annotations
  *
  * @category annotations
  * @since 4.0.0
@@ -1873,14 +2124,33 @@ export const annotate: {
 export const reasonAnnotations: <E>(self: Reason<E>) => Context.Context<never> = effect.reasonAnnotations
 
 /**
- * Reads the merged annotations from all reasons in a {@link Cause}.
+ * Reads the merged annotations from all reasons in a `Cause`.
  *
- * **Details**
+ * **When to use**
+ *
+ * Use to read diagnostic metadata merged from the whole cause.
+ *
+ * **Gotchas**
+ *
+ * When multiple reasons contain the same annotation key, the value from the
+ * later reason wins.
+ *
+ * **Example** (reading merged annotations)
+ *
+ * ```ts
+ * import { Cause, Context } from "effect"
  *
- * Annotations from later reasons overwrite earlier ones when keys collide.
+ * class RequestId extends Context.Service<RequestId, string>()("RequestId") {}
+ *
+ * const cause = Cause.annotate(
+ *   Cause.fail("error"),
+ *   Context.make(RequestId, "req-1")
+ * )
+ *
+ * console.log(Context.getOrUndefined(Cause.annotations(cause), RequestId)) // "req-1"
+ * ```
  *
  * @see {@link reasonAnnotations} — annotations from a single reason
- * @see {@link annotate} — attach annotations
  *
  * @category annotations
  * @since 4.0.0
@@ -1888,7 +2158,12 @@ export const reasonAnnotations: <E>(self: Reason<E>) => Context.Context<never> =
 export const annotations: <E>(self: Cause<E>) => Context.Context<never> = effect.causeAnnotations
 
 /**
- * `Context` key for the stack frame captured at the point of failure.
+ * Context annotation used to store the stack frame captured at the point of failure.
+ *
+ * **When to use**
+ *
+ * Use to read the failure stack-frame annotation from a `Reason` when building
+ * diagnostics, logging, or custom cause renderers.
  *
  * **Details**
  *
@@ -1896,18 +2171,31 @@ export const annotations: <E>(self: Cause<E>) => Context.Context<never> = effect
  * available. Retrieve it via
  * `Context.get(Cause.reasonAnnotations(reason), Cause.StackTrace)`.
  *
+ * @see {@link reasonAnnotations} for reading annotations from a single reason
+ * @see {@link annotations} for reading merged annotations from a cause
+ * @see {@link InterruptorStackTrace} for the interrupt-specific stack-frame annotation
+ *
  * @category annotations
  * @since 4.0.0
  */
 export class StackTrace extends Context.Service<StackTrace, StackFrame>()("effect/Cause/StackTrace") {}
 
 /**
- * `Context` key for the stack frame captured at the point of
+ * Context annotation used to store the stack frame captured at the point of
  * interruption.
  *
+ * **When to use**
+ *
+ * Use when attaching or reading the stack-frame annotation consumed by
+ * interrupt-only cause rendering.
+ *
  * **Details**
  *
- * Similar to {@link StackTrace} but specific to {@link Interrupt} reasons.
+ * Similar to `StackTrace` but specific to `Interrupt` reasons.
+ *
+ * @see {@link StackTrace} for stack frames attached to failures
+ * @see {@link reasonAnnotations} for reading annotations from a single reason
+ * @see {@link annotate} for attaching annotations to a cause
  *
  * @category annotations
  * @since 4.0.0