cli-kiss 0.2.2 → 0.2.3

package/dist/index.d.ts

@@ -1,10 +1,6 @@
 /**
- * An opaque key that uniquely identifies a registered CLI option within a
- * {@link ReaderArgs} instance.
- *
- * Keys are returned by {@link ReaderArgs.registerOption} and passed back to
- * {@link ReaderArgs.getOptionValues} to retrieve the parsed values. The internal
- * representation is intentionally opaque — treat it as a handle, not a string.
+ * Opaque key identifying a registered option within a {@link ReaderArgs} instance.
+ * Returned by {@link ReaderArgs.registerOption}; passed to {@link ReaderArgs.getOptionValues}.
  */
 type ReaderOptionKey = (string | {
     __brand: "ReaderOptionKey";
@@ -12,23 +8,18 @@ type ReaderOptionKey = (string | {
     __brand: "ReaderOptionKey";
 };
 /**
- * Interface for registering and querying CLI options during argument parsing.
- *
- * {@link ReaderArgs} implements both `ReaderOptions` and {@link ReaderPositionals}.
- * The two interfaces are exposed separately so that option and positional parsing logic
- * can depend only on the capability they need.
+ * Option registration and query interface, implemented by {@link ReaderArgs}.
+ * Exposed separately from {@link ReaderPositionals} so parsers depend only on what they need.
  */
 type ReaderOptions = {
     /**
-     * Registers a new option so the parser can recognise it when scanning argument tokens.
+     * Registers an option so the parser can recognise it.
      *
-     * @param definition.longs - The long-form names (without `--`) for this option.
-     * @param definition.shorts - The short-form names (without `-`) for this option.
-     * @param definition.valued - When `true`, the option consumes the following token as
-     *   its value. When `false`, the option is a boolean flag.
-     * @returns An opaque {@link ReaderOptionKey} used to retrieve parsed values later.
-     * @throws `Error` if any of the given names has already been registered, or if a
-     *   short name overlaps (is a prefix of, or has as a prefix, another registered short).
+     * @param definition.longs - Long-form names (without `--`).
+     * @param definition.shorts - Short-form names (without `-`).
+     * @param definition.valued - `true` if the option takes a value; `false` for flags.
+     * @returns A {@link ReaderOptionKey} for later retrieval.
+     * @throws `Error` if a name is already registered or short names overlap.
      */
     registerOption(definition: {
         longs: Array<string>;
@@ -38,71 +29,49 @@ type ReaderOptions = {
     /**
      * Returns all values collected for the option identified by `key`.
      *
-     * @param key - The key returned by a prior {@link ReaderOptions.registerOption} call.
-     * @returns An array of raw string values, one per occurrence of the option on the
-     *   command line. Empty if the option was never provided.
-     * @throws `Error` if `key` was not previously registered on this instance.
+     * @param key - Key from {@link ReaderOptions.registerOption}.
+     * @returns Raw string values, one per occurrence; empty if never provided.
+     * @throws `Error` if `key` was not registered.
      */
     getOptionValues(key: ReaderOptionKey): Array<string>;
 };
 /**
- * Interface for consuming positional (non-option) argument tokens during parsing.
- *
- * {@link ReaderArgs} implements both {@link ReaderOptions} and `ReaderPositionals`.
+ * Positional token consumption interface, implemented by {@link ReaderArgs}.
  */
 type ReaderPositionals = {
     /**
-     * Consumes and returns the next positional token from the argument list, skipping
-     * any option tokens (which are parsed as side-effects).
+     * Returns the next positional token, parsing intervening options as side-effects.
      *
-     * @returns The next positional string value, or `undefined` if no more positionals
-     *   are available.
-     * @throws {@link TypoError} if an unrecognised option token is encountered while
-     *   scanning for the next positional.
+     * @returns The next positional, or `undefined` when exhausted.
+     * @throws {@link TypoError} on an unrecognised option.
      */
     consumePositional(): string | undefined;
 };
 /**
- * The core argument parser for `cli-kiss`. Parses a flat array of raw CLI tokens into
- * named options and positional values.
+ * Core argument parser: converts raw CLI tokens into named options and positionals.
+ * Options must be registered before {@link ReaderArgs.consumePositional} is called.
  *
- * Options must be registered with {@link ReaderArgs.registerOption} **before**
- * {@link ReaderArgs.consumePositional} is called, because the parser needs to know
- * whether each token is an option name, an option value, or a bare positional.
+ * Supported syntax: `--name`, `--name value`, `--name=value`,
+ * `-n`, `-n value`, `-nvalue`, `-abc` (stacked), `--` (end-of-options).
  *
- * **Supported argument syntax:**
- * - Long options: `--name`, `--name value`, `--name=value`
- * - Short options: `-n`, `-n value`, `-n=value`, `-nvalue`, `-abc` (stacked flags)
- * - End-of-options separator: `--` — all subsequent tokens are treated as positionals.
- *
- * In most cases you do not need to use `ReaderArgs` directly; it is created internally
- * by {@link runAndExit}. It is exposed for advanced use cases such as building
- * custom runners.
+ * Created internally by {@link runAndExit}; exposed for advanced / custom runners.
  */
 declare class ReaderArgs {
     #private;
     /**
-     * @param args - The raw command-line tokens to parse. Typically `process.argv.slice(2)`.
-     *   The array is not modified; a read cursor is maintained internally.
+     * @param args - Raw CLI tokens (e.g. `process.argv.slice(2)`). Not mutated.
      */
     constructor(args: ReadonlyArray<string>);
     /**
-     * Registers a CLI option so the parser can recognise it.
-     *
-     * All `longs` and `shorts` are associated with the same returned key. Calling
-     * `getOptionValues(key)` after parsing will return values collected under any of the
-     * registered names.
-     *
-     * Short names support stacking (e.g. `-abc` is parsed as `-a -b -c`) and inline
-     * values (e.g. `-nvalue`). Short names must not be a prefix of, nor have as a prefix,
-     * any other registered short name — the parser uses prefix matching to parse stacked
-     * shorts, so overlapping prefixes would be ambiguous.
+     * Registers an option; all `longs` and `shorts` share the same key.
+     * Short names support stacking (e.g. `-abc`) and inline values (e.g. `-nvalue`),
+     * but must not be prefixes of one another.
      *
      * @param definition.longs - Long-form names (without `--`).
      * @param definition.shorts - Short-form names (without `-`).
-     * @param definition.valued - `true` if the option consumes a value; `false` for flags.
-     * @returns An opaque {@link ReaderOptionKey} to pass to {@link ReaderArgs.getOptionValues}.
-     * @throws `Error` if any name is already registered or if two short names overlap.
+     * @param definition.valued - `true` if the option takes a value; `false` for flags.
+     * @returns A {@link ReaderOptionKey} for {@link ReaderArgs.getOptionValues}.
+     * @throws `Error` if any name is already registered or short names overlap.
      */
     registerOption(definition: {
         longs: Array<string>;
@@ -110,70 +79,51 @@ declare class ReaderArgs {
         valued: boolean;
     }): ReaderOptionKey;
     /**
-     * Returns all raw string values collected for the given option key.
+     * Returns all values collected for the option key.
      *
-     * @param key - A key previously returned by {@link ReaderArgs.registerOption}.
-     * @returns An array of string values, one per occurrence on the command line. For
-     *   flags this will be `["true"]` per occurrence; for valued options it will be the
-     *   literal value strings.
-     * @throws `Error` if `key` was not registered on this instance.
+     * @param key - Key from {@link ReaderArgs.registerOption}.
+     * @returns String values, one per occurrence.
+     * @throws `Error` if `key` was not registered.
      */
     getOptionValues(key: ReaderOptionKey): Array<string>;
     /**
-     * Scans forward through the argument list and returns the next bare positional token,
-     * consuming and parsing any intervening option tokens as side-effects.
-     *
-     * Option tokens encountered during the scan are recorded in the internal results map
-     * (equivalent to recording their values against their key). Any unrecognised option token
-     * causes a {@link TypoError} to be thrown immediately.
-     *
-     * After `--` is encountered, all remaining tokens are treated as positionals.
+     * Returns the next bare positional token.
+     * Parse intervening options as side-effects.
+     * All tokens after `--` are treated as positionals.
      *
-     * @returns The next positional string, or `undefined` when the argument list is
-     *   exhausted.
-     * @throws {@link TypoError} if an unrecognised option (long or short) is encountered.
+     * @returns The next positional, or `undefined` when exhausted.
+     * @throws {@link TypoError} on an unrecognised option.
      */
     consumePositional(): string | undefined;
 }
 
 /**
- * Describes how to decode a raw CLI string token into a typed TypeScript value.
+ * Decodes a raw CLI string into a typed value.
+ * A pair of a human-readable `content` name (e.g. `"Number"`) and a `decoder` function.
  *
- * A `Type` is a pair of:
- * - a `content` string — a human-readable name shown in help/error messages (e.g.
- *   `"String"`, `"Number"`, `"Url"`).
- * - a `decoder` function — converts the raw string or throws a {@link TypoError} on
- *   invalid input.
- *
- * Built-in types: {@link typeString}, {@link typeBoolean}, {@link typeNumber},
+ * Built-in: {@link typeString}, {@link typeBoolean}, {@link typeNumber},
  * {@link typeInteger}, {@link typeDate}, {@link typeUrl}.
+ * Composite: {@link typeOneOf}, {@link typeMapped}, {@link typeTuple}, {@link typeList}.
  *
- * Composite types: {@link typeOneOf}, {@link typeConverted}, {@link typeTuple},
- * {@link typeList}.
- *
- * @typeParam Value - The TypeScript type that the decoder produces.
+ * @typeParam Value - Type produced by the decoder.
  */
 type Type<Value> = {
     /**
-     * Human-readable name for this type, used in help text and error messages.
-     * Examples: `"String"`, `"Number"`, `"Url"`.
+     * Human-readable name shown in help and error messages (e.g. `"String"`, `"Number"`).
      */
     content: string;
     /**
-     * Decodes a raw string token into a `Value`.
+     * Converts a raw CLI string into `Value`.
      *
-     * @param value - The raw string from the command line.
+     * @param input - Raw string from the command line.
      * @returns The decoded value.
-     * @throws {@link TypoError} if the value cannot be decoded.
+     * @throws {@link TypoError} on invalid input.
      */
-    decoder(value: string): Value;
+    decoder(input: string): Value;
 };
 /**
- * A {@link Type} that decodes `"true"` / `"yes"` to `true` and `"false"` / `"no"` to
- * `false` (case-insensitive). Any other value throws a {@link TypoError}.
- *
- * Primarily used internally by {@link optionFlag} for the `--flag=<value>` syntax, but
- * can also be used in positionals or valued options.
+ * Decodes `"true"` / `"yes"` → `true` and `"false"` / `"no"` → `false` (case-insensitive).
+ * Used internally by {@link optionFlag} for the `--flag=<value>` syntax.
  *
  * @example
  * ```ts
@@ -184,13 +134,8 @@ type Type<Value> = {
  */
 declare const typeBoolean: Type<boolean>;
 /**
- * A {@link Type} that parses a date/time string using `Date.parse`.
- *
- * Accepts any format supported by the JavaScript `Date.parse` API, including ISO 8601
- * strings (e.g. `"2024-01-15"`, `"2024-01-15T10:30:00Z"`). Non-parseable values throw
- * a {@link TypoError}.
- *
- * Produces a `Date` object. The decoded value is the result of `new Date(Date.parse(value))`.
+ * Parses a date/time string via `Date.parse` into a `Date` object.
+ * Accepts any format supported by `Date.parse`, including ISO 8601.
  *
  * @example
  * ```ts
@@ -201,11 +146,8 @@ declare const typeBoolean: Type<boolean>;
  */
 declare const typeDate: Type<Date>;
 /**
- * A {@link Type} that parses a string into a JavaScript `number` using the `Number()`
- * constructor.
- *
- * Accepts integers, floating-point values, and scientific notation (e.g. `"3.14"`,
- * `"-1"`, `"1e10"`). Values that produce `NaN` throw a {@link TypoError}.
+ * Parses a string into a `number` via `Number()`.
+ * Accepts integers, floats, and scientific notation; `NaN` throws a {@link TypoError}.
  *
  * @example
  * ```ts
@@ -216,11 +158,8 @@ declare const typeDate: Type<Date>;
  */
 declare const typeNumber: Type<number>;
 /**
- * A {@link Type} that parses a string into a JavaScript `bigint` using the `BigInt()`
- * constructor.
- *
- * Only accepts valid integer strings (e.g. `"42"`, `"-100"`, `"9007199254740993"`).
- * Floating-point strings or non-numeric values throw a {@link TypoError}.
+ * Parses an integer string into a `bigint` via `BigInt()`.
+ * Floats and non-numeric strings throw a {@link TypoError}.
  *
  * @example
  * ```ts
@@ -231,10 +170,8 @@ declare const typeNumber: Type<number>;
  */
 declare const typeInteger: Type<bigint>;
 /**
- * A {@link Type} that parses a string into a `URL` object using the `URL` constructor.
- *
- * The string must be a valid absolute URL (e.g. `"https://example.com/path?q=1"`).
- * Relative URLs and malformed strings throw a {@link TypoError}.
+ * Parses an absolute URL string into a `URL` object.
+ * Relative or malformed URLs throw a {@link TypoError}.
  *
  * @example
  * ```ts
@@ -244,9 +181,7 @@ declare const typeInteger: Type<bigint>;
  */
 declare const typeUrl: Type<URL>;
 /**
- * A {@link Type} that passes the raw string through unchanged (identity decoder).
- *
- * This is the simplest type and accepts any string value without validation.
+ * Identity decoder — passes the raw string through unchanged.
  *
  * @example
  * ```ts
@@ -256,29 +191,21 @@ declare const typeUrl: Type<URL>;
  */
 declare const typeString: Type<string>;
 /**
- * Creates a new {@link Type} by chaining a `before` type decoder with an `after`
- * transformation.
+ * Creates a {@link Type} by chaining `before`'s decoder with an `after` transformation.
+ * `before` errors are prefixed with `"from: <content>"` for traceability.
  *
- * The raw string is first decoded by `before.decoder`; its result is then passed to
- * `after.decoder`. Errors from `before` are wrapped with a "from: <content>" context
- * prefix so that the full decoding path is visible in error messages.
+ * @typeParam Before - Intermediate type from `before.decoder`.
+ * @typeParam After - Final type from `after.decoder`.
  *
- * Use this when an existing type (e.g. {@link typeString}, {@link typeOneOf}) produces
- * an intermediate value that needs a further transformation (e.g. parsing a
- * string-keyed enum into a number).
- *
- * @typeParam Before - The intermediate type produced by `before.decoder`.
- * @typeParam After - The final type produced by `after.decoder`.
- *
- * @param before - The base type that decodes the raw CLI string.
- * @param after - The transformation applied to the `Before` value.
- * @param after.content - Human-readable name for the resulting type (shown in errors).
- * @param after.decoder - Function that converts a `Before` value into `After`.
- * @returns A new {@link Type}`<After>` whose `content` is `after.content`.
+ * @param before - Base decoder for the raw string.
+ * @param after - Transformation applied to the decoded value.
+ * @param after.content - Name for the resulting type (shown in errors).
+ * @param after.decoder - Converts a `Before` value to `After`.
+ * @returns A {@link Type}`<After>`.
  *
  * @example
  * ```ts
- * const typePort = typeConverted(typeNumber, {
+ * const typePort = typeMapped(typeNumber, {
  *   content: "Port",
  *   decoder: (n) => {
  *     if (n < 1 || n > 65535) throw new Error("Out of range");
@@ -289,23 +216,17 @@ declare const typeString: Type<string>;
  * // "--port 99999"  →  TypoError: --port: <PORT>: Port: Out of range
  * ```
  */
-declare function typeConverted<Before, After>(before: Type<Before>, after: {
+declare function typeMapped<Before, After>(before: Type<Before>, after: {
     content: string;
     decoder: (value: Before) => After;
 }): Type<After>;
 /**
- * Creates a {@link Type}`<string>` that only accepts a fixed set of string values.
- *
- * The decoder performs an exact (case-sensitive) lookup in `values`. If the input is
- * not in the set, a {@link TypoError} is thrown listing up to 5 of the valid options.
+ * Creates a {@link Type}`<string>` accepting only a fixed set of string values.
+ * Out-of-set inputs throw a {@link TypoError} listing up to 5 valid options.
  *
- * Combine with {@link typeConverted} to map the accepted strings to a richer type.
- *
- * @param content - Human-readable name for this type shown in help text and error
- *   messages (e.g. `"Environment"`, `"LogLevel"`).
- * @param values - The ordered list of accepted string values. The order is preserved in
- *   the error message preview.
- * @returns A {@link Type}`<string>` that validates membership in `values`.
+ * @param content - Name shown in help and errors (e.g. `"Environment"`).
+ * @param values - Ordered list of accepted values.
+ * @returns A {@link Type}`<string>`.
  *
  * @example
  * ```ts
@@ -314,25 +235,16 @@ declare function typeConverted<Before, After>(before: Type<Before>, after: {
  * typeEnv.decoder("unknown") // throws TypoError: Invalid value: "unknown" (expected one of: "dev" | "staging" | "prod")
  * ```
  */
-declare function typeOneOf(content: string, values: Array<string>): Type<string>;
+declare function typeOneOf<const Value extends string>(content: string, values: Array<Value>): Type<Value>;
 /**
- * Creates a {@link Type} that decodes a single delimited string into a fixed-length
- * tuple of typed elements.
- *
- * The raw string is split on `separator` into exactly `elementTypes.length` parts.
- * Each part is decoded by its corresponding element type. If the number of splits does
- * not match, or if any element's decoder fails, a {@link TypoError} is thrown with the
- * index and element type context.
+ * Splits a delimited string into a fixed-length typed tuple.
+ * Each part is decoded by the corresponding element type; wrong count or decode failure throws {@link TypoError}.
  *
- * The resulting `content` is the element types' `content` values joined by `separator`
- * (e.g. `"Number,String"` for a `[number, string]` tuple with `","` separator).
+ * @typeParam Elements - Tuple of decoded value types (inferred from `elementTypes`).
  *
- * @typeParam Elements - The tuple type of decoded element values (inferred from
- *   `elementTypes`).
- *
- * @param elementTypes - An ordered array of {@link Type}s, one per tuple element.
- * @param separator - The string used to split the raw value (default: `","`).
- * @returns A {@link Type}`<Elements>` tuple type.
+ * @param elementTypes - One {@link Type} per tuple element, in order.
+ * @param separator - Delimiter (default `","`).
+ * @returns A {@link Type}`<Elements>`.
  *
  * @example
  * ```ts
@@ -346,26 +258,14 @@ declare function typeTuple<const Elements extends Array<any>>(elementTypes: {
     [K in keyof Elements]: Type<Elements[K]>;
 }, separator?: string): Type<Elements>;
 /**
- * Creates a {@link Type} that decodes a single delimited string into an array of
- * homogeneous typed elements.
- *
- * The raw string is split on `separator` and each part is decoded by `elementType`.
- * If any element's decoder fails, a {@link TypoError} is thrown with the index and
- * element type context.
- *
- * Unlike {@link typeTuple}, the number of elements is not fixed; the result array
- * length equals the number of `separator`-delimited parts in the input string. To pass
- * an empty array, the user must pass an empty string (`""`), which splits into one
- * empty-string element — consider using {@link optionRepeatable} instead if you want a
- * naturally empty default.
+ * Splits a delimited string into a variable-length typed array.
+ * Each part is decoded by `elementType`; failed decodes throw {@link TypoError}.
+ * Note: splitting an empty string yields one empty element — prefer {@link optionRepeatable} for a zero-default.
  *
- * The `content` is formatted as `"<elementContent>[<sep><elementContent>]..."` to
- * signal repeatability.
+ * @typeParam Value - Element type produced by `elementType.decoder`.
  *
- * @typeParam Value - The TypeScript element type produced by `elementType.decoder`.
- *
- * @param elementType - The {@link Type} used to decode each element.
- * @param separator - The string used to split the raw value (default: `","`).
+ * @param elementType - Decoder applied to each element.
+ * @param separator - Delimiter (default `","`).
  * @returns A {@link Type}`<Array<Value>>`.
  *
  * @example
@@ -381,86 +281,75 @@ declare function typeTuple<const Elements extends Array<any>>(elementTypes: {
 declare function typeList<Value>(elementType: Type<Value>, separator?: string): Type<Array<Value>>;
 
 /**
- * Describes a single CLI option (a flag or a valued option) together with its parsing
- * and usage-generation logic.
+ * A CLI option (flag or valued) with its parsing and usage-generation logic.
  *
- * Options are created with {@link optionFlag}, {@link optionSingleValue}, or
- * {@link optionRepeatable} and are passed via the `options` map of {@link operation}.
+ * Created with {@link optionFlag}, {@link optionSingleValue}, or
+ * {@link optionRepeatable} and passed via the `options` map of {@link operation}.
  *
- * @typeParam Value - The TypeScript type of the parsed option value.
- *   - `boolean` for flags created with {@link optionFlag}.
- *   - `T` for single-value options created with {@link optionSingleValue}.
- *   - `Array<T>` for repeatable options created with {@link optionRepeatable}.
+ * @typeParam Value - Decoded value type.
  */
 type Option<Value> = {
-    /** Returns human-readable metadata used to render the `Options:` section of help. */
+    /**
+     * Returns metadata used to render the `Options:` section of help.
+     */
     generateUsage(): OptionUsage;
     /**
-     * Registers the option on `readerOptions` so the argument reader recognises it, and
-     * returns an {@link OptionParser} that can later retrieve the parsed value(s).
-     *
-     * @param readerOptions - The shared {@link ReaderArgs} that will parse the raw
-     *   command-line tokens.
+     * Registers the option on `readerOptions` and returns an {@link OptionDecoder}.
      */
-    createParser(readerOptions: ReaderArgs): OptionParser<Value>;
+    registerAndMakeDecoder(readerOptions: ReaderArgs): OptionDecoder<Value>;
 };
 /**
- * Retrieves the parsed value for a registered option after argument parsing is complete.
- *
- * Returned by {@link Option.createParser} and called by {@link OperationFactory.createInstance}.
+ * Produced by {@link Option.registerAndMakeDecoder}.
  *
- * @typeParam Value - The TypeScript type of the parsed value.
+ * @typeParam Value - Decoded value type.
  */
-type OptionParser<Value> = {
-    parseValue(): Value;
+type OptionDecoder<Value> = {
+    /**
+     * Returns the decoded option value.
+     *
+     * @throws {@link TypoError} if decoding failed.
+     */
+    getAndDecodeValue(): Value;
 };
 /**
- * Human-readable metadata for a single CLI option, used to render the `Options:` section
+ * Human-readable metadata for a single option, used to render the `Options:` section
  * of the help output produced by {@link usageToStyledLines}.
  */
 type OptionUsage = {
-    /** Short description of what the option does. */
-    description: string | undefined;
     /**
-     * Optional supplementary note shown in parentheses next to the description.
-     * Suitable for short caveats such as `"required"` or `"defaults to 42"`.
-     */
-    hint: string | undefined;
-    /**
-     * The primary long-form name of the option, without the `--` prefix (e.g. `"verbose"`).
-     * The user passes this as `--verbose` on the command line.
+     * Long-form name without `--` (e.g. `"verbose"`).
      */
     long: Lowercase<string>;
     /**
-     * The optional short-form name of the option, without the `-` prefix (e.g. `"v"`).
-     * The user passes this as `-v` on the command line.
+     * Short-form name without `-` (e.g. `"v"`).
      */
     short: string | undefined;
     /**
-     * The value placeholder label shown after the long option name in the help output
-     * (e.g. `"<FILE>"`). `undefined` for flags that take no value.
+     * Help text in usage.
+     */
+    description: string | undefined;
+    /**
+     * Short note shown in parentheses.
+     */
+    hint: string | undefined;
+    /**
+     * Value placeholder in help (e.g. `"<FILE>"`). `undefined` for flags.
      */
     label: Uppercase<string> | undefined;
 };
 /**
- * Creates a boolean flag option — an option that the user passes without a value (e.g.
- * `--verbose`) to signal `true`, or can explicitly set with `--flag=true` / `--flag=no`.
- *
- * **Parsing rules:**
- * - Absent → `false` (or the return value of `default()` when provided).
- * - `--flag` / `--flag=true` / `--flag=yes` → `true`.
- * - `--flag=false` / `--flag=no` → `false`.
- * - Specified more than once → {@link TypoError} ("Must not be set multiple times").
- *
- * @param definition - Configuration for the flag.
- * @param definition.long - Primary long-form name (without `--`). Must be lowercase.
- * @param definition.short - Optional short-form name (without `-`).
- * @param definition.description - Human-readable description for the help output.
- * @param definition.hint - Optional supplementary note shown in parentheses.
- * @param definition.aliases - Additional long/short names that the parser also
- *   recognises as this flag.
- * @param definition.default - Factory for the default value when the flag is absent.
- *   Defaults to `() => false` when omitted.
+ * Creates a boolean flag option (`--verbose`, optionally `--flag=no`).
+ *
+ * Parsing: absent → `false`; `--flag` / `--flag=yes` → `true`; `--flag=no` → `false`;
+ * specified more than once → {@link TypoError}.
+ *
+ * @param definition - Flag configuration.
+ * @param definition.long - Long-form name (without `--`).
+ * @param definition.short - Short-form name (without `-`).
+ * @param definition.description - Help text.
+ * @param definition.hint - Short note shown in parentheses.
+ * @param definition.aliases - Additional names.
+ * @param definition.default - Default when absent. Defaults to `() => false`.
  * @returns An {@link Option}`<boolean>`.
  *
  * @example
@@ -484,32 +373,22 @@ declare function optionFlag(definition: {
     default?: () => boolean;
 }): Option<boolean>;
 /**
- * Creates an option that accepts exactly one value (e.g. `--output dist/` or
- * `--output=dist/`).
- *
- * **Parsing rules:**
- * - Absent → `definition.default()` is called. If the default factory throws, a
- *   {@link TypoError} is produced.
- * - Specified once → the value is decoded with `definition.type`.
- * - Specified more than once → {@link TypoError} ("Requires a single value, but got
- *   multiple").
- *
- * **Value syntax:** `--long value`, `--long=value`, or (if `short` is set) `-s value`,
- * `-s=value`, or `-svalue`.
- *
- * @typeParam Value - The TypeScript type produced by the type decoder.
- *
- * @param definition - Configuration for the option.
- * @param definition.long - Primary long-form name (without `--`). Must be lowercase.
- * @param definition.short - Optional short-form name (without `-`).
- * @param definition.description - Human-readable description for the help output.
- * @param definition.hint - Optional supplementary note shown in parentheses.
- * @param definition.aliases - Additional long/short names the parser also recognises.
- * @param definition.label - Custom label shown in the help output (e.g. `"FILE"`).
- *   Defaults to the uppercased `type.content`.
- * @param definition.type - The {@link Type} used to decode the raw string value.
- * @param definition.default - Factory for the default value when the option is absent.
- *   Throw an error from this factory to make the option effectively required.
+ * Creates an option that accepts exactly one value (e.g. `--output dist/`).
+ *
+ * Parsing: absent → `default()`; once → decoded with `type`; more than once → {@link TypoError}.
+ * Value syntax: `--long value`, `--long=value`, `-s value`, `-s=value`, `-svalue`.
+ *
+ * @typeParam Value - Type produced by the decoder.
+ *
+ * @param definition - Option configuration.
+ * @param definition.long - Long-form name (without `--`).
+ * @param definition.short - Short-form name (without `-`).
+ * @param definition.description - Help text.
+ * @param definition.hint - Short note shown in parentheses.
+ * @param definition.aliases - Additional names.
+ * @param definition.label - Value placeholder in help. Defaults to uppercased `type.content`.
+ * @param definition.type - Decoder for the raw string value.
+ * @param definition.default - Default when absent. Throw to make the option required.
  * @returns An {@link Option}`<Value>`.
  *
  * @example
@@ -538,30 +417,21 @@ declare function optionSingleValue<Value>(definition: {
     default: () => Value;
 }): Option<Value>;
 /**
- * Creates an option that can be specified any number of times, collecting all provided
- * values into an array (e.g. `--file a.ts --file b.ts`).
- *
- * **Parsing rules:**
- * - Absent → empty array `[]`.
- * - Specified N times → array of N decoded values, in the order they appear on the
- *   command line.
- * - Each occurrence is decoded independently with `definition.type`.
- *
- * **Value syntax:** `--long value`, `--long=value`, or (if `short` is set) `-s value`,
- * `-s=value`, or `-svalue`.
- *
- * @typeParam Value - The TypeScript type produced by the type decoder for each
- *   occurrence.
- *
- * @param definition - Configuration for the option.
- * @param definition.long - Primary long-form name (without `--`). Must be lowercase.
- * @param definition.short - Optional short-form name (without `-`).
- * @param definition.description - Human-readable description for the help output.
- * @param definition.hint - Optional supplementary note shown in parentheses.
- * @param definition.aliases - Additional long/short names the parser also recognises.
- * @param definition.label - Custom label shown in the help output (e.g. `"FILE"`).
- *   Defaults to the uppercased `type.content`.
- * @param definition.type - The {@link Type} used to decode each raw string value.
+ * Creates an option that collects every occurrence into an array (e.g. `--file a.ts --file b.ts`).
+ *
+ * Parsing: absent → `[]`; N occurrences → array of N decoded values in order.
+ * Value syntax: `--long value`, `--long=value`, `-s value`, `-s=value`, `-svalue`.
+ *
+ * @typeParam Value - Type produced by the decoder for each occurrence.
+ *
+ * @param definition - Option configuration.
+ * @param definition.long - Long-form name (without `--`).
+ * @param definition.short - Short-form name (without `-`).
+ * @param definition.description - Help text.
+ * @param definition.hint - Short note shown in parentheses.
+ * @param definition.aliases - Additional names.
+ * @param definition.label - Value placeholder in help. Defaults to uppercased `type.content`.
+ * @param definition.type - Decoder applied to each raw string value.
  * @returns An {@link Option}`<Array<Value>>`.
  *
  * @example
@@ -590,80 +460,68 @@ declare function optionRepeatable<Value>(definition: {
 }): Option<Array<Value>>;
 
 /**
- * Describes a single positional argument — a bare (non-option) token on the command
- * line — together with its parsing and usage-generation logic.
+ * A bare (non-option) positional argument with its parsing and usage-generation logic.
  *
- * Positionals are created with {@link positionalRequired}, {@link positionalOptional}, or
- * {@link positionalVariadics} and are passed via the `positionals` array of
- * {@link operation}, where they are consumed in declaration order.
+ * Created with {@link positionalRequired}, {@link positionalOptional}, or
+ * {@link positionalVariadics} and passed via the `positionals` array of
+ * {@link operation}, consumed in declaration order.
  *
- * @typeParam Value - The TypeScript type of the parsed positional value.
+ * @typeParam Value - Decoded value type.
  */
 type Positional<Value> = {
-    /** Returns human-readable metadata used to render the `Positionals:` section of help. */
+    /**
+     * Returns metadata used to render the `Positionals:` section of help.
+     */
     generateUsage(): PositionalUsage;
     /**
-     * Consumes the positional from `readerPositionals` and then returns a parser that produces the final decoded value.
-     *
-     * The parser is created during {@link Operation.createFactory} and may throw a
-     * {@link TypoError} if the positional is missing (when required) or if decoding fails.
-     * @param readerPositionals - The source of positional arguments to be consumed.
+     * Consumes the next positional token from `readerPositionals`.
+     * Returns a decoder that produces the final value.
      */
-    createParser(readerPositionals: ReaderPositionals): PositionalParser<Value>;
+    consumeAndMakeDecoder(readerPositionals: ReaderPositionals): PositionalDecoder<Value>;
 };
 /**
- * Retrieves the parsed value for a positional argument after parsing is complete.
+ * Produced by {@link Positional.consumeAndMakeDecoder}.
  *
- * Returned by {@link Positional.createParser} and called by {@link OperationFactory.createInstance}.
- *
- * @typeParam Value - The TypeScript type of the parsed value.
+ * @typeParam Value - Decoded value type.
  */
-type PositionalParser<Value> = {
+type PositionalDecoder<Value> = {
     /**
-     * Returns the fully decoded and validated value for the positional
+     * Returns the decoded positional value.
      *
-     * @throws {@link TypoError} if the positional was missing (when required) or if decoding failed.
+     * @throws {@link TypoError} if decoding failed.
      */
-    parseValue(): Value;
+    decodeValue(): Value;
 };
 /**
  * Human-readable metadata for a single positional argument, used to render the
  * `Positionals:` section of the help output produced by {@link usageToStyledLines}.
  */
 type PositionalUsage = {
-    /** Short description of what the positional represents. */
+    /**
+     * Help text.
+     */
     description: string | undefined;
     /**
-     * Optional supplementary note shown in parentheses next to the description.
-     * Suitable for short caveats such as `"defaults to 'world'"`.
+     * Short note shown in parentheses.
      */
     hint: string | undefined;
     /**
-     * The placeholder label shown in the usage line and the `Positionals:` section.
-     * Required positionals use angle-bracket notation (e.g. `"<NAME>"`); optional ones
-     * use square-bracket notation (e.g. `"[FILE]"`); variadic ones append `...`
-     * (e.g. `"[ITEM]..."`).
+     * Placeholder label shown in the usage line and the `Positionals:` section.
+     * Required: `<NAME>`, optional: `[NAME]`, variadic: `[NAME]...`.
      */
     label: Uppercase<string>;
 };
 /**
- * Creates a required positional argument — one that must be present on the command line.
- *
- * The parser consumes the next available positional token and decodes it with
- * `definition.type`. If no token is available, a {@link TypoError} is thrown immediately
- * during parsing (i.e. inside {@link Operation.createFactory}).
+ * Creates a required positional — missing token throws {@link TypoError}.
+ * Label defaults to uppercased `type.content` in angle brackets (e.g. `<STRING>`).
  *
- * The label displayed in the usage line defaults to the uppercased `type.content`
- * wrapped in angle brackets (e.g. `<STRING>`). Supply `label` to override.
+ * @typeParam Value - Type produced by the decoder.
  *
- * @typeParam Value - The TypeScript type produced by the type decoder.
- *
- * @param definition - Configuration for the positional.
- * @param definition.description - Human-readable description for the help output.
- * @param definition.hint - Optional supplementary note shown in parentheses.
- * @param definition.label - Custom label shown in the usage line (without angle brackets).
- *   Defaults to the uppercased `type.content`.
- * @param definition.type - The {@link Type} used to decode the raw string token.
+ * @param definition - Positional configuration.
+ * @param definition.description - Help text.
+ * @param definition.hint - Short note shown in parentheses.
+ * @param definition.label - Label without brackets; defaults to uppercased `type.content`.
+ * @param definition.type - Decoder for the raw token.
  * @returns A {@link Positional}`<Value>`.
  *
  * @example
@@ -683,26 +541,17 @@ declare function positionalRequired<Value>(definition: {
     type: Type<Value>;
 }): Positional<Value>;
 /**
- * Creates an optional positional argument — one that may or may not appear on the
- * command line.
- *
- * The parser consumes the next available positional token. If no token is available,
- * `definition.default()` is called to supply the fallback value. If the default factory
- * throws, a {@link TypoError} is produced.
- *
- * The label displayed in the usage line defaults to the uppercased `type.content`
- * wrapped in square brackets (e.g. `[STRING]`). Supply `label` to override.
- *
- * @typeParam Value - The TypeScript type produced by the type decoder (or the default).
- *
- * @param definition - Configuration for the positional.
- * @param definition.description - Human-readable description for the help output.
- * @param definition.hint - Optional supplementary note shown in parentheses.
- * @param definition.label - Custom label shown in the usage line (without square brackets).
- *   Defaults to the uppercased `type.content`.
- * @param definition.type - The {@link Type} used to decode the raw string token.
- * @param definition.default - Factory called when the positional is absent to supply the
- *   default value. Throw from this factory to make omission an error.
+ * Creates an optional positional — absent token falls back to `default()`.
+ * Label defaults to uppercased `type.content` in square brackets (e.g. `[STRING]`).
+ *
+ * @typeParam Value - Type produced by the decoder (or the default).
+ *
+ * @param definition - Positional configuration.
+ * @param definition.description - Help text.
+ * @param definition.hint - Short note shown in parentheses.
+ * @param definition.label - Label without brackets; defaults to uppercased `type.content`.
+ * @param definition.type - Decoder for the raw token.
+ * @param definition.default - Value when absent. Throw to make it required.
  * @returns A {@link Positional}`<Value>`.
  *
  * @example
@@ -725,31 +574,17 @@ declare function positionalOptional<Value>(definition: {
     default: () => Value;
 }): Positional<Value>;
 /**
- * Creates a variadic positional argument — one that collects zero or more remaining
- * positional tokens into an array.
- *
- * The parser greedily consumes tokens until either there are no more tokens or it
- * encounters the optional `endDelimiter` sentinel string, which is consumed but not
- * included in the result. Each token is decoded independently with `definition.type`.
- *
- * If absent entirely, the result is an empty array `[]`.
- *
- * The label displayed in the usage line defaults to the uppercased `type.content`
- * wrapped in square brackets followed by `...` (e.g. `[STRING]...`). When an
- * `endDelimiter` is configured, the delimiter is also shown (e.g. `[STRING]...["--"]`).
- * Supply `label` to override the base label.
- *
- * @typeParam Value - The TypeScript type produced by the type decoder for each token.
- *
- * @param definition - Configuration for the variadic positional.
- * @param definition.endDelimiter - Optional sentinel string that signals the end of
- *   the variadic sequence (e.g. `"--"`). When encountered it is consumed but not
- *   included in the result array.
- * @param definition.description - Human-readable description for the help output.
- * @param definition.hint - Optional supplementary note shown in parentheses.
- * @param definition.label - Custom label shown in the usage line (without brackets).
- *   Defaults to the uppercased `type.content`.
- * @param definition.type - The {@link Type} used to decode each raw string token.
+ * Creates a variadic positional that collects zero or more remaining tokens into an array.
+ * Stops at `endDelimiter` (consumed, not included). Label: `[TYPE]...` notation.
+ *
+ * @typeParam Value - Type produced by the decoder for each token.
+ *
+ * @param definition - Positional configuration.
+ * @param definition.endDelimiter - Sentinel token that stops collection (consumed, not included).
+ * @param definition.description - Help text.
+ * @param definition.hint - Short note shown in parentheses.
+ * @param definition.label - Label without brackets; defaults to uppercased `type.content`.
+ * @param definition.type - Decoder applied to each token.
  * @returns A {@link Positional}`<Array<Value>>`.
  *
  * @example
@@ -772,106 +607,80 @@ declare function positionalVariadics<Value>(definition: {
 }): Positional<Array<Value>>;
 
 /**
- * Describes an operation — the combination of options, positional arguments, and an
- * async execution handler that together form the core logic of a CLI command.
- *
- * An `Operation` is created with {@link operation} and passed to
- * {@link command}, {@link commandWithSubcommands}, or {@link commandChained} to build
- * a full {@link Command}.
- *
- * @typeParam Input - The context value the handler receives at execution time (forwarded
- *   from the parent command's context or from a preceding chained operation).
- * @typeParam Output - The value the handler produces. For leaf operations this is
- *   typically `void`; for intermediate stages it is the payload forwarded to the next
- *   command in a chain.
+ * Options, positionals, and an async handler that together form the logic of a CLI command.
+ *
+ * Created with {@link operation} and passed to {@link command},
+ * {@link commandWithSubcommands}, or {@link commandChained}.
+ *
+ * @typeParam Context - Injected at execution time; forwarded to handlers. Use to inject dependencies.
+ * @typeParam Result - Value produced on execution; typically `void` for leaf commands.
  */
-type Operation<Input, Output> = {
+type Operation<Context, Result> = {
     /**
-     * Returns usage metadata (options and positionals) without consuming any arguments.
-     * Called by the parent command factory when building the help/usage output.
+     * Returns usage metadata without consuming any arguments.
      */
     generateUsage(): OperationUsage;
     /**
-     * Parses options and positionals from `readerArgs` and returns an
-     * {@link OperationFactory} that can create a ready-to-execute
-     * {@link OperationInstance}.
-     *
-     * Any parse error (unknown option, type mismatch, etc.) is captured and re-thrown
-     * when {@link OperationFactory.createInstance} is called.
-     *
-     * @param readerArgs - The shared argument reader. Options are registered on it and
-     *   positionals are consumed in declaration order.
+     * Consumes args from `readerArgs` and returns an {@link OperationDecoder}.
      */
-    createFactory(readerArgs: ReaderArgs): OperationFactory<Input, Output>;
+    consumeAndMakeDecoder(readerArgs: ReaderArgs): OperationDecoder<Context, Result>;
 };
 /**
- * Produced by {@link Operation.createFactory} after argument parsing.
- * Instantiating it finalises value extraction and produces an {@link OperationInstance}.
+ * Produced by {@link Operation.consumeAndMakeDecoder}.
  *
- * @typeParam Input - operation instance input type {@link Operation}.
- * @typeParam Output - operation instance output type {@link Operation}.
+ * @typeParam Context - See {@link Operation}.
+ * @typeParam Result - See {@link Operation}.
  */
-type OperationFactory<Input, Output> = {
+type OperationDecoder<Context, Result> = {
     /**
-     * Extracts the final parsed values for all options and returns an
-     * {@link OperationInstance} ready for execution.
+     * Creates a ready-to-execute {@link OperationInterpreter}.
      *
-     * @throws {@link TypoError} if any option or positional validation failed during
-     *   {@link Operation.createFactory}.
+     * @throws {@link TypoError} if parsing or decoding failed.
      */
-    createInstance(): OperationInstance<Input, Output>;
+    decodeAndMakeInterpreter(): OperationInterpreter<Context, Result>;
 };
 /**
- * A fully parsed, ready-to-execute operation.
+ * A fully parsed, decoded and ready-to-execute operation.
  *
- * @typeParam Input - The value the caller must supply as context.
- * @typeParam Output - The value produced on successful execution.
+ * @typeParam Context - Caller-supplied context.
+ * @typeParam Result - Value produced on success.
  */
-type OperationInstance<Input, Output> = {
+type OperationInterpreter<Context, Result> = {
     /**
-     * Runs the operation handler with the provided input context and the parsed
-     * option/positional values.
-     *
-     * @param input - Context from the parent command (or the root context supplied to
-     *   {@link runAndExit}).
-     * @returns A promise resolving to the handler's return value.
+     * Executes with the provided context.
      */
-    executeWithContext(input: Input): Promise<Output>;
+    executeWithContext(context: Context): Promise<Result>;
 };
 /**
- * Collected usage metadata produced by {@link Operation.generateUsage}.
- * Consumed by the parent command factory when building {@link CommandUsage}.
+ * Usage metadata produced by {@link Operation.generateUsage}.
+ * Consumed when building {@link CommandUsage}.
  */
 type OperationUsage = {
-    /** Usage descriptors for all options registered by this operation. */
+    /**
+     * Usage descriptors for all registered options.
+     */
     options: Array<OptionUsage>;
-    /** Usage descriptors for all positionals declared by this operation, in order. */
+    /**
+     * Usage descriptors for all declared positionals, in order.
+     */
     positionals: Array<PositionalUsage>;
 };
 /**
- * Creates an {@link Operation} from a set of options, positionals, and an
- * async handler function.
- *
- * The `handler` receives:
- * - `context` — the value passed down from the parent command.
- * - `inputs.options` — an object whose keys match those declared in `inputs.options` and whose values are
- *   the parsed option values.
- * - `inputs.positionals` — a tuple whose elements match `inputs.positionals` and whose
- *   values are the parsed positional values, in declaration order.
- *
- * @typeParam Context - The context type accepted by the handler.
- * @typeParam Result - The return type of the handler.
- * @typeParam Options - Object type mapping option keys to their parsed value types.
- * @typeParam Positionals - Tuple type of parsed positional value types, in order.
- *
- * @param inputs - Declares the options and positionals this operation accepts.
- * @param inputs.options - A map from arbitrary keys to {@link Option} descriptors.
- *   The same keys appear in `handler`'s `inputs.options` argument.
- * @param inputs.positionals - An ordered array of {@link Positional} descriptors.
- *   Their parsed values appear in `handler`'s `inputs.positionals` argument, in the
- *   same order.
- * @param handler - The async function that implements the command logic. Receives the
- *   execution context and all parsed inputs.
+ * Creates an {@link Operation} from options, positionals, and an async handler.
+ *
+ * The `handler` receives the parent `context` and an `inputs` object with
+ * `options` (keyed by the same names declared in `inputs.options`) and
+ * `positionals` (a tuple in declaration order).
+ *
+ * @typeParam Context - Context type accepted by the handler.
+ * @typeParam Result - Return type of the handler.
+ * @typeParam Options - Map of option keys to parsed value types.
+ * @typeParam Positionals - Tuple of parsed positional value types, in order.
+ *
+ * @param inputs - Options and positionals this operation accepts.
+ * @param inputs.options - Map of keys to {@link Option} descriptors.
+ * @param inputs.positionals - Ordered array of {@link Positional} descriptors.
+ * @param handler - Async function implementing the command logic.
  * @returns An {@link Operation} ready to be composed into a command.
  *
  * @example
@@ -907,168 +716,158 @@ declare function operation<Context, Result, Options extends {
 }) => Promise<Result>): Operation<Context, Result>;
 
 /**
- * Describes a CLI command: how to parse its arguments from raw CLI input and how to
- * execute it within a given context.
+ * A CLI command — parses arguments and executes within a given context.
+ * Created with {@link command}, {@link commandWithSubcommands}, or {@link commandChained}.
+ * Usually passed through {@link runAndExit} to run.
  *
- * A `Command` is the central building block of a `cli-kiss` CLI.
- * You create one with {@link command}, {@link commandWithSubcommands},
- * or {@link commandChained}, and pass it to {@link runAndExit} to run your CLI.
- *
- * @typeParam Context - The value passed into the command when it is executed. It flows
- *   from {@link runAndExit}'s `context` argument down through the command chain.
- * @typeParam Result - The value produced by executing the command. For root commands
- *   passed to {@link runAndExit} this is always `void`.
+ * @typeParam Context - Injected at execution time; forwarded to handlers. Use to inject dependencies.
+ * @typeParam Result - Value produced on execution; typically `void` for leaf commands.
  */
 type Command<Context, Result> = {
     /**
-     * Returns the static metadata information about this command.
+     * Returns the command's static metadata.
      */
     getInformation(): CommandInformation;
     /**
-     * Parses `readerArgs` and returns a {@link CommandFactory} that can generate usage
-     * information or create a ready-to-run {@link CommandInstance}.
-     *
-     * Parsing errors are captured and deferred: `createFactory` never throws; instead
-     * the error surfaces when {@link CommandFactory.createInstance} is called on the
-     * returned factory.
+     * Consumes args in a `readerArgs` and returns a {@link CommandDecoder}.
      */
-    createFactory(readerArgs: ReaderArgs): CommandFactory<Context, Result>;
+    consumeAndMakeDecoder(readerArgs: ReaderArgs): CommandDecoder<Context, Result>;
 };
 /**
- * Produced by {@link Command.createFactory} after the raw CLI arguments have
- * been parsed. Provides two capabilities:
+ * Produced by {@link Command.consumeAndMakeDecoder}.
  *
- * 1. **Usage generation** — always available, even when parsing failed.
- * 2. **Instance creation** — throws a {@link TypoError} if parsing failed.
- *
- * @typeParam Context - Input passed to the command {@link Command}.
- * @typeParam Result - Result of the command's logic {@link Command}.
+ * @typeParam Context - See {@link Command}.
+ * @typeParam Result - See {@link Command}.
  */
-type CommandFactory<Context, Result> = {
+type CommandDecoder<Context, Result> = {
     /**
-     * Builds the complete {@link CommandUsage} for the currently parsed command path.
-     * This is called to render the `--help` output and on error when `usageOnError`
-     * is enabled.
+     * Builds the {@link CommandUsage} for the current command path.
+     * Used for `--help` and `usageOnError`.
      */
     generateUsage(): CommandUsage;
     /**
-     * Creates a {@link CommandInstance} that is ready to execute.
+     * Creates a ready-to-execute {@link CommandInterpreter}.
      *
-     * @throws {@link TypoError} if the argument parsing that occurred during
-     *   {@link Command.createFactory} encountered an error (e.g. unknown
-     *   option, missing required positional, invalid type).
+     * @throws {@link TypoError} if parsing or decoding failed.
      */
-    createInstance(): CommandInstance<Context, Result>;
+    decodeAndMakeInterpreter(): CommandInterpreter<Context, Result>;
 };
 /**
- * A fully parsed, ready-to-execute command.
+ * A fully parsed, decoded and ready-to-execute command.
  *
- * @typeParam Context - The value the caller must provide when executing the command.
- * @typeParam Result - The value the command produces on successful execution.
+ * @typeParam Context - Caller-supplied context.
+ * @typeParam Result - Value produced on success.
  */
-type CommandInstance<Context, Result> = {
+type CommandInterpreter<Context, Result> = {
     /**
-     * Executes the command with the provided context.
-     *
-     * @param context - Arbitrary value injected by the caller (see {@link runAndExit}).
-     * @returns A promise that resolves to the command's result, or rejects if the
-     *   command handler throws.
+     * Executes with the provided context.
      */
     executeWithContext(context: Context): Promise<Result>;
 };
 /**
- * Static, human-readable metadata attached to a command.
- *
- * This information is displayed in the usage/help output produced by {@link usageToStyledLines}.
+ * Static metadata for a command, shown in `--help` output via {@link usageToStyledLines}.
  */
 type CommandInformation = {
-    /** Short description of what the command does. Shown prominently in the usage header. */
+    /**
+     * Short description shown in the usage header.
+     */
     description: string;
     /**
-     * Optional supplementary note shown in parentheses next to the description.
-     * Suitable for short caveats such as `"deprecated"` or `"experimental"`.
+     * Short note shown in parentheses (e.g. `"deprecated"`, `"experimental"`).
      */
     hint?: string;
     /**
-     * Optional list of additional detail lines printed below the description.
-     * Useful for multi-line explanations, examples, or caveats that don't fit in
-     * a single sentence.
+     * Extra lines printed below the description.
      */
     details?: Array<string>;
+    /**
+     * Examples shown in the `Examples:` section of the usage output.
+     */
+    examples?: Array<{
+        /**
+         * Explanation shown above the example.
+         */
+        explanation: string;
+        /**
+         * Command line args to show as an example of usage.
+         */
+        commandArgs: Array<string | {
+            positional: string;
+        } | {
+            subcommand: string;
+        } | {
+            option: {
+                long: string;
+                value?: string;
+            } | {
+                short: string;
+                value?: string;
+            };
+        }>;
+    }>;
 };
 /**
- * The full usage/help model for a command as it appears after argument parsing.
- *
- * This is produced by {@link CommandFactory.generateUsage} and consumed by
- * {@link usageToStyledLines} to render the `--help` output.
+ * Full usage/help model.
+ * Produced by {@link CommandDecoder.generateUsage},
+ * Consumed by {@link usageToStyledLines}.
  */
 type CommandUsage = {
     /**
-     * Ordered list of breadcrumb segments that form the command's usage line, e.g.:
-     * `Usage: my-cli <POSITIONAL> subcommand <ANOTHER_POSITIONAL>`.
-     *
-     * Each element is either a positional placeholder or a literal subcommand name.
+     * Segments forming the usage line
+     * (e.g. `my-cli <POSITIONAL> subcommand <ANOTHER_POSITIONAL>`).
+     */
+    segments: Array<CommandUsageSegment>;
+    /**
+     * Command's static metadata.
      */
-    breadcrumbs: Array<CommandUsageBreadcrumb>;
-    /** The command's static metadata (description, hint, details). */
     information: CommandInformation;
     /**
-     * Positional arguments that belong to the current command path,
-     * in the order they must appear on the command line.
+     * Positionals in declaration order.
      */
     positionals: Array<PositionalUsage>;
     /**
-     * Subcommands available at the current level of the command hierarchy.
-     * Non-empty only when the command is a {@link commandWithSubcommands} and the
-     * subcommand selection could not be resolved (i.e. on error or `--help`).
+     * Available subcommands. Non-empty when subcommand was not specified.
      */
     subcommands: Array<CommandUsageSubcommand>;
     /**
-     * Options (flags and valued options) accepted by the current command path,
-     * in the order they were registered.
+     * Options in registration order.
      */
     options: Array<OptionUsage>;
 };
 /**
- * A single element in the usage breadcrumb trail shown at the top of the help output.
- *
- * - `{ positional: string }` — A positional placeholder such as `<NAME>` or `[FILE]`.
- * - `{ command: string }` — A literal subcommand token such as `deploy`.
+ * One element in the usage segment trail.
  */
-type CommandUsageBreadcrumb = {
+type CommandUsageSegment = {
     positional: string;
 } | {
     command: string;
 };
 /**
- * Summary information about a single subcommand shown in the `Subcommands:` section
- * of the usage output.
+ * Subcommand entry shown in the `Subcommands:` section of the usage output.
  */
 type CommandUsageSubcommand = {
-    /** The literal token the user types to select this subcommand (e.g. `"deploy"`). */
+    /**
+     * Literal token the user types (e.g. `"deploy"`).
+     */
     name: string;
-    /** Short description forwarded from the subcommand's {@link CommandInformation}. */
+    /**
+     * Short description from the subcommand's {@link CommandInformation}.
+     */
     description: string | undefined;
-    /** Optional hint forwarded from the subcommand's {@link CommandInformation}. */
+    /**
+     * Hint from the subcommand's {@link CommandInformation}.
+     */
     hint: string | undefined;
 };
 /**
- * Creates a leaf command — a command that has no subcommands and directly executes
- * an {@link Operation}.
- *
- * During parsing, `command` reads all positionals and options consumed by `operation`,
- * then asserts that no extra positionals remain. Any unexpected trailing positional
- * causes a {@link TypoError} deferred to {@link CommandFactory.createInstance}.
+ * Creates a leaf command that directly executes an {@link Operation}.
  *
- * @typeParam Context - The context value forwarded to the operation handler at
- *   execution time.
- * @typeParam Result - The value returned by the operation handler.
+ * @typeParam Context - Context forwarded to the handler.
+ * @typeParam Result - Value returned by the handler.
  *
- * @param information - Static metadata (description, hint, details) for the command.
- * @param operation - The operation that defines options, positionals, and the execution
- *   handler for this command.
- * @returns A {@link Command} suitable for passing to {@link runAndExit}
- *   or composing with {@link commandWithSubcommands} / {@link commandChained}.
+ * @param information - Command metadata (description, hint, details).
+ * @param operation - Defines: options, positionals, and the handler.
+ * @returns A {@link Command}.
  *
  * @example
  * ```ts
@@ -1083,34 +882,17 @@ type CommandUsageSubcommand = {
  */
 declare function command<Context, Result>(information: CommandInformation, operation: Operation<Context, Result>): Command<Context, Result>;
 /**
- * Creates a command that first runs an {@link Operation} to produce an
- * intermediate `Payload`, then dispatches execution to one of several named subcommands
- * based on the next positional argument.
- *
- * **Parsing behaviour:**
- * 1. The `operation`'s positionals and options are parsed from `readerArgs`.
- * 2. The next positional token is consumed as the subcommand name.
- *    - If no token is present, a {@link TypoError} is deferred.
- *    - If the token does not match any key in `subcommands`, a {@link TypoError} is
- *      deferred.
- * 3. The matched subcommand's factory is created with the remaining `readerArgs`.
- *
- * **Usage on error / `--help`:** when the subcommand cannot be determined, the usage
- * output lists all available subcommands under a `Subcommands:` section.
- *
- * @typeParam Context - The context value accepted by the root operation handler.
- * @typeParam Payload - The value produced by the root operation and forwarded as the
- *   context to the selected subcommand.
- * @typeParam Result - The value produced by the selected subcommand.
- *
- * @param information - Static metadata shown in the top-level usage when no valid
- *   subcommand has been selected.
- * @param operation - The operation that is always executed first, before the
- *   subcommand. Its output becomes the subcommand's context.
- * @param subcommands - A map of lowercase subcommand names to their
- *   {@link Command}s. The keys are the literal tokens the user types.
- * @returns A {@link Command} that dispatches to one of the provided
- *   subcommands.
+ * Creates a command that runs an {@link Operation} to produce a `Payload`,
+ * then dispatches to a named subcommand based on the next positional token.
+ *
+ * @typeParam Context - Context accepted by `operation`.
+ * @typeParam Payload - Output of `operation`; becomes the subcommand's context.
+ * @typeParam Result - Value produced by the selected subcommand.
+ *
+ * @param information - Command metadata (description, hint, details).
+ * @param operation - Always runs first; its output becomes the subcommand's context.
+ * @param subcommands - Map of subcommand names to their {@link Command}s.
+ * @returns A {@link Command} that dispatches to one of the provided subcommands.
  *
  * @example
  * ```ts
@@ -1128,36 +910,17 @@ declare function commandWithSubcommands<Context, Payload, Result>(information: C
     [subcommand: Lowercase<string>]: Command<Payload, Result>;
 }): Command<Context, Result>;
 /**
- * Creates a command that chains two command stages by piping the output of an
- * {@link Operation} directly into a {@link Command} as its context.
- *
- * Unlike {@link commandWithSubcommands}, there is no runtime token consumed for routing;
- * the `nextCommand` is always the continuation. This is useful for splitting a complex
- * command into reusable pieces, such as a shared authentication step followed by
- * different sub-actions.
- *
- * **Parsing behaviour:**
- * 1. `operation`'s positionals and options are parsed.
- * 2. `nextCommand`'s factory is immediately created from the same `readerArgs` (the
- *    remaining unparsed tokens).
- * 3. At execution time, `operation` runs first; its result is passed as the context to
- *    `nextCommand`.
- *
- * **Usage:** breadcrumbs, positionals, and options from both stages are merged into a
- * single flat usage description. The `information` of `nextCommand` takes precedence in
- * the generated usage output.
- *
- * @typeParam Context - The context value accepted by `operation`.
- * @typeParam Payload - The value produced by `operation` and used as the context for
- *   `nextCommand`.
- * @typeParam Result - The value produced by `nextCommand`.
- *
- * @param information - Fallback metadata used in the usage output when `nextCommand`'s
- *   factory cannot be created (i.e. on parse error in the next stage).
- * @param operation - The first stage operation. Its output becomes `nextCommand`'s
- *   context.
- * @param nextCommand - The second stage command, executed after `operation` succeeds.
- * @returns A {@link Command} that transparently composes the two stages.
+ * Chains an {@link Operation} and a {@link Command}: `operation` runs first, its
+ * output becomes `subcommand`'s context. No token is consumed for routing.
+ *
+ * @typeParam Context - Context accepted by `operation`.
+ * @typeParam Payload - Output of `operation`; becomes `subcommand`'s context.
+ * @typeParam Result - Value produced by `subcommand`.
+ *
+ * @param information - Command metadata (description, hint, details).
+ * @param operation - First stage; its output is passed as `subcommand`'s context.
+ * @param subcommand - Second stage, executed after `operation`.
+ * @returns A {@link Command} transparently composing the two stages.
  *
  * @example
  * ```ts
@@ -1171,56 +934,30 @@ declare function commandWithSubcommands<Context, Payload, Result>(information: C
  * );
  * ```
  */
-declare function commandChained<Context, Payload, Result>(information: CommandInformation, operation: Operation<Context, Payload>, nextCommand: Command<Payload, Result>): Command<Context, Result>;
+declare function commandChained<Context, Payload, Result>(information: CommandInformation, operation: Operation<Context, Payload>, subcommand: Command<Payload, Result>): Command<Context, Result>;
 
 /**
- * Parses the provided CLI arguments against the given command descriptor, executes
- * the matched command, and exits the process with an appropriate exit code.
- *
- * This is the primary entry point for running a `cli-kiss`-based CLI application.
- * It handles argument parsing, `--help` / `--version` flags, usage printing on errors,
- * and exit code management.
- *
- * **Exit codes:**
- * - `0` — Command executed successfully, or `--help` / `--version` was handled.
- * - `1` — Argument parsing failed (a usage summary is also printed to stderr), or the
- *   command threw an unhandled execution error.
- *
- * **Built-in flags:**
- * - `--help` — Enabled by default (`usageOnHelp: true`). Prints the usage summary to
- *   stdout and exits with code `0`. This flag takes precedence over `--version`.
- * - `--version` — Enabled when `buildVersion` is provided. Prints `<cliName> <version>`
- *   to stdout and exits with code `0`.
- *
- * @typeParam Context - Arbitrary value passed unchanged to the command's execution handler.
- *   Use this to inject dependencies (e.g. a database connection, a logger) into your commands.
- *
- * @param cliName - The name of the CLI program (e.g. `"my-cli"`). Used in the usage
- *   summary header and in the `--version` output.
- * @param cliArgs - The raw command-line arguments to parse, typically `process.argv.slice(2)`.
- * @param context - The context value forwarded to the command's execution handler.
- * @param command - The root {@link Command} that describes how to parse and execute
- *   the CLI.
- * @param options - Optional configuration for the runner.
- * @param options.useTtyColors - Controls terminal color output in styled messages.
- *   - `true` — Always apply ANSI color codes.
- *   - `false` — Never apply color codes (plain text).
- *   - `"mock"` — Use a deterministic mock style useful for snapshot testing.
- *   - `undefined` (default) — Auto-detect based on `process.stdout.isTTY` and the
- *     `FORCE_COLOR` / `NO_COLOR` environment variables.
- * @param options.usageOnHelp - When `true` (default), registers a `--help` flag that
- *   prints the usage summary and exits with code `0`.
- * @param options.usageOnError - When `true` (default), prints the usage summary to
- *   stderr before the error message whenever argument parsing fails.
- * @param options.buildVersion - When provided, registers a `--version` flag that prints
- *   `<cliName> <buildVersion>` to stdout and exits with code `0`.
- * @param options.onError - Custom handler for errors thrown during command execution.
- *   If omitted, the error is printed to stderr via {@link TypoSupport}.
- * @param options.onExit - Overrides the process exit function (default: `process.exit`).
- *   Useful for testing — supply a function that throws or captures the exit code instead
- *   of actually terminating the process.
- *
- * @returns A `Promise<never>` because the function always terminates by calling `onExit`.
+ * Main entry point: parses CLI arguments, executes the matched command, and exits.
+ * Handles `--help`, `--version`, usage-on-error, and exit codes.
+ *
+ * Exit codes: `0` on success / `--help` / `--version`; `1` on parse or execution error.
+ *
+ * @typeParam Context - Passed unchanged to the command handler; use to inject dependencies.
+ *
+ * @param cliName - Program name used in usage and `--version` output.
+ * @param cliArgs - Raw arguments, typically `process.argv.slice(2)`.
+ * @param context - Forwarded to the command handler, injected dependencies.
+ * @param command - Root {@link Command}.
+ * @param options - Optional runner configuration.
+ * @param options.useTtyColors - Color mode: `true` (always), `false` (never),
+ *   `"mock"` (snapshot-friendly), `undefined` (auto-detect from env).
+ * @param options.usageOnHelp - Enables `--help` flag (default `true`).
+ * @param options.usageOnError - Prints usage to stderr on parse error (default `true`).
+ * @param options.buildVersion - Enables `--version`; prints `<cliName> <buildVersion>`.
+ * @param options.onError - Custom handler for errors.
+ * @param options.onExit - Overrides `process.exit`; useful for testing.
+ *
+ * @returns `Promise<never>` — always calls `onExit`.
  *
  * @example
  * ```ts
@@ -1251,282 +988,231 @@ declare function runAndExit<Context>(cliName: Lowercase<string>, cliArgs: Readon
 }): Promise<never>;
 
 /**
- * Available foreground and background color names for terminal styling.
- *
- * Colors are divided into two groups:
- * - **dark** variants correspond to standard ANSI colors (codes 30–37 / 40–47).
- * - **bright** variants correspond to high-intensity ANSI colors (codes 90–97 / 100–107).
- *
- * Used by {@link TypoStyle}'s `fgColor` and `bgColor` fields.
+ * Color names for terminal styling, used by {@link TypoStyle}.
+ * `dark*` = standard ANSI (30–37); `bright*` = high-intensity (90–97).
  */
 type TypoColor = "darkBlack" | "darkRed" | "darkGreen" | "darkYellow" | "darkBlue" | "darkMagenta" | "darkCyan" | "darkWhite" | "brightBlack" | "brightRed" | "brightGreen" | "brightYellow" | "brightBlue" | "brightMagenta" | "brightCyan" | "brightWhite";
 /**
- * Describes the visual styling to apply to a text segment when rendered by a
- * {@link TypoSupport} instance.
- *
- * All fields are optional. When `TypoSupport` is in `"none"` mode, no styling is
- * applied and the raw text is returned unchanged. In `"tty"` mode the corresponding
- * ANSI escape codes are emitted. In `"mock"` mode a deterministic textual representation
- * is produced (useful for snapshot tests).
+ * Visual styling applied by a {@link TypoSupport} instance.
+ * All fields are optional; ignored entirely in `"none"` mode.
  */
 type TypoStyle = {
-    /** Foreground (text) color. */
+    /**
+     * Foreground (text) color.
+     */
     fgColor?: TypoColor;
-    /** Background color. */
+    /**
+     * Background color.
+     */
     bgColor?: TypoColor;
-    /** Render the text with reduced intensity. */
+    /**
+     * Render with reduced intensity.
+     */
     dim?: boolean;
-    /** Render the text in bold. */
+    /**
+     * Render in bold.
+     */
     bold?: boolean;
-    /** Render the text in italic. */
+    /**
+     * Render in italic.
+     */
     italic?: boolean;
-    /** Render the text with an underline. */
+    /**
+     * Render with an underline.
+     */
     underline?: boolean;
-    /** Render the text with a strikethrough. */
+    /**
+     * Render with a strikethrough.
+     */
     strikethrough?: boolean;
 };
 /**
- * Pre-defined {@link TypoStyle} for section titles in the usage output (e.g.
- * `"Positionals:"`, `"Options:"`).
- * Rendered in bold dark-green.
+ * Pre-defined style for section titles (e.g. `"Positionals:"`). Bold dark-green.
  */
 declare const typoStyleTitle: TypoStyle;
-/** Pre-defined {@link TypoStyle} for logic/type identifiers in error messages. Rendered in bold dark-magenta. */
+/**
+ * Pre-defined style for logic/type identifiers in error messages. Bold dark-magenta.
+ */
 declare const typoStyleLogic: TypoStyle;
-/** Pre-defined {@link TypoStyle} for quoted user-supplied values in error messages. Rendered in bold dark-yellow. */
+/**
+ * Pre-defined style for quoted user-supplied values in error messages. Bold dark-yellow.
+ */
 declare const typoStyleQuote: TypoStyle;
-/** Pre-defined {@link TypoStyle} for failure/error labels (e.g. `"Error:"`). Rendered in bold dark-red. */
+/**
+ * Pre-defined style for failure/error labels (e.g. `"Error:"`). Bold dark-red.
+ */
 declare const typoStyleFailure: TypoStyle;
-/** Pre-defined {@link TypoStyle} for CLI flag/option/command constant names. Rendered in bold dark-cyan. */
+/**
+ * Pre-defined style for CLI flag/option/command names. Bold dark-cyan.
+ */
 declare const typoStyleConstants: TypoStyle;
-/** Pre-defined {@link TypoStyle} for positional placeholders and user-input labels. Rendered in bold dark-blue. */
+/**
+ * Pre-defined style for positional placeholders and user-input labels. Bold dark-blue.
+ */
 declare const typoStyleUserInput: TypoStyle;
-/** Pre-defined {@link TypoStyle} for strong regular text (e.g. command descriptions). Rendered in bold. */
+/**
+ * Pre-defined style for strong regular text (e.g. command descriptions). Bold.
+ */
 declare const typoStyleRegularStrong: TypoStyle;
-/** Pre-defined {@link TypoStyle} for subtle supplementary text (e.g. hints). Rendered in italic and dim. */
+/**
+ * Pre-defined style for subtle supplementary text (e.g. hints). Italic and dim.
+ */
 declare const typoStyleRegularWeaker: TypoStyle;
 /**
- * An immutable styled string segment consisting of a raw text value and an associated
- * {@link TypoStyle}.
- *
- * Multiple `TypoString`s are composed into a {@link TypoText} for multi-part messages.
- * Rendering is deferred until {@link TypoString.computeStyledString} is called with a
- * {@link TypoSupport} instance.
+ * An immutable styled string segment: a raw text value paired with a {@link TypoStyle}.
+ * Compose multiple segments into a {@link TypoText}; rendering is deferred to {@link TypoString.computeStyledString}.
  */
 declare class TypoString {
     #private;
     /**
-     * @param value - The raw text content.
-     * @param typoStyle - The style to apply when rendering. Defaults to `{}` (no style).
+     * @param value - Raw text content.
+     * @param typoStyle - Style to apply when rendering. Defaults to `{}` (no style).
      */
     constructor(value: string, typoStyle?: TypoStyle);
-    /** Returns the unstyled raw text content. */
+    /**
+     * Returns the unstyled raw text content.
+     */
     getRawString(): string;
     /**
-     * Returns the text with ANSI escape codes (or mock markers) applied by `typoSupport`.
+     * Returns the text styled by `typoSupport`.
      *
-     * @param typoSupport - Controls how styles are rendered (tty colors, mock, or none).
+     * @param typoSupport - Rendering mode.
      */
     computeStyledString(typoSupport: TypoSupport): string;
 }
 /**
- * A mutable sequence of {@link TypoString} segments that together form a styled
- * multi-part message.
- *
- * `TypoText` is used throughout the library to build error messages and usage output
- * that carry styling information without being coupled to a specific output mode.
+ * A mutable sequence of {@link TypoString} segments forming a styled multi-part message.
  * Rendering is deferred to {@link TypoText.computeStyledString}.
  */
 declare class TypoText {
     #private;
     /**
-     * Creates a `TypoText` pre-populated with the provided parts. Each part can be a
-     * `TypoText` (flattened by value), a `TypoString`, or a plain `string` (wrapped in an
-     * unstyled `TypoString`).
-     *
-     * @param typoParts - Initial parts to append. Can be any mix of `TypoText`,
-     *   `TypoString`, and `string`.
+     * @param typoParts - Initial segments; `TypoText` is flattened, `string` is wrapped unstyled.
      */
     constructor(...typoParts: Array<TypoText | TypoString | string>);
     /**
-     * Appends a single {@link TypoString} segment to the end of this text.
+     * Appends a {@link TypoString} segment.
      *
-     * @param typoString - The segment to append.
+     * @param typoString - Segment to append.
      */
-    pushString(typoString: TypoString): void;
+    pushString(typoString: TypoString | string): void;
     /**
-     * Appends all segments from another {@link TypoText} to the end of this text
-     * (shallow copy of segments).
+     * Appends all segments from another {@link TypoText} (shallow copy).
      *
-     * @param typoText - The text whose segments are appended.
+     * @param typoText - Source text.
      */
-    pushText(typoText: TypoText): void;
+    pushText(typoText: TypoText | string): void;
     /**
-     * Renders all segments into a single string, applying styles via `typoSupport`.
+     * Renders all segments into a single styled string.
      *
-     * @param typoSupport - Controls how styles are rendered.
-     * @returns The concatenated, optionally styled string.
+     * @param typoSupport - Rendering mode.
+     * @returns Concatenated styled string.
      */
     computeStyledString(typoSupport: TypoSupport): string;
     /**
      * Returns the concatenation of all segments' raw (unstyled) text.
-     * Equivalent to calling {@link TypoText.computeStyledString} with
-     * {@link TypoSupport.none}.
      */
     computeRawString(): string;
     /**
-     * Returns the total character length of the raw (unstyled) text.
-     * Used by {@link TypoGrid} to compute column widths for alignment.
+     * Returns the total character count of the raw (unstyled) text.
      */
     computeRawLength(): number;
 }
 /**
- * A grid of {@link TypoText} cells that renders with column-aligned padding.
- *
- * Each row is an array of `TypoText` cells. When {@link TypoGrid.computeStyledGrid} is
- * called, each column is padded to the width of its widest cell (measured in raw
- * characters). The last column in each row is **not** padded.
- *
- * Used internally by {@link usageToStyledLines} to render the `Positionals:`,
- * `Subcommands:`, and `Options:` sections with neat alignment.
+ * A column-aligned grid of {@link TypoText} cells.
+ * Each column is padded to the widest cell (raw chars); the last column is not padded.
+ * Used by {@link usageToStyledLines} to render `Positionals:`, `Subcommands:`, and `Options:`.
  */
 declare class TypoGrid {
     #private;
     constructor();
     /**
-     * Appends a row of cells to the grid.
+     * Appends a row. All rows should have the same cell count for alignment to be meaningful.
      *
-     * @param cells - An ordered array of {@link TypoText} cells for this row. All rows
-     *   should have the same number of cells for alignment to be meaningful.
+     * @param cells - Ordered {@link TypoText} cells.
      */
     pushRow(cells: Array<TypoText>): void;
     /**
-     * Renders the grid into a 2-D array of styled strings, with space padding added
-     * between columns (except after the last column).
+     * Renders the grid as a 2-D array of styled (and column-padded) strings.
+     * Join each inner array with `""` to get a line.
      *
-     * @param typoSupport - Controls how styles are rendered.
-     * @returns A 2-D array where each inner array is the styled (and padded) cells of
-     *   one row. Join the inner arrays with `""` to get a single line string.
+     * @param typoSupport - Rendering mode.
+     * @returns 2-D array of styled strings.
      */
     computeStyledGrid(typoSupport: TypoSupport): Array<Array<string>>;
 }
 /**
- * An `Error` subclass that carries a {@link TypoText} styled message in addition to
- * the plain-text `Error.message` used by the standard JS error chain.
- *
- * `TypoError` is used throughout `cli-kiss` to report parsing failures (unknown option,
- * type decoding error, missing required argument, etc.). Its styled representation is
- * rendered by {@link TypoSupport.computeStyledErrorMessage} when outputting errors to
- * the terminal.
- *
- * Errors can be chained: if `source` is a `TypoError`, its styled text is appended
- * after `": "` to form the full message context chain.
+ * `Error` subclass with a {@link TypoText} styled message for rich terminal output.
+ * Used throughout the library for parse failures (unknown option, type decode error, etc.).
+ * If `source` is a `TypoError`, its styled text is chained after `": "`.
  */
 declare class TypoError extends Error {
     #private;
     /**
-     * @param currentTypoText - The styled message for this error level.
-     * @param source - An optional cause. If it is a `TypoError`, its styled text is
-     *   appended (chained context). If it is a plain `Error`, its `.message` is appended
-     *   as a plain string. Any other value is stringified with `String()`.
+     * @param currentTypoText - Styled message for this error.
+     * @param source - Optional cause; `TypoError` chains styled text, `Error` appends `.message`, else `String()`.
      */
     constructor(currentTypoText: TypoText, source?: unknown);
     /**
-     * Renders this error's styled message as a string.
+     * Renders the styled error message (without a `"Error:"` prefix).
      *
-     * @param typoSupport - Controls how ANSI styles are applied.
-     * @returns The full styled error message (without a leading `"Error:"` prefix).
+     * @param typoSupport - Rendering mode.
+     * @returns Styled error string.
      */
     computeStyledString(typoSupport: TypoSupport): string;
     /**
-     * Executes `thrower` and returns its result. If `thrower` throws any error, the error
-     * is re-thrown as a new `TypoError` whose message is `context()` with the original
-     * error chained as the source.
-     *
-     * This is a convenience helper for adding contextual information to errors that arise
-     * deep in a call chain (e.g. "at 0: Number: Unable to parse: ...").
+     * Runs `thrower`; on any throw wraps it as a `TypoError` with `context()` prepended.
+     * Useful for adding call-chain context (e.g. `"at 0: Number: ..."`).
      *
-     * @typeParam Value - The return type of `thrower`.
-     * @param thrower - A zero-argument function whose return value is passed through on
-     *   success.
-     * @param context - A zero-argument factory that produces the {@link TypoText} context
-     *   prepended to the caught error. Called only when `thrower` throws.
-     * @returns The value returned by `thrower`.
-     * @throws `TypoError` wrapping the original error with the provided context prepended.
+     * @typeParam Value - Return type of `thrower`.
+     * @param thrower - Function to execute; result passed through on success.
+     * @param context - Produces the {@link TypoText} prepended to the caught error.
+     * @returns Value from `thrower`.
+     * @throws `TypoError` wrapping the original error with context prepended.
      */
     static tryWithContext<Value>(thrower: () => Value, context: () => TypoText): Value;
 }
 /**
- * Controls whether and how ANSI terminal styling is applied when rendering
- * {@link TypoString}, {@link TypoText}, and error messages.
- *
- * Instances are created via the static factory methods:
- * - {@link TypoSupport.none} — strips all styling (plain text).
- * - {@link TypoSupport.tty} — applies ANSI escape codes for color terminals.
- * - {@link TypoSupport.mock} — applies a deterministic textual representation useful
- *   for snapshot tests.
- * - {@link TypoSupport.inferFromProcess} — auto-detects based on `process.stdout.isTTY`
- *   and the `FORCE_COLOR` / `NO_COLOR` environment variables.
- *
- * `TypoSupport` is consumed by {@link runAndExit} (via the `useTtyColors` option)
- * and can also be used directly when building custom usage renderers with {@link usageToStyledLines}.
+ * Controls ANSI terminal styling for {@link TypoString}, {@link TypoText}, and error rendering.
+ * Create via {@link TypoSupport.none}, {@link TypoSupport.tty}, {@link TypoSupport.mock},
+ * or {@link TypoSupport.inferFromProcess}.
  */
 declare class TypoSupport {
     #private;
     private constructor();
     /**
-     * Returns a `TypoSupport` that strips all styling — every styled string is returned
-     * as-is (plain text, no ANSI codes).
+     * Returns a `TypoSupport` that strips all styling (plain text, no ANSI codes).
      */
     static none(): TypoSupport;
     /**
-     * Returns a `TypoSupport` that applies ANSI escape codes.
-     * Use this when writing to a color-capable terminal (`stdout.isTTY === true`).
+     * Returns a `TypoSupport` that applies ANSI escape codes (for color-capable terminals).
      */
     static tty(): TypoSupport;
     /**
-     * Returns a `TypoSupport` that applies a deterministic mock styling representation.
-     *
-     * Instead of real ANSI codes, each style flag is expressed as a readable suffix:
-     * `{text}@color`, `{text}+` (bold), `{text}-` (dim), `{text}*` (italic),
-     * `{text}_` (underline), `{text}~` (strikethrough). Useful for snapshot testing.
+     * Returns a `TypoSupport` with deterministic textual styling for snapshot tests.
+     * Style flags appear as suffixes: `{text}@color`, `{text}+` (bold), `{text}-` (dim),
+     * `{text}*` (italic), `{text}_` (underline), `{text}~` (strikethrough).
      */
     static mock(): TypoSupport;
     /**
-     * Selects a `TypoSupport` mode automatically based on the current process environment:
-     *
-     * 1. `FORCE_COLOR=0` or `NO_COLOR` env var set → {@link TypoSupport.none}.
-     * 2. `FORCE_COLOR` env var set (any truthy value) → {@link TypoSupport.tty}.
-     * 3. `process.stdout.isTTY === true` → {@link TypoSupport.tty}.
-     * 4. Otherwise → {@link TypoSupport.none}.
-     *
-     * Falls back to {@link TypoSupport.none} if `process` is not available (e.g. in a
-     * non-Node environment).
+     * Auto-detects styling mode from the process environment.
+     * `FORCE_COLOR=0` / `NO_COLOR` → none; `FORCE_COLOR` (truthy) / `isTTY` → tty; else → none.
+     * Falls back to none if `process` is unavailable.
      */
     static inferFromProcess(): TypoSupport;
     /**
-     * Applies the given {@link TypoStyle} to `value` and returns the styled string.
+     * Applies `typoStyle` to `value` according to the current mode.
      *
-     * - In `"none"` mode: returns `value` unchanged.
-     * - In `"tty"` mode: wraps `value` in ANSI escape codes and appends a reset code.
-     * - In `"mock"` mode: wraps `value` in a deterministic textual representation.
-     *
-     * @param value - The raw text to style.
-     * @param typoStyle - The style to apply.
-     * @returns The styled string.
+     * @param value - Raw text.
+     * @param typoStyle - Style to apply.
+     * @returns Styled string.
      */
     computeStyledString(value: string, typoStyle: TypoStyle): string;
     /**
-     * Formats an error value as a styled `"Error: <message>"` string.
-     *
-     * - If `error` is a {@link TypoError}, its styled text is used for the message part.
-     * - If `error` is a plain `Error`, its `.message` property is used.
-     * - Otherwise `String(error)` is used.
+     * Formats any thrown value as `"Error: <message>"` with {@link typoStyleFailure} on the prefix.
      *
-     * The `"Error:"` prefix is always styled with {@link typoStyleFailure}.
-     *
-     * @param error - The error to format (any value thrown by a handler).
-     * @returns A styled error string ready to print to stderr.
+     * @param error - Any thrown value.
+     * @returns Styled error string.
      */
     computeStyledErrorMessage(error: unknown): string;
 }
@@ -1537,7 +1223,7 @@ declare class TypoSupport {
  *
  * The output format is:
  * ```
- * Usage: <cliName> [breadcrumbs...]
+ * Usage: <cliName> [segments...]
  *
  * <description> (<hint>)
  * <detail lines...>
@@ -1551,23 +1237,26 @@ declare class TypoSupport {
  * Options:
  *   -s, --long <LABEL>  <description> (<hint>)
  *
+ * Examples:
+ *   <description>
+ *   <command line>
+ *
  * ```
  * Sections that have no entries are omitted. The trailing empty line is always included.
  *
  * Column alignment within each section is handled by {@link TypoGrid}: the widest entry
  * in each column sets the width for the entire section.
  *
- * @param params.cliName - The CLI program name shown at the start of the usage line.
- * @param params.commandUsage - The usage model produced by {@link CommandFactory.generateUsage}.
- * @param params.typoSupport - Controls color/styling of the output.
- * @returns An ordered array of strings, one per output line (including a trailing
- *   empty string for the blank line at the end).
+ * @param params.cliName - Program name for the usage line.
+ * @param params.commandUsage - From {@link CommandDecoder.generateUsage}.
+ * @param params.typoSupport - Rendering mode.
+ * @returns One string per output line; trailing empty string for the blank line at the end.
  *
  * @example
  * ```ts
  * const lines = usageToStyledLines({
  *   cliName: "my-cli",
- *   commandUsage: commandFactory.generateUsage(),
+ *   commandUsage: commandDecoder.generateUsage(),
  *   typoSupport: TypoSupport.tty(),
  * });
  * process.stdout.write(lines.join("\n"));
@@ -1579,4 +1268,4 @@ declare function usageToStyledLines(params: {
     typoSupport: TypoSupport;
 }): string[];
 
-export { type Command, type CommandFactory, type CommandInformation, type CommandInstance, type CommandUsage, type CommandUsageBreadcrumb, type CommandUsageSubcommand, type Operation, type OperationFactory, type OperationInstance, type OperationUsage, type Option, type OptionParser, type OptionUsage, type Positional, type PositionalParser, type PositionalUsage, ReaderArgs, type ReaderOptionKey, type ReaderOptions, type ReaderPositionals, type Type, type TypoColor, TypoError, TypoGrid, TypoString, type TypoStyle, TypoSupport, TypoText, command, commandChained, commandWithSubcommands, operation, optionFlag, optionRepeatable, optionSingleValue, positionalOptional, positionalRequired, positionalVariadics, runAndExit, typeBoolean, typeConverted, typeDate, typeInteger, typeList, typeNumber, typeOneOf, typeString, typeTuple, typeUrl, typoStyleConstants, typoStyleFailure, typoStyleLogic, typoStyleQuote, typoStyleRegularStrong, typoStyleRegularWeaker, typoStyleTitle, typoStyleUserInput, usageToStyledLines };
+export { type Command, type CommandDecoder, type CommandInformation, type CommandInterpreter, type CommandUsage, type CommandUsageSegment, type CommandUsageSubcommand, type Operation, type OperationDecoder, type OperationInterpreter, type OperationUsage, type Option, type OptionDecoder, type OptionUsage, type Positional, type PositionalDecoder, type PositionalUsage, ReaderArgs, type ReaderOptionKey, type ReaderOptions, type ReaderPositionals, type Type, type TypoColor, TypoError, TypoGrid, TypoString, type TypoStyle, TypoSupport, TypoText, command, commandChained, commandWithSubcommands, operation, optionFlag, optionRepeatable, optionSingleValue, positionalOptional, positionalRequired, positionalVariadics, runAndExit, typeBoolean, typeDate, typeInteger, typeList, typeMapped, typeNumber, typeOneOf, typeString, typeTuple, typeUrl, typoStyleConstants, typoStyleFailure, typoStyleLogic, typoStyleQuote, typoStyleRegularStrong, typoStyleRegularWeaker, typoStyleTitle, typoStyleUserInput, usageToStyledLines };