Design the object model and public APIs for a command-line argument parser that a developer embeds in a CLI tool to turn a raw argv array into a typed, validated set of options, positional arguments, and a selected subcommand.

Operating context. One in-process library reused by many tools. It must support boolean flags, valued options in short (-p) and long (--port) forms, positional arguments, git-style nested subcommands, the -- end-of-options marker, default values, required options, repeatable options that collect into a list, and an auto-generated --help. The parser spec is defined once at startup and reused across every invocation; parsing itself runs once per invocation on a single thread, but the spec may be shared read-only.

Out of scope. Shell completion generation, internationalization of help text, merging config files or environment variables, interactive prompts, and the actual command business logic that runs after parsing.

What to produce. The class hierarchy (parser spec, option / flag / positional descriptors, parse result, error types), the public API each class exposes, and how parsing dispatches into a subcommand. Be explicit about: how a new option value-type (e.g. a Duration) plugs in without touching the tokenizer, whether diagnostics are collected or fail-fast, and how subcommands compose without one central switch statement.