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

package/src/unstable/cli/Argument.ts

@@ -1,4 +1,26 @@
 /**
+ * The `Argument` module defines typed positional command-line arguments for
+ * Effect CLI applications. Arguments consume ordered values after a command name
+ * and its flags, then parse them into the types your command handler expects.
+ *
+ * Use this module for required inputs such as file paths, directories, numbers,
+ * dates, choices, secrets, and structured configuration files. Arguments can be
+ * made optional, variadic, validated with Schema, transformed with pure or
+ * effectful functions, and supplied from defaults, config, or prompts when
+ * missing.
+ *
+ * **Gotchas**
+ *
+ * - Positional arguments are order-sensitive; compose them in the same order the
+ *   user should type them.
+ * - `variadic` arguments can consume more than one value, so place them where
+ *   the remaining positional input belongs.
+ * - Use {@link withDescription} and {@link withMetavar} to keep generated help
+ *   text clear, especially when the parser name differs from the value users
+ *   should provide.
+ * - Boolean positional arguments are intentionally not provided. Prefer boolean
+ *   flags, or use {@link choice} for explicit `"true"` / `"false"` values.
+ *
  * @since 4.0.0
  */
 import type * as Config from "../../Config.ts"
@@ -24,8 +46,8 @@ import type * as Primitive from "./Primitive.ts"
  * no flag name to negate (e.g., `--no-verbose`). Use Flag.boolean instead,
  * or use Argument.choice with explicit "true"/"false" strings if needed.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface Argument<A> extends Param.Param<typeof Param.argumentKind, A> {}
 
@@ -36,37 +58,40 @@ export interface Argument<A> extends Param.Param<typeof Param.argumentKind, A> {
 /**
  * Creates a positional string argument.
  *
- * @example
+ * **Example** (Creating a string argument)
+ *
  * ```ts
  * import { Argument } from "effect/unstable/cli"
  *
  * const filename = Argument.string("filename")
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const string = (name: string): Argument<string> => Param.string(Param.argumentKind, name)
 
 /**
  * Creates a positional integer argument.
  *
- * @example
+ * **Example** (Creating an integer argument)
+ *
  * ```ts
  * import { Argument } from "effect/unstable/cli"
  *
  * const count = Argument.integer("count")
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const integer = (name: string): Argument<number> => Param.integer(Param.argumentKind, name)
 
 /**
  * Creates a positional file path argument.
  *
- * @example
+ * **Example** (Creating file path arguments)
+ *
  * ```ts
  * import { Argument } from "effect/unstable/cli"
  *
@@ -74,8 +99,8 @@ export const integer = (name: string): Argument<number> => Param.integer(Param.a
  * const outputFile = Argument.file("output", { mustExist: false }) // Must not exist
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const file = (name: string, options?: {
   readonly mustExist?: boolean | undefined
@@ -84,15 +109,16 @@ export const file = (name: string, options?: {
 /**
  * Creates a positional directory path argument.
  *
- * @example
+ * **Example** (Creating a directory path argument)
+ *
  * ```ts
  * import { Argument } from "effect/unstable/cli"
  *
  * const workspace = Argument.directory("workspace", { mustExist: true }) // Must exist
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const directory = (name: string, options?: {
   readonly mustExist?: boolean | undefined
@@ -101,45 +127,48 @@ export const directory = (name: string, options?: {
 /**
  * Creates a positional float argument.
  *
- * @example
+ * **Example** (Creating a float argument)
+ *
  * ```ts
  * import { Argument } from "effect/unstable/cli"
  *
  * const ratio = Argument.float("ratio")
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const float = (name: string): Argument<number> => Param.float(Param.argumentKind, name)
 
 /**
  * Creates a positional date argument.
  *
- * @example
+ * **Example** (Creating a date argument)
+ *
  * ```ts
  * import { Argument } from "effect/unstable/cli"
  *
  * const startDate = Argument.date("start-date")
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const date = (name: string): Argument<Date> => Param.date(Param.argumentKind, name)
 
 /**
  * Creates a positional choice argument.
  *
- * @example
+ * **Example** (Creating a choice argument)
+ *
  * ```ts
  * import { Argument } from "effect/unstable/cli"
  *
  * const environment = Argument.choice("environment", ["dev", "staging", "prod"])
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const choice = <const Choices extends ReadonlyArray<string>>(
   name: string,
@@ -149,15 +178,16 @@ export const choice = <const Choices extends ReadonlyArray<string>>(
 /**
  * Creates a positional path argument.
  *
- * @example
+ * **Example** (Creating a path argument)
+ *
  * ```ts
  * import { Argument } from "effect/unstable/cli"
  *
  * const configPath = Argument.path("config")
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const path = (name: string, options?: {
   pathType?: "file" | "directory" | "either"
@@ -167,45 +197,52 @@ export const path = (name: string, options?: {
 /**
  * Creates a positional redacted argument that obscures its value.
  *
- * @example
+ * **Example** (Creating a redacted argument)
+ *
  * ```ts
  * import { Argument } from "effect/unstable/cli"
  *
  * const secret = Argument.redacted("secret")
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const redacted = (name: string): Argument<Redacted.Redacted<string>> => Param.redacted(Param.argumentKind, name)
 
 /**
  * Creates a positional argument that reads file content as a string.
  *
- * @example
+ * **Example** (Reading file text)
+ *
  * ```ts
  * import { Argument } from "effect/unstable/cli"
  *
  * const config = Argument.fileText("config-file")
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const fileText = (name: string): Argument<string> => Param.fileText(Param.argumentKind, name)
 
 /**
- * Creates a positional argument that reads and validates file content using a schema.
+ * Creates a positional argument that reads a file and parses its content.
+ *
+ * The parser is chosen from the explicit `format` option or, when omitted, the
+ * file extension. The parsed value is `unknown`; use `fileSchema` when the
+ * parsed content should also be decoded with a Schema.
+ *
+ * **Example** (Parsing file content)
  *
- * @example
  * ```ts
  * import { Argument } from "effect/unstable/cli"
  *
  * const config = Argument.fileParse("config", { format: "json" })
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const fileParse = (
   name: string,
@@ -215,7 +252,8 @@ export const fileParse = (
 /**
  * Creates a positional argument that reads and validates file content using a schema.
  *
- * @example
+ * **Example** (Validating file content with a schema)
+ *
  * ```ts
  * import { Schema } from "effect"
  * import { Argument } from "effect/unstable/cli"
@@ -228,8 +266,8 @@ export const fileParse = (
  * const config = Argument.fileSchema("config", ConfigSchema)
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const fileSchema = <A>(
   name: string,
@@ -240,7 +278,8 @@ export const fileSchema = <A>(
 /**
  * Creates an empty sentinel argument that always fails to parse.
  *
- * @example
+ * **Example** (Creating a sentinel argument)
+ *
  * ```ts
  * import { Argument } from "effect/unstable/cli"
  *
@@ -248,8 +287,8 @@ export const fileSchema = <A>(
  * const noArg = Argument.none
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const none: Argument<never> = Param.none(Param.argumentKind)
 
@@ -260,22 +299,24 @@ export const none: Argument<never> = Param.none(Param.argumentKind)
 /**
  * Makes a positional argument optional.
  *
- * @example
+ * **Example** (Making an argument optional)
+ *
  * ```ts
  * import { Argument } from "effect/unstable/cli"
  *
  * const optionalVersion = Argument.string("version").pipe(Argument.optional)
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const optional = <A>(arg: Argument<A>): Argument<Option.Option<A>> => Param.optional(arg)
 
 /**
  * Adds a description to a positional argument.
  *
- * @example
+ * **Example** (Adding an argument description)
+ *
  * ```ts
  * import { Argument } from "effect/unstable/cli"
  *
@@ -284,14 +325,15 @@ export const optional = <A>(arg: Argument<A>): Argument<Option.Option<A>> => Par
  * )
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const withDescription: {
   /**
    * Adds a description to a positional argument.
    *
-   * @example
+   * **Example** (Adding an argument description)
+   *
    * ```ts
    * import { Argument } from "effect/unstable/cli"
    *
@@ -300,14 +342,15 @@ export const withDescription: {
    * )
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <A>(description: string): (self: Argument<A>) => Argument<A>
   /**
    * Adds a description to a positional argument.
    *
-   * @example
+   * **Example** (Adding an argument description)
+   *
    * ```ts
    * import { Argument } from "effect/unstable/cli"
    *
@@ -316,8 +359,8 @@ export const withDescription: {
    * )
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <A>(self: Argument<A>, description: string): Argument<A>
 } = dual(2, <A>(self: Argument<A>, description: string) => Param.withDescription(self, description))
@@ -325,43 +368,46 @@ export const withDescription: {
 /**
  * Provides a default value for a positional argument.
  *
- * @example
+ * **Example** (Providing a default value)
+ *
  * ```ts
  * import { Argument } from "effect/unstable/cli"
  *
  * const port = Argument.integer("port").pipe(Argument.withDefault(8080))
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const withDefault: {
   /**
    * Provides a default value for a positional argument.
    *
-   * @example
+   * **Example** (Providing a default value)
+   *
    * ```ts
    * import { Argument } from "effect/unstable/cli"
    *
    * const port = Argument.integer("port").pipe(Argument.withDefault(8080))
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <const B>(defaultValue: B | Effect.Effect<B, CliError.CliError, Param.Environment>): <A>(self: Argument<A>) => Argument<A | B>
   /**
    * Provides a default value for a positional argument.
    *
-   * @example
+   * **Example** (Providing a default value)
+   *
    * ```ts
    * import { Argument } from "effect/unstable/cli"
    *
    * const port = Argument.integer("port").pipe(Argument.withDefault(8080))
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <A, const B>(
    self: Argument<A>,
@@ -372,7 +418,8 @@ export const withDefault: {
 /**
  * Adds a fallback config that is loaded when a required argument is missing.
  *
- * @example
+ * **Example** (Loading a fallback config)
+ *
  * ```ts
  * import { Config } from "effect"
  * import { Argument } from "effect/unstable/cli"
@@ -382,14 +429,15 @@ export const withDefault: {
  * )
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const withFallbackConfig: {
   /**
    * Adds a fallback config that is loaded when a required argument is missing.
    *
-   * @example
+   * **Example** (Loading a fallback config)
+   *
    * ```ts
    * import { Config } from "effect"
    * import { Argument } from "effect/unstable/cli"
@@ -399,14 +447,15 @@ export const withFallbackConfig: {
    * )
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <B>(config: Config.Config<B>): <A>(self: Argument<A>) => Argument<A | B>
   /**
    * Adds a fallback config that is loaded when a required argument is missing.
    *
-   * @example
+   * **Example** (Loading a fallback config)
+   *
    * ```ts
    * import { Config } from "effect"
    * import { Argument } from "effect/unstable/cli"
@@ -416,8 +465,8 @@ export const withFallbackConfig: {
    * )
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <A, B>(self: Argument<A>, config: Config.Config<B>): Argument<A | B>
 } = dual(2, <A, B>(self: Argument<A>, config: Config.Config<B>) => Param.withFallbackConfig(self, config))
@@ -425,7 +474,8 @@ export const withFallbackConfig: {
 /**
  * Adds a fallback prompt that is shown when a required argument is missing.
  *
- * @example
+ * **Example** (Showing a fallback prompt)
+ *
  * ```ts
  * import { Argument, Prompt } from "effect/unstable/cli"
  *
@@ -434,14 +484,15 @@ export const withFallbackConfig: {
  * )
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const withFallbackPrompt: {
   /**
    * Adds a fallback prompt that is shown when a required argument is missing.
    *
-   * @example
+   * **Example** (Showing a fallback prompt)
+   *
    * ```ts
    * import { Argument, Prompt } from "effect/unstable/cli"
    *
@@ -450,14 +501,15 @@ export const withFallbackPrompt: {
    * )
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <B>(prompt: Param.FallbackPrompt<B>): <A>(self: Argument<A>) => Argument<A | B>
   /**
    * Adds a fallback prompt that is shown when a required argument is missing.
    *
-   * @example
+   * **Example** (Showing a fallback prompt)
+   *
    * ```ts
    * import { Argument, Prompt } from "effect/unstable/cli"
    *
@@ -466,8 +518,8 @@ export const withFallbackPrompt: {
    * )
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <A, B>(self: Argument<A>, prompt: Param.FallbackPrompt<B>): Argument<A | B>
 } = dual(2, <A, B>(self: Argument<A>, prompt: Param.FallbackPrompt<B>) => Param.withFallbackPrompt(self, prompt))
@@ -475,7 +527,8 @@ export const withFallbackPrompt: {
 /**
  * Creates a variadic positional argument that accepts multiple values.
  *
- * @example
+ * **Example** (Accepting multiple values)
+ *
  * ```ts
  * import { Argument } from "effect/unstable/cli"
  *
@@ -493,14 +546,15 @@ export const withFallbackPrompt: {
  * )
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const variadic: {
   /**
    * Creates a variadic positional argument that accepts multiple values.
    *
-   * @example
+   * **Example** (Accepting multiple values)
+   *
    * ```ts
    * import { Argument } from "effect/unstable/cli"
    *
@@ -518,14 +572,15 @@ export const variadic: {
    * )
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   (options?: Param.VariadicParamOptions | undefined): <A>(self: Argument<A>) => Argument<ReadonlyArray<A>>
   /**
    * Creates a variadic positional argument that accepts multiple values.
    *
-   * @example
+   * **Example** (Accepting multiple values)
+   *
    * ```ts
    * import { Argument } from "effect/unstable/cli"
    *
@@ -543,8 +598,8 @@ export const variadic: {
    * )
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <A>(self: Argument<A>, options?: Param.VariadicParamOptions | undefined): Argument<ReadonlyArray<A>>
 } = dual(2, <A>(
@@ -555,7 +610,8 @@ export const variadic: {
 /**
  * Transforms the parsed value of a positional argument.
  *
- * @example
+ * **Example** (Mapping parsed values)
+ *
  * ```ts
  * import { Argument } from "effect/unstable/cli"
  *
@@ -564,14 +620,15 @@ export const variadic: {
  * )
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const map: {
   /**
    * Transforms the parsed value of a positional argument.
    *
-   * @example
+   * **Example** (Mapping parsed values)
+   *
    * ```ts
    * import { Argument } from "effect/unstable/cli"
    *
@@ -580,14 +637,15 @@ export const map: {
    * )
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <A, B>(f: (a: A) => B): (self: Argument<A>) => Argument<B>
   /**
    * Transforms the parsed value of a positional argument.
    *
-   * @example
+   * **Example** (Mapping parsed values)
+   *
    * ```ts
    * import { Argument } from "effect/unstable/cli"
    *
@@ -596,8 +654,8 @@ export const map: {
    * )
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <A, B>(self: Argument<A>, f: (a: A) => B): Argument<B>
 } = dual(2, <A, B>(self: Argument<A>, f: (a: A) => B) => Param.map(self, f))
@@ -605,7 +663,8 @@ export const map: {
 /**
  * Transforms the parsed value of a positional argument using an effectful function.
  *
- * @example
+ * **Example** (Validating values effectfully)
+ *
  * ```ts
  * import { Effect } from "effect"
  * import { Argument, CliError } from "effect/unstable/cli"
@@ -623,14 +682,15 @@ export const map: {
  * )
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const mapEffect: {
   /**
    * Transforms the parsed value of a positional argument using an effectful function.
    *
-   * @example
+   * **Example** (Validating values effectfully)
+   *
    * ```ts
    * import { Effect } from "effect"
    * import { Argument, CliError } from "effect/unstable/cli"
@@ -648,14 +708,15 @@ export const mapEffect: {
    * )
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <A, B>(f: (a: A) => Effect.Effect<B, CliError.CliError, Param.Environment>): (self: Argument<A>) => Argument<B>
   /**
    * Transforms the parsed value of a positional argument using an effectful function.
    *
-   * @example
+   * **Example** (Validating values effectfully)
+   *
    * ```ts
    * import { Effect } from "effect"
    * import { Argument, CliError } from "effect/unstable/cli"
@@ -673,8 +734,8 @@ export const mapEffect: {
    * )
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <A, B>(
    self: Argument<A>,
@@ -688,7 +749,8 @@ export const mapEffect: {
 /**
  * Transforms the parsed value of a positional argument using a function that may throw.
  *
- * @example
+ * **Example** (Mapping values that may throw)
+ *
  * ```ts
  * import { Argument } from "effect/unstable/cli"
  *
@@ -701,14 +763,15 @@ export const mapEffect: {
  * )
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const mapTryCatch: {
   /**
    * Transforms the parsed value of a positional argument using a function that may throw.
    *
-   * @example
+   * **Example** (Mapping values that may throw)
+   *
    * ```ts
    * import { Argument } from "effect/unstable/cli"
    *
@@ -721,14 +784,15 @@ export const mapTryCatch: {
    * )
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <A, B>(f: (a: A) => B, onError: (error: unknown) => string): (self: Argument<A>) => Argument<B>
   /**
    * Transforms the parsed value of a positional argument using a function that may throw.
    *
-   * @example
+   * **Example** (Mapping values that may throw)
+   *
    * ```ts
    * import { Argument } from "effect/unstable/cli"
    *
@@ -741,8 +805,8 @@ export const mapTryCatch: {
    * )
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <A, B>(self: Argument<A>, f: (a: A) => B, onError: (error: unknown) => string): Argument<B>
 } = dual(3, <A, B>(
@@ -754,43 +818,46 @@ export const mapTryCatch: {
 /**
  * Creates a variadic argument that requires at least n values.
  *
- * @example
+ * **Example** (Requiring a minimum number of values)
+ *
  * ```ts
  * import { Argument } from "effect/unstable/cli"
  *
  * const files = Argument.string("files").pipe(Argument.atLeast(1))
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const atLeast: {
   /**
    * Creates a variadic argument that requires at least n values.
    *
-   * @example
+   * **Example** (Requiring a minimum number of values)
+   *
    * ```ts
    * import { Argument } from "effect/unstable/cli"
    *
    * const files = Argument.string("files").pipe(Argument.atLeast(1))
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <A>(min: number): (self: Argument<A>) => Argument<ReadonlyArray<A>>
   /**
    * Creates a variadic argument that requires at least n values.
    *
-   * @example
+   * **Example** (Requiring a minimum number of values)
+   *
    * ```ts
    * import { Argument } from "effect/unstable/cli"
    *
    * const files = Argument.string("files").pipe(Argument.atLeast(1))
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <A>(self: Argument<A>, min: number): Argument<ReadonlyArray<A>>
 } = dual(2, <A>(self: Argument<A>, min: number) => Param.atLeast(self, min))
@@ -798,43 +865,46 @@ export const atLeast: {
 /**
  * Creates a variadic argument that accepts at most n values.
  *
- * @example
+ * **Example** (Limiting the maximum number of values)
+ *
  * ```ts
  * import { Argument } from "effect/unstable/cli"
  *
  * const files = Argument.string("files").pipe(Argument.atMost(5))
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const atMost: {
   /**
    * Creates a variadic argument that accepts at most n values.
    *
-   * @example
+   * **Example** (Limiting the maximum number of values)
+   *
    * ```ts
    * import { Argument } from "effect/unstable/cli"
    *
    * const files = Argument.string("files").pipe(Argument.atMost(5))
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <A>(max: number): (self: Argument<A>) => Argument<ReadonlyArray<A>>
   /**
    * Creates a variadic argument that accepts at most n values.
    *
-   * @example
+   * **Example** (Limiting the maximum number of values)
+   *
    * ```ts
    * import { Argument } from "effect/unstable/cli"
    *
    * const files = Argument.string("files").pipe(Argument.atMost(5))
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <A>(self: Argument<A>, max: number): Argument<ReadonlyArray<A>>
 } = dual(2, <A>(self: Argument<A>, max: number) => Param.atMost(self, max))
@@ -842,43 +912,46 @@ export const atMost: {
 /**
  * Creates a variadic argument that accepts between min and max values.
  *
- * @example
+ * **Example** (Requiring a range of values)
+ *
  * ```ts
  * import { Argument } from "effect/unstable/cli"
  *
  * const files = Argument.string("files").pipe(Argument.between(1, 5))
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const between: {
   /**
    * Creates a variadic argument that accepts between min and max values.
    *
-   * @example
+   * **Example** (Requiring a range of values)
+   *
    * ```ts
    * import { Argument } from "effect/unstable/cli"
    *
    * const files = Argument.string("files").pipe(Argument.between(1, 5))
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <A>(min: number, max: number): (self: Argument<A>) => Argument<ReadonlyArray<A>>
   /**
    * Creates a variadic argument that accepts between min and max values.
    *
-   * @example
+   * **Example** (Requiring a range of values)
+   *
    * ```ts
    * import { Argument } from "effect/unstable/cli"
    *
    * const files = Argument.string("files").pipe(Argument.between(1, 5))
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <A>(self: Argument<A>, min: number, max: number): Argument<ReadonlyArray<A>>
 } = dual(3, <A>(self: Argument<A>, min: number, max: number) => Param.between(self, min, max))
@@ -886,7 +959,8 @@ export const between: {
 /**
  * Validates parsed values against a Schema.
  *
- * @example
+ * **Example** (Validating parsed values with a schema)
+ *
  * ```ts
  * import { Schema } from "effect"
  * import { Argument } from "effect/unstable/cli"
@@ -896,14 +970,15 @@ export const between: {
  * )
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const withSchema: {
   /**
    * Validates parsed values against a Schema.
    *
-   * @example
+   * **Example** (Validating parsed values with a schema)
+   *
    * ```ts
    * import { Schema } from "effect"
    * import { Argument } from "effect/unstable/cli"
@@ -913,14 +988,15 @@ export const withSchema: {
    * )
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <A, B>(schema: Schema.Codec<B, A>): (self: Argument<A>) => Argument<B>
   /**
    * Validates parsed values against a Schema.
    *
-   * @example
+   * **Example** (Validating parsed values with a schema)
+   *
    * ```ts
    * import { Schema } from "effect"
    * import { Argument } from "effect/unstable/cli"
@@ -930,8 +1006,8 @@ export const withSchema: {
    * )
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <A, B>(self: Argument<A>, schema: Schema.Codec<B, A>): Argument<B>
 } = dual(2, <A, B>(self: Argument<A>, schema: Schema.Codec<B, A>) => Param.withSchema(self, schema))
@@ -939,7 +1015,8 @@ export const withSchema: {
 /**
  * Creates a positional choice argument with custom value mapping.
  *
- * @example
+ * **Example** (Mapping choices to values)
+ *
  * ```ts
  * import { Argument } from "effect/unstable/cli"
  *
@@ -951,8 +1028,8 @@ export const withSchema: {
  * ])
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const choiceWithValue = <const Choices extends ReadonlyArray<readonly [string, any]>>(
   name: string,
@@ -969,7 +1046,8 @@ export const choiceWithValue = <const Choices extends ReadonlyArray<readonly [st
  * The metavar is displayed in usage text to indicate what value the user should provide.
  * For example, `<FILE>` shows `FILE` as the metavar.
  *
- * @example
+ * **Example** (Setting a metavar)
+ *
  * ```ts
  * import { Argument } from "effect/unstable/cli"
  *
@@ -978,8 +1056,8 @@ export const choiceWithValue = <const Choices extends ReadonlyArray<readonly [st
  * )
  * ```
  *
- * @since 4.0.0
  * @category metadata
+ * @since 4.0.0
  */
 export const withMetavar: {
   // -------------------------------------------------------------------------------------
@@ -992,7 +1070,8 @@ export const withMetavar: {
    * The metavar is displayed in usage text to indicate what value the user should provide.
    * For example, `<FILE>` shows `FILE` as the metavar.
    *
-   * @example
+   * **Example** (Setting a metavar)
+   *
    * ```ts
    * import { Argument } from "effect/unstable/cli"
    *
@@ -1001,8 +1080,8 @@ export const withMetavar: {
    * )
    * ```
    *
-   * @since 4.0.0
    * @category metadata
+   * @since 4.0.0
    */
   <A>(metavar: string): (self: Argument<A>) => Argument<A>
   // -------------------------------------------------------------------------------------
@@ -1015,7 +1094,8 @@ export const withMetavar: {
    * The metavar is displayed in usage text to indicate what value the user should provide.
    * For example, `<FILE>` shows `FILE` as the metavar.
    *
-   * @example
+   * **Example** (Setting a metavar)
+   *
    * ```ts
    * import { Argument } from "effect/unstable/cli"
    *
@@ -1024,8 +1104,8 @@ export const withMetavar: {
    * )
    * ```
    *
-   * @since 4.0.0
    * @category metadata
+   * @since 4.0.0
    */
   <A>(self: Argument<A>, metavar: string): Argument<A>
 } = dual(2, <A>(self: Argument<A>, metavar: string) => Param.withMetavar(self, metavar))
@@ -1033,7 +1113,8 @@ export const withMetavar: {
 /**
  * Filters parsed values, failing with a custom error message if the predicate returns false.
  *
- * @example
+ * **Example** (Filtering parsed values)
+ *
  * ```ts
  * import { Argument } from "effect/unstable/cli"
  *
@@ -1045,14 +1126,15 @@ export const withMetavar: {
  * )
  * ```
  *
- * @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 { Argument } from "effect/unstable/cli"
    *
@@ -1064,14 +1146,15 @@ export const filter: {
    * )
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <A>(predicate: (a: A) => boolean, onFalse: (a: A) => string): (self: Argument<A>) => Argument<A>
   /**
    * Filters parsed values, failing with a custom error message if the predicate returns false.
    *
-   * @example
+   * **Example** (Filtering parsed values)
+   *
    * ```ts
    * import { Argument } from "effect/unstable/cli"
    *
@@ -1083,8 +1166,8 @@ export const filter: {
    * )
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <A>(self: Argument<A>, predicate: (a: A) => boolean, onFalse: (a: A) => string): Argument<A>
 } = dual(3, <A>(
@@ -1097,7 +1180,8 @@ export const filter: {
  * Filters and transforms parsed values, failing with a custom error message
  * if the filter function returns None.
  *
- * @example
+ * **Example** (Filtering and mapping parsed values)
+ *
  * ```ts
  * import { Option } from "effect"
  * import { Argument } from "effect/unstable/cli"
@@ -1110,15 +1194,16 @@ export const filter: {
  * )
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const filterMap: {
   /**
    * Filters and transforms parsed values, failing with a custom error message
    * if the filter function returns None.
    *
-   * @example
+   * **Example** (Filtering and mapping parsed values)
+   *
    * ```ts
    * import { Option } from "effect"
    * import { Argument } from "effect/unstable/cli"
@@ -1131,15 +1216,16 @@ export const filterMap: {
    * )
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <A, B>(f: (a: A) => Option.Option<B>, onNone: (a: A) => string): (self: Argument<A>) => Argument<B>
   /**
    * Filters and transforms parsed values, failing with a custom error message
    * if the filter function returns None.
    *
-   * @example
+   * **Example** (Filtering and mapping parsed values)
+   *
    * ```ts
    * import { Option } from "effect"
    * import { Argument } from "effect/unstable/cli"
@@ -1152,8 +1238,8 @@ export const filterMap: {
    * )
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <A, B>(self: Argument<A>, f: (a: A) => Option.Option<B>, onNone: (a: A) => string): Argument<B>
 } = dual(3, <A, B>(
@@ -1165,7 +1251,8 @@ export const filterMap: {
 /**
  * Provides a fallback argument to use if this argument fails to parse.
  *
- * @example
+ * **Example** (Providing a fallback argument)
+ *
  * ```ts
  * import { Argument } from "effect/unstable/cli"
  *
@@ -1174,14 +1261,15 @@ export const filterMap: {
  * )
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const orElse: {
   /**
    * Provides a fallback argument to use if this argument fails to parse.
    *
-   * @example
+   * **Example** (Providing a fallback argument)
+   *
    * ```ts
    * import { Argument } from "effect/unstable/cli"
    *
@@ -1190,14 +1278,15 @@ export const orElse: {
    * )
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <B>(that: LazyArg<Argument<B>>): <A>(self: Argument<A>) => Argument<A | B>
   /**
    * Provides a fallback argument to use if this argument fails to parse.
    *
-   * @example
+   * **Example** (Providing a fallback argument)
+   *
    * ```ts
    * import { Argument } from "effect/unstable/cli"
    *
@@ -1206,8 +1295,8 @@ export const orElse: {
    * )
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <A, B>(self: Argument<A>, that: LazyArg<Argument<B>>): Argument<A | B>
 } = dual(2, <A, B>(self: Argument<A>, that: LazyArg<Argument<B>>) => Param.orElse(self, that))
@@ -1215,7 +1304,8 @@ export const orElse: {
 /**
  * Provides a fallback argument, wrapping results in Result to distinguish which succeeded.
  *
- * @example
+ * **Example** (Returning which fallback succeeded)
+ *
  * ```ts
  * import { Argument } from "effect/unstable/cli"
  *
@@ -1225,14 +1315,15 @@ export const orElse: {
  * // Returns Result<string, string>
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const orElseResult: {
   /**
    * Provides a fallback argument, wrapping results in Result to distinguish which succeeded.
    *
-   * @example
+   * **Example** (Returning which fallback succeeded)
+   *
    * ```ts
    * import { Argument } from "effect/unstable/cli"
    *
@@ -1242,14 +1333,15 @@ export const orElseResult: {
    * // Returns Result<string, string>
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <B>(that: LazyArg<Argument<B>>): <A>(self: Argument<A>) => Argument<Result.Result<A, B>>
   /**
    * Provides a fallback argument, wrapping results in Result to distinguish which succeeded.
    *
-   * @example
+   * **Example** (Returning which fallback succeeded)
+   *
    * ```ts
    * import { Argument } from "effect/unstable/cli"
    *
@@ -1259,8 +1351,8 @@ export const orElseResult: {
    * // Returns Result<string, string>
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <A, B>(self: Argument<A>, that: LazyArg<Argument<B>>): Argument<Result.Result<A, B>>
 } = dual(2, <A, B>(self: Argument<A>, that: LazyArg<Argument<B>>) => Param.orElseResult(self, that))