zod-args-parser 2.0.0-beta.1 → 2.0.0-beta.3

package/LICENSE

@@ -19,3 +19,4 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
+

package/README.md

@@ -16,25 +16,31 @@ A strictly typed command-line arguments parser powered by schema validation.
   - [Creating a subcommand](#creating-a-subcommand)
   - [Creating options](#creating-options)
   - [Creating typed arguments](#creating-typed-arguments)
+  - [Sharing options and typed arguments](#sharing-options-and-typed-arguments)
   - [Using Schemas](#using-schemas)
   - [Default Values and Optional Inputs](#default-values-and-optional-inputs)
   - [Positionals vs Typed Arguments](#positionals-vs-typed-arguments)
   - [Option and Argument Constraints](#option-and-argument-constraints)
   - [Negating a boolean option](#negating-a-boolean-option)
+  - [Structured Object Options](#structured-object-options)
+  - [Execute commands programmatically](#execute-commands-programmatically)
   - [Creating a Custom Help Message Style](#creating-a-custom-help-message-style)
   - [Help Message as HTML](#help-message-as-html)
+  - [Handling and Inspecting Errors](#handling-and-inspecting-errors)
+  - [Loading from a CDN](#loading-from-a-cdn)
 - [API Reference](#api-reference)
-  - [Type Utilities](#type-utilities)
-  - [Coerce Helpers](#coerce-helpers)
-  - [Markdown Generation](#markdown-generation)
-  - [Autocompletion Script Generation](#autocompletion-script-generation)
-  - [Help Message](#help-message)
-  - [PrintHelpOptions](#printhelpoptions)
-  - [Cli](#cli)
-  - [Subcommand](#subcommand)
-  - [Option](#option)
-  - [Argument](#argument)
-  - [Context Type](#context-type)
+  - [Type Utilities](docs/api-reference.md#type-utilities)
+  - [Coerce Helpers](docs/api-reference.md#coerce-helpers)
+  - [Markdown Generation](docs/api-reference.md#markdown-generation)
+  - [Autocompletion Script Generation](docs/api-reference.md#autocompletion-script-generation)
+  - [Help Message](docs/api-reference.md#help-message)
+  - [PrintHelpOptions](docs/api-reference.md#printhelpoptions)
+  - [Cli](docs/api-reference.md#cli)
+  - [Subcommand](docs/api-reference.md#subcommand)
+  - [Option](docs/api-reference.md#option)
+  - [Argument](docs/api-reference.md#argument)
+  - [Context Type](docs/api-reference.md#context-type)
+  - [Error Types](docs/api-reference.md#error-types)
 - [License](#license)
 
 ## Features
@@ -65,46 +71,24 @@ The following example uses `zod` as the validation library, but you can use any
 import * as z from "zod";
 import { defineCLI, coerce } from "zod-args-parser";
 
-// Define the CLI program (main command)
-const listyCLI = defineCLI({
-  cliName: "listy",
-
-  subcommands: [
-    // ...
-  ],
-
+const cli = defineCLI({
+  cliName: "hello",
   options: {
-    help: {
-      schema: z.boolean().optional(),
-      coerce: coerce.boolean,
+    /** `--name` or `-n` */
+    name: {
+      aliases: ["n"],
+      schema: z.string().default("world"),
     },
   },
-
-  arguments: {
-    // ...
-  },
 });
 
-// When the CLI (main command) is executed
-listyCLI.onExecute(results => {
-  const { help } = results.options;
-
-  // print help for the CLI
-  if (help && listyCLI.generateCliHelpMessage) {
-    console.log(listyCLI.generateCliHelpMessage());
-    return;
-  }
-
-  console.error("Please try `listy --help`");
+cli.onExecute(({ options }) => {
+  console.log(`Hello, ${options.name}!`);
 });
 
-// Run the CLI and pass in the command line arguments
-const results = listyCLI.run(process.argv.slice(2));
-
-// Inspect parsed results
-if (results.error) {
-  console.error(results.error.message);
-  console.log("\n`listy --help` for more information");
+const result = cli.run(process.argv.slice(2));
+if (result.error) {
+  console.error(result.error.message);
 }
 ```
 
@@ -220,6 +204,7 @@ Option names can use any common case style:
 - LIST_NAME `=>` --list-name
 
 ```ts
+import * as z from "zod";
 import { defineSubcommand, coerce } from "zod-args-parser";
 
 const createListCommand = defineSubcommand({
@@ -329,6 +314,52 @@ const createListCommand = defineSubcommand({
 });
 ```
 
+### Sharing options and typed arguments
+
+Options and typed arguments can be shared between subcommands/main CLI.
+
+```ts
+// shared.ts
+import * as z from "zod";
+import { defineArguments, defineOptions, coerce } from "zod-args-parser";
+
+export const sharedOptions = defineOptions({
+  verbose: {
+    schema: z.boolean().optional(),
+    coerce: coerce.boolean,
+    meta: {
+      description: "Enable verbose mode.",
+    },
+  },
+});
+
+export const sharedArguments = defineArguments({
+  // ...
+});
+```
+
+```ts
+// add-command.ts
+import * as z from "zod";
+import { defineSubcommand, coerce } from "zod-args-parser";
+
+import { sharedOptions, sharedArguments } from "./shared.ts";
+
+export const addCommand = defineSubcommand({
+  //...
+
+  options: {
+    // ...
+    ...sharedOptions,
+  },
+
+  arguments: {
+    // ...
+    ...sharedArguments,
+  },
+});
+```
+
 ### Using schemas
 
 Other validation libraries can be used as long as they support [`StandardSchemaV1`](https://github.com/standard-schema/standard-schema) and allow primitive types to be optional or have default values.
@@ -392,17 +423,130 @@ Both options and typed arguments support rules to control valid combinations:
 
 ### Negating a boolean option
 
-Boolean options can be negated by prefixing them with `no-` or by using the equals sign `=`.
+Boolean flags are `true` when they appear on the command line.  
+Prefixing a flag with `--no-` inverts its final value.
+
+When a value is explicitly assigned (`=true` or `=false`), the assignment is applied first, then the `--no-` prefix flips the result.
+
+Examples:
+
+```sh
+--bool           true
+--no-bool        false
+```
+
+```sh
+--bool=true      true
+--bool=false     false
+```
+
+```sh
+--no-bool=true   false   # assigned true → inverted
+--no-bool=false  true    # assigned false → inverted
+```
+
+Short-form flags follow the same logic, but do **not** accept `=value` syntax:
+
+```sh
+-v               true
+--no-v           false
+```
+
+```sh
+-v=true          ERROR
+-v=false         ERROR
+```
+
+```sh
+--no-v=true      false
+--no-v=false     true
+```
+
+### Structured Object Options
+
+Options using `coerce.object` receive **stringified JSON** and are parsed with `JSON.parse`.  
+They also support **dotted flags** to assign nested fields without writing full JSON.
+
+See [Coerce Helpers](./docs/api-reference.md#coerce-helpers).
+
+```ts
+import * as z from "zod";
+import { defineCLI, coerce } from "zod-args-parser";
+
+const cli = defineCLI({
+  cliName: "listy",
+  options: {
+    db: {
+      schema: z
+        .object({
+          host: z.string().default("localhost"),
+          port: z.number().default(5432),
+          https: z.boolean().default(false),
+          credentials: z.object({
+            user: z.string(),
+            pass: z.string(),
+          }),
+        })
+        .optional(),
+
+      // Accepts either a full JSON string or individual "dotted" flags,
+      // parsed with JSON.parse.
+      coerce: coerce.object({ coerceBoolean: true, coerceNumber: ["port"] }),
+
+      meta: {
+        placeholder: "<.host,.port,.credentials.user,.credentials.pass>",
+        description: "Database configuration object. Parsed as JSON; supports dotted flags.",
+        example: "--db.host=prod-db --db.credentials.user=alice --db.credentials.pass=secret",
+      },
+    },
+  },
+});
+
+cli.onExecute(({ options }) => {
+  console.log(options.db);
+});
+```
+
+#### Usage Examples
 
 ```sh
---bool        true
---no-bool     false
+# Dotted flags for nested values using `=`
+listy --db.https=true --db.host=db.local --db.port=3306 --db.credentials.user=root --db.credentials.pass=toor
+
+# Dotted flags for nested values without `=`
+listy --db.https true --db.host db.local --db.port 3306 --db.credentials.user root --db.credentials.pass toor
+
+# Full JSON input (stringified)
+listy --db '{"host":"db.local","https":true,"credentials":{"user":"root","pass":"toor"}}'
+```
+
+### Execute commands programmatically
+
+You can execute the main CLI or a specific subcommand directly from code.  
+The input is provided as an object (`{ options, arguments, positionals }`) and is validated using the defined schemas.  
+Invalid input throws an error. Use `.executeAsync()` if your `onExecute` handler is asynchronous.
+
+> [!NOTE]  
+> `run()` is like calling the CLI from the terminal.
+> `execute()` is like calling a function directly.
 
---bool=true   true
---bool=false  false
+```ts
+import { InferOptionsInputType } from "zod-args-parser";
+
+import { listyCLI } from "./cli.ts";
+
+// In this example, Listy only defines options — no typed arguments or positionals.
+// To keep the function simple, we accept only the options as input.
+
+/** @throws {CliError} */
+export function executeListy(options: InferOptionsInputType<typeof listyCLI>) {
+  listyCLI.execute({ options });
+}
 
--v            true
---no-v        false
+/** @throws {CliError} */
+export async function executeListyAsync(options: InferOptionsInputType<typeof listyCLI>) {
+  await listyCLI.executeAsync({ options });
+}
 ```
 
 ### Creating a Custom Help Message Style
@@ -452,257 +596,75 @@ span._markdown * {
 }
 ```
 
-## API Reference
-
-### Type Utilities
-
-#### `InferInputType<T extends Cli | Subcommand>`
+### Handling and Inspecting Errors
 
-Infer options, arguments, and positionals input types from the CLI/subcommand definition.
+The library processes input in four stages. Errors can occur at any step:
 
-#### `InferOutputType<T extends Cli | Subcommand>`
+1. **Definition Validation** — Ensures the CLI and subcommand definitions are valid.
+2. **Argument Parsing** — Reads terminal input and builds the initial parse result.
+3. **Context Validation** — Applies schema validation and dependency rules.
+4. **Execution** — Runs the command or subcommand once all checks succeed.
 
-Infer options, arguments, and positionals output types from the CLI/subcommand definition.
+After running your CLI, the returned result may contain an error. You can narrow down the error by its **cause** or **code** to handle it specifically.
 
-#### `InferOptionsInputType<T extends Cli | Subcommand>`
-
-Infer options input type from the CLI/subcommand definition.
-
-#### `InferOptionsOutputType<T extends Cli | Subcommand>`
-
-Infer options output type from the CLI/subcommand definition.
-
-#### `InferArgumentsInputType<T extends Cli | Subcommand>`
-
-Infer arguments input type from the CLI/subcommand definition.
-
-#### `InferArgumentsOutputType<T extends Cli | Subcommand>`
-
-Infer arguments output type from the CLI/subcommand definition.
+See [Error Reference](./docs/api-reference.md#error-types)
 
 ```ts
-import type { defineSubcommand, InferInputType, InferOutputType } from "zod-args-parser";
-
-const subcommand = defineSubcommand({
-  // ...
-});
-
-type InputType = InferInputType<typeof subcommand>;
-type OutputType = InferOutputType<typeof subcommand>;
-```
-
-### Coerce Helpers
-
-- `coerce.string`
-- `coerce.number`
-- `coerce.boolean`
-- `coerce.stringArray(separator: string)`
-- `coerce.numberArray(separator: string)`
-- `coerce.booleanArray(separator: string)`
-- `coerce.stringSet(separator: string)`
-- `coerce.numberSet(separator: string)`
-- `coerce.booleanSet(separator: string)`
-- `coerce.json<T>()`
-
-### Markdown Generation
-
-#### generateMarkdown
-
-`(cliDefinition: Cli) => string`
-
-Generate markdown documentation for a **CLI definition** and return it as a `string`.
-
-### Autocomplete Script Generation
-
-#### generateBashAutocompleteScript
-
-`(cliDefinition: Cli) => string`
-
-Generate a Bash autocomplete script for a **CLI definition** and return it as a `string`.
-
-#### generateZshAutocompleteScript
-
-`(cliDefinition: Cli) => string`
-
-Generate a zsh autocomplete script for a **CLI definition** and return it as a `string`.
-
-#### generatePowerShellAutocompleteScript
-
-`(cliDefinition: Cli) => string`
+import { ErrorCause, ValidationErrorCode } from "zod-args-parser";
 
-Generate a PowerShell autocomplete script for a **CLI definition** and return it as a `string`.
+const results = listyCLI.run(input);
 
-### Help Message
-
-#### generateCliHelpMessage
-
-`(cliDefinition: Cli, printOptions?: PrintHelpOptions) => string`
-
-Generate a help message for a **CLI definition** and return it as a `string`.  
-See [`PrintHelpOptions`](#printhelpoptions) and [`Cli`](#cli).
-
-#### generateSubcommandHelpMessage
-
-`(commandDefinition: Subcommand, options?: PrintHelpOptions, cliName?: string) => string`
-
-Generate a help message for a **subcommand definition** and return it as a `string`.  
-See [`PrintHelpOptions`](#printhelpoptions) and [`Subcommand`](#subcommand).
-
-#### printCliHelp
-
-`(cliDefinition: Cli, options?: PrintHelpOptions) => void`
-
-Print a help message for a **CLI definition**.  
-See [`PrintHelpOptions`](#printhelpoptions) and [`Cli`](#cli).
+if (results.error) {
+  // Check the type of error by its cause
+  if (results.error.cause === ErrorCause.Parse) {
+    // Handle parsing-related errors
+  }
 
-#### printSubcommandHelp
+  // Check for a specific error code
+  if (results.error.code === ValidationErrorCode.SchemaValidationFailed) {
+    const { commandKind, commandName, kind, name, inputValue, issues } = results.error.context;
 
-`(commandDefinition: Subcommand, options?: PrintHelpOptions, cliName?: string) => void`
+    console.error(
+      "validation error:",
+      `the ${kind} "${name}"`,
+      `for ${commandKind} "${commandName}" failed to validate the input:`,
+      inputValue,
+    );
 
-Print a help message for a **subcommand definition**.  
-See [`PrintHelpOptions`](#printhelpoptions) and [`Subcommand`](#subcommand).
+    // Detailed validation issues
+    console.log(issues);
+  }
+}
+```
 
-### PrintHelpOptions
+### Loading from a CDN
 
-| Option                  | Type                   | Default                     | Description                                                                         |
-| ----------------------- | ---------------------- | --------------------------- | ----------------------------------------------------------------------------------- |
-| style                   | `HelpMessageStyle`     | `helpMessageStyles.default` | The style to use for the help message.                                              |
-| kebabCaseArgumentName   | `boolean`              | `true`                      | Whether to transform the argument (not option) name to kebab case.                  |
-| markdownRenderer        | `"terminal" \| "html"` | `"terminal"`                | The renderer to use for the markdown.                                               |
-| indentBeforeName        | `number`               | `2`                         | The number of spaces before the name of option/argument/subcommand.                 |
-| indentAfterName         | `number`               | `4`                         | Spaces after the name, between the name and description (space between columns).    |
-| indentBeforePlaceholder | `number`               | `1`                         | The number of spaces to put before the placeholder.                                 |
-| newLineIndent           | `number`               | `0`                         | Spaces before a new line for description or example under description.              |
-| emptyLines              | `number`               | `0`                         | Number of empty lines between lines.                                                |
-| emptyLinesBeforeTitle   | `number`               | `1`                         | Number of empty lines before the title.                                             |
-| emptyLinesAfterTitle    | `number`               | `0`                         | Number of empty lines after the title.                                              |
-| exampleKeyword          | `string`               | `"Example:"`                | The keyword to use for examples.                                                    |
-| optionalKeyword         | `string`               | `"(optional)"`              | The keyword to use for optional values.                                             |
-| defaultKeyword          | `string`               | `"(default: {{ value }})"`  | The keyword to indicate default values, with `{{ value }}` replaced by the default. |
-| usageTitle              | `string`               | `"USAGE"`                   | The title to use for the usage section.                                             |
-| descriptionTitle        | `string`               | `"DESCRIPTION"`             | The title to use for the description section.                                       |
-| commandsTitle           | `string`               | `"COMMANDS"`                | The title to use for the commands section.                                          |
-| optionsTitle            | `string`               | `"OPTIONS"`                 | The title to use for the options section.                                           |
-| argumentsTitle          | `string`               | `"ARGUMENTS"`               | The title to use for the arguments section.                                         |
-| exampleTitle            | `string`               | `"EXAMPLE"`                 | The title to use for the examples section.                                          |
+**Global IIFE**
 
-### Cli
+```html
+<!-- using jsdelivr -->
+<script src="https://cdn.jsdelivr.net/npm/zod-args-parser"></script>
 
-| Property            | Type                       | Description                                                                                                                                                                                          |
-| ------------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `cliName`           | `string`                   | The name of the CLI program (main command).                                                                                                                                                          |
-| `subcommands?`      | `Subcommand[]`             | Array of subcommands. Do not manually construct subcommand objects; always create them via `defineSubcommand()` and pass the returned object. See [`Subcommand Definition`](#subcommand-definition). |
-| `allowPositionals?` | `boolean`                  | When `true`, enables positional arguments for the CLI; positionals are untyped `string[]`. If typed `arguments` are present, they are parsed first and any remaining args become `positionals`.      |
-| `options?`          | `Record<string, Option>`   | A dictionary of option definitions keyed by a valid JavaScript variable name (e.g., `inputDir` → `--input-dir`). See [`Option Definition`](#option-definition).                                      |
-| `arguments?`        | `Record<string, Argument>` | Strictly ordered typed arguments. See [`Argument Definition`](#argument-definition).                                                                                                                 |
-| `meta?`             | `CliMeta`                  | Metadata for the CLI used for help messages and documentation generation.                                                                                                                            |
+<!-- using unpkg -->
+<script src="https://unpkg.com/zod-args-parser"></script>
 
-### CliMeta
+<script>
+  // Access the library as a global
+  const { defineCLI, coerce } = ZodArgsParser;
+</script>
+```
 
-| Property               | Type     | Description                                                                                                                     |
-| ---------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------- |
-| `usage?`               | `string` | Usage string example (e.g., `cliName subcommand [options] <arg1> <arg2>`).                                                      |
-| `description?`         | `string` | Short explanation. Supports multi-line text and ANSI colors. Preferred for terminal output when present.                        |
-| `descriptionMarkdown?` | `string` | Markdown-formatted description used for generated documentation and terminal markdown. Used for Markdown generation if present. |
-| `example?`             | `string` | Examples shown to the user (displayed as a code block in Markdown).                                                             |
+**ESM Module**
 
-### Subcommand
+```html
+<script type="module">
+  import { defineCLI, coerce } from "https://cdn.jsdelivr.net/npm/zod-args-parser/+esm";
+</script>
+```
 
-| Property            | Type                       | Description                                                                                                                                                                                             |
-| ------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `name`              | `string`                   | The subcommand name. Must be unique within a CLI across names and aliases.                                                                                                                              |
-| `aliases?`          | `string[]`                 | A list of aliases that can be used to invoke this subcommand. Must not collide with other names or aliases in the same CLI.                                                                             |
-| `allowPositionals?` | `boolean`                  | When `true`, enables positional arguments for this subcommand. Positionals are untyped `string[]`. If typed `arguments` are present, they are parsed first and any remaining args become `positionals`. |
-| `options?`          | `Record<string, Option>`   | A dictionary of option definitions keyed by a valid JavaScript variable name (e.g., `inputDir` → `--input-dir`). See [`Option Definition`](#option-definition).                                         |
-| `arguments?`        | `Record<string, Argument>` | Strictly ordered, typed arguments (the order matters). [`Argument Definition`](#argument-definition).                                                                                                   |
-| `meta?`             | `SubcommandMeta`           | Metadata used for help messages and documentation generation. Inlined in the table below.                                                                                                               |
+## API Reference
 
-### SubcommandMeta
-
-| Property               | Type      | Description                                                                                                                                                                                                 |
-| ---------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `placeholder?`         | `string`  | Text displayed after the subcommand name to show expected arguments (e.g., `<list> <items>`).                                                                                                               |
-| `usage?`               | `string`  | Usage string example (e.g. `cliName subcommand [options] <arg1> <arg2>`).                                                                                                                                   |
-| `description?`         | `string`  | Short explanation. Supports multi-line text and ANSI color styles. Preferred for terminal output if both `description` and `descriptionMarkdown` are provided.                                              |
-| `descriptionMarkdown?` | `string`  | Markdown-formatted description used for generated documentation and terminal markdown. If both `description` and `descriptionMarkdown` are provided, `descriptionMarkdown` is used for Markdown generation. |
-| `example?`             | `string`  | Examples shown to the user (displayed inside a code block in markdown).                                                                                                                                     |
-| `hidden?`              | `boolean` | When `true`, hide this item from documentation/help output. Useful for internal or undocumented commands/options.                                                                                           |
-
-### Option
-
-| Property        | Type                | Description                                                                                                                          |
-| --------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
-| `aliases?`      | `string[]`          | A list of short alias keys (JavaScript variable names) that map to short CLI flags (e.g., `i` → `-i`).                               |
-| `schema`        | `Schema`            | A schema to validate the user input. (e.g., Zod: `z.string().optional()`).                                                           |
-| `coerce?`       | `CoerceMethod<...>` | Coercion function used to convert `string` input to the schema's output type. Not required when the expected input type is `string`. |
-| `exclusive?`    | `boolean`           | When `true`, this option must appear on its own (except for entries listed in `requires`).                                           |
-| `requires?`     | `string[]`          | Names of other options/arguments that must be explicitly provided when this option is used.                                          |
-| `conflictWith?` | `string[]`          | Names of other options/arguments that conflict with this option.                                                                     |
-| `meta?`         | `OptionMeta`        | Metadata used for help messages and documentation generation. Inlined in the table below.                                            |
-
-### OptionMeta
-
-| Property       | Type      | Description                                                                                    |
-| -------------- | --------- | ---------------------------------------------------------------------------------------------- |
-| `placeholder?` | `string`  | Text to display as a placeholder for the expected value (e.g., `<path>`).                      |
-| `default?`     | `string`  | Custom default value shown in docs/help. Use an empty string to intentionally show no default. |
-| `optional?`    | `boolean` | Override whether this option is considered optional in the generated help documentation.       |
-
-### Argument
-
-| Property        | Type                | Description                                                                                                                          |
-| --------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
-| `schema`        | `Schema`            | Schema to validate the user input.                                                                                                   |
-| `coerce?`       | `CoerceMethod<...>` | Coercion function used to convert `string` input to the schema's output type. Not required when the expected input type is `string`. |
-| `exclusive?`    | `boolean`           | When `true`, this argument must appear on its own (except for items listed in `requires`).                                           |
-| `requires?`     | `string[]`          | Names of other options/arguments that must be explicitly provided when this argument is used.                                        |
-| `conflictWith?` | `string[]`          | Names of other options/arguments that conflict with this argument.                                                                   |
-| `meta?`         | `ArgumentMeta`      | Metadata used for help messages and documentation generation. Inlined in the table below.                                            |
-
-### ArgumentMeta
-
-| Property    | Type      | Description                                                                                    |
-| ----------- | --------- | ---------------------------------------------------------------------------------------------- |
-| `name?`     | `string`  | Override the argument name in the help message and documentation.                              |
-| `default?`  | `string`  | Custom default value shown in help/docs. Use an empty string to intentionally show no default. |
-| `optional?` | `boolean` | Override whether this argument is considered optional in the generated help documentation.     |
-
-### Context Type
-
-Represents detailed information about how each option or argument was provided (terminal, default, or programmatic).  
-Useful for inspecting where values came from and what raw input was used.
-
-#### Context
-
-| Field         | Type                              | Description                                       |
-| ------------- | --------------------------------- | ------------------------------------------------- |
-| `subcommand`  | `string` \| `undefined`           | Name of the executed subcommand, if any.          |
-| `options`     | `Record<string, OptionContext>`   | Per-option context, with source and raw values.   |
-| `arguments`   | `Record<string, ArgumentContext>` | Per-argument context, with source and raw values. |
-| `positionals` | `string[]` \| `never`             | Raw positional arguments when allowed.            |
-
-#### OptionContext
-
-| Property       | Description                                                                          |
-| -------------- | ------------------------------------------------------------------------------------ |
-| `schema`       | Schema used to validate the option.                                                  |
-| `optional`     | Whether the option schema is optional.                                               |
-| `defaultValue` | Default value from the schema, if any.                                               |
-| `flag`         | CLI flag used (e.g., `--foo`, `-f`) when source is `terminal`.                       |
-| `stringValue`  | Raw string provided from CLI when source is `terminal`.                              |
-| `passedValue`  | Value passed programmatically when source is `programmatic`.                         |
-| `source`       | `"terminal"`, `"default"`, or `"programmatic"` indicates how the value was supplied. |
-
-#### ArgumentContext
-
-| Property       | Description                                                                          |
-| -------------- | ------------------------------------------------------------------------------------ |
-| `schema`       | Schema used to validate the argument.                                                |
-| `optional`     | Whether the argument schema is optional.                                             |
-| `defaultValue` | Default value from the schema, if any.                                               |
-| `stringValue`  | Raw string from CLI when source is `terminal`.                                       |
-| `passedValue`  | Value passed programmatically when source is `programmatic`.                         |
-| `source`       | `"terminal"`, `"default"`, or `"programmatic"` indicates how the value was supplied. |
+See the [API Reference](./docs/api-reference.md) for more information.
 
 ## License