Align docs with current API behavior

Author: xoofx

site/docs/advanced.md

@@ -91,9 +91,11 @@ var app = new CommandApp("myexe")
 ```
 
 This adds two sub-commands:
-- `completion <shell>` — generates the shell completion script
+- `completion <shell>` (hidden) — generates the shell completion script
 - `__complete` (hidden) — handles completion requests from the shell
 
+Both commands are hidden from default help output, but callable directly.
+
 ### Installing Completions
 
 Generate and source the completion script for your shell:
@@ -348,9 +350,10 @@ dotnet run -c Release --project src/XenoAtom.CommandLine.Benchmarks
 
 XenoAtom.CommandLine is fully compatible with NativeAOT publishing:
 
-- No reflection usage
+- No runtime code generation, dynamic proxies, or runtime binding
 - All types are trimmer-safe
 - `EnumWrapper<T>` avoids runtime reflection for enum parsing
+- Built-in defaults use only lightweight assembly metadata lookups (for example command name/version discovery)
 
 Publish with NativeAOT:
 

site/docs/arguments.md

@@ -137,7 +137,7 @@ var app = new CommandApp("myexe")
 Running `myexe --help`:
 
 ```
-Usage: myexe [options] <input> [<output>] [<extra>]...
+Usage: myexe [options] <input> [<output>] <extra>*
 
   -h, -?, --help             Show this message and exit
 

site/docs/commands.md

@@ -91,7 +91,7 @@ Available commands:
 Running `myexe commit --help`:
 
 ```
-Usage: myexe commit [options] [<files>]...
+Usage: myexe commit [options] <files>*
 
 Options:
   -m, --message=MESSAGE      Commit MESSAGE
@@ -306,12 +306,14 @@ If no version string is provided, it extracts the version from the assembly's in
 
 Understanding the parsing flow helps debug complex scenarios:
 
-1. Parse options (tokens starting with `-`, `--`, or `/`), applying option callbacks as values are consumed.
-2. If sub-commands exist and a token matches a sub-command name, dispatch to that sub-command.
-3. Parse positional arguments (`CommandArgument`) for the selected command.
+1. Parse options for the current command (tokens starting with `-`, `--`, or `/`), applying option callbacks as values are consumed.
+2. If help/version is requested for the current command, stop and render output.
+3. Apply environment-variable fallbacks for options not set on the command line.
 4. Run option constraint checks (mutually exclusive, requires).
-5. Invoke the command action and return its exit code.
-6. On error, the error is reported to `Error` and `RunAsync` returns `1`.
+5. If sub-commands exist and the next token matches an active sub-command, dispatch to that sub-command and repeat.
+6. Parse positional arguments (`CommandArgument`) for the resolved command.
+7. Invoke the command action and return its exit code.
+8. On error, the error is reported to `Error` and `RunAsync` returns `1`.
 
 If the parser is currently expecting a value for an option, the next token is **always** consumed as that value — even if it looks like `--` or matches a sub-command name.
 

site/docs/help-output.md

@@ -273,7 +273,7 @@ For rich colored and visual help output, install the optional `XenoAtom.CommandL
 dotnet add package XenoAtom.CommandLine.Terminal
 ```
 
-> **Note:** This package targets `net10.0` and depends on `XenoAtom.Terminal`.
+> **Note:** This package targets `net10.0` and depends on `XenoAtom.Terminal.UI` (which pulls `XenoAtom.Terminal` transitively).
 
 ### TerminalMarkupCommandOutput
 
@@ -365,7 +365,7 @@ XenoAtom.CommandLine provides informative error messages by default:
 
 ```
 myexe: Unknown option: --unkown
-Did you mean '--unknown'?
+Did you mean: --unknown
 Use `myexe --help` for usage.
 ```
 
@@ -375,7 +375,7 @@ When an option exists but is inside an inactive `CommandGroup`:
 
 ```
 myexe: Unknown option: --special1
-Note: option '--special1' exists but is inactive in the current context.
+Note: `--special1` matches an option that is currently inactive in this context.
 Use `myexe --help` for usage.
 ```
 

site/docs/validation.md

@@ -28,7 +28,8 @@ var app = new CommandApp("myexe")
 If validation fails, a clear error message is shown:
 
 ```
-myexe: The value '99999' is not valid for option '--port'. The value must be between 1 and 65535.
+myexe: Invalid value for option `--port`: The value must be between 1 and 65535.
+Use `myexe --help` for usage.
 ```
 
 ## Built-in Validators
@@ -129,7 +130,8 @@ app.AddMutuallyExclusive("json", "xml", "csv");
 If the user passes `--json --xml`, the error is:
 
 ```
-myexe: Options --json and --xml cannot be used together.
+myexe: Options `--json` and `--xml` cannot be used together.
+Use `myexe --help` for usage.
 ```
 
 ### Requires Constraint
@@ -150,7 +152,8 @@ app.AddRequires("password", "user");
 If the user passes `--password secret` without `--user`, the error is:
 
 ```
-myexe: Option --password requires --user to also be specified.
+myexe: Option `--password` requires `--user` to also be specified.
+Use `myexe --help` for usage.
 ```
 
 ### Combining Constraints