effect 4.0.0-beta.65 → 4.0.0-beta.67

package/src/unstable/cli/Flag.ts

@@ -1,4 +1,23 @@
 /**
+ * The `Flag` module provides typed command-line options for Effect CLI
+ * applications. A `Flag<A>` describes how to read one named option from the
+ * parsed command line, validate it, and produce a value of type `A`.
+ *
+ * Use flags for inputs that are naturally named options, such as ports,
+ * verbosity switches, configuration files, output directories, enum-like
+ * choices, secrets, and repeated values. Constructors such as {@link string},
+ * {@link boolean}, {@link integer}, {@link file}, and {@link fileSchema}
+ * define the accepted input shape, while combinators add aliases, defaults,
+ * optionality, fallback config or prompts, validation, and typed mapping.
+ *
+ * Flag names are rendered as long options, for example `Flag.integer("port")`
+ * parses `--port 8080`. Boolean flags also support the disabled form shown by
+ * this module's boolean documentation, and repeated flags are modeled with the
+ * repetition combinators instead of by manually inspecting raw arguments. Help
+ * text is generated from flag metadata, so prefer {@link withDescription} and
+ * {@link withMetavar} when a flag's value, format, or file-system expectation
+ * would otherwise be ambiguous.
+ *
  * @since 4.0.0
  */
 import type * as Config from "../../Config.ts"
@@ -19,8 +38,8 @@ import type * as Primitive from "./Primitive.ts"
 /**
  * Represents a command-line flag.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface Flag<A> extends Param.Param<typeof Param.flagKind, A> {}
 
@@ -31,7 +50,8 @@ export interface Flag<A> extends Param.Param<typeof Param.flagKind, A> {}
 /**
  * Creates a string flag that accepts text input.
  *
- * @example
+ * **Example** (Creating string flags)
+ *
  * ```ts
  * import { Flag } from "effect/unstable/cli"
  *
@@ -39,15 +59,16 @@ export interface Flag<A> extends Param.Param<typeof Param.flagKind, A> {}
  * // Usage: --name "John Doe"
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const string = (name: string): Flag<string> => Param.string(Param.flagKind, name)
 
 /**
  * Creates a boolean flag that can be enabled or disabled.
  *
- * @example
+ * **Example** (Creating boolean flags)
+ *
  * ```ts
  * import { Flag } from "effect/unstable/cli"
  *
@@ -55,15 +76,16 @@ export const string = (name: string): Flag<string> => Param.string(Param.flagKin
  * // Usage: --verbose (true) or --no-verbose (false)
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const boolean = (name: string): Flag<boolean> => Param.boolean(Param.flagKind, name)
 
 /**
  * Creates an integer flag that accepts whole number input.
  *
- * @example
+ * **Example** (Creating integer flags)
+ *
  * ```ts
  * import { Flag } from "effect/unstable/cli"
  *
@@ -71,15 +93,16 @@ export const boolean = (name: string): Flag<boolean> => Param.boolean(Param.flag
  * // Usage: --port 8080
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const integer = (name: string): Flag<number> => Param.integer(Param.flagKind, name)
 
 /**
  * Creates a float flag that accepts decimal number input.
  *
- * @example
+ * **Example** (Creating float flags)
+ *
  * ```ts
  * import { Flag } from "effect/unstable/cli"
  *
@@ -87,15 +110,16 @@ export const integer = (name: string): Flag<number> => Param.integer(Param.flagK
  * // Usage: --rate 3.14
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const float = (name: string): Flag<number> => Param.float(Param.flagKind, name)
 
 /**
  * Creates a date flag that accepts date input in ISO format.
  *
- * @example
+ * **Example** (Creating date flags)
+ *
  * ```ts
  * import { Flag } from "effect/unstable/cli"
  *
@@ -103,8 +127,8 @@ export const float = (name: string): Flag<number> => Param.float(Param.flagKind,
  * // Usage: --start-date 2023-12-25
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const date = (name: string): Flag<Date> => Param.date(Param.flagKind, name)
 
@@ -112,7 +136,8 @@ export const date = (name: string): Flag<Date> => Param.date(Param.flagKind, nam
  * Constructs option parameters that represent a choice between several inputs.
  * Each tuple maps a string flag value to an associated typed value.
  *
- * @example
+ * **Example** (Creating flag choices with values)
+ *
  * ```ts
  * import { Flag } from "effect/unstable/cli"
  *
@@ -127,8 +152,8 @@ export const date = (name: string): Flag<Date> => Param.date(Param.flagKind, nam
  * ])
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const choiceWithValue = <const Choice extends ReadonlyArray<readonly [string, any]>>(
   name: string,
@@ -138,8 +163,8 @@ export const choiceWithValue = <const Choice extends ReadonlyArray<readonly [str
 /**
  * Simpler variant of `choiceWithValue` which maps each string to itself.
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const choice = <const Choices extends ReadonlyArray<string>>(
   name: string,
@@ -149,7 +174,8 @@ export const choice = <const Choices extends ReadonlyArray<string>>(
 /**
  * Creates a path flag that accepts file system path input with validation options.
  *
- * @example
+ * **Example** (Creating path flags)
+ *
  * ```ts
  * import { Flag } from "effect/unstable/cli"
  *
@@ -169,8 +195,8 @@ export const choice = <const Choices extends ReadonlyArray<string>>(
  * })
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const path = (name: string, options?: {
   readonly pathType?: "file" | "directory" | "either" | undefined
@@ -181,7 +207,8 @@ export const path = (name: string, options?: {
 /**
  * Creates a file path flag that accepts file paths with optional existence validation.
  *
- * @example
+ * **Example** (Creating file flags)
+ *
  * ```ts
  * import { Flag } from "effect/unstable/cli"
  *
@@ -194,8 +221,8 @@ export const path = (name: string, options?: {
  * // Usage: --config ./config.yaml (file must exist)
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const file = (name: string, options?: {
   readonly mustExist?: boolean | undefined
@@ -204,7 +231,8 @@ export const file = (name: string, options?: {
 /**
  * Creates a directory path flag that accepts directory paths with optional existence validation.
  *
- * @example
+ * **Example** (Creating directory flags)
+ *
  * ```ts
  * import { Flag } from "effect/unstable/cli"
  *
@@ -217,17 +245,22 @@ export const file = (name: string, options?: {
  * // Usage: --source ./src (directory must exist)
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const directory = (name: string, options?: {
   readonly mustExist?: boolean | undefined
 }): Flag<string> => Param.directory(Param.flagKind, name, options)
 
 /**
- * Creates a redacted flag that securely handles sensitive string input.
+ * Creates a string flag whose parsed value is wrapped in `Redacted.Redacted`
+ * so stringification and logging redact the value.
+ *
+ * Values supplied on the command line may still be visible to the operating
+ * system or shell history.
+ *
+ * **Example** (Creating redacted flags)
  *
- * @example
  * ```ts
  * import { Effect, Redacted } from "effect"
  * import { Flag } from "effect/unstable/cli"
@@ -244,15 +277,16 @@ export const directory = (name: string, options?: {
  * })
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const redacted = (name: string): Flag<Redacted.Redacted<string>> => Param.redacted(Param.flagKind, name)
 
 /**
  * Creates a flag that reads and returns file content as a string.
  *
- * @example
+ * **Example** (Reading file text)
+ *
  * ```ts
  * import { Flag } from "effect/unstable/cli"
  *
@@ -260,8 +294,8 @@ export const redacted = (name: string): Flag<Redacted.Redacted<string>> => Param
  * // --config-file ./app.json will read the file content
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const fileText = (name: string): Flag<string> => Param.fileText(Param.flagKind, name)
 
@@ -271,7 +305,8 @@ export const fileText = (name: string): Flag<string> => Param.fileText(Param.fla
  * 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 { Flag } from "effect/unstable/cli"
  *
@@ -283,8 +318,8 @@ export const fileText = (name: string): Flag<string> => Param.fileText(Param.fla
  * const jsonConfig = Flag.fileParse("json-config", { format: "json" })
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const fileParse = (
   name: string,
@@ -295,7 +330,8 @@ export const fileParse = (
  * Creates a flag that reads and validates file content using the specified
  * schema.
  *
- * @example
+ * **Example** (Validating file contents)
+ *
  * ```ts
  * import { Schema } from "effect"
  * import { Flag } from "effect/unstable/cli"
@@ -308,8 +344,8 @@ export const fileParse = (
  * const config = Flag.fileSchema("config", ConfigSchema, { format: "json" })
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const fileSchema = <A>(
   name: string,
@@ -324,7 +360,8 @@ export const fileSchema = <A>(
  * Note: Requires at least one key=value pair. Multiple pairs are merged
  * into a single record.
  *
- * @example
+ * **Example** (Parsing key-value pairs)
+ *
  * ```ts
  * import { Flag } from "effect/unstable/cli"
  *
@@ -332,8 +369,8 @@ export const fileSchema = <A>(
  * // --env FOO=bar --env BAZ=qux will parse to { FOO: "bar", BAZ: "qux" }
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const keyValuePair = (name: string): Flag<Record<string, string>> => Param.keyValuePair(Param.flagKind, name)
 
@@ -341,16 +378,20 @@ export const keyValuePair = (name: string): Flag<Record<string, string>> => Para
  * Creates an empty sentinel flag that always fails to parse.
  * This is useful for creating placeholder flags or for combinators.
  *
- * @example
+ * **Example** (Creating sentinel flags)
+ *
  * ```ts
  * import { Flag } from "effect/unstable/cli"
  *
- * // Used as a placeholder in flag combinators
- * const conditionalFlag = true ? Flag.string("value") : Flag.none
+ * const makeValueFlag = (includeValue: boolean) =>
+ *   includeValue ? Flag.string("value") : Flag.none
+ *
+ * console.log(makeValueFlag(true) === Flag.none) // false
+ * console.log(makeValueFlag(false) === Flag.none) // true
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const none: Flag<never> = Param.none(Param.flagKind)
 
@@ -361,7 +402,8 @@ export const none: Flag<never> = Param.none(Param.flagKind)
 /**
  * Adds an alias to a flag, allowing it to be referenced by multiple names.
  *
- * @example
+ * **Example** (Adding flag aliases)
+ *
  * ```ts
  * import { Flag } from "effect/unstable/cli"
  *
@@ -377,8 +419,8 @@ export const none: Flag<never> = Param.none(Param.flagKind)
  * )
  * ```
  *
- * @since 4.0.0
  * @category aliasing
+ * @since 4.0.0
  */
 export const withAlias: {
   // -------------------------------------------------------------------------------------
@@ -388,7 +430,8 @@ export const withAlias: {
   /**
    * Adds an alias to a flag, allowing it to be referenced by multiple names.
    *
-   * @example
+   * **Example** (Adding flag aliases)
+   *
    * ```ts
    * import { Flag } from "effect/unstable/cli"
    *
@@ -404,8 +447,8 @@ export const withAlias: {
    * )
    * ```
    *
-   * @since 4.0.0
    * @category aliasing
+   * @since 4.0.0
    */
   <A>(alias: string): (self: Flag<A>) => Flag<A>
   // -------------------------------------------------------------------------------------
@@ -415,7 +458,8 @@ export const withAlias: {
   /**
    * Adds an alias to a flag, allowing it to be referenced by multiple names.
    *
-   * @example
+   * **Example** (Adding flag aliases)
+   *
    * ```ts
    * import { Flag } from "effect/unstable/cli"
    *
@@ -431,8 +475,8 @@ export const withAlias: {
    * )
    * ```
    *
-   * @since 4.0.0
    * @category aliasing
+   * @since 4.0.0
    */
   <A>(self: Flag<A>, alias: string): Flag<A>
 } = dual(2, <A>(self: Flag<A>, alias: string): Flag<A> => Param.withAlias(self, alias))
@@ -440,7 +484,8 @@ export const withAlias: {
 /**
  * Adds a description to a flag for help documentation.
  *
- * @example
+ * **Example** (Adding help descriptions)
+ *
  * ```ts
  * import { Flag } from "effect/unstable/cli"
  *
@@ -453,14 +498,15 @@ export const withAlias: {
  * )
  * ```
  *
- * @since 4.0.0
  * @category help documentation
+ * @since 4.0.0
  */
 export const withDescription: {
   /**
    * Adds a description to a flag for help documentation.
    *
-   * @example
+   * **Example** (Adding help descriptions)
+   *
    * ```ts
    * import { Flag } from "effect/unstable/cli"
    *
@@ -473,14 +519,15 @@ export const withDescription: {
    * )
    * ```
    *
-   * @since 4.0.0
    * @category help documentation
+   * @since 4.0.0
    */
   <A>(description: string): (self: Flag<A>) => Flag<A>
   /**
    * Adds a description to a flag for help documentation.
    *
-   * @example
+   * **Example** (Adding help descriptions)
+   *
    * ```ts
    * import { Flag } from "effect/unstable/cli"
    *
@@ -493,8 +540,8 @@ export const withDescription: {
    * )
    * ```
    *
-   * @since 4.0.0
    * @category help documentation
+   * @since 4.0.0
    */
   <A>(self: Flag<A>, description: string): Flag<A>
 } = dual(2, <A>(self: Flag<A>, description: string) => Param.withDescription(self, description))
@@ -509,7 +556,8 @@ export const withDescription: {
  * 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 { Flag } from "effect/unstable/cli"
  *
@@ -525,8 +573,8 @@ export const withDescription: {
  * // In help: --timeout SECONDS
  * ```
  *
- * @since 4.0.0
  * @category metadata
+ * @since 4.0.0
  */
 export const withMetavar: {
   // -------------------------------------------------------------------------------------
@@ -539,7 +587,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 { Flag } from "effect/unstable/cli"
    *
@@ -555,8 +604,8 @@ export const withMetavar: {
    * // In help: --timeout SECONDS
    * ```
    *
-   * @since 4.0.0
    * @category metadata
+   * @since 4.0.0
    */
   <A>(metavar: string): (self: Flag<A>) => Flag<A>
   // -------------------------------------------------------------------------------------
@@ -569,7 +618,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 { Flag } from "effect/unstable/cli"
    *
@@ -585,8 +635,8 @@ export const withMetavar: {
    * // In help: --timeout SECONDS
    * ```
    *
-   * @since 4.0.0
    * @category metadata
+   * @since 4.0.0
    */
   <A>(self: Flag<A>, metavar: string): Flag<A>
 } = dual(2, <A>(self: Flag<A>, metavar: string) => Param.withMetavar(self, metavar))
@@ -594,7 +644,8 @@ export const withMetavar: {
 /**
  * Makes a flag optional, returning an Option type that can be None if not provided.
  *
- * @example
+ * **Example** (Making flags optional)
+ *
  * ```ts
  * import { Effect, Option } from "effect"
  * import { Flag } from "effect/unstable/cli"
@@ -614,15 +665,16 @@ export const withMetavar: {
  * })
  * ```
  *
- * @since 4.0.0
  * @category optionality
+ * @since 4.0.0
  */
 export const optional = <A>(param: Flag<A>): Flag<Option.Option<A>> => Param.optional(param)
 
 /**
  * Provides a default value for a flag when it's not specified.
  *
- * @example
+ * **Example** (Providing default values)
+ *
  * ```ts
  * import { Flag } from "effect/unstable/cli"
  *
@@ -637,14 +689,15 @@ export const optional = <A>(param: Flag<A>): Flag<Option.Option<A>> => Param.opt
  * // If --host is not provided, defaults to "localhost"
  * ```
  *
- * @since 4.0.0
  * @category optionality
+ * @since 4.0.0
  */
 export const withDefault: {
   /**
    * Provides a default value for a flag when it's not specified.
    *
-   * @example
+   * **Example** (Providing default values)
+   *
    * ```ts
    * import { Flag } from "effect/unstable/cli"
    *
@@ -659,14 +712,15 @@ export const withDefault: {
    * // If --host is not provided, defaults to "localhost"
    * ```
    *
-   * @since 4.0.0
    * @category optionality
+   * @since 4.0.0
    */
   <const B>(defaultValue: B | Effect.Effect<B, CliError.CliError, Param.Environment>): <A>(self: Flag<A>) => Flag<A | B>
   /**
    * Provides a default value for a flag when it's not specified.
    *
-   * @example
+   * **Example** (Providing default values)
+   *
    * ```ts
    * import { Flag } from "effect/unstable/cli"
    *
@@ -681,8 +735,8 @@ export const withDefault: {
    * // If --host is not provided, defaults to "localhost"
    * ```
    *
-   * @since 4.0.0
    * @category optionality
+   * @since 4.0.0
    */
   <A, const B>(
    self: Flag<A>,
@@ -693,7 +747,8 @@ export const withDefault: {
 /**
  * Adds a fallback config that is loaded when a required flag is missing.
  *
- * @example
+ * **Example** (Falling back to config)
+ *
  * ```ts
  * import { Config } from "effect"
  * import { Flag } from "effect/unstable/cli"
@@ -703,14 +758,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 flag is missing.
    *
-   * @example
+   * **Example** (Falling back to config)
+   *
    * ```ts
    * import { Config } from "effect"
    * import { Flag } from "effect/unstable/cli"
@@ -720,14 +776,15 @@ export const withFallbackConfig: {
    * )
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <B>(config: Config.Config<B>): <A>(self: Flag<A>) => Flag<A | B>
   /**
    * Adds a fallback config that is loaded when a required flag is missing.
    *
-   * @example
+   * **Example** (Falling back to config)
+   *
    * ```ts
    * import { Config } from "effect"
    * import { Flag } from "effect/unstable/cli"
@@ -737,8 +794,8 @@ export const withFallbackConfig: {
    * )
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <A, B>(self: Flag<A>, config: Config.Config<B>): Flag<A | B>
 } = dual(2, <A, B>(self: Flag<A>, config: Config.Config<B>) => Param.withFallbackConfig(self, config))
@@ -746,7 +803,8 @@ export const withFallbackConfig: {
 /**
  * Adds a fallback prompt that is shown when a required flag is missing.
  *
- * @example
+ * **Example** (Falling back to prompts)
+ *
  * ```ts
  * import { Flag, Prompt } from "effect/unstable/cli"
  *
@@ -755,14 +813,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 flag is missing.
    *
-   * @example
+   * **Example** (Falling back to prompts)
+   *
    * ```ts
    * import { Flag, Prompt } from "effect/unstable/cli"
    *
@@ -771,14 +830,15 @@ export const withFallbackPrompt: {
    * )
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <B>(prompt: Param.FallbackPrompt<B>): <A>(self: Flag<A>) => Flag<A | B>
   /**
    * Adds a fallback prompt that is shown when a required flag is missing.
    *
-   * @example
+   * **Example** (Falling back to prompts)
+   *
    * ```ts
    * import { Flag, Prompt } from "effect/unstable/cli"
    *
@@ -787,8 +847,8 @@ export const withFallbackPrompt: {
    * )
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   <A, B>(self: Flag<A>, prompt: Param.FallbackPrompt<B>): Flag<A | B>
 } = dual(2, <A, B>(self: Flag<A>, prompt: Param.FallbackPrompt<B>) => Param.withFallbackPrompt(self, prompt))
@@ -796,7 +856,8 @@ export const withFallbackPrompt: {
 /**
  * Transforms the parsed value of a flag using a mapping function.
  *
- * @example
+ * **Example** (Mapping parsed values)
+ *
  * ```ts
  * import { Flag } from "effect/unstable/cli"
  *
@@ -811,14 +872,15 @@ export const withFallbackPrompt: {
  * )
  * ```
  *
- * @since 4.0.0
  * @category mapping
+ * @since 4.0.0
  */
 export const map: {
   /**
    * Transforms the parsed value of a flag using a mapping function.
    *
-   * @example
+   * **Example** (Mapping parsed values)
+   *
    * ```ts
    * import { Flag } from "effect/unstable/cli"
    *
@@ -833,14 +895,15 @@ export const map: {
    * )
    * ```
    *
-   * @since 4.0.0
    * @category mapping
+   * @since 4.0.0
    */
   <A, B>(f: (a: A) => B): (self: Flag<A>) => Flag<B>
   /**
    * Transforms the parsed value of a flag using a mapping function.
    *
-   * @example
+   * **Example** (Mapping parsed values)
+   *
    * ```ts
    * import { Flag } from "effect/unstable/cli"
    *
@@ -855,8 +918,8 @@ export const map: {
    * )
    * ```
    *
-   * @since 4.0.0
    * @category mapping
+   * @since 4.0.0
    */
   <A, B>(self: Flag<A>, f: (a: A) => B): Flag<B>
 } = dual(2, <A, B>(self: Flag<A>, f: (a: A) => B) => Param.map(self, f))
@@ -864,7 +927,8 @@ export const map: {
 /**
  * Transforms the parsed value using an Effect that can perform IO operations.
  *
- * @example
+ * **Example** (Mapping parsed values effectfully)
+ *
  * ```ts
  * import { Effect, FileSystem } from "effect"
  * import { Flag } from "effect/unstable/cli"
@@ -879,14 +943,15 @@ export const map: {
  * )
  * ```
  *
- * @since 4.0.0
  * @category mapping
+ * @since 4.0.0
  */
 export const mapEffect: {
   /**
    * Transforms the parsed value using an Effect that can perform IO operations.
    *
-   * @example
+   * **Example** (Mapping parsed values effectfully)
+   *
    * ```ts
    * import { Effect, FileSystem } from "effect"
    * import { Flag } from "effect/unstable/cli"
@@ -901,14 +966,15 @@ export const mapEffect: {
    * )
    * ```
    *
-   * @since 4.0.0
    * @category mapping
+   * @since 4.0.0
    */
   <A, B>(f: (a: A) => Effect.Effect<B, CliError.CliError, Param.Environment>): (self: Flag<A>) => Flag<B>
   /**
    * Transforms the parsed value using an Effect that can perform IO operations.
    *
-   * @example
+   * **Example** (Mapping parsed values effectfully)
+   *
    * ```ts
    * import { Effect, FileSystem } from "effect"
    * import { Flag } from "effect/unstable/cli"
@@ -923,8 +989,8 @@ export const mapEffect: {
    * )
    * ```
    *
-   * @since 4.0.0
    * @category mapping
+   * @since 4.0.0
    */
   <A, B>(
    self: Flag<A>,
@@ -938,7 +1004,8 @@ export const mapEffect: {
 /**
  * Transforms the parsed value using a function that might throw, with error handling.
  *
- * @example
+ * **Example** (Mapping thrown errors)
+ *
  * ```ts
  * import { Flag } from "effect/unstable/cli"
  *
@@ -959,14 +1026,15 @@ export const mapEffect: {
  * )
  * ```
  *
- * @since 4.0.0
  * @category mapping
+ * @since 4.0.0
  */
 export const mapTryCatch: {
   /**
    * Transforms the parsed value using a function that might throw, with error handling.
    *
-   * @example
+   * **Example** (Mapping thrown errors)
+   *
    * ```ts
    * import { Flag } from "effect/unstable/cli"
    *
@@ -987,14 +1055,15 @@ export const mapTryCatch: {
    * )
    * ```
    *
-   * @since 4.0.0
    * @category mapping
+   * @since 4.0.0
    */
   <A, B>(f: (a: A) => B, onError: (error: unknown) => string): (self: Flag<A>) => Flag<B>
   /**
    * Transforms the parsed value using a function that might throw, with error handling.
    *
-   * @example
+   * **Example** (Mapping thrown errors)
+   *
    * ```ts
    * import { Flag } from "effect/unstable/cli"
    *
@@ -1015,8 +1084,8 @@ export const mapTryCatch: {
    * )
    * ```
    *
-   * @since 4.0.0
    * @category mapping
+   * @since 4.0.0
    */
   <A, B>(self: Flag<A>, f: (a: A) => B, onError: (error: unknown) => string): Flag<B>
 } = dual(3, <A, B>(
@@ -1028,7 +1097,8 @@ export const mapTryCatch: {
 /**
  * Requires a flag to be specified at least a minimum number of times.
  *
- * @example
+ * **Example** (Requiring repeated values)
+ *
  * ```ts
  * import { Flag } from "effect/unstable/cli"
  *
@@ -1042,14 +1112,15 @@ export const mapTryCatch: {
  * // Requires at least 1 tag
  * ```
  *
- * @since 4.0.0
  * @category repetition
+ * @since 4.0.0
  */
 export const atLeast: {
   /**
    * Requires a flag to be specified at least a minimum number of times.
    *
-   * @example
+   * **Example** (Requiring repeated values)
+   *
    * ```ts
    * import { Flag } from "effect/unstable/cli"
    *
@@ -1063,14 +1134,15 @@ export const atLeast: {
    * // Requires at least 1 tag
    * ```
    *
-   * @since 4.0.0
    * @category repetition
+   * @since 4.0.0
    */
   <A>(min: number): (self: Flag<A>) => Flag<ReadonlyArray<A>>
   /**
    * Requires a flag to be specified at least a minimum number of times.
    *
-   * @example
+   * **Example** (Requiring repeated values)
+   *
    * ```ts
    * import { Flag } from "effect/unstable/cli"
    *
@@ -1084,8 +1156,8 @@ export const atLeast: {
    * // Requires at least 1 tag
    * ```
    *
-   * @since 4.0.0
    * @category repetition
+   * @since 4.0.0
    */
   <A>(self: Flag<A>, min: number): Flag<ReadonlyArray<A>>
 } = dual(2, <A>(self: Flag<A>, min: number) => Param.atLeast(self, min))
@@ -1093,7 +1165,8 @@ export const atLeast: {
 /**
  * Limits a flag to be specified at most a maximum number of times.
  *
- * @example
+ * **Example** (Limiting repeated values)
+ *
  * ```ts
  * import { Flag } from "effect/unstable/cli"
  *
@@ -1107,14 +1180,15 @@ export const atLeast: {
  * // Allows at most 1 debug flag
  * ```
  *
- * @since 4.0.0
  * @category repetition
+ * @since 4.0.0
  */
 export const atMost: {
   /**
    * Limits a flag to be specified at most a maximum number of times.
    *
-   * @example
+   * **Example** (Limiting repeated values)
+   *
    * ```ts
    * import { Flag } from "effect/unstable/cli"
    *
@@ -1128,14 +1202,15 @@ export const atMost: {
    * // Allows at most 1 debug flag
    * ```
    *
-   * @since 4.0.0
    * @category repetition
+   * @since 4.0.0
    */
   <A>(max: number): (self: Flag<A>) => Flag<ReadonlyArray<A>>
   /**
    * Limits a flag to be specified at most a maximum number of times.
    *
-   * @example
+   * **Example** (Limiting repeated values)
+   *
    * ```ts
    * import { Flag } from "effect/unstable/cli"
    *
@@ -1149,8 +1224,8 @@ export const atMost: {
    * // Allows at most 1 debug flag
    * ```
    *
-   * @since 4.0.0
    * @category repetition
+   * @since 4.0.0
    */
   <A>(self: Flag<A>, max: number): Flag<ReadonlyArray<A>>
 } = dual(2, <A>(self: Flag<A>, max: number) => Param.atMost(self, max))
@@ -1158,7 +1233,8 @@ export const atMost: {
 /**
  * Constrains a flag to be specified between a minimum and maximum number of times.
  *
- * @example
+ * **Example** (Bounding repeated values)
+ *
  * ```ts
  * import { Flag } from "effect/unstable/cli"
  *
@@ -1172,14 +1248,15 @@ export const atMost: {
  * // Allows 0-5 exclude patterns
  * ```
  *
- * @since 4.0.0
  * @category repetition
+ * @since 4.0.0
  */
 export const between: {
   /**
    * Constrains a flag to be specified between a minimum and maximum number of times.
    *
-   * @example
+   * **Example** (Bounding repeated values)
+   *
    * ```ts
    * import { Flag } from "effect/unstable/cli"
    *
@@ -1193,14 +1270,15 @@ export const between: {
    * // Allows 0-5 exclude patterns
    * ```
    *
-   * @since 4.0.0
    * @category repetition
+   * @since 4.0.0
    */
   <A>(min: number, max: number): (self: Flag<A>) => Flag<ReadonlyArray<A>>
   /**
    * Constrains a flag to be specified between a minimum and maximum number of times.
    *
-   * @example
+   * **Example** (Bounding repeated values)
+   *
    * ```ts
    * import { Flag } from "effect/unstable/cli"
    *
@@ -1214,8 +1292,8 @@ export const between: {
    * // Allows 0-5 exclude patterns
    * ```
    *
-   * @since 4.0.0
    * @category repetition
+   * @since 4.0.0
    */
   <A>(self: Flag<A>, min: number, max: number): Flag<ReadonlyArray<A>>
 } = dual(3, <A>(self: Flag<A>, min: number, max: number) => Param.between(self, min, max))
@@ -1223,7 +1301,8 @@ export const between: {
 /**
  * Transforms and filters a flag value, failing with a custom error if the transformation returns None.
  *
- * @example
+ * **Example** (Filtering and transforming values)
+ *
  * ```ts
  * import { Option } from "effect"
  * import { Flag } from "effect/unstable/cli"
@@ -1245,14 +1324,15 @@ export const between: {
  * )
  * ```
  *
- * @since 4.0.0
  * @category filtering
+ * @since 4.0.0
  */
 export const filterMap: {
   /**
    * Transforms and filters a flag value, failing with a custom error if the transformation returns None.
    *
-   * @example
+   * **Example** (Filtering and transforming values)
+   *
    * ```ts
    * import { Option } from "effect"
    * import { Flag } from "effect/unstable/cli"
@@ -1274,14 +1354,15 @@ export const filterMap: {
    * )
    * ```
    *
-   * @since 4.0.0
    * @category filtering
+   * @since 4.0.0
    */
   <A, B>(f: (a: A) => Option.Option<B>, onNone: (a: A) => string): (self: Flag<A>) => Flag<B>
   /**
    * Transforms and filters a flag value, failing with a custom error if the transformation returns None.
    *
-   * @example
+   * **Example** (Filtering and transforming values)
+   *
    * ```ts
    * import { Option } from "effect"
    * import { Flag } from "effect/unstable/cli"
@@ -1303,8 +1384,8 @@ export const filterMap: {
    * )
    * ```
    *
-   * @since 4.0.0
    * @category filtering
+   * @since 4.0.0
    */
   <A, B>(self: Flag<A>, f: (a: A) => Option.Option<B>, onNone: (a: A) => string): Flag<B>
 } = dual(3, <A, B>(
@@ -1316,7 +1397,8 @@ export const filterMap: {
 /**
  * Filters a flag value based on a predicate, failing with a custom error if the predicate returns false.
  *
- * @example
+ * **Example** (Filtering parsed values)
+ *
  * ```ts
  * import { Flag } from "effect/unstable/cli"
  *
@@ -1337,14 +1419,15 @@ export const filterMap: {
  * )
  * ```
  *
- * @since 4.0.0
  * @category filtering
+ * @since 4.0.0
  */
 export const filter: {
   /**
    * Filters a flag value based on a predicate, failing with a custom error if the predicate returns false.
    *
-   * @example
+   * **Example** (Filtering parsed values)
+   *
    * ```ts
    * import { Flag } from "effect/unstable/cli"
    *
@@ -1365,14 +1448,15 @@ export const filter: {
    * )
    * ```
    *
-   * @since 4.0.0
    * @category filtering
+   * @since 4.0.0
    */
   <A>(predicate: (a: A) => boolean, onFalse: (a: A) => string): (self: Flag<A>) => Flag<A>
   /**
    * Filters a flag value based on a predicate, failing with a custom error if the predicate returns false.
    *
-   * @example
+   * **Example** (Filtering parsed values)
+   *
    * ```ts
    * import { Flag } from "effect/unstable/cli"
    *
@@ -1393,8 +1477,8 @@ export const filter: {
    * )
    * ```
    *
-   * @since 4.0.0
    * @category filtering
+   * @since 4.0.0
    */
   <A>(self: Flag<A>, predicate: (a: A) => boolean, onFalse: (a: A) => string): Flag<A>
 } = dual(3, <A>(
@@ -1406,7 +1490,8 @@ export const filter: {
 /**
  * Provides an alternative flag if the first one fails to parse.
  *
- * @example
+ * **Example** (Falling back to another flag)
+ *
  * ```ts
  * import { Flag } from "effect/unstable/cli"
  *
@@ -1423,14 +1508,15 @@ export const filter: {
  * )
  * ```
  *
- * @since 4.0.0
  * @category alternatives
+ * @since 4.0.0
  */
 export const orElse: {
   /**
    * Provides an alternative flag if the first one fails to parse.
    *
-   * @example
+   * **Example** (Falling back to another flag)
+   *
    * ```ts
    * import { Flag } from "effect/unstable/cli"
    *
@@ -1447,14 +1533,15 @@ export const orElse: {
    * )
    * ```
    *
-   * @since 4.0.0
    * @category alternatives
+   * @since 4.0.0
    */
   <B>(that: LazyArg<Flag<B>>): <A>(self: Flag<A>) => Flag<A | B>
   /**
    * Provides an alternative flag if the first one fails to parse.
    *
-   * @example
+   * **Example** (Falling back to another flag)
+   *
    * ```ts
    * import { Flag } from "effect/unstable/cli"
    *
@@ -1471,8 +1558,8 @@ export const orElse: {
    * )
    * ```
    *
-   * @since 4.0.0
    * @category alternatives
+   * @since 4.0.0
    */
   <A, B>(self: Flag<A>, that: LazyArg<Flag<B>>): Flag<A | B>
 } = dual(2, <A, B>(self: Flag<A>, that: LazyArg<Flag<B>>) => Param.orElse(self, that))
@@ -1480,7 +1567,8 @@ export const orElse: {
 /**
  * Tries to parse with the first flag, then the second, returning a Result that indicates which succeeded.
  *
- * @example
+ * **Example** (Returning fallback results)
+ *
  * ```ts
  * import { Effect, Result } from "effect"
  * import { Flag } from "effect/unstable/cli"
@@ -1504,14 +1592,15 @@ export const orElse: {
  * })
  * ```
  *
- * @since 4.0.0
  * @category alternatives
+ * @since 4.0.0
  */
 export const orElseResult: {
   /**
    * Tries to parse with the first flag, then the second, returning a Result that indicates which succeeded.
    *
-   * @example
+   * **Example** (Returning fallback results)
+   *
    * ```ts
    * import { Effect, Result } from "effect"
    * import { Flag } from "effect/unstable/cli"
@@ -1535,14 +1624,15 @@ export const orElseResult: {
    * })
    * ```
    *
-   * @since 4.0.0
    * @category alternatives
+   * @since 4.0.0
    */
   <B>(that: LazyArg<Flag<B>>): <A>(self: Flag<A>) => Flag<Result.Result<A, B>>
   /**
    * Tries to parse with the first flag, then the second, returning a Result that indicates which succeeded.
    *
-   * @example
+   * **Example** (Returning fallback results)
+   *
    * ```ts
    * import { Effect, Result } from "effect"
    * import { Flag } from "effect/unstable/cli"
@@ -1566,8 +1656,8 @@ export const orElseResult: {
    * })
    * ```
    *
-   * @since 4.0.0
    * @category alternatives
+   * @since 4.0.0
    */
   <A, B>(self: Flag<A>, that: LazyArg<Flag<B>>): Flag<Result.Result<A, B>>
 } = dual(2, <A, B>(self: Flag<A>, that: LazyArg<Flag<B>>) => Param.orElseResult(self, that))
@@ -1575,12 +1665,13 @@ export const orElseResult: {
 /**
  * Validates and transforms a flag value using a Schema codec.
  *
- * @example
+ * **Example** (Validating with schemas)
+ *
  * ```ts
  * import { Schema } from "effect"
  * import { Flag } from "effect/unstable/cli"
  *
- * const isEmail = Schema.isIncludes("@", {
+ * const isEmail = Schema.isPattern(/^[^\s@]+@[^\s@]+\.[^\s@]+$/, {
  *   message: "Must be a valid email address"
  * })
  *
@@ -1605,19 +1696,20 @@ export const orElseResult: {
  * )
  * ```
  *
- * @since 4.0.0
  * @category schemas
+ * @since 4.0.0
  */
 export const withSchema: {
   /**
    * Validates and transforms a flag value using a Schema codec.
    *
-   * @example
+   * **Example** (Validating with schemas)
+   *
    * ```ts
    * import { Schema } from "effect"
    * import { Flag } from "effect/unstable/cli"
    *
-   * const isEmail = Schema.isIncludes("@", {
+   * const isEmail = Schema.isPattern(/^[^\s@]+@[^\s@]+\.[^\s@]+$/, {
    *   message: "Must be a valid email address"
    * })
    *
@@ -1642,19 +1734,20 @@ export const withSchema: {
    * )
    * ```
    *
-   * @since 4.0.0
    * @category schemas
+   * @since 4.0.0
    */
   <A, B>(schema: Schema.Codec<B, A>): (self: Flag<A>) => Flag<B>
   /**
    * Validates and transforms a flag value using a Schema codec.
    *
-   * @example
+   * **Example** (Validating with schemas)
+   *
    * ```ts
    * import { Schema } from "effect"
    * import { Flag } from "effect/unstable/cli"
    *
-   * const isEmail = Schema.isIncludes("@", {
+   * const isEmail = Schema.isPattern(/^[^\s@]+@[^\s@]+\.[^\s@]+$/, {
    *   message: "Must be a valid email address"
    * })
    *
@@ -1679,8 +1772,8 @@ export const withSchema: {
    * )
    * ```
    *
-   * @since 4.0.0
    * @category schemas
+   * @since 4.0.0
    */
   <A, B>(self: Flag<A>, schema: Schema.Codec<B, A>): Flag<B>
 } = dual(2, <A, B>(self: Flag<A>, schema: Schema.Codec<B, A>) => Param.withSchema(self, schema))