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

package/src/Array.ts

@@ -1,79 +1,80 @@
 /**
- * Utilities for working with immutable arrays (and non-empty arrays) in a
- * functional style. All functions treat arrays as immutable — they return new
- * arrays rather than mutating the input.
- *
- * ## Mental model
- *
- * - **`Array<A>`** is a standard JS array. All functions in this module return
- *   new arrays; the input is never mutated.
- * - **`NonEmptyReadonlyArray<A>`** (`readonly [A, ...Array<A>]`) is a readonly
- *   array guaranteed to have at least one element. Many functions preserve or
- *   require this guarantee at the type level.
- * - **`NonEmptyArray<A>`** is the mutable counterpart: `[A, ...Array<A>]`.
- * - Most functions are **dual** — they can be called either as
- *   `Array.fn(array, arg)` (data-first) or piped as
- *   `pipe(array, Array.fn(arg))` (data-last).
- * - Functions that access elements by index return `Option<A>` for safety; use
- *   the `*NonEmpty` variants (e.g. {@link headNonEmpty}) when you already know
- *   the array is non-empty.
- * - Set-like operations ({@link union}, {@link intersection},
- *   {@link difference}) use `Equal.equivalence()` by default; use the `*With`
- *   variants for custom equality.
- *
- * ## Common tasks
- *
- * - **Create** an array: {@link make}, {@link of}, {@link empty},
- *   {@link fromIterable}, {@link range}, {@link makeBy}, {@link replicate},
- *   {@link unfold}
- * - **Access** elements: {@link head}, {@link last}, {@link get}, {@link tail},
- *   {@link init}
- * - **Transform**: {@link map}, {@link flatMap}, {@link flatten}
- * - **Filter**: {@link filter}, {@link partition}, {@link dedupe}
- * - **Combine**: {@link append}, {@link prepend}, {@link appendAll},
- *   {@link prependAll}, {@link zip}, {@link cartesian}
- * - **Split**: {@link splitAt}, {@link chunksOf}, {@link span}, {@link window}
- * - **Search**: {@link findFirst}, {@link findLast}, {@link contains}
- * - **Sort**: {@link sort}, {@link sortBy}, {@link sortWith}
- * - **Fold**: {@link reduce}, {@link scan}, {@link join}
- * - **Group**: {@link groupBy}, {@link group}, {@link groupWith}
- * - **Set operations**: {@link union}, {@link intersection},
- *   {@link difference}
- * - **Match** on empty vs non-empty: {@link match}, {@link matchLeft},
- *   {@link matchRight}
- * - **Check** properties: {@link isArray}, {@link isArrayNonEmpty},
- *   {@link every}, {@link some}
- *
- * ## Gotchas
- *
- * - {@link fromIterable} returns the original array reference when given an
- *   array; if you need a copy, use {@link copy}.
- * - `sort`, `reverse`, etc. always allocate a new array — the input is never
- *   mutated.
- * - {@link makeBy} and {@link replicate} normalize `n` to an integer >= 1 —
- *   they never produce an empty array.
- * - {@link range}`(start, end)` is inclusive on both ends. If `start > end` it
- *   returns `[start]`.
- * - Functions returning `Option` (e.g. {@link head}, {@link findFirst}) return
- *   `Option.none()` for empty inputs — they never throw.
- *
- * ## Quickstart
- *
- * **Example** (Basic array operations)
- *
- * ```ts
- * import { Array } from "effect"
- *
- * const numbers = Array.make(1, 2, 3, 4, 5)
- *
- * const doubled = Array.map(numbers, (n) => n * 2)
- * console.log(doubled) // [2, 4, 6, 8, 10]
+ * The `Array` module provides functional operations for JavaScript arrays,
+ * readonly arrays, and arrays that are known to contain at least one element.
+ * Operations that transform, reorder, or update collections allocate new arrays
+ * instead of mutating their inputs, while preserving useful type information
+ * such as non-emptiness when the operation can prove it.
+ *
+ * **Mental model**
+ *
+ * - A regular `Array<A>` is still the built-in JavaScript array type; this
+ *   module supplies functional constructors, combinators, searches, folds,
+ *   grouping, sorting, and set-like operations around it.
+ * - {@link NonEmptyReadonlyArray} and {@link NonEmptyArray} encode
+ *   non-emptiness at the type level. APIs with `NonEmpty` in the name can avoid
+ *   `Option` because an element is guaranteed to exist.
+ * - Most functions are dual. You can call them data-first, such as
+ *   `Array.map(values, f)`, or data-last in a pipeline, such as
+ *   `pipe(values, Array.map(f))`.
+ * - Safe element access returns {@link Option}; unsafe or `NonEmpty` variants
+ *   are for code that already has a proof an index or element exists.
+ * - Set-like operations such as {@link union}, {@link intersection}, and
+ *   {@link difference} use the {@link Equal} protocol by default. Use the
+ *   `*With` variants when equality is domain-specific.
+ *
+ * **Common tasks**
+ *
+ * - Create arrays with {@link make}, {@link of}, {@link empty},
+ *   {@link fromIterable}, {@link range}, {@link makeBy}, {@link replicate}, and
+ *   {@link unfold}.
+ * - Access edges or indexes with {@link head}, {@link last}, {@link get},
+ *   {@link tail}, and {@link init}.
+ * - Transform and flatten with {@link map}, {@link flatMap}, and
+ *   {@link flatten}.
+ * - Keep, split, or deduplicate values with {@link filter}, {@link partition},
+ *   {@link dedupe}, and {@link dedupeAdjacent}.
+ * - Combine collections with {@link append}, {@link prepend}, {@link appendAll},
+ *   {@link prependAll}, {@link zip}, and {@link cartesian}.
+ * - Chunk, window, and slice with {@link splitAt}, {@link chunksOf},
+ *   {@link span}, and {@link window}.
+ * - Sort with {@link sort}, {@link sortWith}, and {@link sortBy}.
+ * - Fold or aggregate with {@link reduce}, {@link scan}, {@link join}, and
+ *   {@link countBy}.
+ * - Match empty and non-empty cases with {@link match}, {@link matchLeft}, and
+ *   {@link matchRight}.
+ *
+ * **Gotchas**
+ *
+ * - {@link fromIterable} returns the original array reference when the input is
+ *   already an array. Use {@link copy} when you need a fresh shallow copy.
+ * - {@link makeBy}, {@link range}, and {@link replicate} always return
+ *   non-empty arrays. `range(start, end)` is inclusive and returns `[start]`
+ *   when `start > end`.
+ * - Functions returning {@link Option}, such as {@link head} and
+ *   {@link findFirst}, return `Option.none()` for empty inputs instead of
+ *   throwing.
+ * - `NonEmpty` return types describe what the function can prove, not what may
+ *   happen for a particular runtime value after filtering.
+ *
+ * **Example** (Filtering and transforming)
+ *
+ * ```ts
+ * import { Array, Option, pipe } from "effect"
+ *
+ * const numbers = [1, 2, 3, 4, 5]
+ *
+ * const doubledEvens = pipe(
+ *   numbers,
+ *   Array.filter((n) => n % 2 === 0),
+ *   Array.map((n) => n * 2)
+ * )
  *
- * const evens = Array.filter(numbers, (n) => n % 2 === 0)
- * console.log(evens) // [2, 4]
+ * console.log(doubledEvens)
+ * // [4, 8]
  *
- * const sum = Array.reduce(numbers, 0, (acc, n) => acc + n)
- * console.log(sum) // 15
+ * const first = Array.head(doubledEvens)
+ * console.log(Option.getOrElse(first, () => 0))
+ * // 4
  * ```
  *
  * @see {@link make} — create a non-empty array from elements
@@ -101,12 +102,12 @@ import * as Tuple from "./Tuple.ts"
 import type { NoInfer, TupleOf } from "./Types.ts"
 
 /**
- * Reference to the global `Array` constructor.
+ * Exposes the global array constructor.
  *
  * **When to use**
  *
- * Use this when you need the native `Array` constructor while the `Array`
- * namespace is in scope (e.g. `Array.Array.isArray`, `Array.Array.from`).
+ * Use to access native JavaScript array constructor methods such as `isArray`
+ * or `from` from the Effect module namespace.
  *
  * **Example** (Using the Array constructor)
  *
@@ -137,7 +138,7 @@ export interface ReadonlyArrayTypeLambda extends TypeLambda {
  *
  * **When to use**
  *
- * Use this type when you need to ensure non-emptiness at the type level while
+ * 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.
  *
  * **Example** (Typing a non-empty array)
@@ -160,6 +161,11 @@ export type NonEmptyReadonlyArray<A> = readonly [A, ...Array<A>]
 /**
  * A mutable array guaranteed to have at least one element.
  *
+ * **When to use**
+ *
+ * Use when mutation is acceptable and non-emptiness must be tracked at the type
+ * level.
+ *
  * **Details**
  *
  * This is the mutable counterpart of {@link NonEmptyReadonlyArray}. Most Array
@@ -188,7 +194,7 @@ export type NonEmptyArray<A> = [A, ...Array<A>]
  *
  * **When to use**
  *
- * - Use when you have literal values and want a typed non-empty array.
+ * 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.
  *
@@ -216,7 +222,7 @@ export const make = <Elements extends NonEmptyArray<unknown>>(
  *
  * **When to use**
  *
- * - Use when you need a pre-sized array and will fill it imperatively.
+ * 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.
  *
@@ -241,7 +247,7 @@ export const allocate = <A = never>(n: number): Array<A | undefined> => new Arra
  *
  * **When to use**
  *
- * - Use when you need an array whose values depend on the index.
+ * 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))`.
  *
@@ -266,7 +272,7 @@ export const makeBy: {
    *
    * **When to use**
    *
-   * - Use when you need an array whose values depend on the index.
+   * 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))`.
    *
@@ -291,7 +297,7 @@ export const makeBy: {
    *
    * **When to use**
    *
-   * - Use when you need an array whose values depend on the index.
+   * 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))`.
    *
@@ -326,7 +332,7 @@ export const makeBy: {
  *
  * **When to use**
  *
- * - Use when you need a sequence of consecutive integers.
+ * Use when you need a sequence of consecutive integers.
  * - If `start > end`, returns `[start]`.
  * - Always returns a `NonEmptyArray`.
  *
@@ -352,7 +358,7 @@ export const range = (start: number, end: number): NonEmptyArray<number> =>
  *
  * **When to use**
  *
- * - Use when you need multiple copies of the same value.
+ * 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))`.
  *
@@ -376,7 +382,7 @@ export const replicate: {
    *
    * **When to use**
    *
-   * - Use when you need multiple copies of the same value.
+   * 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))`.
    *
@@ -400,7 +406,7 @@ export const replicate: {
    *
    * **When to use**
    *
-   * - Use when you need multiple copies of the same value.
+   * 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))`.
    *
@@ -424,6 +430,10 @@ export const replicate: {
 /**
  * Converts an `Iterable` to an `Array`.
  *
+ * **When to use**
+ *
+ * Use to convert any `Iterable` (Set, Generator, etc.) into an array.
+ *
  * **Details**
  *
  * - If the input is already an array, returns it **by reference** (no copy).
@@ -452,6 +462,11 @@ export const fromIterable = <A>(collection: Iterable<A>): Array<A> =>
 /**
  * Normalizes a value that is either a single element or an array into an array.
  *
+ * **When to use**
+ *
+ * Use to normalize input that may be a single value or an array into a consistent
+ * array.
+ *
  * **Details**
  *
  * - If the input is already an array, returns it by reference.
@@ -478,6 +493,11 @@ export const ensure = <A>(self: ReadonlyArray<A> | A): Array<A> => Array.isArray
 /**
  * Converts a record into an array of `[key, value]` tuples.
  *
+ * **When to use**
+ *
+ * Use to convert a record into an array of key-value tuples for iteration or
+ * transformation.
+ *
  * **Details**
  *
  * - Key order follows `Object.entries` semantics.
@@ -492,6 +512,9 @@ export const ensure = <A>(self: ReadonlyArray<A> | A): Array<A> => Array.isArray
  * console.log(result) // [["a", 1], ["b", 2], ["c", 3]]
  * ```
  *
+ * @see {@link Record.toEntries} the equivalent function from the Record module
+ * @see {@link Record.fromEntries} to build a record from an array of tuples
+ *
  * @category converting
  * @since 2.0.0
  */
@@ -500,6 +523,10 @@ export const fromRecord: <K extends string, A>(self: Readonly<Record<K, A>>) =>
 /**
  * Converts an `Option` to an array: `Some(a)` becomes `[a]`, `None` becomes `[]`.
  *
+ * **When to use**
+ *
+ * Use to convert a single `Option` into an array for downstream array operations.
+ *
  * **Example** (Option to array)
  *
  * ```ts
@@ -521,7 +548,7 @@ export const fromOption: <A>(self: Option.Option<A>) => Array<A> = Option.toArra
  *
  * **When to use**
  *
- * - Use when you need to branch on whether an array has elements.
+ * Use when you need to branch on whether an array has elements.
  * - `onNonEmpty` receives a `NonEmptyReadonlyArray`.
  * - Dual: data-first or data-last.
  *
@@ -550,7 +577,7 @@ export const match: {
    *
    * **When to use**
    *
-   * - Use when you need to branch on whether an array has elements.
+   * Use when you need to branch on whether an array has elements.
    * - `onNonEmpty` receives a `NonEmptyReadonlyArray`.
    * - Dual: data-first or data-last.
    *
@@ -584,7 +611,7 @@ export const match: {
    *
    * **When to use**
    *
-   * - Use when you need to branch on whether an array has elements.
+   * Use when you need to branch on whether an array has elements.
    * - `onNonEmpty` receives a `NonEmptyReadonlyArray`.
    * - Dual: data-first or data-last.
    *
@@ -626,10 +653,14 @@ export const match: {
  * Pattern-matches on an array from the left, providing the first element and
  * the remaining elements separately.
  *
+ * **When to use**
+ *
+ * Use to pattern-match when you need the first element and remaining elements as
+ * separate values.
+ *
  * **Details**
  *
- * - `onNonEmpty` receives `(head, tail)` where `tail` is the rest of the array.
- * - Use when you want to process the first element differently from the rest.
+ * `onNonEmpty` receives `(head, tail)` where `tail` is the rest of the array.
  *
  * **Example** (Head and tail destructuring)
  *
@@ -655,10 +686,14 @@ export const matchLeft: {
    * Pattern-matches on an array from the left, providing the first element and
    * the remaining elements separately.
    *
+   * **When to use**
+   *
+   * Use to pattern-match when you need the first element and remaining elements as
+   * separate values.
+   *
    * **Details**
    *
-   * - `onNonEmpty` receives `(head, tail)` where `tail` is the rest of the array.
-   * - Use when you want to process the first element differently from the rest.
+   * `onNonEmpty` receives `(head, tail)` where `tail` is the rest of the array.
    *
    * **Example** (Head and tail destructuring)
    *
@@ -689,10 +724,14 @@ export const matchLeft: {
    * Pattern-matches on an array from the left, providing the first element and
    * the remaining elements separately.
    *
+   * **When to use**
+   *
+   * Use to pattern-match when you need the first element and remaining elements as
+   * separate values.
+   *
    * **Details**
    *
-   * - `onNonEmpty` receives `(head, tail)` where `tail` is the rest of the array.
-   * - Use when you want to process the first element differently from the rest.
+   * `onNonEmpty` receives `(head, tail)` where `tail` is the rest of the array.
    *
    * **Example** (Head and tail destructuring)
    *
@@ -732,10 +771,14 @@ export const matchLeft: {
  * Pattern-matches on an array from the right, providing all elements except the
  * last and the last element separately.
  *
+ * **When to use**
+ *
+ * Use to pattern-match when you need all but the last element and the last element
+ * as separate values.
+ *
  * **Details**
  *
- * - `onNonEmpty` receives `(init, last)` where `init` is everything but the last element.
- * - Use when you want to process the last element differently from the rest.
+ * `onNonEmpty` receives `(init, last)` where `init` is everything but the last element.
  *
  * **Example** (Init and last destructuring)
  *
@@ -761,10 +804,14 @@ export const matchRight: {
    * Pattern-matches on an array from the right, providing all elements except the
    * last and the last element separately.
    *
+   * **When to use**
+   *
+   * Use to pattern-match when you need all but the last element and the last element
+   * as separate values.
+   *
    * **Details**
    *
-   * - `onNonEmpty` receives `(init, last)` where `init` is everything but the last element.
-   * - Use when you want to process the last element differently from the rest.
+   * `onNonEmpty` receives `(init, last)` where `init` is everything but the last element.
    *
    * **Example** (Init and last destructuring)
    *
@@ -795,10 +842,14 @@ export const matchRight: {
    * Pattern-matches on an array from the right, providing all elements except the
    * last and the last element separately.
    *
+   * **When to use**
+   *
+   * Use to pattern-match when you need all but the last element and the last element
+   * as separate values.
+   *
    * **Details**
    *
-   * - `onNonEmpty` receives `(init, last)` where `init` is everything but the last element.
-   * - Use when you want to process the last element differently from the rest.
+   * `onNonEmpty` receives `(init, last)` where `init` is everything but the last element.
    *
    * **Example** (Init and last destructuring)
    *
@@ -840,10 +891,13 @@ export const matchRight: {
 /**
  * Adds a single element to the front of an iterable, returning a `NonEmptyArray`.
  *
+ * **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.
- * - Does not mutate the input.
  *
  * **Example** (Prepending an element)
  *
@@ -864,10 +918,13 @@ export const prepend: {
   /**
    * Adds a single element to the front of an iterable, returning a `NonEmptyArray`.
    *
+   * **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.
-   * - Does not mutate the input.
    *
    * **Example** (Prepending an element)
    *
@@ -888,10 +945,13 @@ export const prepend: {
   /**
    * Adds a single element to the front of an iterable, returning a `NonEmptyArray`.
    *
+   * **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.
-   * - Does not mutate the input.
    *
    * **Example** (Prepending an element)
    *
@@ -914,10 +974,13 @@ export const prepend: {
 /**
  * Prepends all elements from a prefix iterable to the front of an array.
  *
+ * **When to use**
+ *
+ * Use to prepend multiple elements from an iterable to the front of an array.
+ *
  * **Details**
  *
  * - If either input is non-empty, the result is a `NonEmptyArray`.
- * - Does not mutate the input.
  *
  * **Example** (Prepending multiple elements)
  *
@@ -938,10 +1001,13 @@ export const prependAll: {
   /**
    * Prepends all elements from a prefix iterable to the front of an array.
    *
+   * **When to use**
+   *
+   * Use to prepend multiple elements from an iterable to the front of an array.
+   *
    * **Details**
    *
    * - If either input is non-empty, the result is a `NonEmptyArray`.
-   * - Does not mutate the input.
    *
    * **Example** (Prepending multiple elements)
    *
@@ -962,10 +1028,13 @@ export const prependAll: {
   /**
    * Prepends all elements from a prefix iterable to the front of an array.
    *
+   * **When to use**
+   *
+   * Use to prepend multiple elements from an iterable to the front of an array.
+   *
    * **Details**
    *
    * - If either input is non-empty, the result is a `NonEmptyArray`.
-   * - Does not mutate the input.
    *
    * **Example** (Prepending multiple elements)
    *
@@ -986,10 +1055,13 @@ export const prependAll: {
   /**
    * Prepends all elements from a prefix iterable to the front of an array.
    *
+   * **When to use**
+   *
+   * Use to prepend multiple elements from an iterable to the front of an array.
+   *
    * **Details**
    *
    * - If either input is non-empty, the result is a `NonEmptyArray`.
-   * - Does not mutate the input.
    *
    * **Example** (Prepending multiple elements)
    *
@@ -1010,10 +1082,13 @@ export const prependAll: {
   /**
    * Prepends all elements from a prefix iterable to the front of an array.
    *
+   * **When to use**
+   *
+   * Use to prepend multiple elements from an iterable to the front of an array.
+   *
    * **Details**
    *
    * - If either input is non-empty, the result is a `NonEmptyArray`.
-   * - Does not mutate the input.
    *
    * **Example** (Prepending multiple elements)
    *
@@ -1039,10 +1114,14 @@ export const prependAll: {
 /**
  * Adds a single element to the end of an iterable, returning a `NonEmptyArray`.
  *
+ * **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.
- * - Does not mutate the input.
  *
  * **Example** (Appending an element)
  *
@@ -1063,10 +1142,14 @@ export const append: {
   /**
    * Adds a single element to the end of an iterable, returning a `NonEmptyArray`.
    *
+   * **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.
-   * - Does not mutate the input.
    *
    * **Example** (Appending an element)
    *
@@ -1087,10 +1170,14 @@ export const append: {
   /**
    * Adds a single element to the end of an iterable, returning a `NonEmptyArray`.
    *
+   * **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.
-   * - Does not mutate the input.
    *
    * **Example** (Appending an element)
    *
@@ -1113,10 +1200,14 @@ export const append: {
 /**
  * Concatenates two iterables into a single array.
  *
+ * **When to use**
+ *
+ * Use to combine two iterable inputs into a new array with the second input's
+ * elements after the first.
+ *
  * **Details**
  *
  * - If either input is non-empty, the result is a `NonEmptyArray`.
- * - Does not mutate the inputs.
  *
  * **Example** (Concatenating arrays)
  *
@@ -1137,10 +1228,14 @@ export const appendAll: {
   /**
    * Concatenates two iterables into a single array.
    *
+   * **When to use**
+   *
+   * Use to combine two iterable inputs into a new array with the second input's
+   * elements after the first.
+   *
    * **Details**
    *
    * - If either input is non-empty, the result is a `NonEmptyArray`.
-   * - Does not mutate the inputs.
    *
    * **Example** (Concatenating arrays)
    *
@@ -1161,10 +1256,14 @@ export const appendAll: {
   /**
    * Concatenates two iterables into a single array.
    *
+   * **When to use**
+   *
+   * Use to combine two iterable inputs into a new array with the second input's
+   * elements after the first.
+   *
    * **Details**
    *
    * - If either input is non-empty, the result is a `NonEmptyArray`.
-   * - Does not mutate the inputs.
    *
    * **Example** (Concatenating arrays)
    *
@@ -1185,10 +1284,14 @@ export const appendAll: {
   /**
    * Concatenates two iterables into a single array.
    *
+   * **When to use**
+   *
+   * Use to combine two iterable inputs into a new array with the second input's
+   * elements after the first.
+   *
    * **Details**
    *
    * - If either input is non-empty, the result is a `NonEmptyArray`.
-   * - Does not mutate the inputs.
    *
    * **Example** (Concatenating arrays)
    *
@@ -1209,10 +1312,14 @@ export const appendAll: {
   /**
    * Concatenates two iterables into a single array.
    *
+   * **When to use**
+   *
+   * Use to combine two iterable inputs into a new array with the second input's
+   * elements after the first.
+   *
    * **Details**
    *
    * - If either input is non-empty, the result is a `NonEmptyArray`.
-   * - Does not mutate the inputs.
    *
    * **Example** (Concatenating arrays)
    *
@@ -1236,7 +1343,11 @@ export const appendAll: {
 )
 
 /**
- * Left-to-right fold that keeps every intermediate accumulator value.
+ * Folds left-to-right while keeping every intermediate accumulator value.
+ *
+ * **When to use**
+ *
+ * Use to compute a running accumulator where each intermediate value is needed.
  *
  * **Details**
  *
@@ -1261,7 +1372,11 @@ export const appendAll: {
  */
 export const scan: {
   /**
-   * Left-to-right fold that keeps every intermediate accumulator value.
+   * Folds left-to-right while keeping every intermediate accumulator value.
+   *
+   * **When to use**
+   *
+   * Use to compute a running accumulator where each intermediate value is needed.
    *
    * **Details**
    *
@@ -1286,7 +1401,11 @@ export const scan: {
    */
   <B, A>(b: B, f: (b: B, a: A) => B): (self: Iterable<A>) => NonEmptyArray<B>
   /**
-   * Left-to-right fold that keeps every intermediate accumulator value.
+   * Folds left-to-right while keeping every intermediate accumulator value.
+   *
+   * **When to use**
+   *
+   * Use to compute a running accumulator where each intermediate value is needed.
    *
    * **Details**
    *
@@ -1321,7 +1440,12 @@ export const scan: {
 })
 
 /**
- * Right-to-left fold that keeps every intermediate accumulator value.
+ * Folds right-to-left while keeping every intermediate accumulator value.
+ *
+ * **When to use**
+ *
+ * Use to compute a running accumulator from right to left where each intermediate
+ * value is needed.
  *
  * **Details**
  *
@@ -1345,7 +1469,12 @@ export const scan: {
  */
 export const scanRight: {
   /**
-   * Right-to-left fold that keeps every intermediate accumulator value.
+   * Folds right-to-left while keeping every intermediate accumulator value.
+   *
+   * **When to use**
+   *
+   * Use to compute a running accumulator from right to left where each intermediate
+   * value is needed.
    *
    * **Details**
    *
@@ -1369,7 +1498,12 @@ export const scanRight: {
    */
   <B, A>(b: B, f: (b: B, a: A) => B): (self: Iterable<A>) => NonEmptyArray<B>
   /**
-   * Right-to-left fold that keeps every intermediate accumulator value.
+   * Folds right-to-left while keeping every intermediate accumulator value.
+   *
+   * **When to use**
+   *
+   * Use to compute a running accumulator from right to left where each intermediate
+   * value is needed.
    *
    * **Details**
    *
@@ -1403,7 +1537,11 @@ export const scanRight: {
 })
 
 /**
- * Tests whether a value is an `Array`.
+ * Checks whether a value is an `Array`.
+ *
+ * **When to use**
+ *
+ * Use to verify a value is a mutable array, narrowing its type to `Array<unknown>`.
  *
  * **Details**
  *
@@ -1427,7 +1565,11 @@ export const scanRight: {
  */
 export const isArray: {
   /**
-   * Tests whether a value is an `Array`.
+   * Checks whether a value is an `Array`.
+   *
+   * **When to use**
+   *
+   * Use to verify a value is a mutable array, narrowing its type to `Array<unknown>`.
    *
    * **Details**
    *
@@ -1451,7 +1593,11 @@ export const isArray: {
    */
   (self: unknown): self is Array<unknown>
   /**
-   * Tests whether a value is an `Array`.
+   * Checks whether a value is an `Array`.
+   *
+   * **When to use**
+   *
+   * Use to verify a value is a mutable array, narrowing its type to `Array<unknown>`.
    *
    * **Details**
    *
@@ -1477,7 +1623,7 @@ export const isArray: {
 } = Array.isArray
 
 /**
- * Tests whether a mutable `Array` is empty, narrowing the type to `[]`.
+ * Checks whether a mutable `Array` is empty, narrowing the type to `[]`.
  *
  * **Example** (Checking for an empty array)
  *
@@ -1497,7 +1643,7 @@ export const isArray: {
 export const isArrayEmpty = <A>(self: Array<A>): self is [] => self.length === 0
 
 /**
- * Tests whether a `ReadonlyArray` is empty, narrowing the type to `readonly []`.
+ * Checks whether a `ReadonlyArray` is empty, narrowing the type to `readonly []`.
  *
  * **Example** (Checking for an empty readonly array)
  *
@@ -1517,7 +1663,7 @@ export const isArrayEmpty = <A>(self: Array<A>): self is [] => self.length === 0
 export const isReadonlyArrayEmpty: <A>(self: ReadonlyArray<A>) => self is readonly [] = isArrayEmpty as any
 
 /**
- * Tests whether a mutable `Array` is non-empty, narrowing the type to
+ * Checks whether a mutable `Array` is non-empty, narrowing the type to
  * `NonEmptyArray`.
  *
  * **Example** (Checking for a non-empty array)
@@ -1538,7 +1684,7 @@ export const isReadonlyArrayEmpty: <A>(self: ReadonlyArray<A>) => self is readon
 export const isArrayNonEmpty: <A>(self: Array<A>) => self is NonEmptyArray<A> = internalArray.isArrayNonEmpty
 
 /**
- * Tests whether a `ReadonlyArray` is non-empty, narrowing the type to
+ * Checks whether a `ReadonlyArray` is non-empty, narrowing the type to
  * `NonEmptyReadonlyArray`.
  *
  * **Example** (Checking for a non-empty readonly array)
@@ -1562,6 +1708,10 @@ export const isReadonlyArrayNonEmpty: <A>(self: ReadonlyArray<A>) => self is Non
 /**
  * Returns the number of elements in a `ReadonlyArray`.
  *
+ * **When to use**
+ *
+ * Use when you need length as a composable function rather than a property access.
+ *
  * **Example** (Getting the length)
  *
  * ```ts
@@ -1583,9 +1733,14 @@ export function isOutOfBounds<A>(i: number, as: ReadonlyArray<A>): boolean {
 const clamp = <A>(i: number, as: ReadonlyArray<A>): number => Math.floor(Math.min(Math.max(0, i), as.length))
 
 /**
- * Safely reads an element at the given index, returning `Option.some` or
+ * Reads an element at the given index safely, returning `Option.some` or
  * `Option.none` if the index is out of bounds.
  *
+ * **When to use**
+ *
+ * Use when you need to read an array element by index and handle an
+ * out-of-bounds index as `Option.none`.
+ *
  * **Details**
  *
  * - The index is floored to an integer.
@@ -1600,18 +1755,23 @@ const clamp = <A>(i: number, as: ReadonlyArray<A>): number => Math.floor(Math.mi
  * console.log(Array.get([1, 2, 3], 10)) // None
  * ```
  *
- * @see {@link getUnsafe} — throws on out of bounds
- * @see {@link head} — get the first element
- * @see {@link last} — get the last element
+ * @see {@link getUnsafe} for indexed access that throws when the index is out of bounds
+ * @see {@link head} for reading the first element as an `Option`
+ * @see {@link last} for reading the last element as an `Option`
  *
  * @category getters
  * @since 2.0.0
  */
 export const get: {
   /**
-   * Safely reads an element at the given index, returning `Option.some` or
+   * Reads an element at the given index safely, returning `Option.some` or
    * `Option.none` if the index is out of bounds.
    *
+   * **When to use**
+   *
+   * Use when you need to read an array element by index and handle an
+   * out-of-bounds index as `Option.none`.
+   *
    * **Details**
    *
    * - The index is floored to an integer.
@@ -1626,18 +1786,23 @@ export const get: {
    * console.log(Array.get([1, 2, 3], 10)) // None
    * ```
    *
-   * @see {@link getUnsafe} — throws on out of bounds
-   * @see {@link head} — get the first element
-   * @see {@link last} — get the last element
+   * @see {@link getUnsafe} for indexed access that throws when the index is out of bounds
+   * @see {@link head} for reading the first element as an `Option`
+   * @see {@link last} for reading the last element as an `Option`
    *
    * @category getters
    * @since 2.0.0
    */
   (index: number): <A>(self: ReadonlyArray<A>) => Option.Option<A>
   /**
-   * Safely reads an element at the given index, returning `Option.some` or
+   * Reads an element at the given index safely, returning `Option.some` or
    * `Option.none` if the index is out of bounds.
    *
+   * **When to use**
+   *
+   * Use when you need to read an array element by index and handle an
+   * out-of-bounds index as `Option.none`.
+   *
    * **Details**
    *
    * - The index is floored to an integer.
@@ -1652,9 +1817,9 @@ export const get: {
    * console.log(Array.get([1, 2, 3], 10)) // None
    * ```
    *
-   * @see {@link getUnsafe} — throws on out of bounds
-   * @see {@link head} — get the first element
-   * @see {@link last} — get the last element
+   * @see {@link getUnsafe} for indexed access that throws when the index is out of bounds
+   * @see {@link head} for reading the first element as an `Option`
+   * @see {@link last} for reading the last element as an `Option`
    *
    * @category getters
    * @since 2.0.0
@@ -1668,6 +1833,11 @@ export const get: {
 /**
  * Reads an element at the given index, throwing if the index is out of bounds.
  *
+ * **When to use**
+ *
+ * Use to read an 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>"`.
@@ -1691,6 +1861,11 @@ export const getUnsafe: {
   /**
    * Reads an element at the given index, throwing if the index is out of bounds.
    *
+   * **When to use**
+   *
+   * Use to read an 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>"`.
@@ -1714,6 +1889,11 @@ export const getUnsafe: {
   /**
    * Reads an element at the given index, throwing if the index is out of bounds.
    *
+   * **When to use**
+   *
+   * Use to read an 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>"`.
@@ -1745,6 +1925,11 @@ export const getUnsafe: {
 /**
  * Splits a non-empty array into its first element and the remaining elements.
  *
+ * **When to use**
+ *
+ * Use when you have a `NonEmptyReadonlyArray` and need both its first element
+ * and the remaining elements as separate values.
+ *
  * **Details**
  *
  * - Returns a tuple `[head, tail]`.
@@ -1759,9 +1944,9 @@ export const getUnsafe: {
  * console.log(result) // [1, [2, 3, 4]]
  * ```
  *
- * @see {@link unappend} — split into init + last
- * @see {@link headNonEmpty} — get only the head
- * @see {@link tailNonEmpty} — get only the tail
+ * @see {@link unappend} for splitting a non-empty array into init and last
+ * @see {@link headNonEmpty} for getting only the first element
+ * @see {@link tailNonEmpty} for getting only the elements after the first
  *
  * @category splitting
  * @since 2.0.0
@@ -1774,6 +1959,11 @@ export const unprepend = <A>(
  * Splits a non-empty array into all elements except the last, and the last
  * element.
  *
+ * **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.
+ *
  * **Details**
  *
  * - Returns a tuple `[init, last]`.
@@ -1788,9 +1978,9 @@ export const unprepend = <A>(
  * console.log(result) // [[1, 2, 3], 4]
  * ```
  *
- * @see {@link unprepend} — split into head + tail
- * @see {@link initNonEmpty} — get only the init
- * @see {@link lastNonEmpty} — get only the last
+ * @see {@link unprepend} for splitting a non-empty array into head and tail
+ * @see {@link initNonEmpty} for getting only the elements before the last
+ * @see {@link lastNonEmpty} for getting only the last element
  *
  * @category splitting
  * @since 2.0.0
@@ -1800,9 +1990,13 @@ export const unappend = <A>(
 ): [arrayWithoutLastElement: Array<A>, lastElement: A] => [initNonEmpty(self), lastNonEmpty(self)]
 
 /**
- * Returns the first element of an array wrapped in `Option.some`, or
+ * Returns the first element of an array safely wrapped in `Option.some`, or
  * `Option.none` if the array is empty.
  *
+ * **When to use**
+ *
+ * Use to safely get the first element of an array that may be empty.
+ *
  * **Example** (Getting the first element)
  *
  * ```ts
@@ -1824,6 +2018,11 @@ export const head: <A>(self: ReadonlyArray<A>) => Option.Option<A> = get(0)
  * Returns the first element of a `NonEmptyReadonlyArray` directly (no `Option`
  * wrapper).
  *
+ * **When to use**
+ *
+ * Use to get the first element without `Option` wrapping when the array is known
+ * to be non-empty.
+ *
  * **Example** (Getting the head of a non-empty array)
  *
  * ```ts
@@ -1840,9 +2039,13 @@ export const head: <A>(self: ReadonlyArray<A>) => Option.Option<A> = get(0)
 export const headNonEmpty: <A>(self: NonEmptyReadonlyArray<A>) => A = getUnsafe(0)
 
 /**
- * Returns the last element of an array wrapped in `Option.some`, or
+ * Returns the last element of an array safely wrapped in `Option.some`, or
  * `Option.none` if the array is empty.
  *
+ * **When to use**
+ *
+ * Use to safely get the last element of an array that may be empty.
+ *
  * **Example** (Getting the last element)
  *
  * ```ts
@@ -1865,6 +2068,11 @@ export const last = <A>(self: ReadonlyArray<A>): Option.Option<A> =>
  * Returns the last element of a `NonEmptyReadonlyArray` directly (no `Option`
  * wrapper).
  *
+ * **When to use**
+ *
+ * Use to get the last element without `Option` wrapping when the array is known
+ * to be non-empty.
+ *
  * **Example** (Getting the last of a non-empty array)
  *
  * ```ts
@@ -1881,7 +2089,11 @@ export const last = <A>(self: ReadonlyArray<A>): Option.Option<A> =>
 export const lastNonEmpty = <A>(self: NonEmptyReadonlyArray<A>): A => self[self.length - 1]
 
 /**
- * Returns all elements except the first, wrapped in an `Option`.
+ * Returns all elements except the first safely, wrapped in an `Option`.
+ *
+ * **When to use**
+ *
+ * Use to safely get all elements after the first when the iterable may be empty.
  *
  * **Details**
  *
@@ -1911,6 +2123,10 @@ export function tail<A>(self: Iterable<A>): Option.Option<Array<A>> {
 /**
  * Returns all elements except the first of a `NonEmptyReadonlyArray`.
  *
+ * **When to use**
+ *
+ * Use to get all elements after the first when the array is known to be non-empty.
+ *
  * **Example** (Getting the tail of a non-empty array)
  *
  * ```ts
@@ -1928,7 +2144,11 @@ export function tail<A>(self: Iterable<A>): Option.Option<Array<A>> {
 export const tailNonEmpty = <A>(self: NonEmptyReadonlyArray<A>): Array<A> => self.slice(1)
 
 /**
- * Returns all elements except the last, wrapped in an `Option`.
+ * Returns all elements except the last safely, wrapped in an `Option`.
+ *
+ * **When to use**
+ *
+ * Use to safely get all elements before the last when the iterable may be empty.
  *
  * **Details**
  *
@@ -1958,6 +2178,10 @@ export function init<A>(self: Iterable<A>): Option.Option<Array<A>> {
 /**
  * Returns all elements except the last of a `NonEmptyReadonlyArray`.
  *
+ * **When to use**
+ *
+ * Use to get all elements before the last when the array is known to be non-empty.
+ *
  * **Example** (Getting init of a non-empty array)
  *
  * ```ts
@@ -1977,6 +2201,10 @@ export const initNonEmpty = <A>(self: NonEmptyReadonlyArray<A>): Array<A> => sel
 /**
  * Keeps the first `n` elements, creating a new array.
  *
+ * **When to use**
+ *
+ * Use to keep up to the first `n` elements from an iterable as a new array.
+ *
  * **Details**
  *
  * - `n` is clamped to `[0, length]`.
@@ -1990,9 +2218,9 @@ export const initNonEmpty = <A>(self: NonEmptyReadonlyArray<A>): Array<A> => sel
  * console.log(Array.take([1, 2, 3, 4, 5], 3)) // [1, 2, 3]
  * ```
  *
- * @see {@link takeRight} — keep from the end
- * @see {@link takeWhile} — keep while predicate holds
- * @see {@link drop} — remove from the start
+ * @see {@link takeRight} for keeping elements from the end
+ * @see {@link takeWhile} for keeping an initial prefix while a predicate holds
+ * @see {@link drop} for removing elements from the start
  *
  * @category getters
  * @since 2.0.0
@@ -2001,6 +2229,10 @@ export const take: {
   /**
    * Keeps the first `n` elements, creating a new array.
    *
+   * **When to use**
+   *
+   * Use to keep up to the first `n` elements from an iterable as a new array.
+   *
    * **Details**
    *
    * - `n` is clamped to `[0, length]`.
@@ -2014,9 +2246,9 @@ export const take: {
    * console.log(Array.take([1, 2, 3, 4, 5], 3)) // [1, 2, 3]
    * ```
    *
-   * @see {@link takeRight} — keep from the end
-   * @see {@link takeWhile} — keep while predicate holds
-   * @see {@link drop} — remove from the start
+   * @see {@link takeRight} for keeping elements from the end
+   * @see {@link takeWhile} for keeping an initial prefix while a predicate holds
+   * @see {@link drop} for removing elements from the start
    *
    * @category getters
    * @since 2.0.0
@@ -2025,6 +2257,10 @@ export const take: {
   /**
    * Keeps the first `n` elements, creating a new array.
    *
+   * **When to use**
+   *
+   * Use to keep up to the first `n` elements from an iterable as a new array.
+   *
    * **Details**
    *
    * - `n` is clamped to `[0, length]`.
@@ -2038,9 +2274,9 @@ export const take: {
    * console.log(Array.take([1, 2, 3, 4, 5], 3)) // [1, 2, 3]
    * ```
    *
-   * @see {@link takeRight} — keep from the end
-   * @see {@link takeWhile} — keep while predicate holds
-   * @see {@link drop} — remove from the start
+   * @see {@link takeRight} for keeping elements from the end
+   * @see {@link takeWhile} for keeping an initial prefix while a predicate holds
+   * @see {@link drop} for removing elements from the start
    *
    * @category getters
    * @since 2.0.0
@@ -2054,6 +2290,10 @@ export const take: {
 /**
  * Keeps the last `n` elements, creating a new array.
  *
+ * **When to use**
+ *
+ * Use to keep the last `n` elements of an iterable.
+ *
  * **Details**
  *
  * - `n` is clamped to `[0, length]`.
@@ -2077,6 +2317,10 @@ export const takeRight: {
   /**
    * Keeps the last `n` elements, creating a new array.
    *
+   * **When to use**
+   *
+   * Use to keep the last `n` elements of an iterable.
+   *
    * **Details**
    *
    * - `n` is clamped to `[0, length]`.
@@ -2100,6 +2344,10 @@ export const takeRight: {
   /**
    * Keeps the last `n` elements, creating a new array.
    *
+   * **When to use**
+   *
+   * Use to keep the last `n` elements of an iterable.
+   *
    * **Details**
    *
    * - `n` is clamped to `[0, length]`.
@@ -2130,6 +2378,11 @@ export const takeRight: {
  * Takes elements from the start while the predicate holds, stopping at the
  * first element that fails.
  *
+ * **When to use**
+ *
+ * Use to keep the leading elements of an iterable while each element satisfies
+ * a predicate, returning the retained prefix as an array.
+ *
  * **Details**
  *
  * - Supports refinements for type narrowing.
@@ -2143,9 +2396,9 @@ export const takeRight: {
  * console.log(Array.takeWhile([1, 3, 2, 4, 1, 2], (x) => x < 4)) // [1, 3, 2]
  * ```
  *
- * @see {@link take} — take a fixed count
- * @see {@link dropWhile} — drop while predicate holds
- * @see {@link span} — split into matching prefix + rest
+ * @see {@link take} for keeping a fixed number of leading elements
+ * @see {@link dropWhile} for removing the matching prefix and keeping the rest
+ * @see {@link span} for splitting the matching prefix from the remaining elements
  *
  * @category getters
  * @since 2.0.0
@@ -2155,6 +2408,11 @@ export const takeWhile: {
    * Takes elements from the start while the predicate holds, stopping at the
    * first element that fails.
    *
+   * **When to use**
+   *
+   * Use to keep the leading elements of an iterable while each element satisfies
+   * a predicate, returning the retained prefix as an array.
+   *
    * **Details**
    *
    * - Supports refinements for type narrowing.
@@ -2168,9 +2426,9 @@ export const takeWhile: {
    * console.log(Array.takeWhile([1, 3, 2, 4, 1, 2], (x) => x < 4)) // [1, 3, 2]
    * ```
    *
-   * @see {@link take} — take a fixed count
-   * @see {@link dropWhile} — drop while predicate holds
-   * @see {@link span} — split into matching prefix + rest
+   * @see {@link take} for keeping a fixed number of leading elements
+   * @see {@link dropWhile} for removing the matching prefix and keeping the rest
+   * @see {@link span} for splitting the matching prefix from the remaining elements
    *
    * @category getters
    * @since 2.0.0
@@ -2180,6 +2438,11 @@ export const takeWhile: {
    * Takes elements from the start while the predicate holds, stopping at the
    * first element that fails.
    *
+   * **When to use**
+   *
+   * Use to keep the leading elements of an iterable while each element satisfies
+   * a predicate, returning the retained prefix as an array.
+   *
    * **Details**
    *
    * - Supports refinements for type narrowing.
@@ -2193,9 +2456,9 @@ export const takeWhile: {
    * console.log(Array.takeWhile([1, 3, 2, 4, 1, 2], (x) => x < 4)) // [1, 3, 2]
    * ```
    *
-   * @see {@link take} — take a fixed count
-   * @see {@link dropWhile} — drop while predicate holds
-   * @see {@link span} — split into matching prefix + rest
+   * @see {@link take} for keeping a fixed number of leading elements
+   * @see {@link dropWhile} for removing the matching prefix and keeping the rest
+   * @see {@link span} for splitting the matching prefix from the remaining elements
    *
    * @category getters
    * @since 2.0.0
@@ -2205,6 +2468,11 @@ export const takeWhile: {
    * Takes elements from the start while the predicate holds, stopping at the
    * first element that fails.
    *
+   * **When to use**
+   *
+   * Use to keep the leading elements of an iterable while each element satisfies
+   * a predicate, returning the retained prefix as an array.
+   *
    * **Details**
    *
    * - Supports refinements for type narrowing.
@@ -2218,9 +2486,9 @@ export const takeWhile: {
    * console.log(Array.takeWhile([1, 3, 2, 4, 1, 2], (x) => x < 4)) // [1, 3, 2]
    * ```
    *
-   * @see {@link take} — take a fixed count
-   * @see {@link dropWhile} — drop while predicate holds
-   * @see {@link span} — split into matching prefix + rest
+   * @see {@link take} for keeping a fixed number of leading elements
+   * @see {@link dropWhile} for removing the matching prefix and keeping the rest
+   * @see {@link span} for splitting the matching prefix from the remaining elements
    *
    * @category getters
    * @since 2.0.0
@@ -2230,6 +2498,11 @@ export const takeWhile: {
    * Takes elements from the start while the predicate holds, stopping at the
    * first element that fails.
    *
+   * **When to use**
+   *
+   * Use to keep the leading elements of an iterable while each element satisfies
+   * a predicate, returning the retained prefix as an array.
+   *
    * **Details**
    *
    * - Supports refinements for type narrowing.
@@ -2243,9 +2516,9 @@ export const takeWhile: {
    * console.log(Array.takeWhile([1, 3, 2, 4, 1, 2], (x) => x < 4)) // [1, 3, 2]
    * ```
    *
-   * @see {@link take} — take a fixed count
-   * @see {@link dropWhile} — drop while predicate holds
-   * @see {@link span} — split into matching prefix + rest
+   * @see {@link take} for keeping a fixed number of leading elements
+   * @see {@link dropWhile} for removing the matching prefix and keeping the rest
+   * @see {@link span} for splitting the matching prefix from the remaining elements
    *
    * @category getters
    * @since 2.0.0
@@ -2267,11 +2540,19 @@ export const takeWhile: {
 /**
  * Takes elements from the start while a `Filter` succeeds, collecting transformed values.
  *
+ * **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
+ * that produces a failure result.
+ *
  * **Details**
  *
  * - The filter receives `(element, index)`.
  * - Stops at the first filter failure.
  *
+ * @see {@link takeWhile} for taking a prefix based on a boolean predicate
+ *
  * @category getters
  * @since 4.0.0
  */
@@ -2279,11 +2560,19 @@ export const takeWhileFilter: {
   /**
    * Takes elements from the start while a `Filter` succeeds, collecting transformed values.
    *
+   * **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
+   * that produces a failure result.
+   *
    * **Details**
    *
    * - The filter receives `(element, index)`.
    * - Stops at the first filter failure.
    *
+   * @see {@link takeWhile} for taking a prefix based on a boolean predicate
+   *
    * @category getters
    * @since 4.0.0
    */
@@ -2291,11 +2580,19 @@ export const takeWhileFilter: {
   /**
    * Takes elements from the start while a `Filter` succeeds, collecting transformed values.
    *
+   * **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
+   * that produces a failure result.
+   *
    * **Details**
    *
    * - The filter receives `(element, index)`.
    * - Stops at the first filter failure.
    *
+   * @see {@link takeWhile} for taking a prefix based on a boolean predicate
+   *
    * @category getters
    * @since 4.0.0
    */
@@ -2332,6 +2629,11 @@ const spanIndex = <A>(self: Iterable<A>, predicate: (a: A, i: number) => boolean
  * Splits an iterable into two arrays: the longest prefix where the predicate
  * holds, and the remaining elements.
  *
+ * **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.
+ *
  * **Details**
  *
  * - Equivalent to `[takeWhile(pred), dropWhile(pred)]` but more efficient
@@ -2346,9 +2648,9 @@ const spanIndex = <A>(self: Iterable<A>, predicate: (a: A, i: number) => boolean
  * console.log(Array.span([1, 3, 2, 4, 5], (x) => x % 2 === 1)) // [[1, 3], [2, 4, 5]]
  * ```
  *
- * @see {@link takeWhile} — keep only the matching prefix
- * @see {@link dropWhile} — keep only the rest
- * @see {@link splitWhere} — split at the first element matching a predicate
+ * @see {@link takeWhile} for keeping only the matching prefix
+ * @see {@link dropWhile} for keeping only the elements after the matching prefix
+ * @see {@link splitWhere} for splitting at the first element that satisfies a predicate
  *
  * @category splitting
  * @since 2.0.0
@@ -2358,6 +2660,11 @@ export const span: {
    * Splits an iterable into two arrays: the longest prefix where the predicate
    * holds, and the remaining elements.
    *
+   * **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.
+   *
    * **Details**
    *
    * - Equivalent to `[takeWhile(pred), dropWhile(pred)]` but more efficient
@@ -2372,9 +2679,9 @@ export const span: {
    * console.log(Array.span([1, 3, 2, 4, 5], (x) => x % 2 === 1)) // [[1, 3], [2, 4, 5]]
    * ```
    *
-   * @see {@link takeWhile} — keep only the matching prefix
-   * @see {@link dropWhile} — keep only the rest
-   * @see {@link splitWhere} — split at the first element matching a predicate
+   * @see {@link takeWhile} for keeping only the matching prefix
+   * @see {@link dropWhile} for keeping only the elements after the matching prefix
+   * @see {@link splitWhere} for splitting at the first element that satisfies a predicate
    *
    * @category splitting
    * @since 2.0.0
@@ -2384,6 +2691,11 @@ export const span: {
    * Splits an iterable into two arrays: the longest prefix where the predicate
    * holds, and the remaining elements.
    *
+   * **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.
+   *
    * **Details**
    *
    * - Equivalent to `[takeWhile(pred), dropWhile(pred)]` but more efficient
@@ -2398,9 +2710,9 @@ export const span: {
    * console.log(Array.span([1, 3, 2, 4, 5], (x) => x % 2 === 1)) // [[1, 3], [2, 4, 5]]
    * ```
    *
-   * @see {@link takeWhile} — keep only the matching prefix
-   * @see {@link dropWhile} — keep only the rest
-   * @see {@link splitWhere} — split at the first element matching a predicate
+   * @see {@link takeWhile} for keeping only the matching prefix
+   * @see {@link dropWhile} for keeping only the elements after the matching prefix
+   * @see {@link splitWhere} for splitting at the first element that satisfies a predicate
    *
    * @category splitting
    * @since 2.0.0
@@ -2410,6 +2722,11 @@ export const span: {
    * Splits an iterable into two arrays: the longest prefix where the predicate
    * holds, and the remaining elements.
    *
+   * **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.
+   *
    * **Details**
    *
    * - Equivalent to `[takeWhile(pred), dropWhile(pred)]` but more efficient
@@ -2424,9 +2741,9 @@ export const span: {
    * console.log(Array.span([1, 3, 2, 4, 5], (x) => x % 2 === 1)) // [[1, 3], [2, 4, 5]]
    * ```
    *
-   * @see {@link takeWhile} — keep only the matching prefix
-   * @see {@link dropWhile} — keep only the rest
-   * @see {@link splitWhere} — split at the first element matching a predicate
+   * @see {@link takeWhile} for keeping only the matching prefix
+   * @see {@link dropWhile} for keeping only the elements after the matching prefix
+   * @see {@link splitWhere} for splitting at the first element that satisfies a predicate
    *
    * @category splitting
    * @since 2.0.0
@@ -2436,6 +2753,11 @@ export const span: {
    * Splits an iterable into two arrays: the longest prefix where the predicate
    * holds, and the remaining elements.
    *
+   * **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.
+   *
    * **Details**
    *
    * - Equivalent to `[takeWhile(pred), dropWhile(pred)]` but more efficient
@@ -2450,9 +2772,9 @@ export const span: {
    * console.log(Array.span([1, 3, 2, 4, 5], (x) => x % 2 === 1)) // [[1, 3], [2, 4, 5]]
    * ```
    *
-   * @see {@link takeWhile} — keep only the matching prefix
-   * @see {@link dropWhile} — keep only the rest
-   * @see {@link splitWhere} — split at the first element matching a predicate
+   * @see {@link takeWhile} for keeping only the matching prefix
+   * @see {@link dropWhile} for keeping only the elements after the matching prefix
+   * @see {@link splitWhere} for splitting at the first element that satisfies a predicate
    *
    * @category splitting
    * @since 2.0.0
@@ -2469,6 +2791,11 @@ export const span: {
 /**
  * Removes the first `n` elements, creating a new array.
  *
+ * **When to use**
+ *
+ * Use to keep the suffix of an iterable after skipping a fixed number of
+ * leading elements.
+ *
  * **Details**
  *
  * - `n` is clamped to `[0, length]`.
@@ -2482,9 +2809,9 @@ export const span: {
  * console.log(Array.drop([1, 2, 3, 4, 5], 2)) // [3, 4, 5]
  * ```
  *
- * @see {@link dropRight} — remove from the end
- * @see {@link dropWhile} — remove while predicate holds
- * @see {@link take} — keep from the start
+ * @see {@link dropRight} for removing a fixed number of elements from the end
+ * @see {@link dropWhile} for removing a prefix based on a predicate instead of a fixed count
+ * @see {@link take} for keeping a fixed number of elements from the start
  *
  * @category getters
  * @since 2.0.0
@@ -2493,6 +2820,11 @@ export const drop: {
   /**
    * Removes the first `n` elements, creating a new array.
    *
+   * **When to use**
+   *
+   * Use to keep the suffix of an iterable after skipping a fixed number of
+   * leading elements.
+   *
    * **Details**
    *
    * - `n` is clamped to `[0, length]`.
@@ -2506,9 +2838,9 @@ export const drop: {
    * console.log(Array.drop([1, 2, 3, 4, 5], 2)) // [3, 4, 5]
    * ```
    *
-   * @see {@link dropRight} — remove from the end
-   * @see {@link dropWhile} — remove while predicate holds
-   * @see {@link take} — keep from the start
+   * @see {@link dropRight} for removing a fixed number of elements from the end
+   * @see {@link dropWhile} for removing a prefix based on a predicate instead of a fixed count
+   * @see {@link take} for keeping a fixed number of elements from the start
    *
    * @category getters
    * @since 2.0.0
@@ -2517,6 +2849,11 @@ export const drop: {
   /**
    * Removes the first `n` elements, creating a new array.
    *
+   * **When to use**
+   *
+   * Use to keep the suffix of an iterable after skipping a fixed number of
+   * leading elements.
+   *
    * **Details**
    *
    * - `n` is clamped to `[0, length]`.
@@ -2530,9 +2867,9 @@ export const drop: {
    * console.log(Array.drop([1, 2, 3, 4, 5], 2)) // [3, 4, 5]
    * ```
    *
-   * @see {@link dropRight} — remove from the end
-   * @see {@link dropWhile} — remove while predicate holds
-   * @see {@link take} — keep from the start
+   * @see {@link dropRight} for removing a fixed number of elements from the end
+   * @see {@link dropWhile} for removing a prefix based on a predicate instead of a fixed count
+   * @see {@link take} for keeping a fixed number of elements from the start
    *
    * @category getters
    * @since 2.0.0
@@ -2546,9 +2883,13 @@ export const drop: {
 /**
  * Removes the last `n` elements, creating a new array.
  *
+ * **When to use**
+ *
+ * Use to remove the last `n` elements from an iterable.
+ *
  * **Details**
  *
- * - `n` is clamped to `[0, length]`.
+ * `n` is clamped to `[0, length]`.
  *
  * **Example** (Dropping from the end)
  *
@@ -2568,9 +2909,13 @@ export const dropRight: {
   /**
    * Removes the last `n` elements, creating a new array.
    *
+   * **When to use**
+   *
+   * Use to remove the last `n` elements from an iterable.
+   *
    * **Details**
    *
-   * - `n` is clamped to `[0, length]`.
+   * `n` is clamped to `[0, length]`.
    *
    * **Example** (Dropping from the end)
    *
@@ -2590,9 +2935,13 @@ export const dropRight: {
   /**
    * Removes the last `n` elements, creating a new array.
    *
+   * **When to use**
+   *
+   * Use to remove the last `n` elements from an iterable.
+   *
    * **Details**
    *
-   * - `n` is clamped to `[0, length]`.
+   * `n` is clamped to `[0, length]`.
    *
    * **Example** (Dropping from the end)
    *
@@ -2617,9 +2966,13 @@ export const dropRight: {
 /**
  * Drops elements from the start while the predicate holds, returning the rest.
  *
+ * **When to use**
+ *
+ * Use to remove a leading prefix of elements that satisfy a predicate.
+ *
  * **Details**
  *
- * - The predicate receives `(element, index)`.
+ * The predicate receives `(element, index)`.
  *
  * **Example** (Dropping while condition holds)
  *
@@ -2639,9 +2992,13 @@ export const dropWhile: {
   /**
    * Drops elements from the start while the predicate holds, returning the rest.
    *
+   * **When to use**
+   *
+   * Use to remove a leading prefix of elements that satisfy a predicate.
+   *
    * **Details**
    *
-   * - The predicate receives `(element, index)`.
+   * The predicate receives `(element, index)`.
    *
    * **Example** (Dropping while condition holds)
    *
@@ -2661,9 +3018,13 @@ export const dropWhile: {
   /**
    * Drops elements from the start while the predicate holds, returning the rest.
    *
+   * **When to use**
+   *
+   * Use to remove a leading prefix of elements that satisfy a predicate.
+   *
    * **Details**
    *
-   * - The predicate receives `(element, index)`.
+   * The predicate receives `(element, index)`.
    *
    * **Example** (Dropping while condition holds)
    *
@@ -2695,11 +3056,19 @@ export const dropWhile: {
 /**
  * Drops elements from the start while a `Filter` succeeds.
  *
+ * **When to use**
+ *
+ * Use when dropping a prefix requires computing a `Result` per element instead
+ * of a simple boolean predicate.
+ *
  * **Details**
  *
  * - The filter receives `(element, index)`.
  * - Returns 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
+ *
  * @category getters
  * @since 4.0.0
  */
@@ -2707,11 +3076,19 @@ export const dropWhileFilter: {
   /**
    * Drops elements from the start while a `Filter` succeeds.
    *
+   * **When to use**
+   *
+   * Use when dropping a prefix requires computing a `Result` per element instead
+   * of a simple boolean predicate.
+   *
    * **Details**
    *
    * - The filter receives `(element, index)`.
    * - Returns 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
+   *
    * @category getters
    * @since 4.0.0
    */
@@ -2719,11 +3096,19 @@ export const dropWhileFilter: {
   /**
    * Drops elements from the start while a `Filter` succeeds.
    *
+   * **When to use**
+   *
+   * Use when dropping a prefix requires computing a `Result` per element instead
+   * of a simple boolean predicate.
+   *
    * **Details**
    *
    * - The filter receives `(element, index)`.
    * - Returns 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
+   *
    * @category getters
    * @since 4.0.0
    */
@@ -2747,6 +3132,11 @@ export const dropWhileFilter: {
  * Returns the index of the first element matching the predicate, wrapped in an
  * `Option`.
  *
+ * **When to use**
+ *
+ * Use to find the index of the first matching element from the start of an
+ * iterable.
+ *
  * **Example** (Finding an index)
  *
  * ```ts
@@ -2766,6 +3156,11 @@ export const findFirstIndex: {
    * Returns the index of the first element matching the predicate, wrapped in an
    * `Option`.
    *
+   * **When to use**
+   *
+   * Use to find the index of the first matching element from the start of an
+   * iterable.
+   *
    * **Example** (Finding an index)
    *
    * ```ts
@@ -2785,6 +3180,11 @@ export const findFirstIndex: {
    * Returns the index of the first element matching the predicate, wrapped in an
    * `Option`.
    *
+   * **When to use**
+   *
+   * Use to find the index of the first matching element from the start of an
+   * iterable.
+   *
    * **Example** (Finding an index)
    *
    * ```ts
@@ -2815,6 +3215,10 @@ export const findFirstIndex: {
  * Returns the index of the last element matching the predicate, wrapped in an
  * `Option`.
  *
+ * **When to use**
+ *
+ * Use to find the index of the last matching element from the end of an array.
+ *
  * **Example** (Finding the last matching index)
  *
  * ```ts
@@ -2834,6 +3238,10 @@ export const findLastIndex: {
    * Returns the index of the last element matching the predicate, wrapped in an
    * `Option`.
    *
+   * **When to use**
+   *
+   * Use to find the index of the last matching element from the end of an array.
+   *
    * **Example** (Finding the last matching index)
    *
    * ```ts
@@ -2853,6 +3261,10 @@ export const findLastIndex: {
    * Returns the index of the last element matching the predicate, wrapped in an
    * `Option`.
    *
+   * **When to use**
+   *
+   * Use to find the index of the last matching element from the end of an array.
+   *
    * **Example** (Finding the last matching index)
    *
    * ```ts
@@ -2882,6 +3294,11 @@ export const findLastIndex: {
  * Returns the first element matching a predicate, refinement, or mapping
  * function, wrapped in `Option`.
  *
+ * **When to use**
+ *
+ * Use to scan an iterable in iteration order and return the first selected
+ * element or mapped value as an `Option`.
+ *
  * **Details**
  *
  * - Accepts a predicate `(a, i) => boolean`, a refinement, or a function
@@ -2908,6 +3325,11 @@ export const findFirst: {
    * Returns the first element matching a predicate, refinement, or mapping
    * function, wrapped in `Option`.
    *
+   * **When to use**
+   *
+   * Use to scan an iterable in iteration order and return the first selected
+   * element or mapped value as an `Option`.
+   *
    * **Details**
    *
    * - Accepts a predicate `(a, i) => boolean`, a refinement, or a function
@@ -2934,6 +3356,11 @@ export const findFirst: {
    * Returns the first element matching a predicate, refinement, or mapping
    * function, wrapped in `Option`.
    *
+   * **When to use**
+   *
+   * Use to scan an iterable in iteration order and return the first selected
+   * element or mapped value as an `Option`.
+   *
    * **Details**
    *
    * - Accepts a predicate `(a, i) => boolean`, a refinement, or a function
@@ -2960,6 +3387,11 @@ export const findFirst: {
    * Returns the first element matching a predicate, refinement, or mapping
    * function, wrapped in `Option`.
    *
+   * **When to use**
+   *
+   * Use to scan an iterable in iteration order and return the first selected
+   * element or mapped value as an `Option`.
+   *
    * **Details**
    *
    * - Accepts a predicate `(a, i) => boolean`, a refinement, or a function
@@ -2986,6 +3418,11 @@ export const findFirst: {
    * Returns the first element matching a predicate, refinement, or mapping
    * function, wrapped in `Option`.
    *
+   * **When to use**
+   *
+   * Use to scan an iterable in iteration order and return the first selected
+   * element or mapped value as an `Option`.
+   *
    * **Details**
    *
    * - Accepts a predicate `(a, i) => boolean`, a refinement, or a function
@@ -3012,6 +3449,11 @@ export const findFirst: {
    * Returns the first element matching a predicate, refinement, or mapping
    * function, wrapped in `Option`.
    *
+   * **When to use**
+   *
+   * Use to scan an iterable in iteration order and return the first selected
+   * element or mapped value as an `Option`.
+   *
    * **Details**
    *
    * - Accepts a predicate `(a, i) => boolean`, a refinement, or a function
@@ -3038,6 +3480,11 @@ export const findFirst: {
    * Returns the first element matching a predicate, refinement, or mapping
    * function, wrapped in `Option`.
    *
+   * **When to use**
+   *
+   * Use to scan an iterable in iteration order and return the first selected
+   * element or mapped value as an `Option`.
+   *
    * **Details**
    *
    * - Accepts a predicate `(a, i) => boolean`, a refinement, or a function
@@ -3066,6 +3513,10 @@ export const findFirst: {
  * Returns the first selected value together with its index, wrapped in an
  * `Option`.
  *
+ * **When to use**
+ *
+ * Use to find both the first matching element and its index in one pass.
+ *
  * **Details**
  *
  * Accepts a predicate, a refinement, or a function returning `Option`. For an
@@ -3091,6 +3542,10 @@ export const findFirstWithIndex: {
    * Returns the first selected value together with its index, wrapped in an
    * `Option`.
    *
+   * **When to use**
+   *
+   * Use to find both the first matching element and its index in one pass.
+   *
    * **Details**
    *
    * Accepts a predicate, a refinement, or a function returning `Option`. For an
@@ -3116,6 +3571,10 @@ export const findFirstWithIndex: {
    * Returns the first selected value together with its index, wrapped in an
    * `Option`.
    *
+   * **When to use**
+   *
+   * Use to find both the first matching element and its index in one pass.
+   *
    * **Details**
    *
    * Accepts a predicate, a refinement, or a function returning `Option`. For an
@@ -3141,6 +3600,10 @@ export const findFirstWithIndex: {
    * Returns the first selected value together with its index, wrapped in an
    * `Option`.
    *
+   * **When to use**
+   *
+   * Use to find both the first matching element and its index in one pass.
+   *
    * **Details**
    *
    * Accepts a predicate, a refinement, or a function returning `Option`. For an
@@ -3166,6 +3629,10 @@ export const findFirstWithIndex: {
    * Returns the first selected value together with its index, wrapped in an
    * `Option`.
    *
+   * **When to use**
+   *
+   * Use to find both the first matching element and its index in one pass.
+   *
    * **Details**
    *
    * Accepts a predicate, a refinement, or a function returning `Option`. For an
@@ -3191,6 +3658,10 @@ export const findFirstWithIndex: {
    * Returns the first selected value together with its index, wrapped in an
    * `Option`.
    *
+   * **When to use**
+   *
+   * Use to find both the first matching element and its index in one pass.
+   *
    * **Details**
    *
    * Accepts a predicate, a refinement, or a function returning `Option`. For an
@@ -3216,6 +3687,10 @@ export const findFirstWithIndex: {
    * Returns the first selected value together with its index, wrapped in an
    * `Option`.
    *
+   * **When to use**
+   *
+   * Use to find both the first matching element and its index in one pass.
+   *
    * **Details**
    *
    * Accepts a predicate, a refinement, or a function returning `Option`. For an
@@ -3265,6 +3740,10 @@ export const findFirstWithIndex: {
  * Returns the last element matching a predicate, refinement, or mapping
  * function, wrapped in `Option`.
  *
+ * **When to use**
+ *
+ * Use to find the last matching element from the end of an array.
+ *
  * **Details**
  *
  * - Searches from the end of the array.
@@ -3289,6 +3768,10 @@ export const findLast: {
    * Returns the last element matching a predicate, refinement, or mapping
    * function, wrapped in `Option`.
    *
+   * **When to use**
+   *
+   * Use to find the last matching element from the end of an array.
+   *
    * **Details**
    *
    * - Searches from the end of the array.
@@ -3313,6 +3796,10 @@ export const findLast: {
    * Returns the last element matching a predicate, refinement, or mapping
    * function, wrapped in `Option`.
    *
+   * **When to use**
+   *
+   * Use to find the last matching element from the end of an array.
+   *
    * **Details**
    *
    * - Searches from the end of the array.
@@ -3337,6 +3824,10 @@ export const findLast: {
    * Returns the last element matching a predicate, refinement, or mapping
    * function, wrapped in `Option`.
    *
+   * **When to use**
+   *
+   * Use to find the last matching element from the end of an array.
+   *
    * **Details**
    *
    * - Searches from the end of the array.
@@ -3361,6 +3852,10 @@ export const findLast: {
    * Returns the last element matching a predicate, refinement, or mapping
    * function, wrapped in `Option`.
    *
+   * **When to use**
+   *
+   * Use to find the last matching element from the end of an array.
+   *
    * **Details**
    *
    * - Searches from the end of the array.
@@ -3385,6 +3880,10 @@ export const findLast: {
    * Returns the last element matching a predicate, refinement, or mapping
    * function, wrapped in `Option`.
    *
+   * **When to use**
+   *
+   * Use to find the last matching element from the end of an array.
+   *
    * **Details**
    *
    * - Searches from the end of the array.
@@ -3409,6 +3908,10 @@ export const findLast: {
    * Returns the last element matching a predicate, refinement, or mapping
    * function, wrapped in `Option`.
    *
+   * **When to use**
+   *
+   * Use to find the last matching element from the end of an array.
+   *
    * **Details**
    *
    * - Searches from the end of the array.
@@ -3454,13 +3957,16 @@ export const findLast: {
 )
 
 /**
- * Inserts an element at the specified index, returning a new `NonEmptyArray`
+ * Inserts an element at the specified index safely, returning a new `NonEmptyArray`
  * wrapped in an `Option`.
  *
+ * **When to use**
+ *
+ * Use to insert a single element at a specific position in an array.
+ *
  * **Details**
  *
  * - Valid indices: `0` to `length` (inclusive — inserting at `length` appends).
- * - Does not mutate the input.
  *
  * **Example** (Inserting at an index)
  *
@@ -3478,13 +3984,16 @@ export const findLast: {
  */
 export const insertAt: {
   /**
-   * Inserts an element at the specified index, returning a new `NonEmptyArray`
+   * Inserts an element at the specified index safely, returning a new `NonEmptyArray`
    * wrapped in an `Option`.
    *
+   * **When to use**
+   *
+   * Use to insert a single element at a specific position in an array.
+   *
    * **Details**
    *
    * - Valid indices: `0` to `length` (inclusive — inserting at `length` appends).
-   * - Does not mutate the input.
    *
    * **Example** (Inserting at an index)
    *
@@ -3502,13 +4011,16 @@ export const insertAt: {
    */
   <B>(i: number, b: B): <A>(self: Iterable<A>) => Option.Option<NonEmptyArray<A | B>>
   /**
-   * Inserts an element at the specified index, returning a new `NonEmptyArray`
+   * Inserts an element at the specified index safely, returning a new `NonEmptyArray`
    * wrapped in an `Option`.
    *
+   * **When to use**
+   *
+   * Use to insert a single element at a specific position in an array.
+   *
    * **Details**
    *
    * - Valid indices: `0` to `length` (inclusive — inserting at `length` appends).
-   * - Does not mutate the input.
    *
    * **Example** (Inserting at an index)
    *
@@ -3535,13 +4047,16 @@ export const insertAt: {
 })
 
 /**
- * Replaces the element at the specified index with a new value, returning the
+ * Replaces the element at the specified index safely with a new value, returning the
  * updated array in `Option.some`.
  *
+ * **When to use**
+ *
+ * Use to set a fixed replacement value at a specific index.
+ *
  * **Details**
  *
  * - Returns `Option.none()` when the index is out of bounds.
- * - Does not mutate the input.
  *
  * **Example** (Replacing an element)
  *
@@ -3559,13 +4074,16 @@ export const insertAt: {
  */
 export const replace: {
   /**
-   * Replaces the element at the specified index with a new value, returning the
+   * Replaces the element at the specified index safely with a new value, returning the
    * updated array in `Option.some`.
    *
+   * **When to use**
+   *
+   * Use to set a fixed replacement value at a specific index.
+   *
    * **Details**
    *
    * - Returns `Option.none()` when the index is out of bounds.
-   * - Does not mutate the input.
    *
    * **Example** (Replacing an element)
    *
@@ -3585,13 +4103,16 @@ export const replace: {
     self: S
   ) => Option.Option<ReadonlyArray.With<S, ReadonlyArray.Infer<S> | B>>
   /**
-   * Replaces the element at the specified index with a new value, returning the
+   * Replaces the element at the specified index safely with a new value, returning the
    * updated array in `Option.some`.
    *
+   * **When to use**
+   *
+   * Use to set a fixed replacement value at a specific index.
+   *
    * **Details**
    *
    * - Returns `Option.none()` when the index is out of bounds.
-   * - Does not mutate the input.
    *
    * **Example** (Replacing an element)
    *
@@ -3614,13 +4135,17 @@ export const replace: {
 )
 
 /**
- * Applies a function to the element at the specified index, returning the
+ * Applies a function to the element at the specified index safely, returning the
  * updated array in `Option.some`.
  *
+ * **When to use**
+ *
+ * Use to derive a replacement value from the current element at a specific
+ * index while leaving the other elements unchanged.
+ *
  * **Details**
  *
  * - Returns `Option.none()` when the index is out of bounds.
- * - Does not mutate the input.
  *
  * **Example** (Modifying an element)
  *
@@ -3640,13 +4165,17 @@ export const replace: {
  */
 export const modify: {
   /**
-   * Applies a function to the element at the specified index, returning the
+   * Applies a function to the element at the specified index safely, returning the
    * updated array in `Option.some`.
    *
+   * **When to use**
+   *
+   * Use to derive a replacement value from the current element at a specific
+   * index while leaving the other elements unchanged.
+   *
    * **Details**
    *
    * - Returns `Option.none()` when the index is out of bounds.
-   * - Does not mutate the input.
    *
    * **Example** (Modifying an element)
    *
@@ -3666,13 +4195,17 @@ export const modify: {
    */
   <A, B, S extends Iterable<A> = Iterable<A>>(i: number, f: (a: ReadonlyArray.Infer<S>) => B): (self: S) => Option.Option<ReadonlyArray.With<S, ReadonlyArray.Infer<S> | B>>
   /**
-   * Applies a function to the element at the specified index, returning the
+   * Applies a function to the element at the specified index safely, returning the
    * updated array in `Option.some`.
    *
+   * **When to use**
+   *
+   * Use to derive a replacement value from the current element at a specific
+   * index while leaving the other elements unchanged.
+   *
    * **Details**
    *
    * - Returns `Option.none()` when the index is out of bounds.
-   * - Does not mutate the input.
    *
    * **Example** (Modifying an element)
    *
@@ -3706,9 +4239,9 @@ export const modify: {
  * Removes the element at the specified index, returning a new array. If the
  * index is out of bounds, returns a copy of the original.
  *
- * **Details**
+ * **When to use**
  *
- * - Does not mutate the input.
+ * Use to remove a single element at a known index.
  *
  * **Example** (Removing an element)
  *
@@ -3730,9 +4263,9 @@ export const remove: {
    * Removes the element at the specified index, returning a new array. If the
    * index is out of bounds, returns a copy of the original.
    *
-   * **Details**
+   * **When to use**
    *
-   * - Does not mutate the input.
+   * Use to remove a single element at a known index.
    *
    * **Example** (Removing an element)
    *
@@ -3754,9 +4287,9 @@ export const remove: {
    * Removes the element at the specified index, returning a new array. If the
    * index is out of bounds, returns a copy of the original.
    *
-   * **Details**
+   * **When to use**
    *
-   * - Does not mutate the input.
+   * Use to remove a single element at a known index.
    *
    * **Example** (Removing an element)
    *
@@ -3786,9 +4319,12 @@ export const remove: {
 /**
  * Reverses an iterable into a new array.
  *
+ * **When to use**
+ *
+ * Use to reverse the order of elements without mutating the original input.
+ *
  * **Details**
  *
- * - Does not mutate the input.
  * - Preserves `NonEmptyArray` in the return type.
  *
  * **Example** (Reversing an array)
@@ -3810,9 +4346,12 @@ export const reverse = <S extends Iterable<any>>(
 /**
  * Sorts an array by the given `Order`, returning a new array.
  *
+ * **When to use**
+ *
+ * Use to sort an array using a single `Order` comparator.
+ *
  * **Details**
  *
- * - Does not mutate the input.
  * - Preserves `NonEmptyArray` in the return type.
  * - Use {@link sortWith} to sort by a derived key, or {@link sortBy} for
  *   multi-key sorting.
@@ -3835,9 +4374,12 @@ export const sort: {
   /**
    * Sorts an array by the given `Order`, returning a new array.
    *
+   * **When to use**
+   *
+   * Use to sort an array using a single `Order` comparator.
+   *
    * **Details**
    *
-   * - Does not mutate the input.
    * - Preserves `NonEmptyArray` in the return type.
    * - Use {@link sortWith} to sort by a derived key, or {@link sortBy} for
    *   multi-key sorting.
@@ -3860,9 +4402,12 @@ export const sort: {
   /**
    * Sorts an array by the given `Order`, returning a new array.
    *
+   * **When to use**
+   *
+   * Use to sort an array using a single `Order` comparator.
+   *
    * **Details**
    *
-   * - Does not mutate the input.
    * - Preserves `NonEmptyArray` in the return type.
    * - Use {@link sortWith} to sort by a derived key, or {@link sortBy} for
    *   multi-key sorting.
@@ -3885,9 +4430,12 @@ export const sort: {
   /**
    * Sorts an array by the given `Order`, returning a new array.
    *
+   * **When to use**
+   *
+   * Use to sort an array using a single `Order` comparator.
+   *
    * **Details**
    *
-   * - Does not mutate the input.
    * - Preserves `NonEmptyArray` in the return type.
    * - Use {@link sortWith} to sort by a derived key, or {@link sortBy} for
    *   multi-key sorting.
@@ -3917,10 +4465,14 @@ export const sort: {
  * Sorts an array by a derived key using a mapping function and an `Order` for
  * that key.
  *
+ * **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.
+ *
  * **Details**
  *
  * - Equivalent to `sort(Order.mapInput(order, f))` but more convenient.
- * - Does not mutate the input.
  *
  * **Example** (Sorting strings by length)
  *
@@ -3931,8 +4483,8 @@ export const sort: {
  * // ["b", "cc", "aaa"]
  * ```
  *
- * @see {@link sort} — sort by a direct `Order`
- * @see {@link sortBy} — sort by multiple orders
+ * @see {@link sort} for sorting with an `Order` that compares the elements directly
+ * @see {@link sortBy} for sorting with multiple `Order`s applied in sequence
  *
  * @category elements
  * @since 2.0.0
@@ -3942,10 +4494,14 @@ export const sortWith: {
    * Sorts an array by a derived key using a mapping function and an `Order` for
    * that key.
    *
+   * **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.
+   *
    * **Details**
    *
    * - Equivalent to `sort(Order.mapInput(order, f))` but more convenient.
-   * - Does not mutate the input.
    *
    * **Example** (Sorting strings by length)
    *
@@ -3956,8 +4512,8 @@ export const sortWith: {
    * // ["b", "cc", "aaa"]
    * ```
    *
-   * @see {@link sort} — sort by a direct `Order`
-   * @see {@link sortBy} — sort by multiple orders
+   * @see {@link sort} for sorting with an `Order` that compares the elements directly
+   * @see {@link sortBy} for sorting with multiple `Order`s applied in sequence
    *
    * @category elements
    * @since 2.0.0
@@ -3967,10 +4523,14 @@ export const sortWith: {
    * Sorts an array by a derived key using a mapping function and an `Order` for
    * that key.
    *
+   * **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.
+   *
    * **Details**
    *
    * - Equivalent to `sort(Order.mapInput(order, f))` but more convenient.
-   * - Does not mutate the input.
    *
    * **Example** (Sorting strings by length)
    *
@@ -3981,8 +4541,8 @@ export const sortWith: {
    * // ["b", "cc", "aaa"]
    * ```
    *
-   * @see {@link sort} — sort by a direct `Order`
-   * @see {@link sortBy} — sort by multiple orders
+   * @see {@link sort} for sorting with an `Order` that compares the elements directly
+   * @see {@link sortBy} for sorting with multiple `Order`s applied in sequence
    *
    * @category elements
    * @since 2.0.0
@@ -3992,10 +4552,14 @@ export const sortWith: {
    * Sorts an array by a derived key using a mapping function and an `Order` for
    * that key.
    *
+   * **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.
+   *
    * **Details**
    *
    * - Equivalent to `sort(Order.mapInput(order, f))` but more convenient.
-   * - Does not mutate the input.
    *
    * **Example** (Sorting strings by length)
    *
@@ -4006,8 +4570,8 @@ export const sortWith: {
    * // ["b", "cc", "aaa"]
    * ```
    *
-   * @see {@link sort} — sort by a direct `Order`
-   * @see {@link sortBy} — sort by multiple orders
+   * @see {@link sort} for sorting with an `Order` that compares the elements directly
+   * @see {@link sortBy} for sorting with multiple `Order`s applied in sequence
    *
    * @category elements
    * @since 2.0.0
@@ -4023,6 +4587,11 @@ export const sortWith: {
  * Sorts an array by multiple `Order`s applied in sequence: the first order is
  * used first; ties are broken by the second order, and so on.
  *
+ * **When to use**
+ *
+ * Use to sort by multiple criteria where later orders break ties from earlier
+ * ones.
+ *
  * **Details**
  *
  * - Data-last only (returns a function).
@@ -4075,6 +4644,10 @@ export const sortBy = <S extends Iterable<any>>(
  * Pairs elements from two iterables by position. If the iterables differ in
  * length, the extra elements from the longer one are discarded.
  *
+ * **When to use**
+ *
+ * Use to pair corresponding elements from two iterables when you need simple pairs without a custom combiner.
+ *
  * **Details**
  *
  * - Returns `NonEmptyArray` when both inputs are non-empty.
@@ -4098,6 +4671,10 @@ export const zip: {
    * Pairs elements from two iterables by position. If the iterables differ in
    * length, the extra elements from the longer one are discarded.
    *
+   * **When to use**
+   *
+   * Use to pair corresponding elements from two iterables when you need simple pairs without a custom combiner.
+   *
    * **Details**
    *
    * - Returns `NonEmptyArray` when both inputs are non-empty.
@@ -4121,6 +4698,10 @@ export const zip: {
    * Pairs elements from two iterables by position. If the iterables differ in
    * length, the extra elements from the longer one are discarded.
    *
+   * **When to use**
+   *
+   * Use to pair corresponding elements from two iterables when you need simple pairs without a custom combiner.
+   *
    * **Details**
    *
    * - Returns `NonEmptyArray` when both inputs are non-empty.
@@ -4144,6 +4725,10 @@ export const zip: {
    * Pairs elements from two iterables by position. If the iterables differ in
    * length, the extra elements from the longer one are discarded.
    *
+   * **When to use**
+   *
+   * Use to pair corresponding elements from two iterables when you need simple pairs without a custom combiner.
+   *
    * **Details**
    *
    * - Returns `NonEmptyArray` when both inputs are non-empty.
@@ -4167,6 +4752,10 @@ export const zip: {
    * Pairs elements from two iterables by position. If the iterables differ in
    * length, the extra elements from the longer one are discarded.
    *
+   * **When to use**
+   *
+   * Use to pair corresponding elements from two iterables when you need simple pairs without a custom combiner.
+   *
    * **Details**
    *
    * - Returns `NonEmptyArray` when both inputs are non-empty.
@@ -4336,6 +4925,10 @@ export const unzip: <S extends Iterable<readonly [any, any]>>(
 /**
  * Places a separator element between every pair of elements.
  *
+ * **When to use**
+ *
+ * Use to insert a separator between elements, for example when preparing data for display or concatenation.
+ *
  * **Details**
  *
  * - Preserves `NonEmptyArray` in the return type.
@@ -4358,6 +4951,10 @@ export const intersperse: {
   /**
    * Places a separator element between every pair of elements.
    *
+   * **When to use**
+   *
+   * Use to insert a separator between elements, for example when preparing data for display or concatenation.
+   *
    * **Details**
    *
    * - Preserves `NonEmptyArray` in the return type.
@@ -4380,6 +4977,10 @@ export const intersperse: {
   /**
    * Places a separator element between every pair of elements.
    *
+   * **When to use**
+   *
+   * Use to insert a separator between elements, for example when preparing data for display or concatenation.
+   *
    * **Details**
    *
    * - Preserves `NonEmptyArray` in the return type.
@@ -4402,6 +5003,10 @@ export const intersperse: {
   /**
    * Places a separator element between every pair of elements.
    *
+   * **When to use**
+   *
+   * Use to insert a separator between elements, for example when preparing data for display or concatenation.
+   *
    * **Details**
    *
    * - Preserves `NonEmptyArray` in the return type.
@@ -4441,6 +5046,10 @@ export const intersperse: {
  * Applies a function to the first element of a non-empty array, returning a
  * new array.
  *
+ * **When to use**
+ *
+ * Use to transform the first element of a non-empty array while preserving the rest.
+ *
  * **Example** (Modifying the head)
  *
  * ```ts
@@ -4460,6 +5069,10 @@ export const modifyHeadNonEmpty: {
    * Applies a function to the first element of a non-empty array, returning a
    * new array.
    *
+   * **When to use**
+   *
+   * Use to transform the first element of a non-empty array while preserving the rest.
+   *
    * **Example** (Modifying the head)
    *
    * ```ts
@@ -4479,6 +5092,10 @@ export const modifyHeadNonEmpty: {
    * Applies a function to the first element of a non-empty array, returning a
    * new array.
    *
+   * **When to use**
+   *
+   * Use to transform the first element of a non-empty array while preserving the rest.
+   *
    * **Example** (Modifying the head)
    *
    * ```ts
@@ -4684,9 +5301,14 @@ export const setLastNonEmpty: {
 )
 
 /**
- * Rotates an array by `n` steps. Positive `n` rotates right; negative `n`
+ * Transforms an array by rotating it `n` steps. Positive `n` rotates right; negative `n`
  * rotates left.
  *
+ * **When to use**
+ *
+ * Use when elements should wrap around the end of the array rather than being
+ * dropped.
+ *
  * **Details**
  *
  * - `n` is rounded to the nearest integer before rotating.
@@ -4701,14 +5323,22 @@ export const setLastNonEmpty: {
  * console.log(Array.rotate(["a", "b", "c", "d"], 2)) // ["c", "d", "a", "b"]
  * ```
  *
+ * @see {@link take} for taking a fixed number of elements from the start
+ * @see {@link drop} for dropping a fixed number of elements from the start
+ *
  * @category elements
  * @since 2.0.0
  */
 export const rotate: {
   /**
-   * Rotates an array by `n` steps. Positive `n` rotates right; negative `n`
+   * Transforms an array by rotating it `n` steps. Positive `n` rotates right; negative `n`
    * rotates left.
    *
+   * **When to use**
+   *
+   * Use when elements should wrap around the end of the array rather than being
+   * dropped.
+   *
    * **Details**
    *
    * - `n` is rounded to the nearest integer before rotating.
@@ -4723,14 +5353,22 @@ export const rotate: {
    * console.log(Array.rotate(["a", "b", "c", "d"], 2)) // ["c", "d", "a", "b"]
    * ```
    *
+   * @see {@link take} for taking a fixed number of elements from the start
+   * @see {@link drop} for dropping a fixed number of elements from the start
+   *
    * @category elements
    * @since 2.0.0
    */
   (n: number): <S extends Iterable<any>>(self: S) => ReadonlyArray.With<S, ReadonlyArray.Infer<S>>
   /**
-   * Rotates an array by `n` steps. Positive `n` rotates right; negative `n`
+   * Transforms an array by rotating it `n` steps. Positive `n` rotates right; negative `n`
    * rotates left.
    *
+   * **When to use**
+   *
+   * Use when elements should wrap around the end of the array rather than being
+   * dropped.
+   *
    * **Details**
    *
    * - `n` is rounded to the nearest integer before rotating.
@@ -4745,14 +5383,22 @@ export const rotate: {
    * console.log(Array.rotate(["a", "b", "c", "d"], 2)) // ["c", "d", "a", "b"]
    * ```
    *
+   * @see {@link take} for taking a fixed number of elements from the start
+   * @see {@link drop} for dropping a fixed number of elements from the start
+   *
    * @category elements
    * @since 2.0.0
    */
   <A>(self: NonEmptyReadonlyArray<A>, n: number): NonEmptyArray<A>
   /**
-   * Rotates an array by `n` steps. Positive `n` rotates right; negative `n`
+   * Transforms an array by rotating it `n` steps. Positive `n` rotates right; negative `n`
    * rotates left.
    *
+   * **When to use**
+   *
+   * Use when elements should wrap around the end of the array rather than being
+   * dropped.
+   *
    * **Details**
    *
    * - `n` is rounded to the nearest integer before rotating.
@@ -4767,6 +5413,9 @@ export const rotate: {
    * console.log(Array.rotate(["a", "b", "c", "d"], 2)) // ["c", "d", "a", "b"]
    * ```
    *
+   * @see {@link take} for taking a fixed number of elements from the start
+   * @see {@link drop} for dropping a fixed number of elements from the start
+   *
    * @category elements
    * @since 2.0.0
    */
@@ -4792,6 +5441,11 @@ export const rotate: {
 /**
  * Returns a membership-test function using a custom equivalence.
  *
+ * **When to use**
+ *
+ * Use when checking membership with caller-provided equality instead of
+ * `Equal.equivalence()`.
+ *
  * **Example** (Custom equality check)
  *
  * ```ts
@@ -4801,7 +5455,7 @@ export const rotate: {
  * console.log(pipe([1, 2, 3, 4], containsNumber(3))) // true
  * ```
  *
- * @see {@link contains} — uses default `Equal.equivalence()`
+ * @see {@link contains} for the `Equal.equivalence()` variant
  *
  * @category elements
  * @since 2.0.0
@@ -4820,9 +5474,14 @@ export const containsWith = <A>(isEquivalent: (self: A, that: A) => boolean): {
   })
 
 /**
- * Tests whether an array contains a value, using `Equal.equivalence()` for
+ * Checks whether an array contains a value, using `Equal.equivalence()` for
  * comparison.
  *
+ * **When to use**
+ *
+ * Use to check membership with Effect's default equality instead of providing a
+ * comparison function.
+ *
  * **Example** (Checking membership)
  *
  * ```ts
@@ -4838,9 +5497,14 @@ export const containsWith = <A>(isEquivalent: (self: A, that: A) => boolean): {
  */
 export const contains: {
   /**
-   * Tests whether an array contains a value, using `Equal.equivalence()` for
+   * Checks whether an array contains a value, using `Equal.equivalence()` for
    * comparison.
    *
+   * **When to use**
+   *
+   * Use to check membership with Effect's default equality instead of providing a
+   * comparison function.
+   *
    * **Example** (Checking membership)
    *
    * ```ts
@@ -4856,9 +5520,14 @@ export const contains: {
    */
   <A>(a: A): (self: Iterable<A>) => boolean
   /**
-   * Tests whether an array contains a value, using `Equal.equivalence()` for
+   * Checks whether an array contains a value, using `Equal.equivalence()` for
    * comparison.
    *
+   * **When to use**
+   *
+   * Use to check membership with Effect's default equality instead of providing a
+   * comparison function.
+   *
    * **Example** (Checking membership)
    *
    * ```ts
@@ -4876,8 +5545,13 @@ export const contains: {
 } = containsWith(Equal.asEquivalence())
 
 /**
- * Repeatedly applies a function that consumes a prefix of the array and
- * produces a value plus the remaining elements, collecting the values.
+ * Applies a function repeatedly to consume prefixes of the array and collect
+ * the values it produces.
+ *
+ * **When to use**
+ *
+ * Use when the grouping logic is custom and each step needs to return both a
+ * value and the remaining input.
  *
  * **Details**
  *
@@ -4906,8 +5580,13 @@ export const contains: {
  */
 export const chop: {
   /**
-   * Repeatedly applies a function that consumes a prefix of the array and
-   * produces a value plus the remaining elements, collecting the values.
+   * Applies a function repeatedly to consume prefixes of the array and collect
+   * the values it produces.
+   *
+   * **When to use**
+   *
+   * Use when the grouping logic is custom and each step needs to return both a
+   * value and the remaining input.
    *
    * **Details**
    *
@@ -4938,8 +5617,13 @@ export const chop: {
     f: (as: NonEmptyReadonlyArray<ReadonlyArray.Infer<S>>) => readonly [B, ReadonlyArray<ReadonlyArray.Infer<S>>]
   ): (self: S) => ReadonlyArray.With<S, ReadonlyArray.Infer<S>>
   /**
-   * Repeatedly applies a function that consumes a prefix of the array and
-   * produces a value plus the remaining elements, collecting the values.
+   * Applies a function repeatedly to consume prefixes of the array and collect
+   * the values it produces.
+   *
+   * **When to use**
+   *
+   * Use when the grouping logic is custom and each step needs to return both a
+   * value and the remaining input.
    *
    * **Details**
    *
@@ -4971,8 +5655,13 @@ export const chop: {
     f: (as: NonEmptyReadonlyArray<A>) => readonly [B, ReadonlyArray<A>]
   ): NonEmptyArray<B>
   /**
-   * Repeatedly applies a function that consumes a prefix of the array and
-   * produces a value plus the remaining elements, collecting the values.
+   * Applies a function repeatedly to consume prefixes of the array and collect
+   * the values it produces.
+   *
+   * **When to use**
+   *
+   * Use when the grouping logic is custom and each step needs to return both a
+   * value and the remaining input.
    *
    * **Details**
    *
@@ -5025,6 +5714,10 @@ export const chop: {
 /**
  * Splits an iterable into two arrays at the given index.
  *
+ * **When to use**
+ *
+ * Use to divide an array into a prefix and suffix at a specific position.
+ *
  * **Details**
  *
  * - `n` can be `0` (all elements in the second array).
@@ -5048,6 +5741,10 @@ export const splitAt: {
   /**
    * Splits an iterable into two arrays at the given index.
    *
+   * **When to use**
+   *
+   * Use to divide an array into a prefix and suffix at a specific position.
+   *
    * **Details**
    *
    * - `n` can be `0` (all elements in the second array).
@@ -5071,6 +5768,10 @@ export const splitAt: {
   /**
    * Splits an iterable into two arrays at the given index.
    *
+   * **When to use**
+   *
+   * Use to divide an array into a prefix and suffix at a specific position.
+   *
    * **Details**
    *
    * - `n` can be `0` (all elements in the second array).
@@ -5170,6 +5871,10 @@ export const splitAtNonEmpty: {
 /**
  * Splits an iterable into `n` roughly equal-sized chunks.
  *
+ * **When to use**
+ *
+ * Use to distribute elements across a fixed number of groups, such as when splitting work across threads.
+ *
  * **Details**
  *
  * - Uses `chunksOf(ceil(length / n))` internally.
@@ -5192,6 +5897,10 @@ export const split: {
   /**
    * Splits an iterable into `n` roughly equal-sized chunks.
    *
+   * **When to use**
+   *
+   * Use to distribute elements across a fixed number of groups, such as when splitting work across threads.
+   *
    * **Details**
    *
    * - Uses `chunksOf(ceil(length / n))` internally.
@@ -5214,6 +5923,10 @@ export const split: {
   /**
    * Splits an iterable into `n` roughly equal-sized chunks.
    *
+   * **When to use**
+   *
+   * Use to distribute elements across a fixed number of groups, such as when splitting work across threads.
+   *
    * **Details**
    *
    * - Uses `chunksOf(ceil(length / n))` internally.
@@ -5242,6 +5955,10 @@ export const split: {
  * Splits an iterable at the first element matching the predicate. The matching
  * element is included in the second array.
  *
+ * **When to use**
+ *
+ * Use to split an array at a condition boundary when you know which element marks the transition point.
+ *
  * **Example** (Splitting at a condition)
  *
  * ```ts
@@ -5261,6 +5978,10 @@ export const splitWhere: {
    * Splits an iterable at the first element matching the predicate. The matching
    * element is included in the second array.
    *
+   * **When to use**
+   *
+   * Use to split an array at a condition boundary when you know which element marks the transition point.
+   *
    * **Example** (Splitting at a condition)
    *
    * ```ts
@@ -5280,6 +6001,10 @@ export const splitWhere: {
    * Splits an iterable at the first element matching the predicate. The matching
    * element is included in the second array.
    *
+   * **When to use**
+   *
+   * Use to split an array at a condition boundary when you know which element marks the transition point.
+   *
    * **Example** (Splitting at a condition)
    *
    * ```ts
@@ -5304,6 +6029,11 @@ export const splitWhere: {
 /**
  * Creates a shallow copy of an array.
  *
+ * **When to use**
+ *
+ * Use to create a distinct array reference for an existing array, for example
+ * before mutating the returned array.
+ *
  * **Details**
  *
  * - Preserves `NonEmptyArray` in the return type.
@@ -5329,6 +6059,11 @@ export const copy: {
   /**
    * Creates a shallow copy of an array.
    *
+   * **When to use**
+   *
+   * Use to create a distinct array reference for an existing array, for example
+   * before mutating the returned array.
+   *
    * **Details**
    *
    * - Preserves `NonEmptyArray` in the return type.
@@ -5354,6 +6089,11 @@ export const copy: {
   /**
    * Creates a shallow copy of an array.
    *
+   * **When to use**
+   *
+   * Use to create a distinct array reference for an existing array, for example
+   * before mutating the returned array.
+   *
    * **Details**
    *
    * - Preserves `NonEmptyArray` in the return type.
@@ -5382,6 +6122,10 @@ export const copy: {
  * Pads or truncates an array to exactly `n` elements, filling with `fill`
  * if the array is shorter, or slicing if longer.
  *
+ * **When to use**
+ *
+ * Use to ensure an array has a specific length, padding with a fill value or truncating as needed.
+ *
  * **Details**
  *
  * - Returns an empty array when `n <= 0`.
@@ -5405,6 +6149,10 @@ export const pad: {
    * Pads or truncates an array to exactly `n` elements, filling with `fill`
    * if the array is shorter, or slicing if longer.
    *
+   * **When to use**
+   *
+   * Use to ensure an array has a specific length, padding with a fill value or truncating as needed.
+   *
    * **Details**
    *
    * - Returns an empty array when `n <= 0`.
@@ -5430,6 +6178,10 @@ export const pad: {
    * Pads or truncates an array to exactly `n` elements, filling with `fill`
    * if the array is shorter, or slicing if longer.
    *
+   * **When to use**
+   *
+   * Use to ensure an array has a specific length, padding with a fill value or truncating as needed.
+   *
    * **Details**
    *
    * - Returns an empty array when `n <= 0`.
@@ -5463,6 +6215,11 @@ export const pad: {
  * Splits an iterable into chunks of length `n`. The last chunk may be shorter
  * if `n` does not evenly divide the length.
  *
+ * **When to use**
+ *
+ * Use to divide an iterable into non-overlapping chunks with a maximum chunk
+ * size.
+ *
  * **Details**
  *
  * - `chunksOf(n)([])` is `[]`, not `[[]]`.
@@ -5488,6 +6245,11 @@ export const chunksOf: {
    * Splits an iterable into chunks of length `n`. The last chunk may be shorter
    * if `n` does not evenly divide the length.
    *
+   * **When to use**
+   *
+   * Use to divide an iterable into non-overlapping chunks with a maximum chunk
+   * size.
+   *
    * **Details**
    *
    * - `chunksOf(n)([])` is `[]`, not `[[]]`.
@@ -5515,6 +6277,11 @@ export const chunksOf: {
    * Splits an iterable into chunks of length `n`. The last chunk may be shorter
    * if `n` does not evenly divide the length.
    *
+   * **When to use**
+   *
+   * Use to divide an iterable into non-overlapping chunks with a maximum chunk
+   * size.
+   *
    * **Details**
    *
    * - `chunksOf(n)([])` is `[]`, not `[[]]`.
@@ -5540,6 +6307,11 @@ export const chunksOf: {
    * Splits an iterable into chunks of length `n`. The last chunk may be shorter
    * if `n` does not evenly divide the length.
    *
+   * **When to use**
+   *
+   * Use to divide an iterable into non-overlapping chunks with a maximum chunk
+   * size.
+   *
    * **Details**
    *
    * - `chunksOf(n)([])` is `[]`, not `[[]]`.
@@ -5572,6 +6344,10 @@ export const chunksOf: {
 /**
  * Creates overlapping sliding windows of size `n`.
  *
+ * **When to use**
+ *
+ * Use to process sequences with a moving window, such as for computing running averages or detecting patterns.
+ *
  * **Details**
  *
  * - Returns an empty array if `n <= 0` or the array has fewer than `n` elements.
@@ -5595,6 +6371,10 @@ export const window: {
   /**
    * Creates overlapping sliding windows of size `n`.
    *
+   * **When to use**
+   *
+   * Use to process sequences with a moving window, such as for computing running averages or detecting patterns.
+   *
    * **Details**
    *
    * - Returns an empty array if `n <= 0` or the array has fewer than `n` elements.
@@ -5618,6 +6398,10 @@ export const window: {
   /**
    * Creates overlapping sliding windows of size `n`.
    *
+   * **When to use**
+   *
+   * Use to process sequences with a moving window, such as for computing running averages or detecting patterns.
+   *
    * **Details**
    *
    * - Returns an empty array if `n <= 0` or the array has fewer than `n` elements.
@@ -5652,6 +6436,11 @@ export const window: {
 /**
  * Groups consecutive equal elements using a custom equivalence function.
  *
+ * **When to use**
+ *
+ * Use when a non-empty array is already arranged so matching elements are
+ * adjacent and you need a custom equivalence function.
+ *
  * **Details**
  *
  * - Only groups **adjacent** elements — non-adjacent duplicates stay separate.
@@ -5666,8 +6455,8 @@ export const window: {
  * // [["a", "a"], ["b", "b", "b"], ["c"], ["a"]]
  * ```
  *
- * @see {@link group} — uses default equality
- * @see {@link groupBy} — group by a key function into a record
+ * @see {@link group} for grouping adjacent elements with `Equal.equivalence()`
+ * @see {@link groupBy} for grouping all elements into a record by key, regardless of adjacency
  *
  * @category grouping
  * @since 2.0.0
@@ -5676,6 +6465,11 @@ export const groupWith: {
   /**
    * Groups consecutive equal elements using a custom equivalence function.
    *
+   * **When to use**
+   *
+   * Use when a non-empty array is already arranged so matching elements are
+   * adjacent and you need a custom equivalence function.
+   *
    * **Details**
    *
    * - Only groups **adjacent** elements — non-adjacent duplicates stay separate.
@@ -5690,8 +6484,8 @@ export const groupWith: {
    * // [["a", "a"], ["b", "b", "b"], ["c"], ["a"]]
    * ```
    *
-   * @see {@link group} — uses default equality
-   * @see {@link groupBy} — group by a key function into a record
+   * @see {@link group} for grouping adjacent elements with `Equal.equivalence()`
+   * @see {@link groupBy} for grouping all elements into a record by key, regardless of adjacency
    *
    * @category grouping
    * @since 2.0.0
@@ -5700,6 +6494,11 @@ export const groupWith: {
   /**
    * Groups consecutive equal elements using a custom equivalence function.
    *
+   * **When to use**
+   *
+   * Use when a non-empty array is already arranged so matching elements are
+   * adjacent and you need a custom equivalence function.
+   *
    * **Details**
    *
    * - Only groups **adjacent** elements — non-adjacent duplicates stay separate.
@@ -5714,8 +6513,8 @@ export const groupWith: {
    * // [["a", "a"], ["b", "b", "b"], ["c"], ["a"]]
    * ```
    *
-   * @see {@link group} — uses default equality
-   * @see {@link groupBy} — group by a key function into a record
+   * @see {@link group} for grouping adjacent elements with `Equal.equivalence()`
+   * @see {@link groupBy} for grouping all elements into a record by key, regardless of adjacency
    *
    * @category grouping
    * @since 2.0.0
@@ -5746,6 +6545,11 @@ export const groupWith: {
 /**
  * Groups consecutive equal elements using `Equal.equivalence()`.
  *
+ * **When to use**
+ *
+ * Use when equal values are already adjacent and Effect's default equality is
+ * the right comparison.
+ *
  * **Details**
  *
  * - Only groups **adjacent** elements.
@@ -5772,6 +6576,10 @@ export const group: <A>(self: NonEmptyReadonlyArray<A>) => NonEmptyArray<NonEmpt
  * Groups elements into a record by a key-returning function. Each key maps
  * to a `NonEmptyArray` of elements that produced that key.
  *
+ * **When to use**
+ *
+ * Use to build buckets of elements indexed by a computed string or symbol key.
+ *
  * **Details**
  *
  * - Unlike {@link group}/{@link groupWith}, elements do not need to be
@@ -5805,6 +6613,10 @@ export const groupBy: {
    * Groups elements into a record by a key-returning function. Each key maps
    * to a `NonEmptyArray` of elements that produced that key.
    *
+   * **When to use**
+   *
+   * Use to build buckets of elements indexed by a computed string or symbol key.
+   *
    * **Details**
    *
    * - Unlike {@link group}/{@link groupWith}, elements do not need to be
@@ -5838,6 +6650,10 @@ export const groupBy: {
    * Groups elements into a record by a key-returning function. Each key maps
    * to a `NonEmptyArray` of elements that produced that key.
    *
+   * **When to use**
+   *
+   * Use to build buckets of elements indexed by a computed string or symbol key.
+   *
    * **Details**
    *
    * - Unlike {@link group}/{@link groupWith}, elements do not need to be
@@ -5887,6 +6703,11 @@ export const groupBy: {
  * Computes the union of two arrays using a custom equivalence, removing
  * duplicates.
  *
+ * **When to use**
+ *
+ * Use when you need the union of two arrays but duplicate detection must use a
+ * custom equivalence instead of the default `Equal.equivalence()`.
+ *
  * **Example** (Union with custom equality)
  *
  * ```ts
@@ -5895,9 +6716,9 @@ export const groupBy: {
  * console.log(Array.unionWith([1, 2], [2, 3], (a, b) => a === b)) // [1, 2, 3]
  * ```
  *
- * @see {@link union} — uses default equality
- * @see {@link intersection} — elements in both arrays
- * @see {@link difference} — elements only in the first array
+ * @see {@link union} for the `Equal.equivalence()` variant
+ * @see {@link intersectionWith} for keeping elements present in both arrays
+ * @see {@link differenceWith} for keeping elements present only in the first array
  *
  * @category elements
  * @since 2.0.0
@@ -5907,6 +6728,11 @@ export const unionWith: {
    * Computes the union of two arrays using a custom equivalence, removing
    * duplicates.
    *
+   * **When to use**
+   *
+   * Use when you need the union of two arrays but duplicate detection must use a
+   * custom equivalence instead of the default `Equal.equivalence()`.
+   *
    * **Example** (Union with custom equality)
    *
    * ```ts
@@ -5915,9 +6741,9 @@ export const unionWith: {
    * console.log(Array.unionWith([1, 2], [2, 3], (a, b) => a === b)) // [1, 2, 3]
    * ```
    *
-   * @see {@link union} — uses default equality
-   * @see {@link intersection} — elements in both arrays
-   * @see {@link difference} — elements only in the first array
+   * @see {@link union} for the `Equal.equivalence()` variant
+   * @see {@link intersectionWith} for keeping elements present in both arrays
+   * @see {@link differenceWith} for keeping elements present only in the first array
    *
    * @category elements
    * @since 2.0.0
@@ -5930,6 +6756,11 @@ export const unionWith: {
    * Computes the union of two arrays using a custom equivalence, removing
    * duplicates.
    *
+   * **When to use**
+   *
+   * Use when you need the union of two arrays but duplicate detection must use a
+   * custom equivalence instead of the default `Equal.equivalence()`.
+   *
    * **Example** (Union with custom equality)
    *
    * ```ts
@@ -5938,9 +6769,9 @@ export const unionWith: {
    * console.log(Array.unionWith([1, 2], [2, 3], (a, b) => a === b)) // [1, 2, 3]
    * ```
    *
-   * @see {@link union} — uses default equality
-   * @see {@link intersection} — elements in both arrays
-   * @see {@link difference} — elements only in the first array
+   * @see {@link union} for the `Equal.equivalence()` variant
+   * @see {@link intersectionWith} for keeping elements present in both arrays
+   * @see {@link differenceWith} for keeping elements present only in the first array
    *
    * @category elements
    * @since 2.0.0
@@ -5954,6 +6785,11 @@ export const unionWith: {
    * Computes the union of two arrays using a custom equivalence, removing
    * duplicates.
    *
+   * **When to use**
+   *
+   * Use when you need the union of two arrays but duplicate detection must use a
+   * custom equivalence instead of the default `Equal.equivalence()`.
+   *
    * **Example** (Union with custom equality)
    *
    * ```ts
@@ -5962,9 +6798,9 @@ export const unionWith: {
    * console.log(Array.unionWith([1, 2], [2, 3], (a, b) => a === b)) // [1, 2, 3]
    * ```
    *
-   * @see {@link union} — uses default equality
-   * @see {@link intersection} — elements in both arrays
-   * @see {@link difference} — elements only in the first array
+   * @see {@link union} for the `Equal.equivalence()` variant
+   * @see {@link intersectionWith} for keeping elements present in both arrays
+   * @see {@link differenceWith} for keeping elements present only in the first array
    *
    * @category elements
    * @since 2.0.0
@@ -5978,6 +6814,11 @@ export const unionWith: {
    * Computes the union of two arrays using a custom equivalence, removing
    * duplicates.
    *
+   * **When to use**
+   *
+   * Use when you need the union of two arrays but duplicate detection must use a
+   * custom equivalence instead of the default `Equal.equivalence()`.
+   *
    * **Example** (Union with custom equality)
    *
    * ```ts
@@ -5986,9 +6827,9 @@ export const unionWith: {
    * console.log(Array.unionWith([1, 2], [2, 3], (a, b) => a === b)) // [1, 2, 3]
    * ```
    *
-   * @see {@link union} — uses default equality
-   * @see {@link intersection} — elements in both arrays
-   * @see {@link difference} — elements only in the first array
+   * @see {@link union} for the `Equal.equivalence()` variant
+   * @see {@link intersectionWith} for keeping elements present in both arrays
+   * @see {@link differenceWith} for keeping elements present only in the first array
    *
    * @category elements
    * @since 2.0.0
@@ -6141,6 +6982,11 @@ export const union: {
  * Computes the intersection of two arrays using a custom equivalence. Order is
  * determined by the first array.
  *
+ * **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.
+ *
  * **Example** (Intersection with custom equality)
  *
  * ```ts
@@ -6152,9 +6998,9 @@ export const union: {
  * console.log(Array.intersectionWith(isEquivalent)(array2)(array1)) // [{ id: 1 }, { id: 3 }]
  * ```
  *
- * @see {@link intersection} — uses default equality
- * @see {@link union} — elements in either array
- * @see {@link difference} — elements only in the first array
+ * @see {@link intersection} for the `Equal.equivalence()` variant
+ * @see {@link unionWith} for keeping values from either array with custom equality
+ * @see {@link differenceWith} for keeping values only from the first array with custom equality
  *
  * @category elements
  * @since 2.0.0
@@ -6239,6 +7085,11 @@ export const intersection: {
  * Computes elements in the first array that are not in the second, using a
  * custom equivalence.
  *
+ * **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.
+ *
  * **Example** (Difference with custom equality)
  *
  * ```ts
@@ -6248,9 +7099,9 @@ export const intersection: {
  * console.log(diff) // [1]
  * ```
  *
- * @see {@link difference} — uses default equality
- * @see {@link union} — elements in either array
- * @see {@link intersection} — elements in both arrays
+ * @see {@link difference} for the `Equal.equivalence()` variant
+ * @see {@link unionWith} for keeping values from either array with custom equality
+ * @see {@link intersectionWith} for keeping values present in both arrays with custom equality
  *
  * @category elements
  * @since 2.0.0
@@ -6273,6 +7124,11 @@ export const differenceWith = <A>(isEquivalent: (self: A, that: A) => boolean):
  * Computes elements in the first array that are not in the second, using
  * `Equal.equivalence()`.
  *
+ * **When to use**
+ *
+ * Use when you need to keep values from the first array that are absent from
+ * the second and the default `Equal.equivalence()` comparison is appropriate.
+ *
  * **Example** (Array difference)
  *
  * ```ts
@@ -6293,6 +7149,11 @@ export const difference: {
    * Computes elements in the first array that are not in the second, using
    * `Equal.equivalence()`.
    *
+   * **When to use**
+   *
+   * Use when you need to keep values from the first array that are absent from
+   * the second and the default `Equal.equivalence()` comparison is appropriate.
+   *
    * **Example** (Array difference)
    *
    * ```ts
@@ -6313,6 +7174,11 @@ export const difference: {
    * Computes elements in the first array that are not in the second, using
    * `Equal.equivalence()`.
    *
+   * **When to use**
+   *
+   * Use when you need to keep values from the first array that are absent from
+   * the second and the default `Equal.equivalence()` comparison is appropriate.
+   *
    * **Example** (Array difference)
    *
    * ```ts
@@ -6334,6 +7200,10 @@ export const difference: {
 /**
  * Creates an empty array.
  *
+ * **When to use**
+ *
+ * Use to create a typed empty array without allocating placeholder elements.
+ *
  * **Example** (Creating an empty array)
  *
  * ```ts
@@ -6492,6 +7362,10 @@ export declare namespace ReadonlyArray {
 /**
  * Transforms each element using a function, returning a new array.
  *
+ * **When to use**
+ *
+ * Use to transform each element independently while preserving the array shape.
+ *
  * **Details**
  *
  * - The function receives `(element, index)`.
@@ -6514,6 +7388,10 @@ export const map: {
   /**
    * Transforms each element using a function, returning a new array.
    *
+   * **When to use**
+   *
+   * Use to transform each element independently while preserving the array shape.
+   *
    * **Details**
    *
    * - The function receives `(element, index)`.
@@ -6536,6 +7414,10 @@ export const map: {
   /**
    * Transforms each element using a function, returning a new array.
    *
+   * **When to use**
+   *
+   * Use to transform each element independently while preserving the array shape.
+   *
    * **Details**
    *
    * - The function receives `(element, index)`.
@@ -6560,6 +7442,11 @@ export const map: {
 /**
  * Maps each element to an array and flattens the results into a single array.
  *
+ * **When to use**
+ *
+ * Use to map each element to zero or more values and concatenate the results in
+ * one pass.
+ *
  * **Details**
  *
  * - The function receives `(element, index)`.
@@ -6583,6 +7470,11 @@ export const flatMap: {
   /**
    * Maps each element to an array and flattens the results into a single array.
    *
+   * **When to use**
+   *
+   * Use to map each element to zero or more values and concatenate the results in
+   * one pass.
+   *
    * **Details**
    *
    * - The function receives `(element, index)`.
@@ -6606,6 +7498,11 @@ export const flatMap: {
   /**
    * Maps each element to an array and flattens the results into a single array.
    *
+   * **When to use**
+   *
+   * Use to map each element to zero or more values and concatenate the results in
+   * one pass.
+   *
    * **Details**
    *
    * - The function receives `(element, index)`.
@@ -6632,6 +7529,11 @@ export const flatMap: {
   /**
    * Maps each element to an array and flattens the results into a single array.
    *
+   * **When to use**
+   *
+   * Use to map each element to zero or more values and concatenate the results in
+   * one pass.
+   *
    * **Details**
    *
    * - The function receives `(element, index)`.
@@ -6672,6 +7574,11 @@ export const flatMap: {
 /**
  * Flattens a nested array of arrays into a single array.
  *
+ * **When to use**
+ *
+ * Use to collapse one level of nested arrays when no per-element mapping is
+ * needed.
+ *
  * **Example** (Flattening nested arrays)
  *
  * ```ts
@@ -6691,6 +7598,11 @@ export const flatten: <const S extends ReadonlyArray<ReadonlyArray<any>>>(self:
 /**
  * Extracts all `Some` values from an iterable of `Option`s, discarding `None`s.
  *
+ * **When to use**
+ *
+ * Use to collect only present values from `Option` values while discarding
+ * `None` values.
+ *
  * **Example** (Extracting Some values)
  *
  * ```ts
@@ -6722,6 +7634,11 @@ export const getSomes: <T extends Iterable<Option.Option<X>>, X = any>(
  * Extracts all failure values from an iterable of `Result`s, discarding
  * successes.
  *
+ * **When to use**
+ *
+ * Use to collect only failure values from `Result` values while discarding
+ * successes.
+ *
  * **Example** (Extracting failures)
  *
  * ```ts
@@ -6754,6 +7671,11 @@ export const getFailures = <T extends Iterable<Result.Result<any, any>>>(
  * Extracts all success values from an iterable of `Result`s, discarding
  * failures.
  *
+ * **When to use**
+ *
+ * Use to collect only success values from `Result` values while discarding
+ * failures.
+ *
  * **Example** (Extracting successes)
  *
  * ```ts
@@ -6785,6 +7707,11 @@ export const getSuccesses = <T extends Iterable<Result.Result<any, any>>>(
 /**
  * Keeps transformed values for elements where a `Filter` succeeds.
  *
+ * **When to use**
+ *
+ * Use to transform elements with a `Result`-returning filter while discarding
+ * failures.
+ *
  * **Details**
  *
  * - The filter receives `(element, index)`.
@@ -6800,6 +7727,7 @@ export const getSuccesses = <T extends Iterable<Result.Result<any, any>>>(
  * ```
  *
  * @see {@link filter} — keep original elements matching a predicate
+ * @see {@link partition} for keeping both failures and successes
  *
  * @category filtering
  * @since 2.0.0
@@ -6808,6 +7736,11 @@ export const filterMap: {
   /**
    * Keeps transformed values for elements where a `Filter` succeeds.
    *
+   * **When to use**
+   *
+   * Use to transform elements with a `Result`-returning filter while discarding
+   * failures.
+   *
    * **Details**
    *
    * - The filter receives `(element, index)`.
@@ -6823,6 +7756,7 @@ export const filterMap: {
    * ```
    *
    * @see {@link filter} — keep original elements matching a predicate
+   * @see {@link partition} for keeping both failures and successes
    *
    * @category filtering
    * @since 2.0.0
@@ -6831,6 +7765,11 @@ export const filterMap: {
   /**
    * Keeps transformed values for elements where a `Filter` succeeds.
    *
+   * **When to use**
+   *
+   * Use to transform elements with a `Result`-returning filter while discarding
+   * failures.
+   *
    * **Details**
    *
    * - The filter receives `(element, index)`.
@@ -6846,6 +7785,7 @@ export const filterMap: {
    * ```
    *
    * @see {@link filter} — keep original elements matching a predicate
+   * @see {@link partition} for keeping both failures and successes
    *
    * @category filtering
    * @since 2.0.0
@@ -6866,6 +7806,10 @@ export const filterMap: {
 /**
  * Keeps only elements satisfying a predicate (or refinement).
  *
+ * **When to use**
+ *
+ * Use to keep original elements that satisfy a boolean predicate or refinement.
+ *
  * **Details**
  *
  * - The predicate receives `(element, index)`.
@@ -6880,6 +7824,7 @@ export const filterMap: {
  * ```
  *
  * @see {@link partition} — split into matching and non-matching
+ * @see {@link filterMap} for transforming while filtering
  *
  * @category filtering
  * @since 2.0.0
@@ -6888,6 +7833,10 @@ export const filter: {
   /**
    * Keeps only elements satisfying a predicate (or refinement).
    *
+   * **When to use**
+   *
+   * Use to keep original elements that satisfy a boolean predicate or refinement.
+   *
    * **Details**
    *
    * - The predicate receives `(element, index)`.
@@ -6902,6 +7851,7 @@ export const filter: {
    * ```
    *
    * @see {@link partition} — split into matching and non-matching
+   * @see {@link filterMap} for transforming while filtering
    *
    * @category filtering
    * @since 2.0.0
@@ -6910,6 +7860,10 @@ export const filter: {
   /**
    * Keeps only elements satisfying a predicate (or refinement).
    *
+   * **When to use**
+   *
+   * Use to keep original elements that satisfy a boolean predicate or refinement.
+   *
    * **Details**
    *
    * - The predicate receives `(element, index)`.
@@ -6924,6 +7878,7 @@ export const filter: {
    * ```
    *
    * @see {@link partition} — split into matching and non-matching
+   * @see {@link filterMap} for transforming while filtering
    *
    * @category filtering
    * @since 2.0.0
@@ -6932,6 +7887,10 @@ export const filter: {
   /**
    * Keeps only elements satisfying a predicate (or refinement).
    *
+   * **When to use**
+   *
+   * Use to keep original elements that satisfy a boolean predicate or refinement.
+   *
    * **Details**
    *
    * - The predicate receives `(element, index)`.
@@ -6946,6 +7905,7 @@ export const filter: {
    * ```
    *
    * @see {@link partition} — split into matching and non-matching
+   * @see {@link filterMap} for transforming while filtering
    *
    * @category filtering
    * @since 2.0.0
@@ -6954,6 +7914,10 @@ export const filter: {
   /**
    * Keeps only elements satisfying a predicate (or refinement).
    *
+   * **When to use**
+   *
+   * Use to keep original elements that satisfy a boolean predicate or refinement.
+   *
    * **Details**
    *
    * - The predicate receives `(element, index)`.
@@ -6968,6 +7932,7 @@ export const filter: {
    * ```
    *
    * @see {@link partition} — split into matching and non-matching
+   * @see {@link filterMap} for transforming while filtering
    *
    * @category filtering
    * @since 2.0.0
@@ -6990,6 +7955,11 @@ export const filter: {
 /**
  * Splits an iterable using a `Filter` into failures and successes.
  *
+ * **When to use**
+ *
+ * Use to evaluate each element with a `Result`-returning filter and keep both
+ * failure and success values.
+ *
  * **Details**
  *
  * - Returns `[excluded, satisfying]`.
@@ -7007,6 +7977,7 @@ export const filter: {
  * ```
  *
  * @see {@link filter} — keep only matching elements
+ * @see {@link filterMap} for discarding failures
  * @see {@link separate} — split an iterable of `Result` values
  *
  * @category filtering
@@ -7016,6 +7987,11 @@ export const partition: {
   /**
    * Splits an iterable using a `Filter` into failures and successes.
    *
+   * **When to use**
+   *
+   * Use to evaluate each element with a `Result`-returning filter and keep both
+   * failure and success values.
+   *
    * **Details**
    *
    * - Returns `[excluded, satisfying]`.
@@ -7033,6 +8009,7 @@ export const partition: {
    * ```
    *
    * @see {@link filter} — keep only matching elements
+   * @see {@link filterMap} for discarding failures
    * @see {@link separate} — split an iterable of `Result` values
    *
    * @category filtering
@@ -7042,6 +8019,11 @@ export const partition: {
   /**
    * Splits an iterable using a `Filter` into failures and successes.
    *
+   * **When to use**
+   *
+   * Use to evaluate each element with a `Result`-returning filter and keep both
+   * failure and success values.
+   *
    * **Details**
    *
    * - Returns `[excluded, satisfying]`.
@@ -7059,6 +8041,7 @@ export const partition: {
    * ```
    *
    * @see {@link filter} — keep only matching elements
+   * @see {@link filterMap} for discarding failures
    * @see {@link separate} — split an iterable of `Result` values
    *
    * @category filtering
@@ -7089,6 +8072,10 @@ export const partition: {
 /**
  * Separates an iterable of `Result`s into failure values and success values.
  *
+ * **When to use**
+ *
+ * Use to split existing `Result` values into failure and success arrays.
+ *
  * **Details**
  *
  * - Returns `[failures, successes]`.
@@ -7108,6 +8095,7 @@ export const partition: {
  *
  * @see {@link getFailures} — extract only failures
  * @see {@link getSuccesses} — extract only successes
+ * @see {@link partition} for computing `Result` values while splitting
  *
  * @category filtering
  * @since 2.0.0
@@ -7122,6 +8110,10 @@ export const separate: <T extends Iterable<Result.Result<any, any>>>(
 /**
  * Folds an iterable from left to right into a single value.
  *
+ * **When to use**
+ *
+ * Use to combine all elements into one accumulated value from left to right.
+ *
  * **Details**
  *
  * - The function receives `(accumulator, element, index)`.
@@ -7144,6 +8136,10 @@ export const reduce: {
   /**
    * Folds an iterable from left to right into a single value.
    *
+   * **When to use**
+   *
+   * Use to combine all elements into one accumulated value from left to right.
+   *
    * **Details**
    *
    * - The function receives `(accumulator, element, index)`.
@@ -7166,6 +8162,10 @@ export const reduce: {
   /**
    * Folds an iterable from left to right into a single value.
    *
+   * **When to use**
+   *
+   * Use to combine all elements into one accumulated value from left to right.
+   *
    * **Details**
    *
    * - The function receives `(accumulator, element, index)`.
@@ -7194,6 +8194,11 @@ export const reduce: {
 /**
  * Folds an iterable from right to left into a single value.
  *
+ * **When to use**
+ *
+ * Use when folding order matters and values must be combined from right to
+ * left.
+ *
  * **Details**
  *
  * - The function receives `(accumulator, element, index)`.
@@ -7216,6 +8221,11 @@ export const reduceRight: {
   /**
    * Folds an iterable from right to left into a single value.
    *
+   * **When to use**
+   *
+   * Use when folding order matters and values must be combined from right to
+   * left.
+   *
    * **Details**
    *
    * - The function receives `(accumulator, element, index)`.
@@ -7238,6 +8248,11 @@ export const reduceRight: {
   /**
    * Folds an iterable from right to left into a single value.
    *
+   * **When to use**
+   *
+   * Use when folding order matters and values must be combined from right to
+   * left.
+   *
    * **Details**
    *
    * - The function receives `(accumulator, element, index)`.
@@ -7340,6 +8355,10 @@ export const liftOption = <A extends Array<unknown>, B>(
  * Converts a nullable value to an array: `null`/`undefined` becomes `[]`,
  * anything else becomes `[value]`.
  *
+ * **When to use**
+ *
+ * Use to treat a nullable single value as zero or one array element.
+ *
  * **Example** (Nullable to array)
  *
  * ```ts
@@ -7390,6 +8409,11 @@ export const liftNullishOr = <A extends Array<unknown>, B>(
  * Maps each element with a nullable-returning function, keeping only non-null /
  * non-undefined results.
  *
+ * **When to use**
+ *
+ * Use when mapping and filtering in one step, where the mapper can return
+ * `null` or `undefined` to skip elements.
+ *
  * **Example** (FlatMapping with nullable)
  *
  * ```ts
@@ -7399,6 +8423,9 @@ export const liftNullishOr = <A extends Array<unknown>, B>(
  * // [1, 3]
  * ```
  *
+ * @see {@link flatMap} for mapping each element to an array and flattening
+ * @see {@link fromNullishOr} for converting a single nullable value to an array
+ *
  * @category sequencing
  * @since 4.0.0
  */
@@ -7407,6 +8434,11 @@ export const flatMapNullishOr: {
    * Maps each element with a nullable-returning function, keeping only non-null /
    * non-undefined results.
    *
+   * **When to use**
+   *
+   * Use when mapping and filtering in one step, where the mapper can return
+   * `null` or `undefined` to skip elements.
+   *
    * **Example** (FlatMapping with nullable)
    *
    * ```ts
@@ -7416,6 +8448,9 @@ export const flatMapNullishOr: {
    * // [1, 3]
    * ```
    *
+   * @see {@link flatMap} for mapping each element to an array and flattening
+   * @see {@link fromNullishOr} for converting a single nullable value to an array
+   *
    * @category sequencing
    * @since 4.0.0
    */
@@ -7424,6 +8459,11 @@ export const flatMapNullishOr: {
    * Maps each element with a nullable-returning function, keeping only non-null /
    * non-undefined results.
    *
+   * **When to use**
+   *
+   * Use when mapping and filtering in one step, where the mapper can return
+   * `null` or `undefined` to skip elements.
+   *
    * **Example** (FlatMapping with nullable)
    *
    * ```ts
@@ -7433,6 +8473,9 @@ export const flatMapNullishOr: {
    * // [1, 3]
    * ```
    *
+   * @see {@link flatMap} for mapping each element to an array and flattening
+   * @see {@link fromNullishOr} for converting a single nullable value to an array
+   *
    * @category sequencing
    * @since 4.0.0
    */
@@ -7476,9 +8519,14 @@ export const liftResult = <A extends Array<unknown>, E, B>(
 }
 
 /**
- * Tests whether all elements satisfy the predicate. Supports refinements for
+ * Checks whether all elements satisfy the predicate. Supports refinements for
  * type narrowing.
  *
+ * **When to use**
+ *
+ * Use to check that all elements satisfy a predicate, including
+ * refinement-based type narrowing.
+ *
  * **Example** (Testing all elements)
  *
  * ```ts
@@ -7495,9 +8543,14 @@ export const liftResult = <A extends Array<unknown>, E, B>(
  */
 export const every: {
   /**
-   * Tests whether all elements satisfy the predicate. Supports refinements for
+   * Checks whether all elements satisfy the predicate. Supports refinements for
    * type narrowing.
    *
+   * **When to use**
+   *
+   * Use to check that all elements satisfy a predicate, including
+   * refinement-based type narrowing.
+   *
    * **Example** (Testing all elements)
    *
    * ```ts
@@ -7514,9 +8567,14 @@ export const every: {
    */
   <A, B extends A>(refinement: (a: NoInfer<A>, i: number) => a is B): (self: ReadonlyArray<A>) => self is ReadonlyArray<B>
   /**
-   * Tests whether all elements satisfy the predicate. Supports refinements for
+   * Checks whether all elements satisfy the predicate. Supports refinements for
    * type narrowing.
    *
+   * **When to use**
+   *
+   * Use to check that all elements satisfy a predicate, including
+   * refinement-based type narrowing.
+   *
    * **Example** (Testing all elements)
    *
    * ```ts
@@ -7533,9 +8591,14 @@ export const every: {
    */
   <A>(predicate: (a: NoInfer<A>, i: number) => boolean): (self: ReadonlyArray<A>) => boolean
   /**
-   * Tests whether all elements satisfy the predicate. Supports refinements for
+   * Checks whether all elements satisfy the predicate. Supports refinements for
    * type narrowing.
    *
+   * **When to use**
+   *
+   * Use to check that all elements satisfy a predicate, including
+   * refinement-based type narrowing.
+   *
    * **Example** (Testing all elements)
    *
    * ```ts
@@ -7552,9 +8615,14 @@ export const every: {
    */
   <A, B extends A>(self: ReadonlyArray<A>, refinement: (a: A, i: number) => a is B): self is ReadonlyArray<B>
   /**
-   * Tests whether all elements satisfy the predicate. Supports refinements for
+   * Checks whether all elements satisfy the predicate. Supports refinements for
    * type narrowing.
    *
+   * **When to use**
+   *
+   * Use to check that all elements satisfy a predicate, including
+   * refinement-based type narrowing.
+   *
    * **Example** (Testing all elements)
    *
    * ```ts
@@ -7577,7 +8645,7 @@ export const every: {
 )
 
 /**
- * Tests whether at least one element satisfies the predicate. Narrows the type
+ * Checks whether at least one element satisfies the predicate. Narrows the type
  * to `NonEmptyReadonlyArray` on success.
  *
  * **Example** (Testing for any match)
@@ -7597,7 +8665,7 @@ export const every: {
  */
 export const some: {
   /**
-   * Tests whether at least one element satisfies the predicate. Narrows the type
+   * Checks whether at least one element satisfies the predicate. Narrows the type
    * to `NonEmptyReadonlyArray` on success.
    *
    * **Example** (Testing for any match)
@@ -7617,7 +8685,7 @@ export const some: {
    */
   <A>(predicate: (a: NoInfer<A>, i: number) => boolean): (self: ReadonlyArray<A>) => self is NonEmptyReadonlyArray<A>
   /**
-   * Tests whether at least one element satisfies the predicate. Narrows the type
+   * Checks whether at least one element satisfies the predicate. Narrows the type
    * to `NonEmptyReadonlyArray` on success.
    *
    * **Example** (Testing for any match)
@@ -7646,6 +8714,11 @@ export const some: {
  * Applies a function to each suffix of the array (starting from each index),
  * collecting the results.
  *
+ * **When to use**
+ *
+ * Use when a computation depends on every suffix of an array, such as
+ * cumulative aggregations from each position.
+ *
  * **Details**
  *
  * - For index `i`, the function receives `self.slice(i)`.
@@ -7658,6 +8731,8 @@ export const some: {
  * console.log(Array.extend([1, 2, 3], (as) => as.length)) // [3, 2, 1]
  * ```
  *
+ * @see {@link scan} for keeping intermediate accumulator values during a fold
+ *
  * @category mapping
  * @since 2.0.0
  */
@@ -7666,6 +8741,11 @@ export const extend: {
    * Applies a function to each suffix of the array (starting from each index),
    * collecting the results.
    *
+   * **When to use**
+   *
+   * Use when a computation depends on every suffix of an array, such as
+   * cumulative aggregations from each position.
+   *
    * **Details**
    *
    * - For index `i`, the function receives `self.slice(i)`.
@@ -7678,6 +8758,8 @@ export const extend: {
    * console.log(Array.extend([1, 2, 3], (as) => as.length)) // [3, 2, 1]
    * ```
    *
+   * @see {@link scan} for keeping intermediate accumulator values during a fold
+   *
    * @category mapping
    * @since 2.0.0
    */
@@ -7686,6 +8768,11 @@ export const extend: {
    * Applies a function to each suffix of the array (starting from each index),
    * collecting the results.
    *
+   * **When to use**
+   *
+   * Use when a computation depends on every suffix of an array, such as
+   * cumulative aggregations from each position.
+   *
    * **Details**
    *
    * - For index `i`, the function receives `self.slice(i)`.
@@ -7698,6 +8785,8 @@ export const extend: {
    * console.log(Array.extend([1, 2, 3], (as) => as.length)) // [3, 2, 1]
    * ```
    *
+   * @see {@link scan} for keeping intermediate accumulator values during a fold
+   *
    * @category mapping
    * @since 2.0.0
    */
@@ -7907,6 +8996,11 @@ export const makeEquivalence: <A>(
 /**
  * Runs a side-effect for each element. The callback receives `(element, index)`.
  *
+ * **When to use**
+ *
+ * Use to iterate over an array for side-effects only, when no transformed
+ * result is needed.
+ *
  * **Example** (Iterating with side-effects)
  *
  * ```ts
@@ -7915,6 +9009,8 @@ export const makeEquivalence: <A>(
  * Array.forEach([1, 2, 3], (n) => console.log(n)) // 1, 2, 3
  * ```
  *
+ * @see {@link map} for transforming each element into a new array
+ *
  * @category elements
  * @since 2.0.0
  */
@@ -7922,6 +9018,11 @@ export const forEach: {
   /**
    * Runs a side-effect for each element. The callback receives `(element, index)`.
    *
+   * **When to use**
+   *
+   * Use to iterate over an array for side-effects only, when no transformed
+   * result is needed.
+   *
    * **Example** (Iterating with side-effects)
    *
    * ```ts
@@ -7930,6 +9031,8 @@ export const forEach: {
    * Array.forEach([1, 2, 3], (n) => console.log(n)) // 1, 2, 3
    * ```
    *
+   * @see {@link map} for transforming each element into a new array
+   *
    * @category elements
    * @since 2.0.0
    */
@@ -7937,6 +9040,11 @@ export const forEach: {
   /**
    * Runs a side-effect for each element. The callback receives `(element, index)`.
    *
+   * **When to use**
+   *
+   * Use to iterate over an array for side-effects only, when no transformed
+   * result is needed.
+   *
    * **Example** (Iterating with side-effects)
    *
    * ```ts
@@ -7945,6 +9053,8 @@ export const forEach: {
    * Array.forEach([1, 2, 3], (n) => console.log(n)) // 1, 2, 3
    * ```
    *
+   * @see {@link map} for transforming each element into a new array
+   *
    * @category elements
    * @since 2.0.0
    */
@@ -7955,6 +9065,11 @@ export const forEach: {
  * Removes duplicates using a custom equivalence, preserving the order of the
  * first occurrence.
  *
+ * **When to use**
+ *
+ * Use to remove all duplicate elements with a custom equivalence when default
+ * equality is not appropriate.
+ *
  * **Example** (Deduplicating with custom equality)
  *
  * ```ts
@@ -7974,6 +9089,11 @@ export const dedupeWith: {
    * Removes duplicates using a custom equivalence, preserving the order of the
    * first occurrence.
    *
+   * **When to use**
+   *
+   * Use to remove all duplicate elements with a custom equivalence when default
+   * equality is not appropriate.
+   *
    * **Example** (Deduplicating with custom equality)
    *
    * ```ts
@@ -7995,6 +9115,11 @@ export const dedupeWith: {
    * Removes duplicates using a custom equivalence, preserving the order of the
    * first occurrence.
    *
+   * **When to use**
+   *
+   * Use to remove all duplicate elements with a custom equivalence when default
+   * equality is not appropriate.
+   *
    * **Example** (Deduplicating with custom equality)
    *
    * ```ts
@@ -8017,6 +9142,11 @@ export const dedupeWith: {
    * Removes duplicates using a custom equivalence, preserving the order of the
    * first occurrence.
    *
+   * **When to use**
+   *
+   * Use to remove all duplicate elements with a custom equivalence when default
+   * equality is not appropriate.
+   *
    * **Example** (Deduplicating with custom equality)
    *
    * ```ts
@@ -8054,6 +9184,11 @@ export const dedupeWith: {
  * Removes duplicates using `Equal.equivalence()`, preserving the order of the
  * first occurrence.
  *
+ * **When to use**
+ *
+ * Use to remove repeated values from an iterable when Effect's default equality
+ * is the right comparison, preserving the first occurrence.
+ *
  * **Example** (Removing duplicates)
  *
  * ```ts
@@ -8076,6 +9211,12 @@ export const dedupe = <S extends Iterable<any>>(
 /**
  * Removes consecutive duplicate elements using a custom equivalence.
  *
+ * **When to use**
+ *
+ * Use when consecutive duplicates should be collapsed using a custom
+ * equivalence, while equivalent values that appear later should remain in the
+ * result.
+ *
  * **Details**
  *
  * - Non-adjacent duplicates are preserved.
@@ -8099,6 +9240,12 @@ export const dedupeAdjacentWith: {
   /**
    * Removes consecutive duplicate elements using a custom equivalence.
    *
+   * **When to use**
+   *
+   * Use when consecutive duplicates should be collapsed using a custom
+   * equivalence, while equivalent values that appear later should remain in the
+   * result.
+   *
    * **Details**
    *
    * - Non-adjacent duplicates are preserved.
@@ -8122,6 +9269,12 @@ export const dedupeAdjacentWith: {
   /**
    * Removes consecutive duplicate elements using a custom equivalence.
    *
+   * **When to use**
+   *
+   * Use when consecutive duplicates should be collapsed using a custom
+   * equivalence, while equivalent values that appear later should remain in the
+   * result.
+   *
    * **Details**
    *
    * - Non-adjacent duplicates are preserved.
@@ -8157,6 +9310,11 @@ export const dedupeAdjacentWith: {
 /**
  * Removes consecutive duplicate elements using `Equal.equivalence()`.
  *
+ * **When to use**
+ *
+ * Use when you need to collapse consecutive duplicates while preserving later
+ * non-consecutive repeats, and the default equality is sufficient.
+ *
  * **Example** (Removing adjacent duplicates)
  *
  * ```ts
@@ -8229,6 +9387,11 @@ export const join: {
 /**
  * Maps over an array while threading an accumulator through each step, returning both the final state and the mapped array.
  *
+ * **When to use**
+ *
+ * Use when mapping needs state threaded through each element and the final state
+ * is also needed.
+ *
  * **Details**
  *
  * - Combines `map` and `reduce` in a single pass.
@@ -8255,6 +9418,11 @@ export const mapAccum: {
   /**
    * Maps over an array while threading an accumulator through each step, returning both the final state and the mapped array.
    *
+   * **When to use**
+   *
+   * Use when mapping needs state threaded through each element and the final state
+   * is also needed.
+   *
    * **Details**
    *
    * - Combines `map` and `reduce` in a single pass.
@@ -8281,6 +9449,11 @@ export const mapAccum: {
   /**
    * Maps over an array while threading an accumulator through each step, returning both the final state and the mapped array.
    *
+   * **When to use**
+   *
+   * Use when mapping needs state threaded through each element and the final state
+   * is also needed.
+   *
    * **Details**
    *
    * - Combines `map` and `reduce` in a single pass.
@@ -8327,6 +9500,11 @@ export const mapAccum: {
 /**
  * Computes the cartesian product of two arrays, applying a combiner to each pair.
  *
+ * **When to use**
+ *
+ * Use to compute every combination from two arrays and immediately transform
+ * each pair into a custom result.
+ *
  * **Details**
  *
  * - Produces every combination of an element from `self` with an element from `that`.
@@ -8342,7 +9520,7 @@ export const mapAccum: {
  * console.log(result) // ["1-a", "1-b", "2-a", "2-b"]
  * ```
  *
- * @see {@link cartesian} — returns tuples instead of applying a combiner
+ * @see {@link cartesian} for returning tuples instead of applying a combiner
  *
  * @category elements
  * @since 2.0.0
@@ -8351,6 +9529,11 @@ export const cartesianWith: {
   /**
    * Computes the cartesian product of two arrays, applying a combiner to each pair.
    *
+   * **When to use**
+   *
+   * Use to compute every combination from two arrays and immediately transform
+   * each pair into a custom result.
+   *
    * **Details**
    *
    * - Produces every combination of an element from `self` with an element from `that`.
@@ -8366,7 +9549,7 @@ export const cartesianWith: {
    * console.log(result) // ["1-a", "1-b", "2-a", "2-b"]
    * ```
    *
-   * @see {@link cartesian} — returns tuples instead of applying a combiner
+   * @see {@link cartesian} for returning tuples instead of applying a combiner
    *
    * @category elements
    * @since 2.0.0
@@ -8375,6 +9558,11 @@ export const cartesianWith: {
   /**
    * Computes the cartesian product of two arrays, applying a combiner to each pair.
    *
+   * **When to use**
+   *
+   * Use to compute every combination from two arrays and immediately transform
+   * each pair into a custom result.
+   *
    * **Details**
    *
    * - Produces every combination of an element from `self` with an element from `that`.
@@ -8390,7 +9578,7 @@ export const cartesianWith: {
    * console.log(result) // ["1-a", "1-b", "2-a", "2-b"]
    * ```
    *
-   * @see {@link cartesian} — returns tuples instead of applying a combiner
+   * @see {@link cartesian} for returning tuples instead of applying a combiner
    *
    * @category elements
    * @since 2.0.0
@@ -8405,6 +9593,10 @@ export const cartesianWith: {
 /**
  * Computes the cartesian product of two arrays, returning all pairs as tuples.
  *
+ * **When to use**
+ *
+ * Use when you need every `[a, b]` pair from two arrays as tuples.
+ *
  * **Details**
  *
  * - Produces every `[a, b]` combination of an element from `self` with an element from `that`.
@@ -8428,6 +9620,10 @@ export const cartesian: {
   /**
    * Computes the cartesian product of two arrays, returning all pairs as tuples.
    *
+   * **When to use**
+   *
+   * Use when you need every `[a, b]` pair from two arrays as tuples.
+   *
    * **Details**
    *
    * - Produces every `[a, b]` combination of an element from `self` with an element from `that`.
@@ -8451,6 +9647,10 @@ export const cartesian: {
   /**
    * Computes the cartesian product of two arrays, returning all pairs as tuples.
    *
+   * **When to use**
+   *
+   * Use when you need every `[a, b]` pair from two arrays as tuples.
+   *
    * **Details**
    *
    * - Produces every `[a, b]` combination of an element from `self` with an element from `that`.
@@ -8481,11 +9681,11 @@ export const cartesian: {
 // -------------------------------------------------------------------------------------
 
 /**
- * Starting point for the "do simulation" — an array comprehension pattern.
+ * Provides the starting point for the "do simulation" — an array comprehension pattern.
  *
  * **When to use**
  *
- * - Begin a pipeline with `Do`, then use {@link bind} to introduce array variables and {@link let_ let} for plain values.
+ * 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.
  *
@@ -8514,7 +9714,12 @@ export const cartesian: {
 export const Do: ReadonlyArray<{}> = of({})
 
 /**
- * Introduces a new array variable into a do-notation scope, producing the cartesian product with all previous bindings.
+ * Adds a new array variable to a do-notation scope, producing the cartesian product with all previous bindings.
+ *
+ * **When to use**
+ *
+ * Use to add another array-producing binding to an `Array.Do` pipeline, pairing
+ * each existing scope with every value returned by the callback.
  *
  * **Details**
  *
@@ -8545,7 +9750,12 @@ export const Do: ReadonlyArray<{}> = of({})
  */
 export const bind: {
   /**
-   * Introduces a new array variable into a do-notation scope, producing the cartesian product with all previous bindings.
+   * Adds a new array variable to a do-notation scope, producing the cartesian product with all previous bindings.
+   *
+   * **When to use**
+   *
+   * Use to add another array-producing binding to an `Array.Do` pipeline, pairing
+   * each existing scope with every value returned by the callback.
    *
    * **Details**
    *
@@ -8578,7 +9788,12 @@ export const bind: {
     self: ReadonlyArray<A>
   ) => Array<{ [K in N | keyof A]: K extends keyof A ? A[K] : B }>
   /**
-   * Introduces a new array variable into a do-notation scope, producing the cartesian product with all previous bindings.
+   * Adds a new array variable to a do-notation scope, producing the cartesian product with all previous bindings.
+   *
+   * **When to use**
+   *
+   * Use to add another array-producing binding to an `Array.Do` pipeline, pairing
+   * each existing scope with every value returned by the callback.
    *
    * **Details**
    *
@@ -8615,7 +9830,12 @@ export const bind: {
 } = internalDoNotation.bind<ReadonlyArrayTypeLambda>(map, flatMap) as any
 
 /**
- * Names the elements of an array by wrapping each in an object with the given key, starting a do-notation scope.
+ * Wraps each array element in an object with the given key, starting a do-notation scope.
+ *
+ * **When to use**
+ *
+ * Use when you already have an array and want to start a do-notation pipeline
+ * by naming each element.
  *
  * **Details**
  *
@@ -8642,7 +9862,12 @@ export const bind: {
  */
 export const bindTo: {
   /**
-   * Names the elements of an array by wrapping each in an object with the given key, starting a do-notation scope.
+   * Wraps each array element in an object with the given key, starting a do-notation scope.
+   *
+   * **When to use**
+   *
+   * Use when you already have an array and want to start a do-notation pipeline
+   * by naming each element.
    *
    * **Details**
    *
@@ -8669,7 +9894,12 @@ export const bindTo: {
    */
   <N extends string>(tag: N): <A>(self: ReadonlyArray<A>) => Array<{ [K in N]: A }>
   /**
-   * Names the elements of an array by wrapping each in an object with the given key, starting a do-notation scope.
+   * Wraps each array element in an object with the given key, starting a do-notation scope.
+   *
+   * **When to use**
+   *
+   * Use when you already have an array and want to start a do-notation pipeline
+   * by naming each element.
    *
    * **Details**
    *
@@ -8768,7 +9998,12 @@ export function makeReducerConcat<A>(): Reducer.Reducer<Array<A>> {
 }
 
 /**
- * Counts the elements in an iterable that satisfy a predicate.
+ * Computes the number of elements in an iterable that satisfy a predicate.
+ *
+ * **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.
  *
  * **Details**
  *
@@ -8791,7 +10026,12 @@ export function makeReducerConcat<A>(): Reducer.Reducer<Array<A>> {
  */
 export const countBy: {
   /**
-   * Counts the elements in an iterable that satisfy a predicate.
+   * Computes the number of elements in an iterable that satisfy a predicate.
+   *
+   * **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.
    *
    * **Details**
    *
@@ -8814,7 +10054,12 @@ export const countBy: {
    */
   <A>(predicate: (a: NoInfer<A>, i: number) => boolean): (self: Iterable<A>) => number
   /**
-   * Counts the elements in an iterable that satisfy a predicate.
+   * Computes the number of elements in an iterable that satisfy a predicate.
+   *
+   * **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.
    *
    * **Details**
    *