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

package/dist/unstable/cli/Param.js

@@ -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
  */
@@ -25,15 +42,15 @@ const TypeId = "~effect/cli/Param";
 /**
  * Kind discriminator for positional argument parameters.
  *
- * @since 4.0.0
  * @category constants
+ * @since 4.0.0
  */
 export const argumentKind = "argument";
 /**
  * Kind discriminator for flag parameters.
  *
- * @since 4.0.0
  * @category constants
+ * @since 4.0.0
  */
 export const flagKind = "flag";
 const Proto = {
@@ -47,9 +64,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
  *
@@ -60,16 +78,17 @@ const Proto = {
  * }
  * ```
  *
- * @since 4.0.0
  * @category refinements
+ * @since 4.0.0
  */
 export const isParam = u => 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
  *
@@ -80,8 +99,8 @@ export const isParam = u => Predicate.hasProperty(u, TypeId);
  * console.log(Param.isSingle(optionalParam)) // false
  * ```
  *
- * @since 4.0.0
  * @category refinements
+ * @since 4.0.0
  */
 export const isSingle = param => Predicate.isTagged(param, "Single");
 /**
@@ -91,8 +110,14 @@ export const isSingle = param => Predicate.isTagged(param, "Single");
  */
 export const isFlagParam = single => 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 = params => {
   const parse = args => params.kind === argumentKind ? parsePositional(params.name, params.primitiveType, args) : parseFlag(params.name, params.primitiveType, args);
@@ -107,9 +132,10 @@ export const makeSingle = 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
  *
@@ -122,8 +148,8 @@ export const makeSingle = params => {
  * // Usage in CLI: --name "John Doe" or as positional argument
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const string = (kind, name) => makeSingle({
   name,
@@ -133,9 +159,10 @@ export const string = (kind, name) => makeSingle({
 /**
  * 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
  *
@@ -149,8 +176,8 @@ export const string = (kind, name) => makeSingle({
  * // or as positional: true/false
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const boolean = (kind, name) => makeSingle({
   name,
@@ -160,9 +187,10 @@ export const boolean = (kind, name) => makeSingle({
 /**
  * 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
  *
@@ -175,8 +203,8 @@ export const boolean = (kind, name) => makeSingle({
  * // Usage in CLI: --port 8080 or as positional argument: 42
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const integer = (kind, name) => makeSingle({
   name,
@@ -186,9 +214,10 @@ export const integer = (kind, name) => makeSingle({
 /**
  * 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
  *
@@ -201,8 +230,8 @@ export const integer = (kind, name) => makeSingle({
  * // 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 = (kind, name) => makeSingle({
   name,
@@ -212,9 +241,10 @@ export const float = (kind, name) => makeSingle({
 /**
  * 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
  *
@@ -228,8 +258,8 @@ export const float = (kind, name) => makeSingle({
  * // Parses to JavaScript Date object
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const date = (kind, name) => makeSingle({
   name,
@@ -240,9 +270,10 @@ export const date = (kind, name) => makeSingle({
  * 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
  *
@@ -262,8 +293,8 @@ export const date = (kind, name) => makeSingle({
  * ])
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const choiceWithValue = (kind, name, choices) => makeSingle({
   name,
@@ -274,9 +305,10 @@ export const choiceWithValue = (kind, name, choices) => makeSingle({
  * 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
  *
@@ -288,8 +320,8 @@ export const choiceWithValue = (kind, name, choices) => makeSingle({
  * ])
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const choice = (kind, name, choices) => {
   const mappedChoices = choices.map(value => [value, value]);
@@ -298,9 +330,10 @@ export const choice = (kind, name, choices) => {
 /**
  * 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
  *
@@ -318,8 +351,8 @@ export const choice = (kind, name, choices) => {
  * })
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const path = (kind, name, options) => makeSingle({
   name,
@@ -333,9 +366,10 @@ export const path = (kind, name, options) => makeSingle({
  * 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
  *
@@ -348,8 +382,8 @@ export const path = (kind, name, options) => makeSingle({
  * // Usage: --output-dir /path/to/dir --source /existing/dir
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const directory = (kind, name, options) => path(kind, name, {
   pathType: "directory",
@@ -362,9 +396,10 @@ export const directory = (kind, name, options) => path(kind, name, {
  * 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
  *
@@ -377,8 +412,8 @@ export const directory = (kind, name, options) => path(kind, name, {
  * // Usage: --output result.txt --input existing-file.txt
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const file = (kind, name, options) => path(kind, name, {
   pathType: "file",
@@ -389,9 +424,10 @@ export const file = (kind, name, options) => path(kind, name, {
  * 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
  *
@@ -404,8 +440,8 @@ export const file = (kind, name, options) => path(kind, name, {
  * // Usage: --password (value will be hidden in help/logs)
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const redacted = (kind, name) => makeSingle({
   name,
@@ -415,9 +451,10 @@ export const redacted = (kind, name) => makeSingle({
 /**
  * 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
  *
@@ -430,8 +467,8 @@ export const redacted = (kind, name) => makeSingle({
  * // Usage: --config config.txt (reads file content into string)
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const fileText = (kind, name) => makeSingle({
   name,
@@ -444,9 +481,10 @@ export const fileText = (kind, name) => makeSingle({
  * 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
  *
@@ -460,8 +498,8 @@ export const fileText = (kind, name) => makeSingle({
  * })
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const fileParse = (kind, name, options) => makeSingle({
   name,
@@ -471,10 +509,11 @@ export const fileParse = (kind, name, options) => makeSingle({
 /**
  * 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
@@ -495,8 +534,8 @@ export const fileParse = (kind, name, options) => makeSingle({
  * // Usage: --config config.json (reads and validates file content)
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const fileSchema = (kind, name, schema, options) => makeSingle({
   name,
@@ -510,9 +549,10 @@ export const fileSchema = (kind, name, schema, options) => makeSingle({
  * 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
  *
@@ -523,8 +563,8 @@ export const fileSchema = (kind, name, schema, options) => makeSingle({
  * // --property name=value --property debug=true
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const keyValuePair = (kind, name) => map(variadic(makeSingle({
   name,
@@ -538,23 +578,24 @@ export const keyValuePair = (kind, name) => map(variadic(makeSingle({
  *
  * 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)
+ *
+ * const makeDebugParam = (enableDebug: boolean) =>
+ *   enableDebug ? Param.string(Param.flagKind, "debug") : disabledDebugParam
  *
- * // Often used in conditional parameter creation
- * const conditionalParam = process.env.NODE_ENV === "production"
- *   ? Param.string(Param.flagKind, "my-dev-flag")
- *   : Param.none(Param.flagKind)
+ * 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 => makeSingle({
   name: "__none__",
@@ -571,9 +612,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
  *
@@ -589,8 +631,8 @@ const FLAG_DASH_REGEXP = /^-+/;
  * )
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const withAlias = /*#__PURE__*/dual(2, (self, alias) => {
   return transformSingle(self, single => makeSingle({
@@ -604,9 +646,10 @@ export const withAlias = /*#__PURE__*/dual(2, (self, alias) => {
  * 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
  *
@@ -616,8 +659,8 @@ export const withAlias = /*#__PURE__*/dual(2, (self, alias) => {
  * )
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const withDescription = /*#__PURE__*/dual(2, (self, description) => {
   return transformSingle(self, single => makeSingle({
@@ -628,9 +671,10 @@ export const withDescription = /*#__PURE__*/dual(2, (self, description) => {
 /**
  * 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
  *
@@ -639,8 +683,8 @@ export const withDescription = /*#__PURE__*/dual(2, (self, description) => {
  * )
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const map = /*#__PURE__*/dual(2, (self, f) => {
   const parse = args => Effect.map(self.parse(args), ([operands, value]) => [operands, f(value)]);
@@ -662,13 +706,13 @@ const transform = (self, f) => Object.assign(Object.create(Proto), {
 /**
  * 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) =>
@@ -686,17 +730,18 @@ const transform = (self, f) => Object.assign(Object.create(Proto), {
  * )
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const mapEffect = /*#__PURE__*/dual(2, (self, f) => transform(self, parse => args => Effect.flatMap(parse(args), ([leftover, a]) => f(a).pipe(Effect.map(b => [leftover, 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
  *
@@ -709,8 +754,8 @@ export const mapEffect = /*#__PURE__*/dual(2, (self, f) => transform(self, parse
  * )
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const mapTryCatch = /*#__PURE__*/dual(3, (self, f, onError) => {
   const single = getUnderlyingSingleOrThrow(self);
@@ -725,14 +770,16 @@ export const mapTryCatch = /*#__PURE__*/dual(3, (self, f, onError) => {
   })), Effect.map(b => [leftover, b]))));
 });
 /**
- * Creates an optional option that returns None when not provided.
+ * Makes a flag or positional argument optional.
+ *
+ * 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()`.
  *
- * Optional options never fail with MissingOption errors. If the option is not
- * provided on the command line, Option.none() is returned instead.
+ * **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()
@@ -740,8 +787,8 @@ export const mapTryCatch = /*#__PURE__*/dual(3, (self, f, onError) => {
  * const port = Param.optional(Param.integer(Param.flagKind, "port"))
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const optional = param => {
   const parse = Effect.fnUntraced(function* (args) {
@@ -767,15 +814,15 @@ export const optional = param => {
   });
 };
 /**
- * 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
  *
@@ -792,8 +839,8 @@ export const optional = param => {
  * )
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const withDefault = /*#__PURE__*/dual(2, (self, defaultValue) => {
   if (!Effect.isEffect(defaultValue)) {
@@ -807,8 +854,8 @@ export const withDefault = /*#__PURE__*/dual(2, (self, defaultValue) => {
 /**
  * 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 = /*#__PURE__*/dual(2, (self, config) => {
   const toInvalidValue = (error, configError) => new CliError.InvalidValue({
@@ -826,8 +873,8 @@ export const withFallbackConfig = /*#__PURE__*/dual(2, (self, config) => {
 /**
  * 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 = /*#__PURE__*/dual(2, (self, prompt) => {
   const runPrompt = (error, args) => Effect.flatMap(Prompt.isPrompt(prompt) ? Effect.succeed(prompt) : prompt, Prompt.run).pipe(Effect.map(value => [args.arguments, value]), Effect.catchTag("QuitError", () => Effect.fail(error)));
@@ -840,9 +887,10 @@ export const withFallbackPrompt = /*#__PURE__*/dual(2, (self, prompt) => {
  * 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
  *
@@ -858,12 +906,12 @@ export const withFallbackPrompt = /*#__PURE__*/dual(2, (self, prompt) => {
  * // 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 = (self, options) => {
   const single = getUnderlyingSingleOrThrow(self);
@@ -889,9 +937,10 @@ export const variadic = (self, options) => {
  * 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
  *
@@ -913,8 +962,8 @@ export const variadic = (self, options) => {
  * // Result: ["dev", "staging", "v1.0"]
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const between = /*#__PURE__*/dual(3, (self, min, max) => {
   if (min < 0) {
@@ -934,9 +983,10 @@ export const between = /*#__PURE__*/dual(3, (self, min, max) => {
  * 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
  *
@@ -949,8 +999,8 @@ export const between = /*#__PURE__*/dual(3, (self, min, max) => {
  * // Result: ["warning1", "warning2"]
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const atMost = /*#__PURE__*/dual(2, (self, max) => {
   if (max < 0) {
@@ -966,9 +1016,10 @@ export const atMost = /*#__PURE__*/dual(2, (self, max) => {
  * 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
  *
@@ -982,8 +1033,8 @@ export const atMost = /*#__PURE__*/dual(2, (self, max) => {
  * // Result: ["file1.txt", "file2.txt", "file3.txt"]
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const atLeast = /*#__PURE__*/dual(2, (self, min) => {
   if (min < 0) {
@@ -999,10 +1050,11 @@ export const atLeast = /*#__PURE__*/dual(2, (self, min) => {
  *
  * 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(
@@ -1013,8 +1065,8 @@ export const atLeast = /*#__PURE__*/dual(2, (self, min) => {
  * )
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const filterMap = /*#__PURE__*/dual(3, (self, filter, onNone) => mapEffect(self, Effect.fnUntraced(function* (a) {
   const result = filter(a);
@@ -1032,9 +1084,10 @@ export const filterMap = /*#__PURE__*/dual(3, (self, filter, onNone) => mapEffec
 /**
  * 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
  *
@@ -1046,8 +1099,8 @@ export const filterMap = /*#__PURE__*/dual(3, (self, filter, onNone) => mapEffec
  * )
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const filter = /*#__PURE__*/dual(3, (self, predicate, onFalse) => filterMap(self, Option.liftPredicate(predicate), onFalse));
 /**
@@ -1056,9 +1109,10 @@ export const filter = /*#__PURE__*/dual(3, (self, predicate, onFalse) => filterM
  * 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
  *
@@ -1071,8 +1125,8 @@ export const filter = /*#__PURE__*/dual(3, (self, predicate, onFalse) => filterM
  * )
  * ```
  *
- * @since 4.0.0
  * @category metadata
+ * @since 4.0.0
  */
 export const withMetavar = /*#__PURE__*/dual(2, (self, metavar) => transformSingle(self, single => makeSingle({
   ...single,
@@ -1081,10 +1135,11 @@ export const withMetavar = /*#__PURE__*/dual(2, (self, metavar) => transformSing
 /**
  * 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@]+$/)
@@ -1098,8 +1153,8 @@ export const withMetavar = /*#__PURE__*/dual(2, (self, metavar) => transformSing
  * )
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const withSchema = /*#__PURE__*/dual(2, (self, schema) => {
   const decodeParam = Schema.decodeUnknownEffect(schema);
@@ -1116,9 +1171,10 @@ export const withSchema = /*#__PURE__*/dual(2, (self, schema) => {
 /**
  * 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
  *
@@ -1127,16 +1183,21 @@ export const withSchema = /*#__PURE__*/dual(2, (self, schema) => {
  * )
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const orElse = /*#__PURE__*/dual(2, (self, orElse) => transform(self, parse => args => Effect.catch(parse(args), err => orElse(err).parse(args))));
 /**
- * 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
  *
@@ -1146,8 +1207,8 @@ export const orElse = /*#__PURE__*/dual(2, (self, orElse) => transform(self, par
  * // Returns Result<string, string>
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const orElseResult = /*#__PURE__*/dual(2, (self, orElse) => {
   return transform(self, parse => args => Effect.catch(Effect.map(parse(args), ([leftover, value]) => [leftover, Result.succeed(value)]), err => Effect.map(orElse(err).parse(args), ([leftover, value]) => [leftover, Result.fail(value)])));