effect 4.0.0-beta.70 → 4.0.0-beta.71

package/src/Array.ts

@@ -1,79 +1,82 @@
 /**
- * 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 sort}, {@link reverse}, {@link rotate}, and update operations
+ *   allocate new arrays; they do not mutate the input.
+ * - {@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
@@ -105,7 +108,7 @@ import type { NoInfer, TupleOf } from "./Types.ts"
  *
  * **When to use**
  *
- * Use this when you need the native `Array` constructor while the `Array`
+ * Use when you need the native `Array` constructor while the `Array`
  * namespace is in scope (e.g. `Array.Array.isArray`, `Array.Array.from`).
  *
  * **Example** (Using the Array constructor)
@@ -137,7 +140,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 +163,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 +196,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 +224,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 +249,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 +274,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 +299,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 +334,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 +360,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 +384,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 +408,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 +432,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 +464,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 +495,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 +514,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 +525,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 +550,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 +579,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 +613,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 +655,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 +688,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 +726,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 +773,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 +806,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 +844,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,6 +893,10 @@ 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.
@@ -864,6 +921,10 @@ 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.
@@ -888,6 +949,10 @@ 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.
@@ -914,6 +979,10 @@ 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`.
@@ -938,6 +1007,10 @@ 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`.
@@ -962,6 +1035,10 @@ 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`.
@@ -986,6 +1063,10 @@ 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`.
@@ -1010,6 +1091,10 @@ 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`.
@@ -1039,6 +1124,11 @@ 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.
@@ -1063,6 +1153,11 @@ 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.
@@ -1087,6 +1182,11 @@ 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.
@@ -1113,6 +1213,11 @@ 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`.
@@ -1137,6 +1242,11 @@ 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`.
@@ -1161,6 +1271,11 @@ 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`.
@@ -1185,6 +1300,11 @@ 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`.
@@ -1209,6 +1329,11 @@ 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`.
@@ -1238,6 +1363,10 @@ export const appendAll: {
 /**
  * Left-to-right fold that keeps every intermediate accumulator value.
  *
+ * **When to use**
+ *
+ * Use to compute a running accumulator where each intermediate value is needed.
+ *
  * **Details**
  *
  * - The output length is `input.length + 1` (starts with the initial value).
@@ -1263,6 +1392,10 @@ export const scan: {
   /**
    * Left-to-right fold that keeps every intermediate accumulator value.
    *
+   * **When to use**
+   *
+   * Use to compute a running accumulator where each intermediate value is needed.
+   *
    * **Details**
    *
    * - The output length is `input.length + 1` (starts with the initial value).
@@ -1288,6 +1421,10 @@ export const scan: {
   /**
    * Left-to-right fold that keeps every intermediate accumulator value.
    *
+   * **When to use**
+   *
+   * Use to compute a running accumulator where each intermediate value is needed.
+   *
    * **Details**
    *
    * - The output length is `input.length + 1` (starts with the initial value).
@@ -1323,6 +1460,11 @@ export const scan: {
 /**
  * Right-to-left fold that keeps every intermediate accumulator value.
  *
+ * **When to use**
+ *
+ * Use to compute a running accumulator from right to left where each intermediate
+ * value is needed.
+ *
  * **Details**
  *
  * - The output length is `input.length + 1` (ends with the initial value).
@@ -1347,6 +1489,11 @@ export const scanRight: {
   /**
    * Right-to-left fold that keeps every intermediate accumulator value.
    *
+   * **When to use**
+   *
+   * Use to compute a running accumulator from right to left where each intermediate
+   * value is needed.
+   *
    * **Details**
    *
    * - The output length is `input.length + 1` (ends with the initial value).
@@ -1371,6 +1518,11 @@ export const scanRight: {
   /**
    * Right-to-left fold that keeps every intermediate accumulator value.
    *
+   * **When to use**
+   *
+   * Use to compute a running accumulator from right to left where each intermediate
+   * value is needed.
+   *
    * **Details**
    *
    * - The output length is `input.length + 1` (ends with the initial value).
@@ -1405,6 +1557,10 @@ export const scanRight: {
 /**
  * Tests 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**
  *
  * - Acts as a type guard narrowing the input to `Array<unknown>`.
@@ -1429,6 +1585,10 @@ export const isArray: {
   /**
    * Tests 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**
    *
    * - Acts as a type guard narrowing the input to `Array<unknown>`.
@@ -1453,6 +1613,10 @@ export const isArray: {
   /**
    * Tests 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**
    *
    * - Acts as a type guard narrowing the input to `Array<unknown>`.
@@ -1562,6 +1726,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
@@ -1586,6 +1754,11 @@ const clamp = <A>(i: number, as: ReadonlyArray<A>): number => Math.floor(Math.mi
  * Safely reads an element at the given index, 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,9 +1773,9 @@ 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
@@ -1612,6 +1785,11 @@ export const get: {
    * Safely reads an element at the given index, 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,9 +1804,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
@@ -1638,6 +1816,11 @@ export const get: {
    * Safely reads an element at the given index, 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 +1835,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 +1851,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 +1879,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 +1907,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 +1943,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 +1962,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 +1977,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 +1996,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
@@ -1803,6 +2011,10 @@ export const unappend = <A>(
  * Returns the first element of an array 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 +2036,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
@@ -1843,6 +2060,10 @@ export const headNonEmpty: <A>(self: NonEmptyReadonlyArray<A>) => A = getUnsafe(
  * Returns the last element of an array 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 +2086,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
@@ -1883,6 +2109,10 @@ export const lastNonEmpty = <A>(self: NonEmptyReadonlyArray<A>): A => self[self.
 /**
  * Returns all elements except the first, wrapped in an `Option`.
  *
+ * **When to use**
+ *
+ * Use to safely get all elements after the first when the iterable may be empty.
+ *
  * **Details**
  *
  * - Allocates a new array via `slice(1)`.
@@ -1911,6 +2141,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
@@ -1930,6 +2164,10 @@ export const tailNonEmpty = <A>(self: NonEmptyReadonlyArray<A>): Array<A> => sel
 /**
  * Returns all elements except the last, wrapped in an `Option`.
  *
+ * **When to use**
+ *
+ * Use to safely get all elements before the last when the iterable may be empty.
+ *
  * **Details**
  *
  * - Allocates a new array via `slice(0, -1)`.
@@ -1958,6 +2196,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 +2219,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 +2236,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 +2247,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 +2264,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 +2275,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 +2292,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 +2308,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 +2335,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 +2362,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 +2396,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 +2414,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 +2426,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 +2444,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 +2456,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 +2474,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 +2486,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 +2504,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 +2516,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 +2534,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 +2558,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 +2578,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 +2598,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 +2647,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 +2666,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 +2678,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 +2697,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 +2709,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 +2728,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 +2740,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 +2759,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 +2771,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 +2790,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 +2809,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 +2827,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 +2838,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 +2856,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 +2867,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 +2885,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 +2901,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 +2927,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 +2953,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 +2984,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 +3010,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 +3036,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 +3074,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 +3094,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 +3114,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 +3150,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 +3174,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 +3198,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 +3233,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 +3256,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 +3279,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 +3312,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 +3343,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 +3374,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 +3405,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 +3436,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 +3467,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 +3498,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 +3531,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 +3560,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 +3589,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 +3618,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 +3647,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 +3676,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 +3705,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 +3758,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 +3786,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 +3814,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 +3842,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 +3870,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 +3898,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 +3926,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.
@@ -3457,6 +3978,10 @@ export const findLast: {
  * Inserts an element at the specified index, 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).
@@ -3481,6 +4006,10 @@ export const insertAt: {
    * Inserts an element at the specified index, 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).
@@ -3505,6 +4034,10 @@ export const insertAt: {
    * Inserts an element at the specified index, 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).
@@ -3538,6 +4071,10 @@ export const insertAt: {
  * Replaces the element at the specified index 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.
@@ -3562,6 +4099,10 @@ export const replace: {
    * Replaces the element at the specified index 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.
@@ -3588,6 +4129,10 @@ export const replace: {
    * Replaces the element at the specified index 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.
@@ -3617,6 +4162,11 @@ export const replace: {
  * Applies a function to the element at the specified index, 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.
@@ -3643,6 +4193,11 @@ export const modify: {
    * Applies a function to the element at the specified index, 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.
@@ -3669,6 +4224,11 @@ export const modify: {
    * Applies a function to the element at the specified index, 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.
@@ -3706,9 +4266,13 @@ 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.
  *
+ * **When to use**
+ *
+ * Use to remove a single element at a known index.
+ *
  * **Details**
  *
- * - Does not mutate the input.
+ * Does not mutate the input.
  *
  * **Example** (Removing an element)
  *
@@ -3730,9 +4294,13 @@ 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.
    *
+   * **When to use**
+   *
+   * Use to remove a single element at a known index.
+   *
    * **Details**
    *
-   * - Does not mutate the input.
+   * Does not mutate the input.
    *
    * **Example** (Removing an element)
    *
@@ -3754,9 +4322,13 @@ 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.
    *
+   * **When to use**
+   *
+   * Use to remove a single element at a known index.
+   *
    * **Details**
    *
-   * - Does not mutate the input.
+   * Does not mutate the input.
    *
    * **Example** (Removing an element)
    *
@@ -3786,6 +4358,10 @@ 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.
@@ -3810,6 +4386,10 @@ 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.
@@ -3835,6 +4415,10 @@ 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.
@@ -3860,6 +4444,10 @@ 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.
@@ -3885,6 +4473,10 @@ 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.
@@ -3917,6 +4509,11 @@ 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.
@@ -3931,8 +4528,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,6 +4539,11 @@ 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.
@@ -3956,8 +4558,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,6 +4569,11 @@ 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.
@@ -3981,8 +4588,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,6 +4599,11 @@ 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.
@@ -4006,8 +4618,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 +4635,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 +4692,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 +4719,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 +4746,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 +4773,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 +4800,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 +4973,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 +4999,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 +5025,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 +5051,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 +5094,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 +5117,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 +5140,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
@@ -4687,6 +5352,11 @@ export const setLastNonEmpty: {
  * Rotates an array by `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,6 +5371,9 @@ 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
  */
@@ -4709,6 +5382,11 @@ export const rotate: {
    * Rotates an array by `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,6 +5401,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
    */
@@ -4731,6 +5412,11 @@ export const rotate: {
    * Rotates an array by `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,6 +5431,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
    */
@@ -4753,6 +5442,11 @@ export const rotate: {
    * Rotates an array by `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 +5461,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 +5489,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 +5503,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
@@ -4823,6 +5525,11 @@ export const containsWith = <A>(isEquivalent: (self: A, that: A) => boolean): {
  * Tests 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
@@ -4841,6 +5548,11 @@ export const contains: {
    * Tests 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
@@ -4859,6 +5571,11 @@ export const contains: {
    * Tests 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
@@ -4879,6 +5596,11 @@ export const contains: {
  * Repeatedly applies a function that consumes a prefix of the array and
  * produces a value plus the remaining elements, collecting the values.
  *
+ * **When to use**
+ *
+ * Use when the grouping logic is custom and each step needs to return both a
+ * value and the remaining input.
+ *
  * **Details**
  *
  * - The function receives a `NonEmptyReadonlyArray` and returns
@@ -4909,6 +5631,11 @@ 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.
    *
+   * **When to use**
+   *
+   * Use when the grouping logic is custom and each step needs to return both a
+   * value and the remaining input.
+   *
    * **Details**
    *
    * - The function receives a `NonEmptyReadonlyArray` and returns
@@ -4941,6 +5668,11 @@ 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.
    *
+   * **When to use**
+   *
+   * Use when the grouping logic is custom and each step needs to return both a
+   * value and the remaining input.
+   *
    * **Details**
    *
    * - The function receives a `NonEmptyReadonlyArray` and returns
@@ -4974,6 +5706,11 @@ 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.
    *
+   * **When to use**
+   *
+   * Use when the grouping logic is custom and each step needs to return both a
+   * value and the remaining input.
+   *
    * **Details**
    *
    * - The function receives a `NonEmptyReadonlyArray` and returns
@@ -5025,6 +5762,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 +5789,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 +5816,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 +5919,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 +5945,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 +5971,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 +6003,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 +6026,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 +6049,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 +6077,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 +6107,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 +6137,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 +6170,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 +6197,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 +6226,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 +6263,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 +6293,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 +6325,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 +6355,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 +6392,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 +6419,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 +6446,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 +6484,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 +6503,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 +6513,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 +6532,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 +6542,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 +6561,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 +6593,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 +6624,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 +6661,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 +6698,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 +6751,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 +6764,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 +6776,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 +6789,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 +6804,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 +6817,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 +6833,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 +6846,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 +6862,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 +6875,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 +7030,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 +7046,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 +7133,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 +7147,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 +7172,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 +7197,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 +7222,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 +7248,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 +7410,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 +7436,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 +7462,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 +7490,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 +7518,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 +7546,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 +7577,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 +7622,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 +7646,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 +7682,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 +7719,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 +7755,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 +7775,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 +7784,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 +7804,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 +7813,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 +7833,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 +7854,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 +7872,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 +7881,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 +7899,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 +7908,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 +7926,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 +7935,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 +7953,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 +7962,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 +7980,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 +8003,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 +8025,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 +8035,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 +8057,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 +8067,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 +8089,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 +8120,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 +8143,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 +8158,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 +8184,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 +8210,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 +8242,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 +8269,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 +8296,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 +8403,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 +8457,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 +8471,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 +8482,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 +8496,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 +8507,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 +8521,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
    */
@@ -7479,6 +8570,11 @@ export const liftResult = <A extends Array<unknown>, E, B>(
  * Tests 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
@@ -7498,6 +8594,11 @@ export const every: {
    * Tests 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
@@ -7517,6 +8618,11 @@ export const every: {
    * Tests 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
@@ -7536,6 +8642,11 @@ export const every: {
    * Tests 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
@@ -7555,6 +8666,11 @@ export const every: {
    * Tests 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
@@ -7646,6 +8762,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 +8779,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 +8789,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 +8806,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 +8816,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 +8833,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 +9044,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 +9057,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 +9066,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 +9079,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 +9088,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 +9101,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 +9113,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 +9137,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 +9163,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 +9190,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 +9232,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 +9259,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 +9288,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 +9317,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 +9358,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 +9435,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 +9466,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 +9497,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 +9548,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 +9568,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 +9577,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 +9597,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 +9606,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 +9626,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 +9641,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 +9668,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 +9695,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`.
@@ -8485,7 +9733,7 @@ export const cartesian: {
  *
  * **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.
  *
@@ -8516,6 +9764,11 @@ export const Do: ReadonlyArray<{}> = of({})
 /**
  * Introduces a new array variable into 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**
  *
  * - Each `bind` call adds a named property to the accumulated object.
@@ -8547,6 +9800,11 @@ export const bind: {
   /**
    * Introduces a new array variable into 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**
    *
    * - Each `bind` call adds a named property to the accumulated object.
@@ -8580,6 +9838,11 @@ export const bind: {
   /**
    * Introduces a new array variable into 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**
    *
    * - Each `bind` call adds a named property to the accumulated object.
@@ -8617,6 +9880,11 @@ export const bind: {
 /**
  * Names the elements of an array by wrapping each 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**
  *
  * - Equivalent to `Array.map(self, (a) => ({ [tag]: a }))`.
@@ -8644,6 +9912,11 @@ export const bindTo: {
   /**
    * Names the elements of an array by wrapping each 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**
    *
    * - Equivalent to `Array.map(self, (a) => ({ [tag]: a }))`.
@@ -8671,6 +9944,11 @@ export const bindTo: {
   /**
    * Names the elements of an array by wrapping each 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**
    *
    * - Equivalent to `Array.map(self, (a) => ({ [tag]: a }))`.
@@ -8770,6 +10048,11 @@ export function makeReducerConcat<A>(): Reducer.Reducer<Array<A>> {
 /**
  * Counts the 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**
  *
  * - The predicate receives both the element and its index.
@@ -8793,6 +10076,11 @@ export const countBy: {
   /**
    * Counts the 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**
    *
    * - The predicate receives both the element and its index.
@@ -8816,6 +10104,11 @@ export const countBy: {
   /**
    * Counts the 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**
    *
    * - The predicate receives both the element and its index.