effect 4.0.0-beta.66 → 4.0.0-beta.68

package/src/unstable/cli/Param.ts

@@ -1,12 +1,29 @@
 /**
- * @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.
+ * 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.
  *
  * @since 4.0.0
  */
@@ -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,9 +277,10 @@ 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"
+ * import { Param } from "effect/unstable/cli"
  *
  * // @internal - this module is not exported publicly
  *
@@ -233,17 +291,18 @@ 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"
+ * import { Param } from "effect/unstable/cli"
  *
  * // @internal - this module is not exported publicly
  *
@@ -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,9 +363,10 @@ 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"
+ * import { Param } from "effect/unstable/cli"
  *
  * // @internal - this module is not exported publicly
  *
@@ -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,9 +395,10 @@ 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"
+ * import { Param } from "effect/unstable/cli"
  *
  * // @internal - this module is not exported publicly
  *
@@ -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,9 +428,10 @@ 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"
+ * import { Param } from "effect/unstable/cli"
  *
  * // @internal - this module is not exported publicly
  *
@@ -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,9 +460,10 @@ 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"
+ * import { Param } from "effect/unstable/cli"
  *
  * // @internal - this module is not exported publicly
  *
@@ -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,9 +492,10 @@ 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"
+ * import { Param } from "effect/unstable/cli"
  *
  * // @internal - this module is not exported publicly
  *
@@ -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,9 +526,10 @@ 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"
+ * import { Param } from "effect/unstable/cli"
  *
  * // @internal - this module is not exported publicly
  *
@@ -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,9 +566,10 @@ 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"
+ * import { Param } from "effect/unstable/cli"
  *
  * // @internal - this module is not exported publicly
  *
@@ -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,9 +595,10 @@ 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"
+ * import { Param } from "effect/unstable/cli"
  *
  * // @internal - this module is not exported publicly
  *
@@ -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,9 +641,10 @@ 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"
+ * import { Param } from "effect/unstable/cli"
  *
  * // @internal - this module is not exported publicly
  *
@@ -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,9 +679,10 @@ 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"
+ * import { Param } from "effect/unstable/cli"
  *
  * // @internal - this module is not exported publicly
  *
@@ -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,9 +715,10 @@ 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"
+ * import { Param } from "effect/unstable/cli"
  *
  * // @internal - this module is not exported publicly
  *
@@ -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,9 +747,10 @@ 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"
+ * import { Param } from "effect/unstable/cli"
  *
  * // @internal - this module is not exported publicly
  *
@@ -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,9 +779,10 @@ 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"
+ * import { Param } from "effect/unstable/cli"
  *
  * // @internal - this module is not exported publicly
  *
@@ -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,10 +813,11 @@ 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"
+ * import { Param } from "effect/unstable/cli"
  * // @internal - this module is not exported publicly
  *
  * // Parse JSON config file
@@ -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,9 +860,10 @@ 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"
+ * import { Param } from "effect/unstable/cli"
  *
  * // @internal - this module is not exported publicly
  *
@@ -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"
+ * import { Param } from "effect/unstable/cli"
  *
  * // @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,9 +935,10 @@ 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"
+ * import { Param } from "effect/unstable/cli"
  *
  * // @internal - this module is not exported publicly
  *
@@ -872,8 +954,8 @@ const FLAG_DASH_REGEXP = /^-+/
  * )
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const withAlias: {
   /**
@@ -885,9 +967,10 @@ 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"
+   * import { Param } from "effect/unstable/cli"
    *
    * // @internal - this module is not exported publicly
    *
@@ -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,9 +999,10 @@ 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"
+   * import { Param } from "effect/unstable/cli"
    *
    * // @internal - this module is not exported publicly
    *
@@ -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,9 +1036,10 @@ 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"
+ * import { Param } from "effect/unstable/cli"
  *
  * // @internal - this module is not exported publicly
  *
@@ -964,8 +1049,8 @@ export const withAlias: {
  * )
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const withDescription: {
   /**
@@ -974,9 +1059,10 @@ 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"
+   * import { Param } from "effect/unstable/cli"
    *
    * // @internal - this module is not exported publicly
    *
@@ -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,9 +1082,10 @@ 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"
+   * import { Param } from "effect/unstable/cli"
    *
    * // @internal - this module is not exported publicly
    *
@@ -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,9 +1110,10 @@ 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"
+ * import { Param } from "effect/unstable/cli"
  *
  * // @internal - this module is not exported publicly
  *
@@ -1034,16 +1122,17 @@ 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"
+   * import { Param } from "effect/unstable/cli"
    *
    * // @internal - this module is not exported publicly
    *
@@ -1052,16 +1141,17 @@ 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"
+   * import { Param } from "effect/unstable/cli"
    *
    * // @internal - this module is not exported publicly
    *
@@ -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,13 +1194,13 @@ 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"
+ * import { Effect } from "effect"
+ * import { CliError, Param } from "effect/unstable/cli"
  *
  * // @internal - this module is not exported publicly
- * import { Effect } from "effect"
- * import { CliError } from "effect/unstable/cli"
  *
  * const validatedEmail = Param.string(Param.flagKind, "email").pipe(
  *   Param.mapEffect((email) =>
@@ -1128,20 +1218,20 @@ 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"
+   * import { Effect } from "effect"
+   * import { CliError, Param } from "effect/unstable/cli"
    *
    * // @internal - this module is not exported publicly
-   * import { Effect } from "effect"
-   * import { CliError } from "effect/unstable/cli"
    *
    * const validatedEmail = Param.string(Param.flagKind, "email").pipe(
    *   Param.mapEffect((email) =>
@@ -1159,20 +1249,20 @@ 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"
+   * import { Effect } from "effect"
+   * import { CliError, Param } from "effect/unstable/cli"
    *
    * // @internal - this module is not exported publicly
-   * import { Effect } from "effect"
-   * import { CliError } from "effect/unstable/cli"
    *
    * const validatedEmail = Param.string(Param.flagKind, "email").pipe(
    *   Param.mapEffect((email) =>
@@ -1190,8 +1280,8 @@ export const mapEffect: {
    * )
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <Kind extends ParamKind, A, B>(
     self: Param<Kind, A>,
@@ -1214,9 +1304,10 @@ 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"
+ * import { Param } from "effect/unstable/cli"
  *
  * // @internal - this module is not exported publicly
  *
@@ -1229,17 +1320,18 @@ 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"
+   * import { Param } from "effect/unstable/cli"
    *
    * // @internal - this module is not exported publicly
    *
@@ -1252,17 +1344,18 @@ 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"
+   * import { Param } from "effect/unstable/cli"
    *
    * // @internal - this module is not exported publicly
    *
@@ -1275,8 +1368,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,14 +1402,16 @@ 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"
+ * import { Param } from "effect/unstable/cli"
  *
  * // Create an optional port option
  * // - When not provided: returns Option.none()
@@ -1324,8 +1419,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,15 +1457,15 @@ 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"
+ * import { Param } from "effect/unstable/cli"
  *
  * // @internal - this module is not exported publicly
  *
@@ -1387,20 +1482,20 @@ 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"
+   * import { Param } from "effect/unstable/cli"
    *
    * // @internal - this module is not exported publicly
    *
@@ -1417,20 +1512,20 @@ 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"
+   * import { Param } from "effect/unstable/cli"
    *
    * // @internal - this module is not exported publicly
    *
@@ -1447,8 +1542,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 +1568,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 +1620,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 +1659,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,9 +1680,10 @@ 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"
+ * import { Param } from "effect/unstable/cli"
  *
  * // @internal - this module is not exported publicly
  *
@@ -1603,12 +1699,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,9 +1734,10 @@ 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"
+ * import { Param } from "effect/unstable/cli"
  *
  * // @internal - this module is not exported publicly
  *
@@ -1662,8 +1759,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,9 +1769,10 @@ 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"
+   * import { Param } from "effect/unstable/cli"
    *
    * // @internal - this module is not exported publicly
    *
@@ -1696,8 +1794,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,9 +1804,10 @@ 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"
+   * import { Param } from "effect/unstable/cli"
    *
    * // @internal - this module is not exported publicly
    *
@@ -1730,8 +1829,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,9 +1850,10 @@ 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"
+ * import { Param } from "effect/unstable/cli"
  *
  * // @internal - this module is not exported publicly
  *
@@ -1766,8 +1866,8 @@ export const between: {
  * // Result: ["warning1", "warning2"]
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const atMost: {
   /**
@@ -1776,9 +1876,10 @@ 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"
+   * import { Param } from "effect/unstable/cli"
    *
    * // @internal - this module is not exported publicly
    *
@@ -1791,8 +1892,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,9 +1902,10 @@ 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"
+   * import { Param } from "effect/unstable/cli"
    *
    * // @internal - this module is not exported publicly
    *
@@ -1816,8 +1918,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,9 +1935,10 @@ 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"
+ * import { Param } from "effect/unstable/cli"
  *
  * // @internal - this module is not exported publicly
  *
@@ -1849,8 +1952,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,9 +1962,10 @@ 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"
+   * import { Param } from "effect/unstable/cli"
    *
    * // @internal - this module is not exported publicly
    *
@@ -1875,8 +1979,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,9 +1989,10 @@ 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"
+   * import { Param } from "effect/unstable/cli"
    *
    * // @internal - this module is not exported publicly
    *
@@ -1901,8 +2006,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,10 +2023,11 @@ 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"
+ * import { Param } from "effect/unstable/cli"
  * // @internal - this module is not exported publicly
  *
  * const positiveInt = Param.integer(Param.flagKind, "count").pipe(
@@ -1932,8 +2038,8 @@ export const atLeast: {
  * )
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const filterMap: {
   /**
@@ -1942,10 +2048,11 @@ 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"
+   * import { Param } from "effect/unstable/cli"
    * // @internal - this module is not exported publicly
    *
    * const positiveInt = Param.integer(Param.flagKind, "count").pipe(
@@ -1956,8 +2063,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,10 +2073,11 @@ 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"
+   * import { Param } from "effect/unstable/cli"
    * // @internal - this module is not exported publicly
    *
    * const positiveInt = Param.integer(Param.flagKind, "count").pipe(
@@ -1980,8 +2088,8 @@ export const filterMap: {
    * )
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <Kind extends ParamKind, A, B>(
     self: Param<Kind, A>,
@@ -2013,9 +2121,10 @@ 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"
+ * import { Param } from "effect/unstable/cli"
  *
  * // @internal - this module is not exported publicly
  *
@@ -2027,16 +2136,17 @@ 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"
+   * import { Param } from "effect/unstable/cli"
    *
    * // @internal - this module is not exported publicly
    *
@@ -2048,16 +2158,17 @@ 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"
+   * import { Param } from "effect/unstable/cli"
    *
    * // @internal - this module is not exported publicly
    *
@@ -2069,8 +2180,8 @@ export const filter: {
    * )
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <Kind extends ParamKind, A>(
     self: Param<Kind, A>,
@@ -2089,9 +2200,10 @@ 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"
+ * import { Param } from "effect/unstable/cli"
  *
  * // @internal - this module is not exported publicly
  *
@@ -2104,8 +2216,8 @@ export const filter: {
  * )
  * ```
  *
- * @since 4.0.0
  * @category metadata
+ * @since 4.0.0
  */
 export const withMetavar: {
   /**
@@ -2114,9 +2226,10 @@ 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"
+   * import { Param } from "effect/unstable/cli"
    *
    * // @internal - this module is not exported publicly
    *
@@ -2129,8 +2242,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,9 +2252,10 @@ 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"
+   * import { Param } from "effect/unstable/cli"
    *
    * // @internal - this module is not exported publicly
    *
@@ -2154,8 +2268,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,10 +2285,11 @@ 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"
+ * import { Param } from "effect/unstable/cli"
  * // @internal - this module is not exported publicly
  *
  * const isEmail = Schema.isPattern(/^[^\s@]+@[^\s@]+\.[^\s@]+$/)
@@ -2188,17 +2303,18 @@ 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"
+   * import { Param } from "effect/unstable/cli"
    * // @internal - this module is not exported publicly
    *
    * const isEmail = Schema.isPattern(/^[^\s@]+@[^\s@]+\.[^\s@]+$/)
@@ -2212,17 +2328,18 @@ 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"
+   * import { Param } from "effect/unstable/cli"
    * // @internal - this module is not exported publicly
    *
    * const isEmail = Schema.isPattern(/^[^\s@]+@[^\s@]+\.[^\s@]+$/)
@@ -2236,8 +2353,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,9 +2377,10 @@ 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"
+ * import { Param } from "effect/unstable/cli"
  *
  * // @internal - this module is not exported publicly
  *
@@ -2271,16 +2389,17 @@ 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"
+   * import { Param } from "effect/unstable/cli"
    *
    * // @internal - this module is not exported publicly
    *
@@ -2289,16 +2408,17 @@ 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"
+   * import { Param } from "effect/unstable/cli"
    *
    * // @internal - this module is not exported publicly
    *
@@ -2307,8 +2427,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,11 +2441,16 @@ 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"
+ * import { Param } from "effect/unstable/cli"
  *
  * // @internal - this module is not exported publicly
  *
@@ -2335,16 +2460,21 @@ 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"
+   * import { Param } from "effect/unstable/cli"
    *
    * // @internal - this module is not exported publicly
    *
@@ -2354,16 +2484,21 @@ 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"
+   * import { Param } from "effect/unstable/cli"
    *
    * // @internal - this module is not exported publicly
    *
@@ -2373,8 +2508,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>(