effect 4.0.0-beta.73 → 4.0.0-beta.75

package/dist/Array.d.ts

@@ -43,8 +43,8 @@ export interface ReadonlyArrayTypeLambda extends TypeLambda {
  *
  * **When to use**
  *
- * Use when you use this type when you need to ensure non-emptiness at the type level while
- * preventing mutation. Many Array module functions accept or return this type.
+ * Use when non-emptiness must be tracked at the type level while preventing mutation.
+ * Many Array module functions accept or return this type.
  *
  * **Example** (Typing a non-empty array)
  *
@@ -97,9 +97,12 @@ export type NonEmptyArray<A> = [A, ...Array<A>];
  *
  * **When to use**
  *
- * Use when you have literal values and want a typed non-empty array.
- * - The element type is inferred as the union of all arguments.
- * - Always returns a `NonEmptyArray` since at least one argument is required.
+ * Use when you need to create a typed non-empty array from literal values.
+ *
+ * **Details**
+ *
+ * The element type is inferred as the union of all arguments. Because at least
+ * one argument is required, this always returns a `NonEmptyArray`.
  *
  * **Example** (Creating an array from values)
  *
@@ -122,9 +125,11 @@ export declare const make: <Elements extends NonEmptyArray<unknown>>(...elements
  *
  * **When to use**
  *
- * Use when you need a pre-sized array and will fill it imperatively.
- * - Elements are typed as `A | undefined` since slots are empty.
- * - Prefer {@link makeBy} when you can compute each element from its index.
+ * Use when you need a pre-sized array that will be filled imperatively.
+ *
+ * **Details**
+ *
+ * Elements are typed as `A | undefined` because the slots are empty.
  *
  * **Example** (Allocating a fixed-size array)
  *
@@ -146,9 +151,13 @@ export declare const allocate: <A = never>(n: number) => Array<A | undefined>;
  *
  * **When to use**
  *
- * Use when you need an array whose values depend on the index.
- * - `n` is normalized to an integer >= 1 — always returns at least one element.
- * - Dual: `Array.makeBy(5, f)` or `pipe(5, Array.makeBy(f))`.
+ * Use when you need to compute each array element from its index.
+ *
+ * **Details**
+ *
+ * `n` is normalized to an integer greater than or equal to 1, so this function
+ * always returns at least one element. Supports both data-first and data-last
+ * usage.
  *
  * **Example** (Generating values from indices)
  *
@@ -171,9 +180,13 @@ export declare const makeBy: {
      *
      * **When to use**
      *
-     * Use when you need an array whose values depend on the index.
-     * - `n` is normalized to an integer >= 1 — always returns at least one element.
-     * - Dual: `Array.makeBy(5, f)` or `pipe(5, Array.makeBy(f))`.
+     * Use when you need to compute each array element from its index.
+     *
+     * **Details**
+     *
+     * `n` is normalized to an integer greater than or equal to 1, so this function
+     * always returns at least one element. Supports both data-first and data-last
+     * usage.
      *
      * **Example** (Generating values from indices)
      *
@@ -196,9 +209,13 @@ export declare const makeBy: {
      *
      * **When to use**
      *
-     * Use when you need an array whose values depend on the index.
-     * - `n` is normalized to an integer >= 1 — always returns at least one element.
-     * - Dual: `Array.makeBy(5, f)` or `pipe(5, Array.makeBy(f))`.
+     * Use when you need to compute each array element from its index.
+     *
+     * **Details**
+     *
+     * `n` is normalized to an integer greater than or equal to 1, so this function
+     * always returns at least one element. Supports both data-first and data-last
+     * usage.
      *
      * **Example** (Generating values from indices)
      *
@@ -223,9 +240,11 @@ export declare const makeBy: {
  *
  * **When to use**
  *
- * Use when you need a sequence of consecutive integers.
- * - If `start > end`, returns `[start]`.
- * - Always returns a `NonEmptyArray`.
+ * Use when you need a non-empty sequence of consecutive integers.
+ *
+ * **Details**
+ *
+ * If `start > end`, returns `[start]`.
  *
  * **Example** (Creating a range)
  *
@@ -247,9 +266,13 @@ export declare const range: (start: number, end: number) => NonEmptyArray<number
  *
  * **When to use**
  *
- * Use when you need multiple copies of the same value.
- * - `n` is normalized to an integer >= 1 — always returns at least one element.
- * - Dual: `Array.replicate("a", 3)` or `pipe("a", Array.replicate(3))`.
+ * Use when you need a non-empty array containing repeated copies of one value.
+ *
+ * **Details**
+ *
+ * `n` is normalized to an integer greater than or equal to 1, so this function
+ * always returns at least one element. Supports both data-first and data-last
+ * usage.
  *
  * **Example** (Repeating a value)
  *
@@ -271,9 +294,13 @@ export declare const replicate: {
      *
      * **When to use**
      *
-     * Use when you need multiple copies of the same value.
-     * - `n` is normalized to an integer >= 1 — always returns at least one element.
-     * - Dual: `Array.replicate("a", 3)` or `pipe("a", Array.replicate(3))`.
+     * Use when you need a non-empty array containing repeated copies of one value.
+     *
+     * **Details**
+     *
+     * `n` is normalized to an integer greater than or equal to 1, so this function
+     * always returns at least one element. Supports both data-first and data-last
+     * usage.
      *
      * **Example** (Repeating a value)
      *
@@ -295,9 +322,13 @@ export declare const replicate: {
      *
      * **When to use**
      *
-     * Use when you need multiple copies of the same value.
-     * - `n` is normalized to an integer >= 1 — always returns at least one element.
-     * - Dual: `Array.replicate("a", 3)` or `pipe("a", Array.replicate(3))`.
+     * Use when you need a non-empty array containing repeated copies of one value.
+     *
+     * **Details**
+     *
+     * `n` is normalized to an integer greater than or equal to 1, so this function
+     * always returns at least one element. Supports both data-first and data-last
+     * usage.
      *
      * **Example** (Repeating a value)
      *
@@ -324,10 +355,9 @@ export declare const replicate: {
  *
  * **Details**
  *
- * - If the input is already an array, returns it **by reference** (no copy).
- * - Otherwise, creates a new array from the iterable.
- * - Use {@link copy} if you need a fresh array even when the input is already
- *   an array.
+ * If the input is already an array, this returns it by reference without
+ * copying. Otherwise, it creates a new array from the iterable. Use `copy` if
+ * you need a fresh array even when the input is already an array.
  *
  * **Example** (Converting a Set to an array)
  *
@@ -355,9 +385,9 @@ export declare const fromIterable: <A>(collection: Iterable<A>) => Array<A>;
  *
  * **Details**
  *
- * - If the input is already an array, returns it by reference.
- * - If the input is a single value, wraps it in a one-element array.
- * - Useful for APIs that accept `A | Array<A>`.
+ * If the input is already an array, this returns it by reference. If the input
+ * is a single value, this wraps it in a one-element array. This is useful for
+ * APIs that accept `A | Array<A>`.
  *
  * **Example** (Normalizing input)
  *
@@ -385,8 +415,8 @@ export declare const ensure: <A>(self: ReadonlyArray<A> | A) => Array<A>;
  *
  * **Details**
  *
- * - Key order follows `Object.entries` semantics.
- * - Returns an empty array for an empty record.
+ * Key order follows `Object.entries` semantics. Empty records produce an empty
+ * array.
  *
  * **Example** (Record to entries)
  *
@@ -431,9 +461,12 @@ export declare const fromOption: <A>(self: Option.Option<A>) => Array<A>;
  *
  * **When to use**
  *
- * Use when you need to branch on whether an array has elements.
- * - `onNonEmpty` receives a `NonEmptyReadonlyArray`.
- * - Dual: data-first or data-last.
+ * Use when you need to branch on whether an array is empty.
+ *
+ * **Details**
+ *
+ * `onNonEmpty` receives a `NonEmptyReadonlyArray`. Supports both data-first and
+ * data-last usage.
  *
  * **Example** (Branching on emptiness)
  *
@@ -460,9 +493,12 @@ export declare const match: {
      *
      * **When to use**
      *
-     * Use when you need to branch on whether an array has elements.
-     * - `onNonEmpty` receives a `NonEmptyReadonlyArray`.
-     * - Dual: data-first or data-last.
+     * Use when you need to branch on whether an array is empty.
+     *
+     * **Details**
+     *
+     * `onNonEmpty` receives a `NonEmptyReadonlyArray`. Supports both data-first and
+     * data-last usage.
      *
      * **Example** (Branching on emptiness)
      *
@@ -492,9 +528,12 @@ export declare const match: {
      *
      * **When to use**
      *
-     * Use when you need to branch on whether an array has elements.
-     * - `onNonEmpty` receives a `NonEmptyReadonlyArray`.
-     * - Dual: data-first or data-last.
+     * Use when you need to branch on whether an array is empty.
+     *
+     * **Details**
+     *
+     * `onNonEmpty` receives a `NonEmptyReadonlyArray`. Supports both data-first and
+     * data-last usage.
      *
      * **Example** (Branching on emptiness)
      *
@@ -526,8 +565,8 @@ export declare const match: {
  *
  * **When to use**
  *
- * Use to pattern-match when you need the first element and remaining elements as
- * separate values.
+ * Use when you need to branch on an array and handle the non-empty case as the
+ * first element plus the remaining elements.
  *
  * **Details**
  *
@@ -559,8 +598,8 @@ export declare const matchLeft: {
      *
      * **When to use**
      *
-     * Use to pattern-match when you need the first element and remaining elements as
-     * separate values.
+     * Use when you need to branch on an array and handle the non-empty case as the
+     * first element plus the remaining elements.
      *
      * **Details**
      *
@@ -595,8 +634,8 @@ export declare const matchLeft: {
      *
      * **When to use**
      *
-     * Use to pattern-match when you need the first element and remaining elements as
-     * separate values.
+     * Use when you need to branch on an array and handle the non-empty case as the
+     * first element plus the remaining elements.
      *
      * **Details**
      *
@@ -632,8 +671,8 @@ export declare const matchLeft: {
  *
  * **When to use**
  *
- * Use to pattern-match when you need all but the last element and the last element
- * as separate values.
+ * Use when you need to branch on an array and handle the non-empty case as the
+ * elements before the last plus the last element.
  *
  * **Details**
  *
@@ -665,8 +704,8 @@ export declare const matchRight: {
      *
      * **When to use**
      *
-     * Use to pattern-match when you need all but the last element and the last element
-     * as separate values.
+     * Use when you need to branch on an array and handle the non-empty case as the
+     * elements before the last plus the last element.
      *
      * **Details**
      *
@@ -701,8 +740,8 @@ export declare const matchRight: {
      *
      * **When to use**
      *
-     * Use to pattern-match when you need all but the last element and the last element
-     * as separate values.
+     * Use when you need to branch on an array and handle the non-empty case as the
+     * elements before the last plus the last element.
      *
      * **Details**
      *
@@ -737,11 +776,8 @@ export declare const matchRight: {
  *
  * **When to use**
  *
- * Use to add a single element at the start of an iterable and get a `NonEmptyArray`.
- *
- * **Details**
- *
- * - Always returns a non-empty array.
+ * Use when you need to guarantee a non-empty result after adding a required
+ * leading value.
  *
  * **Example** (Prepending an element)
  *
@@ -755,7 +791,7 @@ export declare const matchRight: {
  * @see {@link append} — add to the end
  * @see {@link prependAll} — prepend multiple elements
  *
- * @category concatenating
+ * @category combining
  * @since 2.0.0
  */
 export declare const prepend: {
@@ -764,11 +800,8 @@ export declare const prepend: {
      *
      * **When to use**
      *
-     * Use to add a single element at the start of an iterable and get a `NonEmptyArray`.
-     *
-     * **Details**
-     *
-     * - Always returns a non-empty array.
+     * Use when you need to guarantee a non-empty result after adding a required
+     * leading value.
      *
      * **Example** (Prepending an element)
      *
@@ -782,7 +815,7 @@ export declare const prepend: {
      * @see {@link append} — add to the end
      * @see {@link prependAll} — prepend multiple elements
      *
-     * @category concatenating
+     * @category combining
      * @since 2.0.0
      */
     <B>(head: B): <A>(self: Iterable<A>) => NonEmptyArray<A | B>;
@@ -791,11 +824,8 @@ export declare const prepend: {
      *
      * **When to use**
      *
-     * Use to add a single element at the start of an iterable and get a `NonEmptyArray`.
-     *
-     * **Details**
-     *
-     * - Always returns a non-empty array.
+     * Use when you need to guarantee a non-empty result after adding a required
+     * leading value.
      *
      * **Example** (Prepending an element)
      *
@@ -809,7 +839,7 @@ export declare const prepend: {
      * @see {@link append} — add to the end
      * @see {@link prependAll} — prepend multiple elements
      *
-     * @category concatenating
+     * @category combining
      * @since 2.0.0
      */
     <A, B>(self: Iterable<A>, head: B): NonEmptyArray<A | B>;
@@ -823,7 +853,7 @@ export declare const prepend: {
  *
  * **Details**
  *
- * - If either input is non-empty, the result is a `NonEmptyArray`.
+ * If either input is non-empty, the result is a `NonEmptyArray`.
  *
  * **Example** (Prepending multiple elements)
  *
@@ -837,7 +867,7 @@ export declare const prepend: {
  * @see {@link prepend} — add a single element to the front
  * @see {@link appendAll} — add elements to the end
  *
- * @category concatenating
+ * @category combining
  * @since 2.0.0
  */
 export declare const prependAll: {
@@ -850,7 +880,7 @@ export declare const prependAll: {
      *
      * **Details**
      *
-     * - If either input is non-empty, the result is a `NonEmptyArray`.
+     * If either input is non-empty, the result is a `NonEmptyArray`.
      *
      * **Example** (Prepending multiple elements)
      *
@@ -864,7 +894,7 @@ export declare const prependAll: {
      * @see {@link prepend} — add a single element to the front
      * @see {@link appendAll} — add elements to the end
      *
-     * @category concatenating
+     * @category combining
      * @since 2.0.0
      */
     <S extends Iterable<any>, T extends Iterable<any>>(that: T): (self: S) => ReadonlyArray.OrNonEmpty<S, T, ReadonlyArray.Infer<S> | ReadonlyArray.Infer<T>>;
@@ -877,7 +907,7 @@ export declare const prependAll: {
      *
      * **Details**
      *
-     * - If either input is non-empty, the result is a `NonEmptyArray`.
+     * If either input is non-empty, the result is a `NonEmptyArray`.
      *
      * **Example** (Prepending multiple elements)
      *
@@ -891,7 +921,7 @@ export declare const prependAll: {
      * @see {@link prepend} — add a single element to the front
      * @see {@link appendAll} — add elements to the end
      *
-     * @category concatenating
+     * @category combining
      * @since 2.0.0
      */
     <A, B>(self: Iterable<A>, that: NonEmptyReadonlyArray<B>): NonEmptyArray<A | B>;
@@ -904,7 +934,7 @@ export declare const prependAll: {
      *
      * **Details**
      *
-     * - If either input is non-empty, the result is a `NonEmptyArray`.
+     * If either input is non-empty, the result is a `NonEmptyArray`.
      *
      * **Example** (Prepending multiple elements)
      *
@@ -918,7 +948,7 @@ export declare const prependAll: {
      * @see {@link prepend} — add a single element to the front
      * @see {@link appendAll} — add elements to the end
      *
-     * @category concatenating
+     * @category combining
      * @since 2.0.0
      */
     <A, B>(self: NonEmptyReadonlyArray<A>, that: Iterable<B>): NonEmptyArray<A | B>;
@@ -931,7 +961,7 @@ export declare const prependAll: {
      *
      * **Details**
      *
-     * - If either input is non-empty, the result is a `NonEmptyArray`.
+     * If either input is non-empty, the result is a `NonEmptyArray`.
      *
      * **Example** (Prepending multiple elements)
      *
@@ -945,7 +975,7 @@ export declare const prependAll: {
      * @see {@link prepend} — add a single element to the front
      * @see {@link appendAll} — add elements to the end
      *
-     * @category concatenating
+     * @category combining
      * @since 2.0.0
      */
     <A, B>(self: Iterable<A>, that: Iterable<B>): Array<A | B>;
@@ -955,12 +985,8 @@ export declare const prependAll: {
  *
  * **When to use**
  *
- * Use to add one element to the end of an iterable and get a new
- * `NonEmptyArray`.
- *
- * **Details**
- *
- * - Always returns a non-empty array.
+ * Use when you need to guarantee a non-empty result after adding a required
+ * trailing value.
  *
  * **Example** (Appending an element)
  *
@@ -974,7 +1000,7 @@ export declare const prependAll: {
  * @see {@link prepend} — add to the front
  * @see {@link appendAll} — append multiple elements
  *
- * @category concatenating
+ * @category combining
  * @since 2.0.0
  */
 export declare const append: {
@@ -983,12 +1009,8 @@ export declare const append: {
      *
      * **When to use**
      *
-     * Use to add one element to the end of an iterable and get a new
-     * `NonEmptyArray`.
-     *
-     * **Details**
-     *
-     * - Always returns a non-empty array.
+     * Use when you need to guarantee a non-empty result after adding a required
+     * trailing value.
      *
      * **Example** (Appending an element)
      *
@@ -1002,7 +1024,7 @@ export declare const append: {
      * @see {@link prepend} — add to the front
      * @see {@link appendAll} — append multiple elements
      *
-     * @category concatenating
+     * @category combining
      * @since 2.0.0
      */
     <B>(last: B): <A>(self: Iterable<A>) => NonEmptyArray<A | B>;
@@ -1011,12 +1033,8 @@ export declare const append: {
      *
      * **When to use**
      *
-     * Use to add one element to the end of an iterable and get a new
-     * `NonEmptyArray`.
-     *
-     * **Details**
-     *
-     * - Always returns a non-empty array.
+     * Use when you need to guarantee a non-empty result after adding a required
+     * trailing value.
      *
      * **Example** (Appending an element)
      *
@@ -1030,7 +1048,7 @@ export declare const append: {
      * @see {@link prepend} — add to the front
      * @see {@link appendAll} — append multiple elements
      *
-     * @category concatenating
+     * @category combining
      * @since 2.0.0
      */
     <A, B>(self: Iterable<A>, last: B): NonEmptyArray<A | B>;
@@ -1045,7 +1063,7 @@ export declare const append: {
  *
  * **Details**
  *
- * - If either input is non-empty, the result is a `NonEmptyArray`.
+ * If either input is non-empty, the result is a `NonEmptyArray`.
  *
  * **Example** (Concatenating arrays)
  *
@@ -1059,7 +1077,7 @@ export declare const append: {
  * @see {@link append} — add a single element to the end
  * @see {@link prependAll} — add elements to the front
  *
- * @category concatenating
+ * @category combining
  * @since 2.0.0
  */
 export declare const appendAll: {
@@ -1073,7 +1091,7 @@ export declare const appendAll: {
      *
      * **Details**
      *
-     * - If either input is non-empty, the result is a `NonEmptyArray`.
+     * If either input is non-empty, the result is a `NonEmptyArray`.
      *
      * **Example** (Concatenating arrays)
      *
@@ -1087,7 +1105,7 @@ export declare const appendAll: {
      * @see {@link append} — add a single element to the end
      * @see {@link prependAll} — add elements to the front
      *
-     * @category concatenating
+     * @category combining
      * @since 2.0.0
      */
     <S extends Iterable<any>, T extends Iterable<any>>(that: T): (self: S) => ReadonlyArray.OrNonEmpty<S, T, ReadonlyArray.Infer<S> | ReadonlyArray.Infer<T>>;
@@ -1101,7 +1119,7 @@ export declare const appendAll: {
      *
      * **Details**
      *
-     * - If either input is non-empty, the result is a `NonEmptyArray`.
+     * If either input is non-empty, the result is a `NonEmptyArray`.
      *
      * **Example** (Concatenating arrays)
      *
@@ -1115,7 +1133,7 @@ export declare const appendAll: {
      * @see {@link append} — add a single element to the end
      * @see {@link prependAll} — add elements to the front
      *
-     * @category concatenating
+     * @category combining
      * @since 2.0.0
      */
     <A, B>(self: Iterable<A>, that: NonEmptyReadonlyArray<B>): NonEmptyArray<A | B>;
@@ -1129,7 +1147,7 @@ export declare const appendAll: {
      *
      * **Details**
      *
-     * - If either input is non-empty, the result is a `NonEmptyArray`.
+     * If either input is non-empty, the result is a `NonEmptyArray`.
      *
      * **Example** (Concatenating arrays)
      *
@@ -1143,7 +1161,7 @@ export declare const appendAll: {
      * @see {@link append} — add a single element to the end
      * @see {@link prependAll} — add elements to the front
      *
-     * @category concatenating
+     * @category combining
      * @since 2.0.0
      */
     <A, B>(self: NonEmptyReadonlyArray<A>, that: Iterable<B>): NonEmptyArray<A | B>;
@@ -1157,7 +1175,7 @@ export declare const appendAll: {
      *
      * **Details**
      *
-     * - If either input is non-empty, the result is a `NonEmptyArray`.
+     * If either input is non-empty, the result is a `NonEmptyArray`.
      *
      * **Example** (Concatenating arrays)
      *
@@ -1171,7 +1189,7 @@ export declare const appendAll: {
      * @see {@link append} — add a single element to the end
      * @see {@link prependAll} — add elements to the front
      *
-     * @category concatenating
+     * @category combining
      * @since 2.0.0
      */
     <A, B>(self: Iterable<A>, that: Iterable<B>): Array<A | B>;
@@ -1185,9 +1203,9 @@ export declare const appendAll: {
  *
  * **Details**
  *
- * - The output length is `input.length + 1` (starts with the initial value).
- * - Always returns a `NonEmptyArray` because the initial value is included.
- * - Use {@link reduce} if you only need the final accumulated value.
+ * The output length is `input.length + 1` because it starts with the initial
+ * value. The result is always a `NonEmptyArray`. Use `reduce` if you only need
+ * the final accumulated value.
  *
  * **Example** (Running totals)
  *
@@ -1214,9 +1232,9 @@ export declare const scan: {
      *
      * **Details**
      *
-     * - The output length is `input.length + 1` (starts with the initial value).
-     * - Always returns a `NonEmptyArray` because the initial value is included.
-     * - Use {@link reduce} if you only need the final accumulated value.
+     * The output length is `input.length + 1` because it starts with the initial
+     * value. The result is always a `NonEmptyArray`. Use `reduce` if you only need
+     * the final accumulated value.
      *
      * **Example** (Running totals)
      *
@@ -1243,9 +1261,9 @@ export declare const scan: {
      *
      * **Details**
      *
-     * - The output length is `input.length + 1` (starts with the initial value).
-     * - Always returns a `NonEmptyArray` because the initial value is included.
-     * - Use {@link reduce} if you only need the final accumulated value.
+     * The output length is `input.length + 1` because it starts with the initial
+     * value. The result is always a `NonEmptyArray`. Use `reduce` if you only need
+     * the final accumulated value.
      *
      * **Example** (Running totals)
      *
@@ -1274,8 +1292,8 @@ export declare const scan: {
  *
  * **Details**
  *
- * - The output length is `input.length + 1` (ends with the initial value).
- * - Always returns a `NonEmptyArray`.
+ * The output length is `input.length + 1` because it ends with the initial
+ * value. The result is always a `NonEmptyArray`.
  *
  * **Example** (Reverse running totals)
  *
@@ -1303,8 +1321,8 @@ export declare const scanRight: {
      *
      * **Details**
      *
-     * - The output length is `input.length + 1` (ends with the initial value).
-     * - Always returns a `NonEmptyArray`.
+     * The output length is `input.length + 1` because it ends with the initial
+     * value. The result is always a `NonEmptyArray`.
      *
      * **Example** (Reverse running totals)
      *
@@ -1332,8 +1350,8 @@ export declare const scanRight: {
      *
      * **Details**
      *
-     * - The output length is `input.length + 1` (ends with the initial value).
-     * - Always returns a `NonEmptyArray`.
+     * The output length is `input.length + 1` because it ends with the initial
+     * value. The result is always a `NonEmptyArray`.
      *
      * **Example** (Reverse running totals)
      *
@@ -1361,8 +1379,8 @@ export declare const scanRight: {
  *
  * **Details**
  *
- * - Acts as a type guard narrowing the input to `Array<unknown>`.
- * - Delegates to `globalThis.Array.isArray`.
+ * Acts as a type guard narrowing the input to `Array<unknown>` and delegates to
+ * `globalThis.Array.isArray`.
  *
  * **Example** (Type-guarding an unknown value)
  *
@@ -1389,8 +1407,8 @@ export declare const isArray: {
      *
      * **Details**
      *
-     * - Acts as a type guard narrowing the input to `Array<unknown>`.
-     * - Delegates to `globalThis.Array.isArray`.
+     * Acts as a type guard narrowing the input to `Array<unknown>` and delegates to
+     * `globalThis.Array.isArray`.
      *
      * **Example** (Type-guarding an unknown value)
      *
@@ -1417,8 +1435,8 @@ export declare const isArray: {
      *
      * **Details**
      *
-     * - Acts as a type guard narrowing the input to `Array<unknown>`.
-     * - Delegates to `globalThis.Array.isArray`.
+     * Acts as a type guard narrowing the input to `Array<unknown>` and delegates to
+     * `globalThis.Array.isArray`.
      *
      * **Example** (Type-guarding an unknown value)
      *
@@ -1479,6 +1497,11 @@ export declare const isReadonlyArrayEmpty: <A>(self: ReadonlyArray<A>) => self i
  * Checks whether a mutable `Array` is non-empty, narrowing the type to
  * `NonEmptyArray`.
  *
+ * **When to use**
+ *
+ * Use when you need the narrowed value to remain a mutable `Array` after proving
+ * it has at least one element.
+ *
  * **Example** (Checking for a non-empty array)
  *
  * ```ts
@@ -1499,6 +1522,11 @@ export declare const isArrayNonEmpty: <A>(self: Array<A>) => self is NonEmptyArr
  * Checks whether a `ReadonlyArray` is non-empty, narrowing the type to
  * `NonEmptyReadonlyArray`.
  *
+ * **When to use**
+ *
+ * Use when you need to prove a readonly array has at least one element without
+ * requiring mutable array methods afterward.
+ *
  * **Example** (Checking for a non-empty readonly array)
  *
  * ```ts
@@ -1545,8 +1573,7 @@ export declare const length: <A>(self: ReadonlyArray<A>) => number;
  *
  * **Details**
  *
- * - The index is floored to an integer.
- * - Never throws.
+ * The index is floored to an integer. This never throws.
  *
  * **Example** (Safe index access)
  *
@@ -1576,8 +1603,7 @@ export declare const get: {
      *
      * **Details**
      *
-     * - The index is floored to an integer.
-     * - Never throws.
+     * The index is floored to an integer. This never throws.
      *
      * **Example** (Safe index access)
      *
@@ -1607,8 +1633,7 @@ export declare const get: {
      *
      * **Details**
      *
-     * - The index is floored to an integer.
-     * - Never throws.
+     * The index is floored to an integer. This never throws.
      *
      * **Example** (Safe index access)
      *
@@ -1633,13 +1658,13 @@ export declare const get: {
  *
  * **When to use**
  *
- * Use to read an element at a known valid index when out-of-bounds would be a
- * programming error.
+ * Use to read an array element at a known valid index when out-of-bounds would
+ * be a programming error.
  *
  * **Details**
  *
- * - Throws an `Error` with the message `"Index out of bounds: <i>"`.
- * - Prefer {@link get} for safe access.
+ * Throws an `Error` with the message `"Index out of bounds: <i>"`. Prefer
+ * `get` for safe access.
  *
  * **Example** (Unsafe index access)
  *
@@ -1661,13 +1686,13 @@ export declare const getUnsafe: {
      *
      * **When to use**
      *
-     * Use to read an element at a known valid index when out-of-bounds would be a
-     * programming error.
+     * Use to read an array element at a known valid index when out-of-bounds would
+     * be a programming error.
      *
      * **Details**
      *
-     * - Throws an `Error` with the message `"Index out of bounds: <i>"`.
-     * - Prefer {@link get} for safe access.
+     * Throws an `Error` with the message `"Index out of bounds: <i>"`. Prefer
+     * `get` for safe access.
      *
      * **Example** (Unsafe index access)
      *
@@ -1689,13 +1714,13 @@ export declare const getUnsafe: {
      *
      * **When to use**
      *
-     * Use to read an element at a known valid index when out-of-bounds would be a
-     * programming error.
+     * Use to read an array element at a known valid index when out-of-bounds would
+     * be a programming error.
      *
      * **Details**
      *
-     * - Throws an `Error` with the message `"Index out of bounds: <i>"`.
-     * - Prefer {@link get} for safe access.
+     * Throws an `Error` with the message `"Index out of bounds: <i>"`. Prefer
+     * `get` for safe access.
      *
      * **Example** (Unsafe index access)
      *
@@ -1723,8 +1748,7 @@ export declare const getUnsafe: {
  *
  * **Details**
  *
- * - Returns a tuple `[head, tail]`.
- * - Requires a `NonEmptyReadonlyArray`.
+ * Returns a tuple `[head, tail]` and requires a `NonEmptyReadonlyArray`.
  *
  * **Example** (Destructuring head and tail)
  *
@@ -1749,13 +1773,12 @@ export declare const unprepend: <A>(self: NonEmptyReadonlyArray<A>) => [firstEle
  *
  * **When to use**
  *
- * Use to split a non-empty array from the end when you need both the elements
- * before the last element and the last element.
+ * Use when you need to split a non-empty array into the elements before the
+ * last element and the last element.
  *
  * **Details**
  *
- * - Returns a tuple `[init, last]`.
- * - Requires a `NonEmptyReadonlyArray`.
+ * Returns a tuple `[init, last]` and requires a `NonEmptyReadonlyArray`.
  *
  * **Example** (Destructuring init and last)
  *
@@ -1877,8 +1900,7 @@ export declare const lastNonEmpty: <A>(self: NonEmptyReadonlyArray<A>) => A;
  *
  * **Details**
  *
- * - Allocates a new array via `slice(1)`.
- * - Returns `Option.none()` for empty inputs.
+ * Allocates a new array via `slice(1)`. Empty inputs return `Option.none()`.
  *
  * **Example** (Getting the tail)
  *
@@ -1927,8 +1949,8 @@ export declare const tailNonEmpty: <A>(self: NonEmptyReadonlyArray<A>) => Array<
  *
  * **Details**
  *
- * - Allocates a new array via `slice(0, -1)`.
- * - Returns `Option.none()` for empty inputs.
+ * Allocates a new array via `slice(0, -1)`. Empty inputs return
+ * `Option.none()`.
  *
  * **Example** (Getting init)
  *
@@ -1977,8 +1999,7 @@ export declare const initNonEmpty: <A>(self: NonEmptyReadonlyArray<A>) => Array<
  *
  * **Details**
  *
- * - `n` is clamped to `[0, length]`.
- * - Returns an empty array when `n <= 0`.
+ * `n` is clamped to `[0, length]`. Returns an empty array when `n <= 0`.
  *
  * **Example** (Taking from the start)
  *
@@ -2005,8 +2026,7 @@ export declare const take: {
      *
      * **Details**
      *
-     * - `n` is clamped to `[0, length]`.
-     * - Returns an empty array when `n <= 0`.
+     * `n` is clamped to `[0, length]`. Returns an empty array when `n <= 0`.
      *
      * **Example** (Taking from the start)
      *
@@ -2033,8 +2053,7 @@ export declare const take: {
      *
      * **Details**
      *
-     * - `n` is clamped to `[0, length]`.
-     * - Returns an empty array when `n <= 0`.
+     * `n` is clamped to `[0, length]`. Returns an empty array when `n <= 0`.
      *
      * **Example** (Taking from the start)
      *
@@ -2062,8 +2081,7 @@ export declare const take: {
  *
  * **Details**
  *
- * - `n` is clamped to `[0, length]`.
- * - Returns an empty array when `n <= 0`.
+ * `n` is clamped to `[0, length]`. Returns an empty array when `n <= 0`.
  *
  * **Example** (Taking from the end)
  *
@@ -2089,8 +2107,7 @@ export declare const takeRight: {
      *
      * **Details**
      *
-     * - `n` is clamped to `[0, length]`.
-     * - Returns an empty array when `n <= 0`.
+     * `n` is clamped to `[0, length]`. Returns an empty array when `n <= 0`.
      *
      * **Example** (Taking from the end)
      *
@@ -2116,8 +2133,7 @@ export declare const takeRight: {
      *
      * **Details**
      *
-     * - `n` is clamped to `[0, length]`.
-     * - Returns an empty array when `n <= 0`.
+     * `n` is clamped to `[0, length]`. Returns an empty array when `n <= 0`.
      *
      * **Example** (Taking from the end)
      *
@@ -2146,8 +2162,8 @@ export declare const takeRight: {
  *
  * **Details**
  *
- * - Supports refinements for type narrowing.
- * - The predicate receives `(element, index)`.
+ * Supports refinements for type narrowing. The predicate receives
+ * `(element, index)`.
  *
  * **Example** (Taking while condition holds)
  *
@@ -2176,8 +2192,8 @@ export declare const takeWhile: {
      *
      * **Details**
      *
-     * - Supports refinements for type narrowing.
-     * - The predicate receives `(element, index)`.
+     * Supports refinements for type narrowing. The predicate receives
+     * `(element, index)`.
      *
      * **Example** (Taking while condition holds)
      *
@@ -2206,8 +2222,8 @@ export declare const takeWhile: {
      *
      * **Details**
      *
-     * - Supports refinements for type narrowing.
-     * - The predicate receives `(element, index)`.
+     * Supports refinements for type narrowing. The predicate receives
+     * `(element, index)`.
      *
      * **Example** (Taking while condition holds)
      *
@@ -2236,8 +2252,8 @@ export declare const takeWhile: {
      *
      * **Details**
      *
-     * - Supports refinements for type narrowing.
-     * - The predicate receives `(element, index)`.
+     * Supports refinements for type narrowing. The predicate receives
+     * `(element, index)`.
      *
      * **Example** (Taking while condition holds)
      *
@@ -2266,8 +2282,8 @@ export declare const takeWhile: {
      *
      * **Details**
      *
-     * - Supports refinements for type narrowing.
-     * - The predicate receives `(element, index)`.
+     * Supports refinements for type narrowing. The predicate receives
+     * `(element, index)`.
      *
      * **Example** (Taking while condition holds)
      *
@@ -2291,14 +2307,14 @@ export declare const takeWhile: {
  *
  * **When to use**
  *
- * Use when you need to take a prefix of elements while a function can
- * successfully extract or transform them, stopping at the first element
+ * Use when you need to take a prefix from an iterable while a function can
+ * successfully extract or transform elements, stopping at the first element
  * that produces a failure result.
  *
  * **Details**
  *
- * - The filter receives `(element, index)`.
- * - Stops at the first filter failure.
+ * The filter receives `(element, index)` and processing stops at the first
+ * filter failure.
  *
  * @see {@link takeWhile} for taking a prefix based on a boolean predicate
  *
@@ -2311,14 +2327,14 @@ export declare const takeWhileFilter: {
      *
      * **When to use**
      *
-     * Use when you need to take a prefix of elements while a function can
-     * successfully extract or transform them, stopping at the first element
+     * Use when you need to take a prefix from an iterable while a function can
+     * successfully extract or transform elements, stopping at the first element
      * that produces a failure result.
      *
      * **Details**
      *
-     * - The filter receives `(element, index)`.
-     * - Stops at the first filter failure.
+     * The filter receives `(element, index)` and processing stops at the first
+     * filter failure.
      *
      * @see {@link takeWhile} for taking a prefix based on a boolean predicate
      *
@@ -2331,14 +2347,14 @@ export declare const takeWhileFilter: {
      *
      * **When to use**
      *
-     * Use when you need to take a prefix of elements while a function can
-     * successfully extract or transform them, stopping at the first element
+     * Use when you need to take a prefix from an iterable while a function can
+     * successfully extract or transform elements, stopping at the first element
      * that produces a failure result.
      *
      * **Details**
      *
-     * - The filter receives `(element, index)`.
-     * - Stops at the first filter failure.
+     * The filter receives `(element, index)` and processing stops at the first
+     * filter failure.
      *
      * @see {@link takeWhile} for taking a prefix based on a boolean predicate
      *
@@ -2353,14 +2369,14 @@ export declare const takeWhileFilter: {
  *
  * **When to use**
  *
- * Use to split an iterable into the longest prefix that satisfies a predicate
- * and the elements after that prefix when you need both parts.
+ * Use when you need both the longest predicate-matching prefix and the
+ * remaining elements.
  *
  * **Details**
  *
- * - Equivalent to `[takeWhile(pred), dropWhile(pred)]` but more efficient
- *   (single pass).
- * - Supports refinements for type narrowing of the prefix.
+ * Equivalent to `[takeWhile(pred), dropWhile(pred)]`, but more efficient
+ * because it runs in a single pass. Supports refinements for type narrowing of
+ * the prefix.
  *
  * **Example** (Splitting at predicate boundary)
  *
@@ -2384,14 +2400,14 @@ export declare const span: {
      *
      * **When to use**
      *
-     * Use to split an iterable into the longest prefix that satisfies a predicate
-     * and the elements after that prefix when you need both parts.
+     * Use when you need both the longest predicate-matching prefix and the
+     * remaining elements.
      *
      * **Details**
      *
-     * - Equivalent to `[takeWhile(pred), dropWhile(pred)]` but more efficient
-     *   (single pass).
-     * - Supports refinements for type narrowing of the prefix.
+     * Equivalent to `[takeWhile(pred), dropWhile(pred)]`, but more efficient
+     * because it runs in a single pass. Supports refinements for type narrowing of
+     * the prefix.
      *
      * **Example** (Splitting at predicate boundary)
      *
@@ -2415,14 +2431,14 @@ export declare const span: {
      *
      * **When to use**
      *
-     * Use to split an iterable into the longest prefix that satisfies a predicate
-     * and the elements after that prefix when you need both parts.
+     * Use when you need both the longest predicate-matching prefix and the
+     * remaining elements.
      *
      * **Details**
      *
-     * - Equivalent to `[takeWhile(pred), dropWhile(pred)]` but more efficient
-     *   (single pass).
-     * - Supports refinements for type narrowing of the prefix.
+     * Equivalent to `[takeWhile(pred), dropWhile(pred)]`, but more efficient
+     * because it runs in a single pass. Supports refinements for type narrowing of
+     * the prefix.
      *
      * **Example** (Splitting at predicate boundary)
      *
@@ -2446,14 +2462,14 @@ export declare const span: {
      *
      * **When to use**
      *
-     * Use to split an iterable into the longest prefix that satisfies a predicate
-     * and the elements after that prefix when you need both parts.
+     * Use when you need both the longest predicate-matching prefix and the
+     * remaining elements.
      *
      * **Details**
      *
-     * - Equivalent to `[takeWhile(pred), dropWhile(pred)]` but more efficient
-     *   (single pass).
-     * - Supports refinements for type narrowing of the prefix.
+     * Equivalent to `[takeWhile(pred), dropWhile(pred)]`, but more efficient
+     * because it runs in a single pass. Supports refinements for type narrowing of
+     * the prefix.
      *
      * **Example** (Splitting at predicate boundary)
      *
@@ -2477,14 +2493,14 @@ export declare const span: {
      *
      * **When to use**
      *
-     * Use to split an iterable into the longest prefix that satisfies a predicate
-     * and the elements after that prefix when you need both parts.
+     * Use when you need both the longest predicate-matching prefix and the
+     * remaining elements.
      *
      * **Details**
      *
-     * - Equivalent to `[takeWhile(pred), dropWhile(pred)]` but more efficient
-     *   (single pass).
-     * - Supports refinements for type narrowing of the prefix.
+     * Equivalent to `[takeWhile(pred), dropWhile(pred)]`, but more efficient
+     * because it runs in a single pass. Supports refinements for type narrowing of
+     * the prefix.
      *
      * **Example** (Splitting at predicate boundary)
      *
@@ -2513,8 +2529,8 @@ export declare const span: {
  *
  * **Details**
  *
- * - `n` is clamped to `[0, length]`.
- * - Returns a copy of the full array when `n <= 0`.
+ * `n` is clamped to `[0, length]`. When `n <= 0`, this returns a copy of the
+ * full array.
  *
  * **Example** (Dropping from the start)
  *
@@ -2542,8 +2558,8 @@ export declare const drop: {
      *
      * **Details**
      *
-     * - `n` is clamped to `[0, length]`.
-     * - Returns a copy of the full array when `n <= 0`.
+     * `n` is clamped to `[0, length]`. When `n <= 0`, this returns a copy of the
+     * full array.
      *
      * **Example** (Dropping from the start)
      *
@@ -2571,8 +2587,8 @@ export declare const drop: {
      *
      * **Details**
      *
-     * - `n` is clamped to `[0, length]`.
-     * - Returns a copy of the full array when `n <= 0`.
+     * `n` is clamped to `[0, length]`. When `n <= 0`, this returns a copy of the
+     * full array.
      *
      * **Example** (Dropping from the start)
      *
@@ -2754,13 +2770,13 @@ export declare const dropWhile: {
  *
  * **When to use**
  *
- * Use when dropping a prefix requires computing a `Result` per element instead
- * of a simple boolean predicate.
+ * Use when you need to drop a prefix from an iterable by computing a `Result`
+ * per element instead of using a simple boolean predicate.
  *
  * **Details**
  *
- * - The filter receives `(element, index)`.
- * - Returns the remaining original elements after the first filter failure.
+ * The filter receives `(element, index)`. The result contains the remaining
+ * original elements after the first filter failure.
  *
  * @see {@link dropWhile} for dropping a prefix with a simple boolean predicate
  * @see {@link takeWhileFilter} for keeping only the matching prefix
@@ -2774,13 +2790,13 @@ export declare const dropWhileFilter: {
      *
      * **When to use**
      *
-     * Use when dropping a prefix requires computing a `Result` per element instead
-     * of a simple boolean predicate.
+     * Use when you need to drop a prefix from an iterable by computing a `Result`
+     * per element instead of using a simple boolean predicate.
      *
      * **Details**
      *
-     * - The filter receives `(element, index)`.
-     * - Returns the remaining original elements after the first filter failure.
+     * The filter receives `(element, index)`. The result contains the remaining
+     * original elements after the first filter failure.
      *
      * @see {@link dropWhile} for dropping a prefix with a simple boolean predicate
      * @see {@link takeWhileFilter} for keeping only the matching prefix
@@ -2794,13 +2810,13 @@ export declare const dropWhileFilter: {
      *
      * **When to use**
      *
-     * Use when dropping a prefix requires computing a `Result` per element instead
-     * of a simple boolean predicate.
+     * Use when you need to drop a prefix from an iterable by computing a `Result`
+     * per element instead of using a simple boolean predicate.
      *
      * **Details**
      *
-     * - The filter receives `(element, index)`.
-     * - Returns the remaining original elements after the first filter failure.
+     * The filter receives `(element, index)`. The result contains the remaining
+     * original elements after the first filter failure.
      *
      * @see {@link dropWhile} for dropping a prefix with a simple boolean predicate
      * @see {@link takeWhileFilter} for keeping only the matching prefix
@@ -2964,9 +2980,9 @@ export declare const findLastIndex: {
  *
  * **Details**
  *
- * - Accepts a predicate `(a, i) => boolean`, a refinement, or a function
- *   `(a, i) => Option<B>` for simultaneous find-and-transform.
- * - Returns `Option.none()` if no element matches.
+ * Accepts a predicate `(a, i) => boolean`, a refinement, or a function
+ * `(a, i) => Option<B>` for simultaneous find-and-transform. If no element
+ * matches, this returns `Option.none()`.
  *
  * **Example** (Finding the first match)
  *
@@ -2995,9 +3011,9 @@ export declare const findFirst: {
      *
      * **Details**
      *
-     * - Accepts a predicate `(a, i) => boolean`, a refinement, or a function
-     *   `(a, i) => Option<B>` for simultaneous find-and-transform.
-     * - Returns `Option.none()` if no element matches.
+     * Accepts a predicate `(a, i) => boolean`, a refinement, or a function
+     * `(a, i) => Option<B>` for simultaneous find-and-transform. If no element
+     * matches, this returns `Option.none()`.
      *
      * **Example** (Finding the first match)
      *
@@ -3026,9 +3042,9 @@ export declare const findFirst: {
      *
      * **Details**
      *
-     * - Accepts a predicate `(a, i) => boolean`, a refinement, or a function
-     *   `(a, i) => Option<B>` for simultaneous find-and-transform.
-     * - Returns `Option.none()` if no element matches.
+     * Accepts a predicate `(a, i) => boolean`, a refinement, or a function
+     * `(a, i) => Option<B>` for simultaneous find-and-transform. If no element
+     * matches, this returns `Option.none()`.
      *
      * **Example** (Finding the first match)
      *
@@ -3057,9 +3073,9 @@ export declare const findFirst: {
      *
      * **Details**
      *
-     * - Accepts a predicate `(a, i) => boolean`, a refinement, or a function
-     *   `(a, i) => Option<B>` for simultaneous find-and-transform.
-     * - Returns `Option.none()` if no element matches.
+     * Accepts a predicate `(a, i) => boolean`, a refinement, or a function
+     * `(a, i) => Option<B>` for simultaneous find-and-transform. If no element
+     * matches, this returns `Option.none()`.
      *
      * **Example** (Finding the first match)
      *
@@ -3088,9 +3104,9 @@ export declare const findFirst: {
      *
      * **Details**
      *
-     * - Accepts a predicate `(a, i) => boolean`, a refinement, or a function
-     *   `(a, i) => Option<B>` for simultaneous find-and-transform.
-     * - Returns `Option.none()` if no element matches.
+     * Accepts a predicate `(a, i) => boolean`, a refinement, or a function
+     * `(a, i) => Option<B>` for simultaneous find-and-transform. If no element
+     * matches, this returns `Option.none()`.
      *
      * **Example** (Finding the first match)
      *
@@ -3119,9 +3135,9 @@ export declare const findFirst: {
      *
      * **Details**
      *
-     * - Accepts a predicate `(a, i) => boolean`, a refinement, or a function
-     *   `(a, i) => Option<B>` for simultaneous find-and-transform.
-     * - Returns `Option.none()` if no element matches.
+     * Accepts a predicate `(a, i) => boolean`, a refinement, or a function
+     * `(a, i) => Option<B>` for simultaneous find-and-transform. If no element
+     * matches, this returns `Option.none()`.
      *
      * **Example** (Finding the first match)
      *
@@ -3150,9 +3166,9 @@ export declare const findFirst: {
      *
      * **Details**
      *
-     * - Accepts a predicate `(a, i) => boolean`, a refinement, or a function
-     *   `(a, i) => Option<B>` for simultaneous find-and-transform.
-     * - Returns `Option.none()` if no element matches.
+     * Accepts a predicate `(a, i) => boolean`, a refinement, or a function
+     * `(a, i) => Option<B>` for simultaneous find-and-transform. If no element
+     * matches, this returns `Option.none()`.
      *
      * **Example** (Finding the first match)
      *
@@ -3385,8 +3401,8 @@ export declare const findFirstWithIndex: {
  *
  * **Details**
  *
- * - Searches from the end of the array.
- * - Returns `Option.none()` if no element matches.
+ * Searches from the end of the array. If no element matches, this returns
+ * `Option.none()`.
  *
  * **Example** (Finding the last match)
  *
@@ -3413,8 +3429,8 @@ export declare const findLast: {
      *
      * **Details**
      *
-     * - Searches from the end of the array.
-     * - Returns `Option.none()` if no element matches.
+     * Searches from the end of the array. If no element matches, this returns
+     * `Option.none()`.
      *
      * **Example** (Finding the last match)
      *
@@ -3441,8 +3457,8 @@ export declare const findLast: {
      *
      * **Details**
      *
-     * - Searches from the end of the array.
-     * - Returns `Option.none()` if no element matches.
+     * Searches from the end of the array. If no element matches, this returns
+     * `Option.none()`.
      *
      * **Example** (Finding the last match)
      *
@@ -3469,8 +3485,8 @@ export declare const findLast: {
      *
      * **Details**
      *
-     * - Searches from the end of the array.
-     * - Returns `Option.none()` if no element matches.
+     * Searches from the end of the array. If no element matches, this returns
+     * `Option.none()`.
      *
      * **Example** (Finding the last match)
      *
@@ -3497,8 +3513,8 @@ export declare const findLast: {
      *
      * **Details**
      *
-     * - Searches from the end of the array.
-     * - Returns `Option.none()` if no element matches.
+     * Searches from the end of the array. If no element matches, this returns
+     * `Option.none()`.
      *
      * **Example** (Finding the last match)
      *
@@ -3525,8 +3541,8 @@ export declare const findLast: {
      *
      * **Details**
      *
-     * - Searches from the end of the array.
-     * - Returns `Option.none()` if no element matches.
+     * Searches from the end of the array. If no element matches, this returns
+     * `Option.none()`.
      *
      * **Example** (Finding the last match)
      *
@@ -3553,8 +3569,8 @@ export declare const findLast: {
      *
      * **Details**
      *
-     * - Searches from the end of the array.
-     * - Returns `Option.none()` if no element matches.
+     * Searches from the end of the array. If no element matches, this returns
+     * `Option.none()`.
      *
      * **Example** (Finding the last match)
      *
@@ -3582,7 +3598,7 @@ export declare const findLast: {
  *
  * **Details**
  *
- * - Valid indices: `0` to `length` (inclusive — inserting at `length` appends).
+ * Valid indices are `0` to `length`, inclusive. Inserting at `length` appends.
  *
  * **Example** (Inserting at an index)
  *
@@ -3609,7 +3625,7 @@ export declare const insertAt: {
      *
      * **Details**
      *
-     * - Valid indices: `0` to `length` (inclusive — inserting at `length` appends).
+     * Valid indices are `0` to `length`, inclusive. Inserting at `length` appends.
      *
      * **Example** (Inserting at an index)
      *
@@ -3636,7 +3652,7 @@ export declare const insertAt: {
      *
      * **Details**
      *
-     * - Valid indices: `0` to `length` (inclusive — inserting at `length` appends).
+     * Valid indices are `0` to `length`, inclusive. Inserting at `length` appends.
      *
      * **Example** (Inserting at an index)
      *
@@ -3664,7 +3680,7 @@ export declare const insertAt: {
  *
  * **Details**
  *
- * - Returns `Option.none()` when the index is out of bounds.
+ * Returns `Option.none()` when the index is out of bounds.
  *
  * **Example** (Replacing an element)
  *
@@ -3691,7 +3707,7 @@ export declare const replace: {
      *
      * **Details**
      *
-     * - Returns `Option.none()` when the index is out of bounds.
+     * Returns `Option.none()` when the index is out of bounds.
      *
      * **Example** (Replacing an element)
      *
@@ -3718,7 +3734,7 @@ export declare const replace: {
      *
      * **Details**
      *
-     * - Returns `Option.none()` when the index is out of bounds.
+     * Returns `Option.none()` when the index is out of bounds.
      *
      * **Example** (Replacing an element)
      *
@@ -3742,12 +3758,12 @@ export declare const replace: {
  *
  * **When to use**
  *
- * Use to derive a replacement value from the current element at a specific
- * index while leaving the other elements unchanged.
+ * Use to derive a replacement value from an array element at a specific index
+ * while leaving the other elements unchanged.
  *
  * **Details**
  *
- * - Returns `Option.none()` when the index is out of bounds.
+ * Returns `Option.none()` when the index is out of bounds.
  *
  * **Example** (Modifying an element)
  *
@@ -3772,12 +3788,12 @@ export declare const modify: {
      *
      * **When to use**
      *
-     * Use to derive a replacement value from the current element at a specific
-     * index while leaving the other elements unchanged.
+     * Use to derive a replacement value from an array element at a specific index
+     * while leaving the other elements unchanged.
      *
      * **Details**
      *
-     * - Returns `Option.none()` when the index is out of bounds.
+     * Returns `Option.none()` when the index is out of bounds.
      *
      * **Example** (Modifying an element)
      *
@@ -3802,12 +3818,12 @@ export declare const modify: {
      *
      * **When to use**
      *
-     * Use to derive a replacement value from the current element at a specific
-     * index while leaving the other elements unchanged.
+     * Use to derive a replacement value from an array element at a specific index
+     * while leaving the other elements unchanged.
      *
      * **Details**
      *
-     * - Returns `Option.none()` when the index is out of bounds.
+     * Returns `Option.none()` when the index is out of bounds.
      *
      * **Example** (Modifying an element)
      *
@@ -3833,7 +3849,8 @@ export declare const modify: {
  *
  * **When to use**
  *
- * Use to remove a single element at a known index.
+ * Use when you want a missing index to be a no-op and need a fresh array result
+ * instead of an optional failure.
  *
  * **Example** (Removing an element)
  *
@@ -3857,7 +3874,8 @@ export declare const remove: {
      *
      * **When to use**
      *
-     * Use to remove a single element at a known index.
+     * Use when you want a missing index to be a no-op and need a fresh array result
+     * instead of an optional failure.
      *
      * **Example** (Removing an element)
      *
@@ -3881,7 +3899,8 @@ export declare const remove: {
      *
      * **When to use**
      *
-     * Use to remove a single element at a known index.
+     * Use when you want a missing index to be a no-op and need a fresh array result
+     * instead of an optional failure.
      *
      * **Example** (Removing an element)
      *
@@ -3905,11 +3924,12 @@ export declare const remove: {
  *
  * **When to use**
  *
- * Use to reverse the order of elements without mutating the original input.
+ * Use to reverse an iterable into a new array without mutating the original
+ * input.
  *
  * **Details**
  *
- * - Preserves `NonEmptyArray` in the return type.
+ * Preserves `NonEmptyArray` in the return type.
  *
  * **Example** (Reversing an array)
  *
@@ -3932,9 +3952,8 @@ export declare const reverse: <S extends Iterable<any>>(self: S) => S extends No
  *
  * **Details**
  *
- * - Preserves `NonEmptyArray` in the return type.
- * - Use {@link sortWith} to sort by a derived key, or {@link sortBy} for
- *   multi-key sorting.
+ * Preserves `NonEmptyArray` in the return type. Use `sortWith` to sort by a
+ * derived key, or `sortBy` for multi-key sorting.
  *
  * **Example** (Sorting numbers)
  *
@@ -3960,9 +3979,8 @@ export declare const sort: {
      *
      * **Details**
      *
-     * - Preserves `NonEmptyArray` in the return type.
-     * - Use {@link sortWith} to sort by a derived key, or {@link sortBy} for
-     *   multi-key sorting.
+     * Preserves `NonEmptyArray` in the return type. Use `sortWith` to sort by a
+     * derived key, or `sortBy` for multi-key sorting.
      *
      * **Example** (Sorting numbers)
      *
@@ -3988,9 +4006,8 @@ export declare const sort: {
      *
      * **Details**
      *
-     * - Preserves `NonEmptyArray` in the return type.
-     * - Use {@link sortWith} to sort by a derived key, or {@link sortBy} for
-     *   multi-key sorting.
+     * Preserves `NonEmptyArray` in the return type. Use `sortWith` to sort by a
+     * derived key, or `sortBy` for multi-key sorting.
      *
      * **Example** (Sorting numbers)
      *
@@ -4016,9 +4033,8 @@ export declare const sort: {
      *
      * **Details**
      *
-     * - Preserves `NonEmptyArray` in the return type.
-     * - Use {@link sortWith} to sort by a derived key, or {@link sortBy} for
-     *   multi-key sorting.
+     * Preserves `NonEmptyArray` in the return type. Use `sortWith` to sort by a
+     * derived key, or `sortBy` for multi-key sorting.
      *
      * **Example** (Sorting numbers)
      *
@@ -4042,12 +4058,12 @@ export declare const sort: {
  *
  * **When to use**
  *
- * Use when values need to be sorted by a derived key, such as a string length
- * or object field, while the output should keep the original values.
+ * Use when you need to sort values by a derived key, such as a string length or
+ * object field, while keeping the original values.
  *
  * **Details**
  *
- * - Equivalent to `sort(Order.mapInput(order, f))` but more convenient.
+ * Equivalent to `sort(Order.mapInput(order, f))`, but more convenient.
  *
  * **Example** (Sorting strings by length)
  *
@@ -4071,12 +4087,12 @@ export declare const sortWith: {
      *
      * **When to use**
      *
-     * Use when values need to be sorted by a derived key, such as a string length
-     * or object field, while the output should keep the original values.
+     * Use when you need to sort values by a derived key, such as a string length or
+     * object field, while keeping the original values.
      *
      * **Details**
      *
-     * - Equivalent to `sort(Order.mapInput(order, f))` but more convenient.
+     * Equivalent to `sort(Order.mapInput(order, f))`, but more convenient.
      *
      * **Example** (Sorting strings by length)
      *
@@ -4100,12 +4116,12 @@ export declare const sortWith: {
      *
      * **When to use**
      *
-     * Use when values need to be sorted by a derived key, such as a string length
-     * or object field, while the output should keep the original values.
+     * Use when you need to sort values by a derived key, such as a string length or
+     * object field, while keeping the original values.
      *
      * **Details**
      *
-     * - Equivalent to `sort(Order.mapInput(order, f))` but more convenient.
+     * Equivalent to `sort(Order.mapInput(order, f))`, but more convenient.
      *
      * **Example** (Sorting strings by length)
      *
@@ -4129,12 +4145,12 @@ export declare const sortWith: {
      *
      * **When to use**
      *
-     * Use when values need to be sorted by a derived key, such as a string length
-     * or object field, while the output should keep the original values.
+     * Use when you need to sort values by a derived key, such as a string length or
+     * object field, while keeping the original values.
      *
      * **Details**
      *
-     * - Equivalent to `sort(Order.mapInput(order, f))` but more convenient.
+     * Equivalent to `sort(Order.mapInput(order, f))`, but more convenient.
      *
      * **Example** (Sorting strings by length)
      *
@@ -4164,8 +4180,8 @@ export declare const sortWith: {
  *
  * **Details**
  *
- * - Data-last only (returns a function).
- * - Preserves `NonEmptyArray` in the return type.
+ * This is data-last only and returns a function. The return type preserves
+ * `NonEmptyArray`.
  *
  * **Example** (Multi-key sorting)
  *
@@ -4202,11 +4218,11 @@ export declare const sortBy: <S extends Iterable<any>>(...orders: ReadonlyArray<
  *
  * **When to use**
  *
- * Use to pair corresponding elements from two iterables when you need simple pairs without a custom combiner.
+ * Use when you need simple pairs of corresponding elements from two iterables.
  *
  * **Details**
  *
- * - Returns `NonEmptyArray` when both inputs are non-empty.
+ * Returns `NonEmptyArray` when both inputs are non-empty.
  *
  * **Example** (Zipping two arrays)
  *
@@ -4229,11 +4245,11 @@ export declare const zip: {
      *
      * **When to use**
      *
-     * Use to pair corresponding elements from two iterables when you need simple pairs without a custom combiner.
+     * Use when you need simple pairs of corresponding elements from two iterables.
      *
      * **Details**
      *
-     * - Returns `NonEmptyArray` when both inputs are non-empty.
+     * Returns `NonEmptyArray` when both inputs are non-empty.
      *
      * **Example** (Zipping two arrays)
      *
@@ -4256,11 +4272,11 @@ export declare const zip: {
      *
      * **When to use**
      *
-     * Use to pair corresponding elements from two iterables when you need simple pairs without a custom combiner.
+     * Use when you need simple pairs of corresponding elements from two iterables.
      *
      * **Details**
      *
-     * - Returns `NonEmptyArray` when both inputs are non-empty.
+     * Returns `NonEmptyArray` when both inputs are non-empty.
      *
      * **Example** (Zipping two arrays)
      *
@@ -4283,11 +4299,11 @@ export declare const zip: {
      *
      * **When to use**
      *
-     * Use to pair corresponding elements from two iterables when you need simple pairs without a custom combiner.
+     * Use when you need simple pairs of corresponding elements from two iterables.
      *
      * **Details**
      *
-     * - Returns `NonEmptyArray` when both inputs are non-empty.
+     * Returns `NonEmptyArray` when both inputs are non-empty.
      *
      * **Example** (Zipping two arrays)
      *
@@ -4310,11 +4326,11 @@ export declare const zip: {
      *
      * **When to use**
      *
-     * Use to pair corresponding elements from two iterables when you need simple pairs without a custom combiner.
+     * Use when you need simple pairs of corresponding elements from two iterables.
      *
      * **Details**
      *
-     * - Returns `NonEmptyArray` when both inputs are non-empty.
+     * Returns `NonEmptyArray` when both inputs are non-empty.
      *
      * **Example** (Zipping two arrays)
      *
@@ -4336,6 +4352,11 @@ export declare const zip: {
  * Combines elements from two iterables pairwise using a function. If the
  * iterables differ in length, extra elements are discarded.
  *
+ * **When to use**
+ *
+ * Use when zipping two iterables in an array pipeline and each pair should
+ * become a computed array element instead of a tuple.
+ *
  * **Example** (Zipping with addition)
  *
  * ```ts
@@ -4354,6 +4375,11 @@ export declare const zipWith: {
      * Combines elements from two iterables pairwise using a function. If the
      * iterables differ in length, extra elements are discarded.
      *
+     * **When to use**
+     *
+     * Use when zipping two iterables in an array pipeline and each pair should
+     * become a computed array element instead of a tuple.
+     *
      * **Example** (Zipping with addition)
      *
      * ```ts
@@ -4372,6 +4398,11 @@ export declare const zipWith: {
      * Combines elements from two iterables pairwise using a function. If the
      * iterables differ in length, extra elements are discarded.
      *
+     * **When to use**
+     *
+     * Use when zipping two iterables in an array pipeline and each pair should
+     * become a computed array element instead of a tuple.
+     *
      * **Example** (Zipping with addition)
      *
      * ```ts
@@ -4390,6 +4421,11 @@ export declare const zipWith: {
      * Combines elements from two iterables pairwise using a function. If the
      * iterables differ in length, extra elements are discarded.
      *
+     * **When to use**
+     *
+     * Use when zipping two iterables in an array pipeline and each pair should
+     * become a computed array element instead of a tuple.
+     *
      * **Example** (Zipping with addition)
      *
      * ```ts
@@ -4408,6 +4444,11 @@ export declare const zipWith: {
      * Combines elements from two iterables pairwise using a function. If the
      * iterables differ in length, extra elements are discarded.
      *
+     * **When to use**
+     *
+     * Use when zipping two iterables in an array pipeline and each pair should
+     * become a computed array element instead of a tuple.
+     *
      * **Example** (Zipping with addition)
      *
      * ```ts
@@ -4449,8 +4490,8 @@ export declare const unzip: <S extends Iterable<readonly [any, any]>>(self: S) =
  *
  * **Details**
  *
- * - Preserves `NonEmptyArray` in the return type.
- * - An empty input produces an empty result.
+ * The return type preserves `NonEmptyArray`. Empty inputs produce an empty
+ * result.
  *
  * **Example** (Interspersing a separator)
  *
@@ -4475,8 +4516,8 @@ export declare const intersperse: {
      *
      * **Details**
      *
-     * - Preserves `NonEmptyArray` in the return type.
-     * - An empty input produces an empty result.
+     * The return type preserves `NonEmptyArray`. Empty inputs produce an empty
+     * result.
      *
      * **Example** (Interspersing a separator)
      *
@@ -4501,8 +4542,8 @@ export declare const intersperse: {
      *
      * **Details**
      *
-     * - Preserves `NonEmptyArray` in the return type.
-     * - An empty input produces an empty result.
+     * The return type preserves `NonEmptyArray`. Empty inputs produce an empty
+     * result.
      *
      * **Example** (Interspersing a separator)
      *
@@ -4527,8 +4568,8 @@ export declare const intersperse: {
      *
      * **Details**
      *
-     * - Preserves `NonEmptyArray` in the return type.
-     * - An empty input produces an empty result.
+     * The return type preserves `NonEmptyArray`. Empty inputs produce an empty
+     * result.
      *
      * **Example** (Interspersing a separator)
      *
@@ -4618,6 +4659,11 @@ export declare const modifyHeadNonEmpty: {
 /**
  * Replaces the first element of a non-empty array with a new value.
  *
+ * **When to use**
+ *
+ * Use when you already know the array is non-empty and the replacement value
+ * does not depend on the current first element.
+ *
  * **Example** (Setting the head)
  *
  * ```ts
@@ -4636,6 +4682,11 @@ export declare const setHeadNonEmpty: {
     /**
      * Replaces the first element of a non-empty array with a new value.
      *
+     * **When to use**
+     *
+     * Use when you already know the array is non-empty and the replacement value
+     * does not depend on the current first element.
+     *
      * **Example** (Setting the head)
      *
      * ```ts
@@ -4654,6 +4705,11 @@ export declare const setHeadNonEmpty: {
     /**
      * Replaces the first element of a non-empty array with a new value.
      *
+     * **When to use**
+     *
+     * Use when you already know the array is non-empty and the replacement value
+     * does not depend on the current first element.
+     *
      * **Example** (Setting the head)
      *
      * ```ts
@@ -4674,6 +4730,11 @@ export declare const setHeadNonEmpty: {
  * Applies a function to the last element of a non-empty array, returning a
  * new array.
  *
+ * **When to use**
+ *
+ * Use when you already know the array is non-empty and the new last element
+ * depends on the current last element.
+ *
  * **Example** (Modifying the last element)
  *
  * ```ts
@@ -4693,6 +4754,11 @@ export declare const modifyLastNonEmpty: {
      * Applies a function to the last element of a non-empty array, returning a
      * new array.
      *
+     * **When to use**
+     *
+     * Use when you already know the array is non-empty and the new last element
+     * depends on the current last element.
+     *
      * **Example** (Modifying the last element)
      *
      * ```ts
@@ -4712,6 +4778,11 @@ export declare const modifyLastNonEmpty: {
      * Applies a function to the last element of a non-empty array, returning a
      * new array.
      *
+     * **When to use**
+     *
+     * Use when you already know the array is non-empty and the new last element
+     * depends on the current last element.
+     *
      * **Example** (Modifying the last element)
      *
      * ```ts
@@ -4731,6 +4802,11 @@ export declare const modifyLastNonEmpty: {
 /**
  * Replaces the last element of a non-empty array with a new value.
  *
+ * **When to use**
+ *
+ * Use when you already know the array is non-empty and the replacement value
+ * does not depend on the current last element.
+ *
  * **Example** (Setting the last element)
  *
  * ```ts
@@ -4749,6 +4825,11 @@ export declare const setLastNonEmpty: {
     /**
      * Replaces the last element of a non-empty array with a new value.
      *
+     * **When to use**
+     *
+     * Use when you already know the array is non-empty and the replacement value
+     * does not depend on the current last element.
+     *
      * **Example** (Setting the last element)
      *
      * ```ts
@@ -4767,6 +4848,11 @@ export declare const setLastNonEmpty: {
     /**
      * Replaces the last element of a non-empty array with a new value.
      *
+     * **When to use**
+     *
+     * Use when you already know the array is non-empty and the replacement value
+     * does not depend on the current last element.
+     *
      * **Example** (Setting the last element)
      *
      * ```ts
@@ -4794,9 +4880,9 @@ export declare const setLastNonEmpty: {
  *
  * **Details**
  *
- * - `n` is rounded to the nearest integer before rotating.
- * - Preserves `NonEmptyArray` in the return type.
- * - Returns a copy for empty arrays or when the normalized rotation is `0`.
+ * `n` is rounded to the nearest integer before rotating. The return type
+ * preserves `NonEmptyArray`. Empty arrays, or rotations normalized to `0`,
+ * return a copy.
  *
  * **Example** (Rotating elements)
  *
@@ -4824,9 +4910,9 @@ export declare const rotate: {
      *
      * **Details**
      *
-     * - `n` is rounded to the nearest integer before rotating.
-     * - Preserves `NonEmptyArray` in the return type.
-     * - Returns a copy for empty arrays or when the normalized rotation is `0`.
+     * `n` is rounded to the nearest integer before rotating. The return type
+     * preserves `NonEmptyArray`. Empty arrays, or rotations normalized to `0`,
+     * return a copy.
      *
      * **Example** (Rotating elements)
      *
@@ -4854,9 +4940,9 @@ export declare const rotate: {
      *
      * **Details**
      *
-     * - `n` is rounded to the nearest integer before rotating.
-     * - Preserves `NonEmptyArray` in the return type.
-     * - Returns a copy for empty arrays or when the normalized rotation is `0`.
+     * `n` is rounded to the nearest integer before rotating. The return type
+     * preserves `NonEmptyArray`. Empty arrays, or rotations normalized to `0`,
+     * return a copy.
      *
      * **Example** (Rotating elements)
      *
@@ -4884,9 +4970,9 @@ export declare const rotate: {
      *
      * **Details**
      *
-     * - `n` is rounded to the nearest integer before rotating.
-     * - Preserves `NonEmptyArray` in the return type.
-     * - Returns a copy for empty arrays or when the normalized rotation is `0`.
+     * `n` is rounded to the nearest integer before rotating. The return type
+     * preserves `NonEmptyArray`. Empty arrays, or rotations normalized to `0`,
+     * return a copy.
      *
      * **Example** (Rotating elements)
      *
@@ -4936,8 +5022,8 @@ export declare const containsWith: <A>(isEquivalent: (self: A, that: A) => boole
  *
  * **When to use**
  *
- * Use to check membership with Effect's default equality instead of providing a
- * comparison function.
+ * Use to check whether an iterable contains a value using Effect's default
+ * equality instead of providing a comparison function.
  *
  * **Example** (Checking membership)
  *
@@ -4959,8 +5045,8 @@ export declare const contains: {
      *
      * **When to use**
      *
-     * Use to check membership with Effect's default equality instead of providing a
-     * comparison function.
+     * Use to check whether an iterable contains a value using Effect's default
+     * equality instead of providing a comparison function.
      *
      * **Example** (Checking membership)
      *
@@ -4982,8 +5068,8 @@ export declare const contains: {
      *
      * **When to use**
      *
-     * Use to check membership with Effect's default equality instead of providing a
-     * comparison function.
+     * Use to check whether an iterable contains a value using Effect's default
+     * equality instead of providing a comparison function.
      *
      * **Example** (Checking membership)
      *
@@ -5006,15 +5092,13 @@ export declare const contains: {
  *
  * **When to use**
  *
- * Use when the grouping logic is custom and each step needs to return both a
- * value and the remaining input.
+ * Use when you need custom grouping logic where each step returns both a value
+ * and the remaining input.
  *
  * **Details**
  *
- * - The function receives a `NonEmptyReadonlyArray` and returns
- *   `[value, rest]`.
- * - Continues until the remaining array is empty.
- * - Useful for custom splitting/grouping logic.
+ * The function receives a `NonEmptyReadonlyArray` and returns `[value, rest]`.
+ * Processing continues until the remaining array is empty.
  *
  * **Example** (Chopping an array)
  *
@@ -5041,15 +5125,13 @@ export declare const chop: {
      *
      * **When to use**
      *
-     * Use when the grouping logic is custom and each step needs to return both a
-     * value and the remaining input.
+     * Use when you need custom grouping logic where each step returns both a value
+     * and the remaining input.
      *
      * **Details**
      *
-     * - The function receives a `NonEmptyReadonlyArray` and returns
-     *   `[value, rest]`.
-     * - Continues until the remaining array is empty.
-     * - Useful for custom splitting/grouping logic.
+     * The function receives a `NonEmptyReadonlyArray` and returns `[value, rest]`.
+     * Processing continues until the remaining array is empty.
      *
      * **Example** (Chopping an array)
      *
@@ -5076,15 +5158,13 @@ export declare const chop: {
      *
      * **When to use**
      *
-     * Use when the grouping logic is custom and each step needs to return both a
-     * value and the remaining input.
+     * Use when you need custom grouping logic where each step returns both a value
+     * and the remaining input.
      *
      * **Details**
      *
-     * - The function receives a `NonEmptyReadonlyArray` and returns
-     *   `[value, rest]`.
-     * - Continues until the remaining array is empty.
-     * - Useful for custom splitting/grouping logic.
+     * The function receives a `NonEmptyReadonlyArray` and returns `[value, rest]`.
+     * Processing continues until the remaining array is empty.
      *
      * **Example** (Chopping an array)
      *
@@ -5111,15 +5191,13 @@ export declare const chop: {
      *
      * **When to use**
      *
-     * Use when the grouping logic is custom and each step needs to return both a
-     * value and the remaining input.
+     * Use when you need custom grouping logic where each step returns both a value
+     * and the remaining input.
      *
      * **Details**
      *
-     * - The function receives a `NonEmptyReadonlyArray` and returns
-     *   `[value, rest]`.
-     * - Continues until the remaining array is empty.
-     * - Useful for custom splitting/grouping logic.
+     * The function receives a `NonEmptyReadonlyArray` and returns `[value, rest]`.
+     * Processing continues until the remaining array is empty.
      *
      * **Example** (Chopping an array)
      *
@@ -5150,8 +5228,8 @@ export declare const chop: {
  *
  * **Details**
  *
- * - `n` can be `0` (all elements in the second array).
- * - `n` is floored to an integer.
+ * `n` can be `0`, in which case all elements are placed in the second array.
+ * The index is floored to an integer.
  *
  * **Example** (Splitting at an index)
  *
@@ -5177,8 +5255,8 @@ export declare const splitAt: {
      *
      * **Details**
      *
-     * - `n` can be `0` (all elements in the second array).
-     * - `n` is floored to an integer.
+     * `n` can be `0`, in which case all elements are placed in the second array.
+     * The index is floored to an integer.
      *
      * **Example** (Splitting at an index)
      *
@@ -5204,8 +5282,8 @@ export declare const splitAt: {
      *
      * **Details**
      *
-     * - `n` can be `0` (all elements in the second array).
-     * - `n` is floored to an integer.
+     * `n` can be `0`, in which case all elements are placed in the second array.
+     * The index is floored to an integer.
      *
      * **Example** (Splitting at an index)
      *
@@ -5227,6 +5305,11 @@ export declare const splitAt: {
  * Splits a non-empty array into two parts at the given index. The first part
  * is guaranteed to be non-empty (`n` is clamped to >= 1).
  *
+ * **When to use**
+ *
+ * Use when downstream code requires the left side of the split to contain at
+ * least one element.
+ *
  * **Example** (Splitting a non-empty array)
  *
  * ```ts
@@ -5246,6 +5329,11 @@ export declare const splitAtNonEmpty: {
      * Splits a non-empty array into two parts at the given index. The first part
      * is guaranteed to be non-empty (`n` is clamped to >= 1).
      *
+     * **When to use**
+     *
+     * Use when downstream code requires the left side of the split to contain at
+     * least one element.
+     *
      * **Example** (Splitting a non-empty array)
      *
      * ```ts
@@ -5265,6 +5353,11 @@ export declare const splitAtNonEmpty: {
      * Splits a non-empty array into two parts at the given index. The first part
      * is guaranteed to be non-empty (`n` is clamped to >= 1).
      *
+     * **When to use**
+     *
+     * Use when downstream code requires the left side of the split to contain at
+     * least one element.
+     *
      * **Example** (Splitting a non-empty array)
      *
      * ```ts
@@ -5290,8 +5383,7 @@ export declare const splitAtNonEmpty: {
  *
  * **Details**
  *
- * - Uses `chunksOf(ceil(length / n))` internally.
- * - The last chunk may be shorter.
+ * Uses `chunksOf(ceil(length / n))` internally. The last chunk may be shorter.
  *
  * **Example** (Splitting into groups)
  *
@@ -5316,8 +5408,7 @@ export declare const split: {
      *
      * **Details**
      *
-     * - Uses `chunksOf(ceil(length / n))` internally.
-     * - The last chunk may be shorter.
+     * Uses `chunksOf(ceil(length / n))` internally. The last chunk may be shorter.
      *
      * **Example** (Splitting into groups)
      *
@@ -5342,8 +5433,7 @@ export declare const split: {
      *
      * **Details**
      *
-     * - Uses `chunksOf(ceil(length / n))` internally.
-     * - The last chunk may be shorter.
+     * Uses `chunksOf(ceil(length / n))` internally. The last chunk may be shorter.
      *
      * **Example** (Splitting into groups)
      *
@@ -5366,7 +5456,8 @@ export declare const split: {
  *
  * **When to use**
  *
- * Use to split an array at a condition boundary when you know which element marks the transition point.
+ * Use when you need to split an array at the first element that marks a
+ * condition boundary.
  *
  * **Example** (Splitting at a condition)
  *
@@ -5389,7 +5480,8 @@ export declare const splitWhere: {
      *
      * **When to use**
      *
-     * Use to split an array at a condition boundary when you know which element marks the transition point.
+     * Use when you need to split an array at the first element that marks a
+     * condition boundary.
      *
      * **Example** (Splitting at a condition)
      *
@@ -5412,7 +5504,8 @@ export declare const splitWhere: {
      *
      * **When to use**
      *
-     * Use to split an array at a condition boundary when you know which element marks the transition point.
+     * Use when you need to split an array at the first element that marks a
+     * condition boundary.
      *
      * **Example** (Splitting at a condition)
      *
@@ -5440,8 +5533,8 @@ export declare const splitWhere: {
  *
  * **Details**
  *
- * - Preserves `NonEmptyArray` in the return type.
- * - Useful when you need a distinct reference (e.g. before mutating).
+ * The return type preserves `NonEmptyArray`. Use this when you need a distinct
+ * reference, for example before mutating the returned array.
  *
  * **Example** (Copying an array)
  *
@@ -5470,8 +5563,8 @@ export declare const copy: {
      *
      * **Details**
      *
-     * - Preserves `NonEmptyArray` in the return type.
-     * - Useful when you need a distinct reference (e.g. before mutating).
+     * The return type preserves `NonEmptyArray`. Use this when you need a distinct
+     * reference, for example before mutating the returned array.
      *
      * **Example** (Copying an array)
      *
@@ -5500,8 +5593,8 @@ export declare const copy: {
      *
      * **Details**
      *
-     * - Preserves `NonEmptyArray` in the return type.
-     * - Useful when you need a distinct reference (e.g. before mutating).
+     * The return type preserves `NonEmptyArray`. Use this when you need a distinct
+     * reference, for example before mutating the returned array.
      *
      * **Example** (Copying an array)
      *
@@ -5531,7 +5624,7 @@ export declare const copy: {
  *
  * **Details**
  *
- * - Returns an empty array when `n <= 0`.
+ * Returns an empty array when `n <= 0`.
  *
  * **Example** (Padding an array)
  *
@@ -5558,7 +5651,7 @@ export declare const pad: {
      *
      * **Details**
      *
-     * - Returns an empty array when `n <= 0`.
+     * Returns an empty array when `n <= 0`.
      *
      * **Example** (Padding an array)
      *
@@ -5585,7 +5678,7 @@ export declare const pad: {
      *
      * **Details**
      *
-     * - Returns an empty array when `n <= 0`.
+     * Returns an empty array when `n <= 0`.
      *
      * **Example** (Padding an array)
      *
@@ -5609,14 +5702,13 @@ export declare const pad: {
  *
  * **When to use**
  *
- * Use to divide an iterable into non-overlapping chunks with a maximum chunk
- * size.
+ * Use to divide an iterable into a new array of non-overlapping chunks with a
+ * maximum chunk size.
  *
  * **Details**
  *
- * - `chunksOf(n)([])` is `[]`, not `[[]]`.
- * - Each chunk is a `NonEmptyArray`.
- * - Preserves `NonEmptyArray` in the outer return type.
+ * `chunksOf(n)([])` is `[]`, not `[[]]`. Each chunk is a `NonEmptyArray`, and
+ * the outer return type preserves `NonEmptyArray`.
  *
  * **Example** (Chunking an array)
  *
@@ -5639,14 +5731,13 @@ export declare const chunksOf: {
      *
      * **When to use**
      *
-     * Use to divide an iterable into non-overlapping chunks with a maximum chunk
-     * size.
+     * Use to divide an iterable into a new array of non-overlapping chunks with a
+     * maximum chunk size.
      *
      * **Details**
      *
-     * - `chunksOf(n)([])` is `[]`, not `[[]]`.
-     * - Each chunk is a `NonEmptyArray`.
-     * - Preserves `NonEmptyArray` in the outer return type.
+     * `chunksOf(n)([])` is `[]`, not `[[]]`. Each chunk is a `NonEmptyArray`, and
+     * the outer return type preserves `NonEmptyArray`.
      *
      * **Example** (Chunking an array)
      *
@@ -5669,14 +5760,13 @@ export declare const chunksOf: {
      *
      * **When to use**
      *
-     * Use to divide an iterable into non-overlapping chunks with a maximum chunk
-     * size.
+     * Use to divide an iterable into a new array of non-overlapping chunks with a
+     * maximum chunk size.
      *
      * **Details**
      *
-     * - `chunksOf(n)([])` is `[]`, not `[[]]`.
-     * - Each chunk is a `NonEmptyArray`.
-     * - Preserves `NonEmptyArray` in the outer return type.
+     * `chunksOf(n)([])` is `[]`, not `[[]]`. Each chunk is a `NonEmptyArray`, and
+     * the outer return type preserves `NonEmptyArray`.
      *
      * **Example** (Chunking an array)
      *
@@ -5699,14 +5789,13 @@ export declare const chunksOf: {
      *
      * **When to use**
      *
-     * Use to divide an iterable into non-overlapping chunks with a maximum chunk
-     * size.
+     * Use to divide an iterable into a new array of non-overlapping chunks with a
+     * maximum chunk size.
      *
      * **Details**
      *
-     * - `chunksOf(n)([])` is `[]`, not `[[]]`.
-     * - Each chunk is a `NonEmptyArray`.
-     * - Preserves `NonEmptyArray` in the outer return type.
+     * `chunksOf(n)([])` is `[]`, not `[[]]`. Each chunk is a `NonEmptyArray`, and
+     * the outer return type preserves `NonEmptyArray`.
      *
      * **Example** (Chunking an array)
      *
@@ -5733,8 +5822,8 @@ export declare const chunksOf: {
  *
  * **Details**
  *
- * - Returns an empty array if `n <= 0` or the array has fewer than `n` elements.
- * - Each window is a tuple of exactly `n` elements.
+ * Returns an empty array if `n <= 0` or the array has fewer than `n` elements.
+ * Each window is a tuple of exactly `n` elements.
  *
  * **Example** (Sliding windows)
  *
@@ -5760,8 +5849,8 @@ export declare const window: {
      *
      * **Details**
      *
-     * - Returns an empty array if `n <= 0` or the array has fewer than `n` elements.
-     * - Each window is a tuple of exactly `n` elements.
+     * Returns an empty array if `n <= 0` or the array has fewer than `n` elements.
+     * Each window is a tuple of exactly `n` elements.
      *
      * **Example** (Sliding windows)
      *
@@ -5787,8 +5876,8 @@ export declare const window: {
      *
      * **Details**
      *
-     * - Returns an empty array if `n <= 0` or the array has fewer than `n` elements.
-     * - Each window is a tuple of exactly `n` elements.
+     * Returns an empty array if `n <= 0` or the array has fewer than `n` elements.
+     * Each window is a tuple of exactly `n` elements.
      *
      * **Example** (Sliding windows)
      *
@@ -5811,13 +5900,13 @@ export declare const window: {
  *
  * **When to use**
  *
- * Use when a non-empty array is already arranged so matching elements are
- * adjacent and you need a custom equivalence function.
+ * Use when you already have a non-empty array arranged so matching elements are
+ * adjacent and need a custom equivalence function.
  *
  * **Details**
  *
- * - Only groups **adjacent** elements — non-adjacent duplicates stay separate.
- * - Requires a `NonEmptyReadonlyArray`.
+ * Only adjacent elements are grouped. Non-adjacent duplicates stay separate.
+ * Requires a `NonEmptyReadonlyArray`.
  *
  * **Example** (Grouping consecutive equal elements)
  *
@@ -5840,13 +5929,13 @@ export declare const groupWith: {
      *
      * **When to use**
      *
-     * Use when a non-empty array is already arranged so matching elements are
-     * adjacent and you need a custom equivalence function.
+     * Use when you already have a non-empty array arranged so matching elements are
+     * adjacent and need a custom equivalence function.
      *
      * **Details**
      *
-     * - Only groups **adjacent** elements — non-adjacent duplicates stay separate.
-     * - Requires a `NonEmptyReadonlyArray`.
+     * Only adjacent elements are grouped. Non-adjacent duplicates stay separate.
+     * Requires a `NonEmptyReadonlyArray`.
      *
      * **Example** (Grouping consecutive equal elements)
      *
@@ -5869,13 +5958,13 @@ export declare const groupWith: {
      *
      * **When to use**
      *
-     * Use when a non-empty array is already arranged so matching elements are
-     * adjacent and you need a custom equivalence function.
+     * Use when you already have a non-empty array arranged so matching elements are
+     * adjacent and need a custom equivalence function.
      *
      * **Details**
      *
-     * - Only groups **adjacent** elements — non-adjacent duplicates stay separate.
-     * - Requires a `NonEmptyReadonlyArray`.
+     * Only adjacent elements are grouped. Non-adjacent duplicates stay separate.
+     * Requires a `NonEmptyReadonlyArray`.
      *
      * **Example** (Grouping consecutive equal elements)
      *
@@ -5899,12 +5988,12 @@ export declare const groupWith: {
  *
  * **When to use**
  *
- * Use when equal values are already adjacent and Effect's default equality is
- * the right comparison.
+ * Use when you already have adjacent equal values and Effect's default equality
+ * is the right comparison.
  *
  * **Details**
  *
- * - Only groups **adjacent** elements.
+ * Only adjacent elements are grouped.
  *
  * **Example** (Grouping adjacent equal elements)
  *
@@ -5931,9 +6020,8 @@ export declare const group: <A>(self: NonEmptyReadonlyArray<A>) => NonEmptyArray
  *
  * **Details**
  *
- * - Unlike {@link group}/{@link groupWith}, elements do not need to be
- *   adjacent to be grouped together.
- * - Key function must return a `string` or `symbol`.
+ * Unlike `group` and `groupWith`, elements do not need to be adjacent to be
+ * grouped together. The key function must return a `string` or `symbol`.
  *
  * **Example** (Grouping by a property)
  *
@@ -5968,9 +6056,8 @@ export declare const groupBy: {
      *
      * **Details**
      *
-     * - Unlike {@link group}/{@link groupWith}, elements do not need to be
-     *   adjacent to be grouped together.
-     * - Key function must return a `string` or `symbol`.
+     * Unlike `group` and `groupWith`, elements do not need to be adjacent to be
+     * grouped together. The key function must return a `string` or `symbol`.
      *
      * **Example** (Grouping by a property)
      *
@@ -6005,9 +6092,8 @@ export declare const groupBy: {
      *
      * **Details**
      *
-     * - Unlike {@link group}/{@link groupWith}, elements do not need to be
-     *   adjacent to be grouped together.
-     * - Key function must return a `string` or `symbol`.
+     * Unlike `group` and `groupWith`, elements do not need to be adjacent to be
+     * grouped together. The key function must return a `string` or `symbol`.
      *
      * **Example** (Grouping by a property)
      *
@@ -6266,8 +6352,8 @@ export declare const union: {
  *
  * **When to use**
  *
- * Use when keeping only values present in both arrays and equality must be
- * defined by a custom comparator, such as matching objects by id.
+ * Use when you need to keep only values present in both arrays and equality
+ * must be defined by a custom comparator, such as matching objects by id.
  *
  * **Example** (Intersection with custom equality)
  *
@@ -6295,6 +6381,11 @@ export declare const intersectionWith: <A>(isEquivalent: (self: A, that: A) => b
  * Computes the intersection of two arrays using `Equal.equivalence()`. Order is
  * determined by the first array.
  *
+ * **When to use**
+ *
+ * Use when Effect equality is the right membership test and you want to keep
+ * values present in both inputs while preserving the first input's order.
+ *
  * **Example** (Array intersection)
  *
  * ```ts
@@ -6315,6 +6406,11 @@ export declare const intersection: {
      * Computes the intersection of two arrays using `Equal.equivalence()`. Order is
      * determined by the first array.
      *
+     * **When to use**
+     *
+     * Use when Effect equality is the right membership test and you want to keep
+     * values present in both inputs while preserving the first input's order.
+     *
      * **Example** (Array intersection)
      *
      * ```ts
@@ -6335,6 +6431,11 @@ export declare const intersection: {
      * Computes the intersection of two arrays using `Equal.equivalence()`. Order is
      * determined by the first array.
      *
+     * **When to use**
+     *
+     * Use when Effect equality is the right membership test and you want to keep
+     * values present in both inputs while preserving the first input's order.
+     *
      * **Example** (Array intersection)
      *
      * ```ts
@@ -6358,8 +6459,8 @@ export declare const intersection: {
  *
  * **When to use**
  *
- * Use when keeping only values from the first array and equality must be
- * defined by a custom comparator, such as matching objects by id.
+ * Use when you need to keep only values from the first array and equality must
+ * be defined by a custom comparator, such as matching objects by id.
  *
  * **Example** (Difference with custom equality)
  *
@@ -6604,8 +6705,8 @@ export declare namespace ReadonlyArray {
  *
  * **Details**
  *
- * - The function receives `(element, index)`.
- * - Preserves `NonEmptyArray` in the return type.
+ * The function receives `(element, index)`. The return type preserves
+ * `NonEmptyArray`.
  *
  * **Example** (Doubling values)
  *
@@ -6630,8 +6731,8 @@ export declare const map: {
      *
      * **Details**
      *
-     * - The function receives `(element, index)`.
-     * - Preserves `NonEmptyArray` in the return type.
+     * The function receives `(element, index)`. The return type preserves
+     * `NonEmptyArray`.
      *
      * **Example** (Doubling values)
      *
@@ -6656,8 +6757,8 @@ export declare const map: {
      *
      * **Details**
      *
-     * - The function receives `(element, index)`.
-     * - Preserves `NonEmptyArray` in the return type.
+     * The function receives `(element, index)`. The return type preserves
+     * `NonEmptyArray`.
      *
      * **Example** (Doubling values)
      *
@@ -6679,13 +6780,13 @@ export declare const map: {
  *
  * **When to use**
  *
- * Use to map each element to zero or more values and concatenate the results in
- * one pass.
+ * Use to map each array element to zero or more values and concatenate the
+ * results in one pass.
  *
  * **Details**
  *
- * - The function receives `(element, index)`.
- * - Returns `NonEmptyArray` when both input and mapped arrays are non-empty.
+ * The function receives `(element, index)`. This returns `NonEmptyArray` when
+ * both the input and mapped arrays are non-empty.
  *
  * **Example** (FlatMapping an array)
  *
@@ -6707,13 +6808,13 @@ export declare const flatMap: {
      *
      * **When to use**
      *
-     * Use to map each element to zero or more values and concatenate the results in
-     * one pass.
+     * Use to map each array element to zero or more values and concatenate the
+     * results in one pass.
      *
      * **Details**
      *
-     * - The function receives `(element, index)`.
-     * - Returns `NonEmptyArray` when both input and mapped arrays are non-empty.
+     * The function receives `(element, index)`. This returns `NonEmptyArray` when
+     * both the input and mapped arrays are non-empty.
      *
      * **Example** (FlatMapping an array)
      *
@@ -6735,13 +6836,13 @@ export declare const flatMap: {
      *
      * **When to use**
      *
-     * Use to map each element to zero or more values and concatenate the results in
-     * one pass.
+     * Use to map each array element to zero or more values and concatenate the
+     * results in one pass.
      *
      * **Details**
      *
-     * - The function receives `(element, index)`.
-     * - Returns `NonEmptyArray` when both input and mapped arrays are non-empty.
+     * The function receives `(element, index)`. This returns `NonEmptyArray` when
+     * both the input and mapped arrays are non-empty.
      *
      * **Example** (FlatMapping an array)
      *
@@ -6763,13 +6864,13 @@ export declare const flatMap: {
      *
      * **When to use**
      *
-     * Use to map each element to zero or more values and concatenate the results in
-     * one pass.
+     * Use to map each array element to zero or more values and concatenate the
+     * results in one pass.
      *
      * **Details**
      *
-     * - The function receives `(element, index)`.
-     * - Returns `NonEmptyArray` when both input and mapped arrays are non-empty.
+     * The function receives `(element, index)`. This returns `NonEmptyArray` when
+     * both the input and mapped arrays are non-empty.
      *
      * **Example** (FlatMapping an array)
      *
@@ -6814,8 +6915,8 @@ export declare const flatten: <const S extends ReadonlyArray<ReadonlyArray<any>>
  *
  * **When to use**
  *
- * Use to collect only present values from `Option` values while discarding
- * `None` values.
+ * Use to collect only present values from an iterable of `Option` values while
+ * discarding `None` values.
  *
  * **Example** (Extracting Some values)
  *
@@ -6838,8 +6939,8 @@ export declare const getSomes: <T extends Iterable<Option.Option<X>>, X = any>(s
  *
  * **When to use**
  *
- * Use to collect only failure values from `Result` values while discarding
- * successes.
+ * Use when you can drop the success channel and only need the failure
+ * payloads, not the original result wrappers.
  *
  * **Example** (Extracting failures)
  *
@@ -6863,8 +6964,8 @@ export declare const getFailures: <T extends Iterable<Result.Result<any, any>>>(
  *
  * **When to use**
  *
- * Use to collect only success values from `Result` values while discarding
- * failures.
+ * Use when you can drop the failure channel and only need the success
+ * payloads, not the original result wrappers.
  *
  * **Example** (Extracting successes)
  *
@@ -6887,13 +6988,12 @@ export declare const getSuccesses: <T extends Iterable<Result.Result<any, any>>>
  *
  * **When to use**
  *
- * Use to transform elements with a `Result`-returning filter while discarding
- * failures.
+ * Use to filter an iterable with a `Result`-returning transformation while
+ * discarding failures.
  *
  * **Details**
  *
- * - The filter receives `(element, index)`.
- * - Failures are discarded.
+ * The filter receives `(element, index)`. Failures are discarded.
  *
  * **Example** (Filter and transform)
  *
@@ -6916,13 +7016,12 @@ export declare const filterMap: {
      *
      * **When to use**
      *
-     * Use to transform elements with a `Result`-returning filter while discarding
-     * failures.
+     * Use to filter an iterable with a `Result`-returning transformation while
+     * discarding failures.
      *
      * **Details**
      *
-     * - The filter receives `(element, index)`.
-     * - Failures are discarded.
+     * The filter receives `(element, index)`. Failures are discarded.
      *
      * **Example** (Filter and transform)
      *
@@ -6945,13 +7044,12 @@ export declare const filterMap: {
      *
      * **When to use**
      *
-     * Use to transform elements with a `Result`-returning filter while discarding
-     * failures.
+     * Use to filter an iterable with a `Result`-returning transformation while
+     * discarding failures.
      *
      * **Details**
      *
-     * - The filter receives `(element, index)`.
-     * - Failures are discarded.
+     * The filter receives `(element, index)`. Failures are discarded.
      *
      * **Example** (Filter and transform)
      *
@@ -6975,12 +7073,13 @@ export declare const filterMap: {
  *
  * **When to use**
  *
- * Use to keep original elements that satisfy a boolean predicate or refinement.
+ * Use to filter an iterable into a new array of original elements that satisfy
+ * a boolean predicate or refinement.
  *
  * **Details**
  *
- * - The predicate receives `(element, index)`.
- * - Supports refinements for type narrowing.
+ * The predicate receives `(element, index)`. Refinements are supported for type
+ * narrowing.
  *
  * **Example** (Filtering even numbers)
  *
@@ -7002,12 +7101,13 @@ export declare const filter: {
      *
      * **When to use**
      *
-     * Use to keep original elements that satisfy a boolean predicate or refinement.
+     * Use to filter an iterable into a new array of original elements that satisfy
+     * a boolean predicate or refinement.
      *
      * **Details**
      *
-     * - The predicate receives `(element, index)`.
-     * - Supports refinements for type narrowing.
+     * The predicate receives `(element, index)`. Refinements are supported for type
+     * narrowing.
      *
      * **Example** (Filtering even numbers)
      *
@@ -7029,12 +7129,13 @@ export declare const filter: {
      *
      * **When to use**
      *
-     * Use to keep original elements that satisfy a boolean predicate or refinement.
+     * Use to filter an iterable into a new array of original elements that satisfy
+     * a boolean predicate or refinement.
      *
      * **Details**
      *
-     * - The predicate receives `(element, index)`.
-     * - Supports refinements for type narrowing.
+     * The predicate receives `(element, index)`. Refinements are supported for type
+     * narrowing.
      *
      * **Example** (Filtering even numbers)
      *
@@ -7056,12 +7157,13 @@ export declare const filter: {
      *
      * **When to use**
      *
-     * Use to keep original elements that satisfy a boolean predicate or refinement.
+     * Use to filter an iterable into a new array of original elements that satisfy
+     * a boolean predicate or refinement.
      *
      * **Details**
      *
-     * - The predicate receives `(element, index)`.
-     * - Supports refinements for type narrowing.
+     * The predicate receives `(element, index)`. Refinements are supported for type
+     * narrowing.
      *
      * **Example** (Filtering even numbers)
      *
@@ -7083,12 +7185,13 @@ export declare const filter: {
      *
      * **When to use**
      *
-     * Use to keep original elements that satisfy a boolean predicate or refinement.
+     * Use to filter an iterable into a new array of original elements that satisfy
+     * a boolean predicate or refinement.
      *
      * **Details**
      *
-     * - The predicate receives `(element, index)`.
-     * - Supports refinements for type narrowing.
+     * The predicate receives `(element, index)`. Refinements are supported for type
+     * narrowing.
      *
      * **Example** (Filtering even numbers)
      *
@@ -7111,13 +7214,12 @@ export declare const filter: {
  *
  * **When to use**
  *
- * Use to evaluate each element with a `Result`-returning filter and keep both
- * failure and success values.
+ * Use to partition an iterable by evaluating each element with a
+ * `Result`-returning filter and keeping both failure and success values.
  *
  * **Details**
  *
- * - Returns `[excluded, satisfying]`.
- * - The filter receives `(element, index)`.
+ * Returns `[excluded, satisfying]`. The filter receives `(element, index)`.
  *
  * **Example** (Partitioning with a filter)
  *
@@ -7143,13 +7245,12 @@ export declare const partition: {
      *
      * **When to use**
      *
-     * Use to evaluate each element with a `Result`-returning filter and keep both
-     * failure and success values.
+     * Use to partition an iterable by evaluating each element with a
+     * `Result`-returning filter and keeping both failure and success values.
      *
      * **Details**
      *
-     * - Returns `[excluded, satisfying]`.
-     * - The filter receives `(element, index)`.
+     * Returns `[excluded, satisfying]`. The filter receives `(element, index)`.
      *
      * **Example** (Partitioning with a filter)
      *
@@ -7175,13 +7276,12 @@ export declare const partition: {
      *
      * **When to use**
      *
-     * Use to evaluate each element with a `Result`-returning filter and keep both
-     * failure and success values.
+     * Use to partition an iterable by evaluating each element with a
+     * `Result`-returning filter and keeping both failure and success values.
      *
      * **Details**
      *
-     * - Returns `[excluded, satisfying]`.
-     * - The filter receives `(element, index)`.
+     * Returns `[excluded, satisfying]`. The filter receives `(element, index)`.
      *
      * **Example** (Partitioning with a filter)
      *
@@ -7208,12 +7308,12 @@ export declare const partition: {
  *
  * **When to use**
  *
- * Use to split existing `Result` values into failure and success arrays.
+ * Use to split an iterable of `Result` values into failure and success arrays.
  *
  * **Details**
  *
- * - Returns `[failures, successes]`.
- * - Equivalent to `partition(identity)`.
+ * Returns `[failures, successes]`. This is equivalent to
+ * `partition(identity)`.
  *
  * **Example** (Separating Results)
  *
@@ -7247,7 +7347,7 @@ export declare const separate: <T extends Iterable<Result.Result<any, any>>>(sel
  *
  * **Details**
  *
- * - The function receives `(accumulator, element, index)`.
+ * The function receives `(accumulator, element, index)`.
  *
  * **Example** (Summing an array)
  *
@@ -7273,7 +7373,7 @@ export declare const reduce: {
      *
      * **Details**
      *
-     * - The function receives `(accumulator, element, index)`.
+     * The function receives `(accumulator, element, index)`.
      *
      * **Example** (Summing an array)
      *
@@ -7299,7 +7399,7 @@ export declare const reduce: {
      *
      * **Details**
      *
-     * - The function receives `(accumulator, element, index)`.
+     * The function receives `(accumulator, element, index)`.
      *
      * **Example** (Summing an array)
      *
@@ -7322,12 +7422,11 @@ export declare const reduce: {
  *
  * **When to use**
  *
- * Use when folding order matters and values must be combined from right to
- * left.
+ * Use when you need to fold values from right to left.
  *
  * **Details**
  *
- * - The function receives `(accumulator, element, index)`.
+ * The function receives `(accumulator, element, index)`.
  *
  * **Example** (Right-to-left fold)
  *
@@ -7349,12 +7448,11 @@ export declare const reduceRight: {
      *
      * **When to use**
      *
-     * Use when folding order matters and values must be combined from right to
-     * left.
+     * Use when you need to fold values from right to left.
      *
      * **Details**
      *
-     * - The function receives `(accumulator, element, index)`.
+     * The function receives `(accumulator, element, index)`.
      *
      * **Example** (Right-to-left fold)
      *
@@ -7376,12 +7474,11 @@ export declare const reduceRight: {
      *
      * **When to use**
      *
-     * Use when folding order matters and values must be combined from right to
-     * left.
+     * Use when you need to fold values from right to left.
      *
      * **Details**
      *
-     * - The function receives `(accumulator, element, index)`.
+     * The function receives `(accumulator, element, index)`.
      *
      * **Example** (Right-to-left fold)
      *
@@ -7447,6 +7544,11 @@ export declare const liftPredicate: {
  * Lifts an `Option`-returning function into one that returns an array:
  * `Some(a)` becomes `[a]`, `None` becomes `[]`.
  *
+ * **When to use**
+ *
+ * Use when an optional parser or lookup should participate in array pipelines
+ * as zero-or-one results.
+ *
  * **Example** (Lifting an Option function)
  *
  * ```ts
@@ -7522,7 +7624,7 @@ export declare const liftNullishOr: <A extends Array<unknown>, B>(f: (...a: A) =
  *
  * **When to use**
  *
- * Use when mapping and filtering in one step, where the mapper can return
+ * Use when you need to map and filter in one step, where the mapper can return
  * `null` or `undefined` to skip elements.
  *
  * **Example** (FlatMapping with nullable)
@@ -7547,7 +7649,7 @@ export declare const flatMapNullishOr: {
      *
      * **When to use**
      *
-     * Use when mapping and filtering in one step, where the mapper can return
+     * Use when you need to map and filter in one step, where the mapper can return
      * `null` or `undefined` to skip elements.
      *
      * **Example** (FlatMapping with nullable)
@@ -7572,7 +7674,7 @@ export declare const flatMapNullishOr: {
      *
      * **When to use**
      *
-     * Use when mapping and filtering in one step, where the mapper can return
+     * Use when you need to map and filter in one step, where the mapper can return
      * `null` or `undefined` to skip elements.
      *
      * **Example** (FlatMapping with nullable)
@@ -7596,6 +7698,11 @@ export declare const flatMapNullishOr: {
  * Lifts a `Result`-returning function into one that returns an array: failures
  * produce `[]`, successes produce `[value]`.
  *
+ * **When to use**
+ *
+ * Use when a fallible parser or lookup should participate in array pipelines as
+ * zero-or-one results and the failure value should be discarded.
+ *
  * **Example** (Lifting a Result function)
  *
  * ```ts
@@ -7624,7 +7731,7 @@ export declare const liftResult: <A extends Array<unknown>, E, B>(f: (...a: A) =
  *
  * **When to use**
  *
- * Use to check that all elements satisfy a predicate, including
+ * Use to check whether every array element satisfies a predicate, including
  * refinement-based type narrowing.
  *
  * **Example** (Testing all elements)
@@ -7648,7 +7755,7 @@ export declare const every: {
      *
      * **When to use**
      *
-     * Use to check that all elements satisfy a predicate, including
+     * Use to check whether every array element satisfies a predicate, including
      * refinement-based type narrowing.
      *
      * **Example** (Testing all elements)
@@ -7672,7 +7779,7 @@ export declare const every: {
      *
      * **When to use**
      *
-     * Use to check that all elements satisfy a predicate, including
+     * Use to check whether every array element satisfies a predicate, including
      * refinement-based type narrowing.
      *
      * **Example** (Testing all elements)
@@ -7696,7 +7803,7 @@ export declare const every: {
      *
      * **When to use**
      *
-     * Use to check that all elements satisfy a predicate, including
+     * Use to check whether every array element satisfies a predicate, including
      * refinement-based type narrowing.
      *
      * **Example** (Testing all elements)
@@ -7720,7 +7827,7 @@ export declare const every: {
      *
      * **When to use**
      *
-     * Use to check that all elements satisfy a predicate, including
+     * Use to check whether every array element satisfies a predicate, including
      * refinement-based type narrowing.
      *
      * **Example** (Testing all elements)
@@ -7806,12 +7913,12 @@ export declare const some: {
  *
  * **When to use**
  *
- * Use when a computation depends on every suffix of an array, such as
+ * Use when you need to compute a result from every suffix of an array, such as
  * cumulative aggregations from each position.
  *
  * **Details**
  *
- * - For index `i`, the function receives `self.slice(i)`.
+ * For index `i`, the function receives `self.slice(i)`.
  *
  * **Example** (Suffix lengths)
  *
@@ -7833,12 +7940,12 @@ export declare const extend: {
      *
      * **When to use**
      *
-     * Use when a computation depends on every suffix of an array, such as
+     * Use when you need to compute a result from every suffix of an array, such as
      * cumulative aggregations from each position.
      *
      * **Details**
      *
-     * - For index `i`, the function receives `self.slice(i)`.
+     * For index `i`, the function receives `self.slice(i)`.
      *
      * **Example** (Suffix lengths)
      *
@@ -7860,12 +7967,12 @@ export declare const extend: {
      *
      * **When to use**
      *
-     * Use when a computation depends on every suffix of an array, such as
+     * Use when you need to compute a result from every suffix of an array, such as
      * cumulative aggregations from each position.
      *
      * **Details**
      *
-     * - For index `i`, the function receives `self.slice(i)`.
+     * For index `i`, the function receives `self.slice(i)`.
      *
      * **Example** (Suffix lengths)
      *
@@ -8258,7 +8365,7 @@ export declare const dedupe: <S extends Iterable<any>>(self: S) => S extends Non
  *
  * **Details**
  *
- * - Non-adjacent duplicates are preserved.
+ * Non-adjacent duplicates are preserved.
  *
  * **Example** (Deduplicating adjacent elements)
  *
@@ -8287,7 +8394,7 @@ export declare const dedupeAdjacentWith: {
      *
      * **Details**
      *
-     * - Non-adjacent duplicates are preserved.
+     * Non-adjacent duplicates are preserved.
      *
      * **Example** (Deduplicating adjacent elements)
      *
@@ -8316,7 +8423,7 @@ export declare const dedupeAdjacentWith: {
      *
      * **Details**
      *
-     * - Non-adjacent duplicates are preserved.
+     * Non-adjacent duplicates are preserved.
      *
      * **Example** (Deduplicating adjacent elements)
      *
@@ -8415,15 +8522,15 @@ export declare const join: {
  *
  * **When to use**
  *
- * Use when mapping needs state threaded through each element and the final state
- * is also needed.
+ * Use when you need to map while threading state through each element and keep
+ * the final state.
  *
  * **Details**
  *
- * - Combines `map` and `reduce` in a single pass.
- * - The callback receives the current state, element, and index, and returns `[nextState, mappedValue]`.
- * - Returns `[finalState, mappedArray]`.
- * - Dual: can be used in both data-first and data-last style.
+ * Combines `map` and `reduce` in a single pass. The callback receives the
+ * current state, element, and index, and returns `[nextState, mappedValue]`.
+ * The result is `[finalState, mappedArray]`. This can be used in both
+ * data-first and data-last style.
  *
  * **Example** (Running sum alongside mapped values)
  *
@@ -8446,15 +8553,15 @@ export declare const mapAccum: {
      *
      * **When to use**
      *
-     * Use when mapping needs state threaded through each element and the final state
-     * is also needed.
+     * Use when you need to map while threading state through each element and keep
+     * the final state.
      *
      * **Details**
      *
-     * - Combines `map` and `reduce` in a single pass.
-     * - The callback receives the current state, element, and index, and returns `[nextState, mappedValue]`.
-     * - Returns `[finalState, mappedArray]`.
-     * - Dual: can be used in both data-first and data-last style.
+     * Combines `map` and `reduce` in a single pass. The callback receives the
+     * current state, element, and index, and returns `[nextState, mappedValue]`.
+     * The result is `[finalState, mappedArray]`. This can be used in both
+     * data-first and data-last style.
      *
      * **Example** (Running sum alongside mapped values)
      *
@@ -8477,15 +8584,15 @@ export declare const mapAccum: {
      *
      * **When to use**
      *
-     * Use when mapping needs state threaded through each element and the final state
-     * is also needed.
+     * Use when you need to map while threading state through each element and keep
+     * the final state.
      *
      * **Details**
      *
-     * - Combines `map` and `reduce` in a single pass.
-     * - The callback receives the current state, element, and index, and returns `[nextState, mappedValue]`.
-     * - Returns `[finalState, mappedArray]`.
-     * - Dual: can be used in both data-first and data-last style.
+     * Combines `map` and `reduce` in a single pass. The callback receives the
+     * current state, element, and index, and returns `[nextState, mappedValue]`.
+     * The result is `[finalState, mappedArray]`. This can be used in both
+     * data-first and data-last style.
      *
      * **Example** (Running sum alongside mapped values)
      *
@@ -8514,9 +8621,9 @@ export declare const mapAccum: {
  *
  * **Details**
  *
- * - Produces every combination of an element from `self` with an element from `that`.
- * - Result length is `self.length * that.length`.
- * - Order: iterates `that` for each element of `self`.
+ * Produces every combination of an element from `self` with an element from
+ * `that`, so the result length is `self.length * that.length`. Iteration visits
+ * every element of `that` for each element of `self`.
  *
  * **Example** (Combining numbers and letters)
  *
@@ -8543,9 +8650,9 @@ export declare const cartesianWith: {
      *
      * **Details**
      *
-     * - Produces every combination of an element from `self` with an element from `that`.
-     * - Result length is `self.length * that.length`.
-     * - Order: iterates `that` for each element of `self`.
+     * Produces every combination of an element from `self` with an element from
+     * `that`, so the result length is `self.length * that.length`. Iteration visits
+     * every element of `that` for each element of `self`.
      *
      * **Example** (Combining numbers and letters)
      *
@@ -8572,9 +8679,9 @@ export declare const cartesianWith: {
      *
      * **Details**
      *
-     * - Produces every combination of an element from `self` with an element from `that`.
-     * - Result length is `self.length * that.length`.
-     * - Order: iterates `that` for each element of `self`.
+     * Produces every combination of an element from `self` with an element from
+     * `that`, so the result length is `self.length * that.length`. Iteration visits
+     * every element of `that` for each element of `self`.
      *
      * **Example** (Combining numbers and letters)
      *
@@ -8601,8 +8708,8 @@ export declare const cartesianWith: {
  *
  * **Details**
  *
- * - Produces every `[a, b]` combination of an element from `self` with an element from `that`.
- * - Result length is `self.length * that.length`.
+ * Produces every `[a, b]` combination of an element from `self` with an element
+ * from `that`, so the result length is `self.length * that.length`.
  *
  * **Example** (All pairs of two arrays)
  *
@@ -8628,8 +8735,8 @@ export declare const cartesian: {
      *
      * **Details**
      *
-     * - Produces every `[a, b]` combination of an element from `self` with an element from `that`.
-     * - Result length is `self.length * that.length`.
+     * Produces every `[a, b]` combination of an element from `self` with an element
+     * from `that`, so the result length is `self.length * that.length`.
      *
      * **Example** (All pairs of two arrays)
      *
@@ -8655,8 +8762,8 @@ export declare const cartesian: {
      *
      * **Details**
      *
-     * - Produces every `[a, b]` combination of an element from `self` with an element from `that`.
-     * - Result length is `self.length * that.length`.
+     * Produces every `[a, b]` combination of an element from `self` with an element
+     * from `that`, so the result length is `self.length * that.length`.
      *
      * **Example** (All pairs of two arrays)
      *
@@ -8679,9 +8786,14 @@ export declare const cartesian: {
  *
  * **When to use**
  *
- * Use when begin a pipeline with `Do`, then use {@link bind} to introduce array variables and {@link let_ let} for plain values.
- * - Each `bind` produces the cartesian product of all bound variables (like nested loops).
- * - Use `filter` and `map` in the pipeline to add conditions and transformations.
+ * Use when you want array-comprehension style code with do notation.
+ *
+ * **Details**
+ *
+ * Use {@link bind} to introduce array variables and {@link let_ let} for plain
+ * values. Each `bind` produces the cartesian product of all bound variables,
+ * like nested loops. Use `filter` and `map` in the pipeline to add conditions
+ * and transformations.
  *
  * **Example** (Array comprehension with do notation)
  *
@@ -8716,9 +8828,9 @@ export declare const Do: ReadonlyArray<{}>;
  *
  * **Details**
  *
- * - Each `bind` call adds a named property to the accumulated object.
- * - The callback receives the current scope and must return an array.
- * - Equivalent to `flatMap` + merging the new value into the scope object.
+ * Each `bind` call adds a named property to the accumulated object. The
+ * callback receives the current scope and must return an array. This is
+ * equivalent to `flatMap` plus merging the new value into the scope object.
  *
  * **Example** (Binding two arrays)
  *
@@ -8752,9 +8864,9 @@ export declare const bind: {
      *
      * **Details**
      *
-     * - Each `bind` call adds a named property to the accumulated object.
-     * - The callback receives the current scope and must return an array.
-     * - Equivalent to `flatMap` + merging the new value into the scope object.
+     * Each `bind` call adds a named property to the accumulated object. The
+     * callback receives the current scope and must return an array. This is
+     * equivalent to `flatMap` plus merging the new value into the scope object.
      *
      * **Example** (Binding two arrays)
      *
@@ -8790,9 +8902,9 @@ export declare const bind: {
      *
      * **Details**
      *
-     * - Each `bind` call adds a named property to the accumulated object.
-     * - The callback receives the current scope and must return an array.
-     * - Equivalent to `flatMap` + merging the new value into the scope object.
+     * Each `bind` call adds a named property to the accumulated object. The
+     * callback receives the current scope and must return an array. This is
+     * equivalent to `flatMap` plus merging the new value into the scope object.
      *
      * **Example** (Binding two arrays)
      *
@@ -8829,8 +8941,8 @@ export declare const bind: {
  *
  * **Details**
  *
- * - Equivalent to `Array.map(self, (a) => ({ [tag]: a }))`.
- * - Alternative to starting with `Do` + `bind`; useful when you already have an array.
+ * Equivalent to `Array.map(self, (a) => ({ [tag]: a }))`. This is an
+ * alternative to starting with `Do` plus `bind` when you already have an array.
  *
  * **Example** (Naming an existing array)
  *
@@ -8861,8 +8973,8 @@ export declare const bindTo: {
      *
      * **Details**
      *
-     * - Equivalent to `Array.map(self, (a) => ({ [tag]: a }))`.
-     * - Alternative to starting with `Do` + `bind`; useful when you already have an array.
+     * Equivalent to `Array.map(self, (a) => ({ [tag]: a }))`. This is an
+     * alternative to starting with `Do` plus `bind` when you already have an array.
      *
      * **Example** (Naming an existing array)
      *
@@ -8895,8 +9007,8 @@ export declare const bindTo: {
      *
      * **Details**
      *
-     * - Equivalent to `Array.map(self, (a) => ({ [tag]: a }))`.
-     * - Alternative to starting with `Do` + `bind`; useful when you already have an array.
+     * Equivalent to `Array.map(self, (a) => ({ [tag]: a }))`. This is an
+     * alternative to starting with `Do` plus `bind` when you already have an array.
      *
      * **Example** (Naming an existing array)
      *
@@ -8932,10 +9044,16 @@ export {
 /**
  * Adds a computed plain value to the do-notation scope without introducing a new array dimension.
  *
+ * **When to use**
+ *
+ * Use when each do-notation branch needs a derived field from the current
+ * bindings without multiplying the number of branches.
+ *
  * **Details**
  *
- * - Unlike {@link bind}, the callback returns a single value (not an array), so no cartesian product occurs.
- * - Useful for derived or intermediate values that depend on previously bound variables.
+ * Unlike `bind`, the callback returns a single value instead of an array, so
+ * no cartesian product occurs. Use this for derived or intermediate values
+ * that depend on previously bound variables.
  *
  * **Example** (Adding a computed value)
  *
@@ -8981,13 +9099,13 @@ export declare function makeReducerConcat<A>(): Reducer.Reducer<Array<A>>;
  *
  * **When to use**
  *
- * Use to count how many elements satisfy a predicate when you only need the
- * number of matches instead of the matching elements.
+ * Use when you need to count how many elements of an iterable satisfy a
+ * predicate.
  *
  * **Details**
  *
- * - The predicate receives both the element and its index.
- * - Returns `0` for an empty iterable.
+ * The predicate receives both the element and its index. Empty iterables return
+ * `0`.
  *
  * **Example** (Counting even numbers)
  *
@@ -9009,13 +9127,13 @@ export declare const countBy: {
      *
      * **When to use**
      *
-     * Use to count how many elements satisfy a predicate when you only need the
-     * number of matches instead of the matching elements.
+     * Use when you need to count how many elements of an iterable satisfy a
+     * predicate.
      *
      * **Details**
      *
-     * - The predicate receives both the element and its index.
-     * - Returns `0` for an empty iterable.
+     * The predicate receives both the element and its index. Empty iterables return
+     * `0`.
      *
      * **Example** (Counting even numbers)
      *
@@ -9037,13 +9155,13 @@ export declare const countBy: {
      *
      * **When to use**
      *
-     * Use to count how many elements satisfy a predicate when you only need the
-     * number of matches instead of the matching elements.
+     * Use when you need to count how many elements of an iterable satisfy a
+     * predicate.
      *
      * **Details**
      *
-     * - The predicate receives both the element and its index.
-     * - Returns `0` for an empty iterable.
+     * The predicate receives both the element and its index. Empty iterables return
+     * `0`.
      *
      * **Example** (Counting even numbers)
      *