effect 4.0.0-beta.66 → 4.0.0-beta.67

package/src/unstable/cli/Param.ts

@@ -1,13 +1,30 @@
 /**
+ * The `Param` module defines the shared parser tree used by the unstable CLI
+ * `Argument` and `Flag` modules. A `Param<Kind, A>` describes how to consume
+ * either positional arguments or named flags from parsed command-line input and
+ * return a typed value.
+ *
+ * **Common tasks**
+ *
+ * - Build primitive CLI inputs such as strings, booleans, numbers, choices,
+ *   paths, files, and redacted values
+ * - Attach help metadata with aliases and descriptions
+ * - Transform parsed values with pure or effectful validation
+ * - Model missing inputs with `Option`, defaults, config fallbacks, or prompts
+ * - Accept repeated inputs with variadic, bounded, and non-empty parameters
+ *
+ * **Gotchas**
+ *
+ * - The `Kind` type parameter (`"argument"` or `"flag"`) keeps positional
+ *   arguments and flags separate while allowing the implementation and
+ *   combinators to be shared.
+ * - Combinators preserve the parameter kind, so an argument parameter cannot be
+ *   accidentally composed into a flag parameter or the reverse.
+ * - Parsers return both the remaining positional arguments and the parsed
+ *   value; this is important for argument ordering and variadic parameters.
+ * - Some parsers require CLI services such as filesystem, path, terminal, or
+ *   child-process support through the parsing environment.
  * @internal
- *
- * Param is the polymorphic implementation shared by Argument.ts and Flag.ts.
- * The `Kind` type parameter ("argument" | "flag") enables type-safe separation
- * while sharing parsing logic and combinators.
- *
- * Users should import from `Argument` and `Flag` modules, not this module directly.
- * This module is not exported from the public API.
- *
  * @since 4.0.0
  */
 import * as Config from "../../Config.ts"
@@ -31,8 +48,13 @@ import * as Prompt from "./Prompt.ts"
 const TypeId = "~effect/cli/Param"
 
 /**
- * @since 4.0.0
+ * Polymorphic CLI parameter shared by `Argument` and `Flag`.
+ *
+ * A parameter knows whether it consumes positional arguments or flags and
+ * parses a `ParsedArgs` value into its typed result.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface Param<Kind extends ParamKind, out A> extends Param.Variance<A> {
   readonly _tag: "Single" | "Map" | "Transform" | "Optional" | "Variadic"
@@ -41,60 +63,72 @@ export interface Param<Kind extends ParamKind, out A> extends Param.Variance<A>
 }
 
 /**
- * @since 4.0.0
+ * Discriminator for whether a `Param` parses positional arguments or
+ * command-line flags.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type ParamKind = "argument" | "flag"
 
 /**
- * @since 4.0.0
+ * Services that parameter parsing can require, such as filesystem, path,
+ * terminal, and child-process support.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type Environment = FileSystem.FileSystem | Path.Path | Terminal.Terminal | ChildProcessSpawner
 
 /**
  * Kind discriminator for positional argument parameters.
  *
- * @since 4.0.0
  * @category constants
+ * @since 4.0.0
  */
 export const argumentKind: "argument" = "argument" as const
 
 /**
  * Kind discriminator for flag parameters.
  *
- * @since 4.0.0
  * @category constants
+ * @since 4.0.0
  */
 export const flagKind: "flag" = "flag" as const
 
 /**
  * Represents any parameter.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export type Any = Param<ParamKind, unknown>
 
 /**
  * Represents any positional argument parameter.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export type AnyArgument = Param<typeof argumentKind, unknown>
 
 /**
  * Represents any flag parameter.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export type AnyFlag = Param<typeof flagKind, unknown>
 
 /**
- * @since 4.0.0
+ * Function type used by parameters to parse currently available flags and
+ * positional arguments.
+ *
+ * It returns the remaining positional arguments together with the parsed value,
+ * or fails with a `CliError` while requiring the CLI parsing environment.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type Parse<A> = (args: ParsedArgs) => Effect.Effect<
   readonly [leftover: ReadonlyArray<string>, value: A],
@@ -103,12 +137,16 @@ export type Parse<A> = (args: ParsedArgs) => Effect.Effect<
 >
 
 /**
+ * Namespace containing type-level utilities attached to the `Param` interface.
+ *
  * @since 4.0.0
  */
 export declare namespace Param {
   /**
-   * @since 4.0.0
+   * Variance and pipeability marker carried by every `Param` value.
+   *
    * @category models
+   * @since 4.0.0
    */
   export interface Variance<out A> extends Pipeable {
     readonly [TypeId]: {
@@ -121,8 +159,8 @@ export declare namespace Param {
  * Map of flag names to their provided string values.
  * Multiple occurrences of a flag produce multiple values.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export type Flags = Record<string, ReadonlyArray<string>>
 
@@ -131,8 +169,8 @@ export type Flags = Record<string, ReadonlyArray<string>>
  * - `flags`: already-collected flag values by canonical flag name
  * - `arguments`: remaining positional arguments to be consumed
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface ParsedArgs {
   readonly flags: Flags
@@ -143,16 +181,21 @@ export interface ParsedArgs {
  * Represents a fallback prompt that can either be provided directly or
  * computed effectfully when the parameter is missing.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export type FallbackPrompt<A> =
   | Prompt.Prompt<A>
   | Effect.Effect<Prompt.Prompt<A>, CliError.CliError, Environment>
 
 /**
- * @since 4.0.0
+ * Leaf parameter that reads one named argument or flag with a primitive parser.
+ *
+ * Single parameters carry the user-facing name, aliases, description, primitive
+ * type, and optional metavar/type name used in help output.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface Single<Kind extends ParamKind, out A> extends Param<Kind, A> {
   readonly _tag: "Single"
@@ -165,8 +208,11 @@ export interface Single<Kind extends ParamKind, out A> extends Param<Kind, A> {
 }
 
 /**
- * @since 4.0.0
+ * Parameter node that maps the successfully parsed value of another parameter
+ * with a pure function.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface Map<Kind extends ParamKind, in out A, out B> extends Param<Kind, B> {
   readonly _tag: "Map"
@@ -176,8 +222,12 @@ export interface Map<Kind extends ParamKind, in out A, out B> extends Param<Kind
 }
 
 /**
- * @since 4.0.0
+ * Parameter node that rewrites another parameter's parser, allowing effectful
+ * validation, fallback behavior, or error translation while preserving the same
+ * parameter kind.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface Transform<Kind extends ParamKind, in out A, out B> extends Param<Kind, B> {
   readonly _tag: "Transform"
@@ -187,8 +237,11 @@ export interface Transform<Kind extends ParamKind, in out A, out B> extends Para
 }
 
 /**
- * @since 4.0.0
+ * Parameter node that turns a missing argument or flag into `Option.none()` and
+ * a present parsed value into `Option.some(value)`.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface Optional<Kind extends ParamKind, A> extends Param<Kind, Option.Option<A>> {
   readonly _tag: "Optional"
@@ -197,8 +250,12 @@ export interface Optional<Kind extends ParamKind, A> extends Param<Kind, Option.
 }
 
 /**
- * @since 4.0.0
+ * Parameter node that parses another parameter zero or more times and returns
+ * all parsed values as an array, respecting optional minimum and maximum
+ * occurrence bounds.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface Variadic<Kind extends ParamKind, A> extends Param<Kind, ReadonlyArray<A>> {
   readonly _tag: "Variadic"
@@ -220,7 +277,8 @@ const Proto = {
 /**
  * Type guard to check if a value is a Param.
  *
- * @example
+ * **Example** (Checking for params)
+ *
  * ```ts
  * import * as Param from "effect/unstable/cli/Param"
  *
@@ -233,15 +291,16 @@ const Proto = {
  * }
  * ```
  *
- * @since 4.0.0
  * @category refinements
+ * @since 4.0.0
  */
 export const isParam = (u: unknown): u is Param<any, ParamKind> => Predicate.hasProperty(u, TypeId)
 
 /**
  * Type guard to check if a param is a Single param (not composed).
  *
- * @example
+ * **Example** (Checking for single params)
+ *
  * ```ts
  * import * as Param from "effect/unstable/cli/Param"
  *
@@ -254,8 +313,8 @@ export const isParam = (u: unknown): u is Param<any, ParamKind> => Predicate.has
  * console.log(Param.isSingle(optionalParam)) // false
  * ```
  *
- * @since 4.0.0
  * @category refinements
+ * @since 4.0.0
  */
 export const isSingle = <const Kind extends ParamKind, A>(
   param: Param<Kind, A>
@@ -271,8 +330,14 @@ export const isFlagParam = <A>(
 ): single is Single<typeof flagKind, A> => single.kind === "flag"
 
 /**
- * @since 4.0.0
+ * Constructs a leaf `Single` parameter from its kind, name, primitive parser,
+ * and optional help metadata.
+ *
+ * The returned parser reads either one positional argument or the named flag,
+ * depending on `kind`.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const makeSingle = <const Kind extends ParamKind, A>(params: {
   readonly kind: Kind
@@ -298,7 +363,8 @@ export const makeSingle = <const Kind extends ParamKind, A>(params: {
 /**
  * Creates a string parameter.
  *
- * @example
+ * **Example** (Creating string parameters)
+ *
  * ```ts
  * import * as Param from "effect/unstable/cli/Param"
  *
@@ -313,8 +379,8 @@ export const makeSingle = <const Kind extends ParamKind, A>(params: {
  * // Usage in CLI: --name "John Doe" or as positional argument
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const string = <const Kind extends ParamKind>(
   kind: Kind,
@@ -329,7 +395,8 @@ export const string = <const Kind extends ParamKind>(
 /**
  * Creates a boolean parameter.
  *
- * @example
+ * **Example** (Creating boolean parameters)
+ *
  * ```ts
  * import * as Param from "effect/unstable/cli/Param"
  *
@@ -345,8 +412,8 @@ export const string = <const Kind extends ParamKind>(
  * // or as positional: true/false
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const boolean = <const Kind extends ParamKind>(
   kind: Kind,
@@ -361,7 +428,8 @@ export const boolean = <const Kind extends ParamKind>(
 /**
  * Creates an integer parameter.
  *
- * @example
+ * **Example** (Creating integer parameters)
+ *
  * ```ts
  * import * as Param from "effect/unstable/cli/Param"
  *
@@ -376,8 +444,8 @@ export const boolean = <const Kind extends ParamKind>(
  * // Usage in CLI: --port 8080 or as positional argument: 42
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const integer = <const Kind extends ParamKind>(
   kind: Kind,
@@ -392,7 +460,8 @@ export const integer = <const Kind extends ParamKind>(
 /**
  * Creates a floating-point number parameter.
  *
- * @example
+ * **Example** (Creating float parameters)
+ *
  * ```ts
  * import * as Param from "effect/unstable/cli/Param"
  *
@@ -407,8 +476,8 @@ export const integer = <const Kind extends ParamKind>(
  * // Usage in CLI: --rate 0.95 or as positional argument: 3.14159
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const float = <const Kind extends ParamKind>(
   kind: Kind,
@@ -423,7 +492,8 @@ export const float = <const Kind extends ParamKind>(
 /**
  * Creates a date parameter that parses ISO date strings.
  *
- * @example
+ * **Example** (Creating date parameters)
+ *
  * ```ts
  * import * as Param from "effect/unstable/cli/Param"
  *
@@ -439,8 +509,8 @@ export const float = <const Kind extends ParamKind>(
  * // Parses to JavaScript Date object
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const date = <const Kind extends ParamKind>(
   kind: Kind,
@@ -456,7 +526,8 @@ export const date = <const Kind extends ParamKind>(
  * Constructs command-line params that represent a choice between several
  * inputs. The input will be mapped to it's associated value during parsing.
  *
- * @example
+ * **Example** (Creating valued choices)
+ *
  * ```ts
  * import * as Param from "effect/unstable/cli/Param"
  *
@@ -478,8 +549,8 @@ export const date = <const Kind extends ParamKind>(
  * ])
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const choiceWithValue = <
   const Kind extends ParamKind,
@@ -495,7 +566,8 @@ export const choiceWithValue = <
  * Constructs command-line params that represent a choice between several
  * string inputs.
  *
- * @example
+ * **Example** (Creating string choices)
+ *
  * ```ts
  * import * as Param from "effect/unstable/cli/Param"
  *
@@ -509,8 +581,8 @@ export const choiceWithValue = <
  * ])
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const choice = <
   const Kind extends ParamKind,
@@ -523,7 +595,8 @@ export const choice = <
 /**
  * Creates a path parameter that accepts file or directory paths.
  *
- * @example
+ * **Example** (Creating path parameters)
+ *
  * ```ts
  * import * as Param from "effect/unstable/cli/Param"
  *
@@ -543,8 +616,8 @@ export const choice = <
  * })
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const path = <Kind extends ParamKind>(
   kind: Kind,
@@ -568,7 +641,8 @@ export const path = <Kind extends ParamKind>(
  * This is a convenience function that creates a path parameter with the
  * `pathType` set to `"directory"` and a default type name of `"directory"`.
  *
- * @example
+ * **Example** (Creating directory parameters)
+ *
  * ```ts
  * import * as Param from "effect/unstable/cli/Param"
  *
@@ -583,8 +657,8 @@ export const path = <Kind extends ParamKind>(
  * // Usage: --output-dir /path/to/dir --source /existing/dir
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const directory = <Kind extends ParamKind>(
   kind: Kind,
@@ -605,7 +679,8 @@ export const directory = <Kind extends ParamKind>(
  * This is a convenience function that creates a path parameter with a
  * `pathType` set to `"file"` and a default type name of `"file"`.
  *
- * @example
+ * **Example** (Creating file parameters)
+ *
  * ```ts
  * import * as Param from "effect/unstable/cli/Param"
  *
@@ -620,8 +695,8 @@ export const directory = <Kind extends ParamKind>(
  * // Usage: --output result.txt --input existing-file.txt
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const file = <Kind extends ParamKind>(
   kind: Kind,
@@ -640,7 +715,8 @@ export const file = <Kind extends ParamKind>(
  * Creates a redacted parameter for sensitive data like passwords.
  * The value is masked in help output and logging.
  *
- * @example
+ * **Example** (Creating redacted parameters)
+ *
  * ```ts
  * import * as Param from "effect/unstable/cli/Param"
  *
@@ -655,8 +731,8 @@ export const file = <Kind extends ParamKind>(
  * // Usage: --password (value will be hidden in help/logs)
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const redacted = <Kind extends ParamKind>(
   kind: Kind,
@@ -671,7 +747,8 @@ export const redacted = <Kind extends ParamKind>(
 /**
  * Creates a parameter that reads and returns file content as a string.
  *
- * @example
+ * **Example** (Reading file text)
+ *
  * ```ts
  * import * as Param from "effect/unstable/cli/Param"
  *
@@ -686,8 +763,8 @@ export const redacted = <Kind extends ParamKind>(
  * // Usage: --config config.txt (reads file content into string)
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const fileText = <Kind extends ParamKind>(kind: Kind, name: string): Param<Kind, string> =>
   makeSingle({
@@ -702,7 +779,8 @@ export const fileText = <Kind extends ParamKind>(kind: Kind, name: string): Para
  * The parser that is utilized will depend on the specified `format`, or the
  * extension of the file passed on the command-line if no `format` is specified.
  *
- * @example
+ * **Example** (Parsing file contents)
+ *
  * ```ts
  * import * as Param from "effect/unstable/cli/Param"
  *
@@ -718,8 +796,8 @@ export const fileText = <Kind extends ParamKind>(kind: Kind, name: string): Para
  * })
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const fileParse = <Kind extends ParamKind>(
   kind: Kind,
@@ -735,7 +813,8 @@ export const fileParse = <Kind extends ParamKind>(
 /**
  * Creates a parameter that reads and validates file content using a schema.
  *
- * @example
+ * **Example** (Validating file contents)
+ *
  * ```ts
  * import { Schema } from "effect"
  * import * as Param from "effect/unstable/cli/Param"
@@ -759,8 +838,8 @@ export const fileParse = <Kind extends ParamKind>(
  * // Usage: --config config.json (reads and validates file content)
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const fileSchema = <Kind extends ParamKind, A>(
   kind: Kind,
@@ -781,7 +860,8 @@ export const fileSchema = <Kind extends ParamKind, A>(
  * Note: Requires at least one key=value pair. The parsed pairs are merged
  * into a single record object.
  *
- * @example
+ * **Example** (Parsing key-value pairs)
+ *
  * ```ts
  * import * as Param from "effect/unstable/cli/Param"
  *
@@ -794,8 +874,8 @@ export const fileSchema = <Kind extends ParamKind, A>(
  * // --property name=value --property debug=true
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const keyValuePair = <Kind extends ParamKind>(
   kind: Kind,
@@ -818,23 +898,24 @@ export const keyValuePair = <Kind extends ParamKind>(
  *
  * This is useful for creating placeholder parameters or for combinators.
  *
- * @example
+ * **Example** (Creating sentinel parameters)
+ *
  * ```ts
  * import * as Param from "effect/unstable/cli/Param"
  *
  * // @internal - this module is not exported publicly
  *
- * // Create a none parameter for composition
- * const noneParam = Param.none(Param.flagKind)
+ * const disabledDebugParam = Param.none(Param.flagKind)
  *
- * // Often used in conditional parameter creation
- * const conditionalParam = process.env.NODE_ENV === "production"
- *   ? Param.string(Param.flagKind, "my-dev-flag")
- *   : Param.none(Param.flagKind)
+ * const makeDebugParam = (enableDebug: boolean) =>
+ *   enableDebug ? Param.string(Param.flagKind, "debug") : disabledDebugParam
+ *
+ * console.log(makeDebugParam(true) === disabledDebugParam) // false
+ * console.log(makeDebugParam(false) === disabledDebugParam) // true
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const none = <Kind extends ParamKind>(kind: Kind): Param<Kind, never> =>
   makeSingle({
@@ -854,7 +935,8 @@ const FLAG_DASH_REGEXP = /^-+/
  * This works on any param structure by recursively finding the underlying
  * `Single` node and applying the alias there.
  *
- * @example
+ * **Example** (Adding parameter aliases)
+ *
  * ```ts
  * import * as Param from "effect/unstable/cli/Param"
  *
@@ -872,8 +954,8 @@ const FLAG_DASH_REGEXP = /^-+/
  * )
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const withAlias: {
   /**
@@ -885,7 +967,8 @@ export const withAlias: {
    * This works on any param structure by recursively finding the underlying
    * `Single` node and applying the alias there.
    *
-   * @example
+   * **Example** (Adding parameter aliases)
+   *
    * ```ts
    * import * as Param from "effect/unstable/cli/Param"
    *
@@ -903,8 +986,8 @@ export const withAlias: {
    * )
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <Kind extends ParamKind, A>(alias: string): (self: Param<Kind, A>) => Param<Kind, A>
   /**
@@ -916,7 +999,8 @@ export const withAlias: {
    * This works on any param structure by recursively finding the underlying
    * `Single` node and applying the alias there.
    *
-   * @example
+   * **Example** (Adding parameter aliases)
+   *
    * ```ts
    * import * as Param from "effect/unstable/cli/Param"
    *
@@ -934,8 +1018,8 @@ export const withAlias: {
    * )
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <Kind extends ParamKind, A>(self: Param<Kind, A>, alias: string): Param<Kind, A>
 } = dual(2, <Kind extends ParamKind, A>(self: Param<Kind, A>, alias: string) => {
@@ -952,7 +1036,8 @@ export const withAlias: {
  * Descriptions provide users with information about what the option does
  * when they view help documentation.
  *
- * @example
+ * **Example** (Adding help descriptions)
+ *
  * ```ts
  * import * as Param from "effect/unstable/cli/Param"
  *
@@ -964,8 +1049,8 @@ export const withAlias: {
  * )
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const withDescription: {
   /**
@@ -974,7 +1059,8 @@ export const withDescription: {
    * Descriptions provide users with information about what the option does
    * when they view help documentation.
    *
-   * @example
+   * **Example** (Adding help descriptions)
+   *
    * ```ts
    * import * as Param from "effect/unstable/cli/Param"
    *
@@ -986,8 +1072,8 @@ export const withDescription: {
    * )
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <Kind extends ParamKind, A>(description: string): (self: Param<Kind, A>) => Param<Kind, A>
   /**
@@ -996,7 +1082,8 @@ export const withDescription: {
    * Descriptions provide users with information about what the option does
    * when they view help documentation.
    *
-   * @example
+   * **Example** (Adding help descriptions)
+   *
    * ```ts
    * import * as Param from "effect/unstable/cli/Param"
    *
@@ -1008,8 +1095,8 @@ export const withDescription: {
    * )
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <Kind extends ParamKind, A>(self: Param<Kind, A>, description: string): Param<Kind, A>
 } = dual(2, <Kind extends ParamKind, A>(self: Param<Kind, A>, description: string) => {
@@ -1023,7 +1110,8 @@ export const withDescription: {
 /**
  * Transforms the parsed value of an option using a mapping function.
  *
- * @example
+ * **Example** (Mapping parsed values)
+ *
  * ```ts
  * import * as Param from "effect/unstable/cli/Param"
  *
@@ -1034,14 +1122,15 @@ export const withDescription: {
  * )
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const map: {
   /**
    * Transforms the parsed value of an option using a mapping function.
    *
-   * @example
+   * **Example** (Mapping parsed values)
+   *
    * ```ts
    * import * as Param from "effect/unstable/cli/Param"
    *
@@ -1052,14 +1141,15 @@ export const map: {
    * )
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <A, B>(f: (a: A) => B): <Kind extends ParamKind>(self: Param<Kind, A>) => Param<Kind, B>
   /**
    * Transforms the parsed value of an option using a mapping function.
    *
-   * @example
+   * **Example** (Mapping parsed values)
+   *
    * ```ts
    * import * as Param from "effect/unstable/cli/Param"
    *
@@ -1070,8 +1160,8 @@ export const map: {
    * )
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <Kind extends ParamKind, A, B>(self: Param<Kind, A>, f: (a: A) => B): Param<Kind, B>
 } = dual(2, <Kind extends ParamKind, A, B>(self: Param<Kind, A>, f: (a: A) => B) => {
@@ -1104,7 +1194,8 @@ const transform = <Kind extends ParamKind, A, B>(
 /**
  * Transforms the parsed value of an option using an effectful mapping function.
  *
- * @example
+ * **Example** (Mapping parsed values effectfully)
+ *
  * ```ts
  * import * as Param from "effect/unstable/cli/Param"
  *
@@ -1128,14 +1219,15 @@ const transform = <Kind extends ParamKind, A, B>(
  * )
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const mapEffect: {
   /**
    * Transforms the parsed value of an option using an effectful mapping function.
    *
-   * @example
+   * **Example** (Mapping parsed values effectfully)
+   *
    * ```ts
    * import * as Param from "effect/unstable/cli/Param"
    *
@@ -1159,14 +1251,15 @@ export const mapEffect: {
    * )
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <A, B>(f: (a: A) => Effect.Effect<B, CliError.CliError, Environment>): <Kind extends ParamKind>(self: Param<Kind, A>) => Param<Kind, B>
   /**
    * Transforms the parsed value of an option using an effectful mapping function.
    *
-   * @example
+   * **Example** (Mapping parsed values effectfully)
+   *
    * ```ts
    * import * as Param from "effect/unstable/cli/Param"
    *
@@ -1190,8 +1283,8 @@ export const mapEffect: {
    * )
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <Kind extends ParamKind, A, B>(
     self: Param<Kind, A>,
@@ -1214,7 +1307,8 @@ export const mapEffect: {
  * Transforms the parsed value of an option using a function that may throw,
  * converting any thrown errors into failure messages.
  *
- * @example
+ * **Example** (Mapping thrown errors)
+ *
  * ```ts
  * import * as Param from "effect/unstable/cli/Param"
  *
@@ -1229,15 +1323,16 @@ export const mapEffect: {
  * )
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const mapTryCatch: {
   /**
    * Transforms the parsed value of an option using a function that may throw,
    * converting any thrown errors into failure messages.
    *
-   * @example
+   * **Example** (Mapping thrown errors)
+   *
    * ```ts
    * import * as Param from "effect/unstable/cli/Param"
    *
@@ -1252,15 +1347,16 @@ export const mapTryCatch: {
    * )
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <A, B>(f: (a: A) => B, onError: (error: unknown) => string): <Kind extends ParamKind>(self: Param<Kind, A>) => Param<Kind, B>
   /**
    * Transforms the parsed value of an option using a function that may throw,
    * converting any thrown errors into failure messages.
    *
-   * @example
+   * **Example** (Mapping thrown errors)
+   *
    * ```ts
    * import * as Param from "effect/unstable/cli/Param"
    *
@@ -1275,8 +1371,8 @@ export const mapTryCatch: {
    * )
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <Kind extends ParamKind, A, B>(self: Param<Kind, A>, f: (a: A) => B, onError: (error: unknown) => string): Param<Kind, B>
 } = dual(3, <Kind extends ParamKind, A, B>(
@@ -1309,12 +1405,14 @@ export const mapTryCatch: {
 })
 
 /**
- * Creates an optional option that returns None when not provided.
+ * Makes a flag or positional argument optional.
  *
- * Optional options never fail with MissingOption errors. If the option is not
- * provided on the command line, Option.none() is returned instead.
+ * When the parameter is absent, parsing succeeds with `Option.none()` instead
+ * of failing with a missing option or missing argument error. When present, the
+ * parsed value is wrapped in `Option.some()`.
+ *
+ * **Example** (Making parameters optional)
  *
- * @example
  * ```ts
  * import * as Param from "effect/unstable/cli/Param"
  *
@@ -1324,8 +1422,8 @@ export const mapTryCatch: {
  * const port = Param.optional(Param.integer(Param.flagKind, "port"))
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const optional = <Kind extends ParamKind, A>(
   param: Param<Kind, A>
@@ -1362,13 +1460,13 @@ export const optional = <Kind extends ParamKind, A>(
 }
 
 /**
- * Makes an option optional by providing a default value.
+ * Makes a flag or positional argument optional by supplying a fallback value.
+ *
+ * The fallback may be a pure value or an effect. It is used only when the
+ * parameter is absent; provided values are parsed normally.
  *
- * This combinator is useful when you want to make an existing option optional
- * by providing a fallback value that will be used when the option is not
- * provided on the command line.
+ * **Example** (Providing default values)
  *
- * @example
  * ```ts
  * import * as Param from "effect/unstable/cli/Param"
  *
@@ -1387,18 +1485,18 @@ export const optional = <Kind extends ParamKind, A>(
  * )
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const withDefault: {
   /**
-   * Makes an option optional by providing a default value.
+   * Makes a flag or positional argument optional by supplying a fallback value.
    *
-   * This combinator is useful when you want to make an existing option optional
-   * by providing a fallback value that will be used when the option is not
-   * provided on the command line.
+   * The fallback may be a pure value or an effect. It is used only when the
+   * parameter is absent; provided values are parsed normally.
+   *
+   * **Example** (Providing default values)
    *
-   * @example
    * ```ts
    * import * as Param from "effect/unstable/cli/Param"
    *
@@ -1417,18 +1515,18 @@ export const withDefault: {
    * )
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <const B>(defaultValue: B | Effect.Effect<B, CliError.CliError, Environment>): <Kind extends ParamKind, A>(self: Param<Kind, A>) => Param<Kind, A | B>
   /**
-   * Makes an option optional by providing a default value.
+   * Makes a flag or positional argument optional by supplying a fallback value.
+   *
+   * The fallback may be a pure value or an effect. It is used only when the
+   * parameter is absent; provided values are parsed normally.
    *
-   * This combinator is useful when you want to make an existing option optional
-   * by providing a fallback value that will be used when the option is not
-   * provided on the command line.
+   * **Example** (Providing default values)
    *
-   * @example
    * ```ts
    * import * as Param from "effect/unstable/cli/Param"
    *
@@ -1447,8 +1545,8 @@ export const withDefault: {
    * )
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <Kind extends ParamKind, A, const B>(
     self: Param<Kind, A>,
@@ -1473,22 +1571,22 @@ export const withDefault: {
 /**
  * Adds a fallback config that is loaded when a required parameter is missing.
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const withFallbackConfig: {
   /**
    * Adds a fallback config that is loaded when a required parameter is missing.
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <B>(config: Config.Config<B>): <Kind extends ParamKind, A>(self: Param<Kind, A>) => Param<Kind, A | B>
   /**
    * Adds a fallback config that is loaded when a required parameter is missing.
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <Kind extends ParamKind, A, B>(self: Param<Kind, A>, config: Config.Config<B>): Param<Kind, A | B>
 } = dual(2, <Kind extends ParamKind, A, B>(
@@ -1525,22 +1623,22 @@ export const withFallbackConfig: {
 /**
  * Adds a fallback prompt that is shown when a required parameter is missing.
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const withFallbackPrompt: {
   /**
    * Adds a fallback prompt that is shown when a required parameter is missing.
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <B>(prompt: FallbackPrompt<B>): <Kind extends ParamKind, A>(self: Param<Kind, A>) => Param<Kind, A | B>
   /**
    * Adds a fallback prompt that is shown when a required parameter is missing.
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <Kind extends ParamKind, A, B>(self: Param<Kind, A>, prompt: FallbackPrompt<B>): Param<Kind, A | B>
 } = dual(2, <Kind extends ParamKind, A, B>(
@@ -1564,8 +1662,8 @@ export const withFallbackPrompt: {
 /**
  * Represent options which can be used to configure variadic parameters.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export type VariadicParamOptions = {
   /**
@@ -1585,7 +1683,8 @@ export type VariadicParamOptions = {
  * The min and max parameters are optional - if not provided, the parameter can be
  * specified any number of times (0 to infinity).
  *
- * @example
+ * **Example** (Accepting multiple values)
+ *
  * ```ts
  * import * as Param from "effect/unstable/cli/Param"
  *
@@ -1603,12 +1702,12 @@ export type VariadicParamOptions = {
  * // Variadic with both min and max
  * const limited = Param.variadic(Param.string(Param.flagKind, "item"), {
  *   min: 2, // at least 2 times
- *   max: 2 // at most 5 times
+ *   max: 2 // at most 2 times
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const variadic = <Kind extends ParamKind, A>(
   self: Param<Kind, A>,
@@ -1638,7 +1737,8 @@ export const variadic = <Kind extends ParamKind, A>(
  * This combinator transforms an option to accept between `min` and `max`
  * occurrences on the command line, returning an array of all provided values.
  *
- * @example
+ * **Example** (Bounding repeated values)
+ *
  * ```ts
  * import * as Param from "effect/unstable/cli/Param"
  *
@@ -1662,8 +1762,8 @@ export const variadic = <Kind extends ParamKind, A>(
  * // Result: ["dev", "staging", "v1.0"]
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const between: {
   /**
@@ -1672,7 +1772,8 @@ export const between: {
    * This combinator transforms an option to accept between `min` and `max`
    * occurrences on the command line, returning an array of all provided values.
    *
-   * @example
+   * **Example** (Bounding repeated values)
+   *
    * ```ts
    * import * as Param from "effect/unstable/cli/Param"
    *
@@ -1696,8 +1797,8 @@ export const between: {
    * // Result: ["dev", "staging", "v1.0"]
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <A>(min: number, max: number): <Kind extends ParamKind>(self: Param<Kind, A>) => Param<Kind, ReadonlyArray<A>>
   /**
@@ -1706,7 +1807,8 @@ export const between: {
    * This combinator transforms an option to accept between `min` and `max`
    * occurrences on the command line, returning an array of all provided values.
    *
-   * @example
+   * **Example** (Bounding repeated values)
+   *
    * ```ts
    * import * as Param from "effect/unstable/cli/Param"
    *
@@ -1730,8 +1832,8 @@ export const between: {
    * // Result: ["dev", "staging", "v1.0"]
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <Kind extends ParamKind, A>(self: Param<Kind, A>, min: number, max: number): Param<Kind, ReadonlyArray<A>>
 } = dual(3, <Kind extends ParamKind, A>(self: Param<Kind, A>, min: number, max: number) => {
@@ -1751,7 +1853,8 @@ export const between: {
  * This combinator transforms an option to accept between 0 and `max`
  * occurrences on the command line, returning an array of all provided values.
  *
- * @example
+ * **Example** (Limiting repeated values)
+ *
  * ```ts
  * import * as Param from "effect/unstable/cli/Param"
  *
@@ -1766,8 +1869,8 @@ export const between: {
  * // Result: ["warning1", "warning2"]
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const atMost: {
   /**
@@ -1776,7 +1879,8 @@ export const atMost: {
    * This combinator transforms an option to accept between 0 and `max`
    * occurrences on the command line, returning an array of all provided values.
    *
-   * @example
+   * **Example** (Limiting repeated values)
+   *
    * ```ts
    * import * as Param from "effect/unstable/cli/Param"
    *
@@ -1791,8 +1895,8 @@ export const atMost: {
    * // Result: ["warning1", "warning2"]
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <A>(max: number): <Kind extends ParamKind>(self: Param<Kind, A>) => Param<Kind, ReadonlyArray<A>>
   /**
@@ -1801,7 +1905,8 @@ export const atMost: {
    * This combinator transforms an option to accept between 0 and `max`
    * occurrences on the command line, returning an array of all provided values.
    *
-   * @example
+   * **Example** (Limiting repeated values)
+   *
    * ```ts
    * import * as Param from "effect/unstable/cli/Param"
    *
@@ -1816,8 +1921,8 @@ export const atMost: {
    * // Result: ["warning1", "warning2"]
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <Kind extends ParamKind, A>(self: Param<Kind, A>, max: number): Param<Kind, ReadonlyArray<A>>
 } = dual(2, <Kind extends ParamKind, A>(self: Param<Kind, A>, max: number) => {
@@ -1833,7 +1938,8 @@ export const atMost: {
  * This combinator transforms an option to accept at least `min`
  * occurrences on the command line, returning an array of all provided values.
  *
- * @example
+ * **Example** (Requiring repeated values)
+ *
  * ```ts
  * import * as Param from "effect/unstable/cli/Param"
  *
@@ -1849,8 +1955,8 @@ export const atMost: {
  * // Result: ["file1.txt", "file2.txt", "file3.txt"]
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const atLeast: {
   /**
@@ -1859,7 +1965,8 @@ export const atLeast: {
    * This combinator transforms an option to accept at least `min`
    * occurrences on the command line, returning an array of all provided values.
    *
-   * @example
+   * **Example** (Requiring repeated values)
+   *
    * ```ts
    * import * as Param from "effect/unstable/cli/Param"
    *
@@ -1875,8 +1982,8 @@ export const atLeast: {
    * // Result: ["file1.txt", "file2.txt", "file3.txt"]
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <A>(min: number): <Kind extends ParamKind>(self: Param<Kind, A>) => Param<Kind, ReadonlyArray<A>>
   /**
@@ -1885,7 +1992,8 @@ export const atLeast: {
    * This combinator transforms an option to accept at least `min`
    * occurrences on the command line, returning an array of all provided values.
    *
-   * @example
+   * **Example** (Requiring repeated values)
+   *
    * ```ts
    * import * as Param from "effect/unstable/cli/Param"
    *
@@ -1901,8 +2009,8 @@ export const atLeast: {
    * // Result: ["file1.txt", "file2.txt", "file3.txt"]
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <Kind extends ParamKind, A>(self: Param<Kind, A>, min: number): Param<Kind, ReadonlyArray<A>>
 } = dual(2, <Kind extends ParamKind, A>(self: Param<Kind, A>, min: number) => {
@@ -1918,7 +2026,8 @@ export const atLeast: {
  *
  * This combinator is useful for validation and transformation in a single step.
  *
- * @example
+ * **Example** (Filtering and transforming values)
+ *
  * ```ts
  * import { Option } from "effect"
  * import * as Param from "effect/unstable/cli/Param"
@@ -1932,8 +2041,8 @@ export const atLeast: {
  * )
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const filterMap: {
   /**
@@ -1942,7 +2051,8 @@ export const filterMap: {
    *
    * This combinator is useful for validation and transformation in a single step.
    *
-   * @example
+   * **Example** (Filtering and transforming values)
+   *
    * ```ts
    * import { Option } from "effect"
    * import * as Param from "effect/unstable/cli/Param"
@@ -1956,8 +2066,8 @@ export const filterMap: {
    * )
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <A, B>(filter: (a: A) => Option.Option<B>, onNone: (a: A) => string): <Kind extends ParamKind>(self: Param<Kind, A>) => Param<Kind, B>
   /**
@@ -1966,7 +2076,8 @@ export const filterMap: {
    *
    * This combinator is useful for validation and transformation in a single step.
    *
-   * @example
+   * **Example** (Filtering and transforming values)
+   *
    * ```ts
    * import { Option } from "effect"
    * import * as Param from "effect/unstable/cli/Param"
@@ -1980,8 +2091,8 @@ export const filterMap: {
    * )
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <Kind extends ParamKind, A, B>(
     self: Param<Kind, A>,
@@ -2013,7 +2124,8 @@ export const filterMap: {
 /**
  * Filters parsed values, failing with a custom error message if the predicate returns false.
  *
- * @example
+ * **Example** (Filtering parsed values)
+ *
  * ```ts
  * import * as Param from "effect/unstable/cli/Param"
  *
@@ -2027,14 +2139,15 @@ export const filterMap: {
  * )
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const filter: {
   /**
    * Filters parsed values, failing with a custom error message if the predicate returns false.
    *
-   * @example
+   * **Example** (Filtering parsed values)
+   *
    * ```ts
    * import * as Param from "effect/unstable/cli/Param"
    *
@@ -2048,14 +2161,15 @@ export const filter: {
    * )
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <A>(predicate: Predicate.Predicate<A>, onFalse: (a: A) => string): <Kind extends ParamKind>(self: Param<Kind, A>) => Param<Kind, A>
   /**
    * Filters parsed values, failing with a custom error message if the predicate returns false.
    *
-   * @example
+   * **Example** (Filtering parsed values)
+   *
    * ```ts
    * import * as Param from "effect/unstable/cli/Param"
    *
@@ -2069,8 +2183,8 @@ export const filter: {
    * )
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <Kind extends ParamKind, A>(
     self: Param<Kind, A>,
@@ -2089,7 +2203,8 @@ export const filter: {
  * The metavar is displayed in usage text to indicate what value the user should provide.
  * For example, `--output FILE` shows `FILE` as the metavar.
  *
- * @example
+ * **Example** (Setting metavars)
+ *
  * ```ts
  * import * as Param from "effect/unstable/cli/Param"
  *
@@ -2104,8 +2219,8 @@ export const filter: {
  * )
  * ```
  *
- * @since 4.0.0
  * @category metadata
+ * @since 4.0.0
  */
 export const withMetavar: {
   /**
@@ -2114,7 +2229,8 @@ export const withMetavar: {
    * The metavar is displayed in usage text to indicate what value the user should provide.
    * For example, `--output FILE` shows `FILE` as the metavar.
    *
-   * @example
+   * **Example** (Setting metavars)
+   *
    * ```ts
    * import * as Param from "effect/unstable/cli/Param"
    *
@@ -2129,8 +2245,8 @@ export const withMetavar: {
    * )
    * ```
    *
-   * @since 4.0.0
    * @category metadata
+   * @since 4.0.0
    */
   <K extends ParamKind>(metavar: string): <A>(self: Param<K, A>) => Param<K, A>
   /**
@@ -2139,7 +2255,8 @@ export const withMetavar: {
    * The metavar is displayed in usage text to indicate what value the user should provide.
    * For example, `--output FILE` shows `FILE` as the metavar.
    *
-   * @example
+   * **Example** (Setting metavars)
+   *
    * ```ts
    * import * as Param from "effect/unstable/cli/Param"
    *
@@ -2154,8 +2271,8 @@ export const withMetavar: {
    * )
    * ```
    *
-   * @since 4.0.0
    * @category metadata
+   * @since 4.0.0
    */
   <K extends ParamKind, A>(self: Param<K, A>, metavar: string): Param<K, A>
 } = dual(2, <K extends ParamKind, A>(
@@ -2171,7 +2288,8 @@ export const withMetavar: {
 /**
  * Validates parsed values against a Schema, providing detailed error messages.
  *
- * @example
+ * **Example** (Validating with schemas)
+ *
  * ```ts
  * import { Schema } from "effect"
  * import * as Param from "effect/unstable/cli/Param"
@@ -2188,14 +2306,15 @@ export const withMetavar: {
  * )
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const withSchema: {
   /**
    * Validates parsed values against a Schema, providing detailed error messages.
    *
-   * @example
+   * **Example** (Validating with schemas)
+   *
    * ```ts
    * import { Schema } from "effect"
    * import * as Param from "effect/unstable/cli/Param"
@@ -2212,14 +2331,15 @@ export const withSchema: {
    * )
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <A, B>(schema: Schema.Codec<B, A>): <Kind extends ParamKind>(self: Param<Kind, A>) => Param<Kind, B>
   /**
    * Validates parsed values against a Schema, providing detailed error messages.
    *
-   * @example
+   * **Example** (Validating with schemas)
+   *
    * ```ts
    * import { Schema } from "effect"
    * import * as Param from "effect/unstable/cli/Param"
@@ -2236,8 +2356,8 @@ export const withSchema: {
    * )
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <Kind extends ParamKind, A, B>(self: Param<Kind, A>, schema: Schema.Codec<B, A>): Param<Kind, B>
 } = dual(2, <Kind extends ParamKind, A, B>(
@@ -2260,7 +2380,8 @@ export const withSchema: {
 /**
  * Provides a fallback param to use if this param fails to parse.
  *
- * @example
+ * **Example** (Falling back to another parameter)
+ *
  * ```ts
  * import * as Param from "effect/unstable/cli/Param"
  *
@@ -2271,14 +2392,15 @@ export const withSchema: {
  * )
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const orElse: {
   /**
    * Provides a fallback param to use if this param fails to parse.
    *
-   * @example
+   * **Example** (Falling back to another parameter)
+   *
    * ```ts
    * import * as Param from "effect/unstable/cli/Param"
    *
@@ -2289,14 +2411,15 @@ export const orElse: {
    * )
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <B, Kind extends ParamKind>(orElse: (error: CliError.CliError) => Param<Kind, B>): <A>(self: Param<Kind, A>) => Param<Kind, A | B>
   /**
    * Provides a fallback param to use if this param fails to parse.
    *
-   * @example
+   * **Example** (Falling back to another parameter)
+   *
    * ```ts
    * import * as Param from "effect/unstable/cli/Param"
    *
@@ -2307,8 +2430,8 @@ export const orElse: {
    * )
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <Kind extends ParamKind, A, B>(self: Param<Kind, A>, orElse: (error: CliError.CliError) => Param<Kind, B>): Param<Kind, A | B>
 } = dual(2, <Kind extends ParamKind, A, B>(
@@ -2321,9 +2444,14 @@ export const orElse: {
   ))
 
 /**
- * Provides a fallback param, wrapping results in Either to distinguish which param succeeded.
+ * Provides a fallback param and returns a `Result` indicating which param
+ * succeeded.
+ *
+ * The original param's value is returned as `Result.succeed`, while the
+ * fallback param's value is returned as `Result.fail`.
+ *
+ * **Example** (Returning fallback results)
  *
- * @example
  * ```ts
  * import * as Param from "effect/unstable/cli/Param"
  *
@@ -2335,14 +2463,19 @@ export const orElse: {
  * // Returns Result<string, string>
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const orElseResult: {
   /**
-   * Provides a fallback param, wrapping results in Either to distinguish which param succeeded.
+   * Provides a fallback param and returns a `Result` indicating which param
+   * succeeded.
+   *
+   * The original param's value is returned as `Result.succeed`, while the
+   * fallback param's value is returned as `Result.fail`.
+   *
+   * **Example** (Returning fallback results)
    *
-   * @example
    * ```ts
    * import * as Param from "effect/unstable/cli/Param"
    *
@@ -2354,14 +2487,19 @@ export const orElseResult: {
    * // Returns Result<string, string>
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <Kind extends ParamKind, B>(orElse: (error: CliError.CliError) => Param<Kind, B>): <A>(self: Param<Kind, A>) => Param<Kind, Result.Result<A, B>>
   /**
-   * Provides a fallback param, wrapping results in Either to distinguish which param succeeded.
+   * Provides a fallback param and returns a `Result` indicating which param
+   * succeeded.
+   *
+   * The original param's value is returned as `Result.succeed`, while the
+   * fallback param's value is returned as `Result.fail`.
+   *
+   * **Example** (Returning fallback results)
    *
-   * @example
    * ```ts
    * import * as Param from "effect/unstable/cli/Param"
    *
@@ -2373,8 +2511,8 @@ export const orElseResult: {
    * // Returns Result<string, string>
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <Kind extends ParamKind, A, B>(self: Param<Kind, A>, orElse: (error: CliError.CliError) => Param<Kind, B>): Param<Kind, Result.Result<A, B>>
 } = dual(2, <Kind extends ParamKind, A, B>(