Document 2.0 contracts and migration guidance

Author: xoofx

doc/advanced.md

@@ -49,6 +49,13 @@ var result = app.Parse(["--name", "Alice", "--port", "8080"]);
 - Help/version requests are surfaced via `HelpRequested`/`VersionRequested`.
 - Errors are collected in `Errors` instead of being written to stderr.
 - If `runConfig` is null, `Out` and `Error` default to `TextWriter.Null` to suppress output.
+- Parsing mutates per-run option state (`WasSet` tracking), so command graphs are intended for one invocation at a time.
+
+### Invocation Concurrency Contract
+
+- Command graphs are **not thread-safe for concurrent `RunAsync`/`Parse` calls** on the same command tree.
+- Sequential invocations on the same graph are supported.
+- Create separate command graph instances if you need true parallel invocations.
 
 ### Testing Sub-Commands
 

doc/help-output.md

@@ -252,6 +252,14 @@ The `CommandOutputHelper` class provides utility methods for building custom ren
 - `GetOptionValueName(option, valueIndex)` — value placeholder name
 - `GetDescriptionText(description)` — processed description text
 
+## Descriptor Contracts
+
+For custom outputs and custom command nodes, the following contracts apply:
+
+- `ICommandNodeDescriptor.Description` should be plain help text intent (not renderer-specific markup).
+- `IHelpPreformattedContent.WriteTo(...)` is the preformatted contract for verbatim text output.
+- If a node provides both interfaces, text outputs should prefer `IHelpPreformattedContent` and use `Description` as fallback when preformatted rendering is not supported.
+
 ## Terminal Package
 
 For rich colored and visual help output, install the optional `XenoAtom.CommandLine.Terminal` package:

doc/migration-2.0.md

@@ -0,0 +1,76 @@
+# Migration Guide — 2.0
+
+This guide summarizes the 2.0 API changes that require code updates.
+
+## Breaking Renames
+
+| 1.x | 2.0 |
+|---|---|
+| `OptionException` | `CommandOptionException` |
+| `CommandNode.IsThisNodeActive` | `CommandNode.ActivePredicate` |
+| `Command.OptionsName` | `Command.OptionsSectionName` |
+
+## `ICommandOutput` Unknown Token API
+
+`WriteUnknownTokens` now receives a single report object:
+
+```csharp
+void WriteUnknownTokens(Command command, CommandRunConfig runConfig, UnknownTokenReport report);
+```
+
+`UnknownTokenReport` includes:
+- `Kind`
+- `UnknownTokens`
+- `InvocationTokens` (when available)
+
+Update custom outputs to use `report.Kind`, `report.UnknownTokens`, and `report.InvocationTokens`.
+
+## Metadata Mutability Changes
+
+These members now use construction-time initialization:
+
+- `Command.Hidden` (`init`)
+- `Command.OptionsSectionName` (`init`)
+- `Option.EnvironmentVariable` (`init`)
+- `Option.EnvironmentVariableDelimiter` (`init`)
+
+### Before
+
+```csharp
+var hidden = new Command("secret");
+hidden.Hidden = true;
+
+app.Options["name"].EnvironmentVariable = "APP_NAME";
+```
+
+### After
+
+```csharp
+var hidden = new Command("secret")
+{
+    Hidden = true
+};
+
+app.Add("n|name=", "Name", value => { }, envVar: "APP_NAME");
+```
+
+## New Clarity Helpers
+
+The following helpers were added to reduce overload ambiguity and improve intent:
+
+- `AddRemainder(string? description = null)`
+- `AddText(string text)`
+- `AddSection(string header)` (auto-appends `:` when missing)
+
+## Overload Parity Additions
+
+Typed and list families now support `hidden` parity:
+
+- `Add<T>(..., Action<T> action, bool hidden)`
+- `Add<T>(..., ICollection<T> list, bool hidden)`
+- Validation and env-var variants with `hidden` support are available for typed/list overloads.
+
+## Notes
+
+- Key/value (`Action<TKey, TValue>`) overloads intentionally still do **not** support env-var fallback or validation delegates.
+- Command graphs remain single-invocation-at-a-time; avoid concurrent `RunAsync`/`Parse` on the same graph instance.

doc/options.md

@@ -265,6 +265,7 @@ Options can be hidden from help output:
 ```
 
 Hidden options are still functional — they just don't appear in `--help`.
+Set metadata (`hidden`, `envVar`, `envVarDelimiter`) while declaring options; these settings are part of construction-time configuration.
 
 ## Environment Variable Fallback
 

doc/readme.md

@@ -34,6 +34,7 @@ await app.RunAsync(args);
 | [Validation & Constraints](validation.md) | Value validation (`Validate.Range`, `Validate.NonEmpty`, `Validate.FileExists`, …), mutually exclusive options, requires constraints |
 | [Help & Output](help-output.md) | Help text, `CommandUsage`, custom `ICommandOutput` rendering, Terminal markup and visual output |
 | [Advanced Topics](advanced.md) | Parse API for testing, shell completions, response files, `CommandConfig`, `CommandRunConfig`, localization, `EnumWrapper<T>`, NativeAOT, performance |
+| [Migration 2.0](migration-2.0.md) | Breaking changes and upgrade checklist from 1.x |
 
 ## Quick Links
 

readme.md

@@ -110,6 +110,7 @@ Notes:
 - `CommandUsage()` defaults to `Usage: {NAME} {SYNTAX}` and `{SYNTAX}` is derived from your declared options/commands/arguments.
 - Positional arguments are strict by default: declare `<arg>` / `<arg>?` / `<arg>*` / `<arg>+`, or declare `<>` to forward remaining arguments to the command action.
 - Convenience helpers are available when not using collection initializers: `AddRemainder(...)`, `AddSection(...)`, and `AddText(...)`.
+- A command graph instance is intended for one invocation at a time (`RunAsync`/`Parse` are not concurrent-safe on the same graph).
 
 Running `myexe --help` will output:
 
@@ -227,6 +228,7 @@ Example of the advanced sample with an error:
 | [Validation & Constraints](doc/validation.md) | Value validation, mutually exclusive options, requires constraints |
 | [Help & Output](doc/help-output.md) | Help text, `CommandUsage`, custom output rendering, Terminal package |
 | [Advanced Topics](doc/advanced.md) | Parse API, shell completions, response files, configuration, environment variables, performance |
+| [Migration 2.0](doc/migration-2.0.md) | Breaking changes and upgrade steps |
 
 ## 🏗️ Build
 

src/XenoAtom.CommandLine/ICommandNodeDescriptor.cs

@@ -5,12 +5,16 @@
 namespace XenoAtom.CommandLine;
 
 /// <summary>
-/// Interface used to add a description to a <see cref="CommandNode"/>>.
+/// Provides plain-text help description intent for a <see cref="CommandNode"/>.
 /// </summary>
 public interface ICommandNodeDescriptor
 {
     /// <summary>
-    /// Gets the description of this command node (option, command...).
+    /// Gets the plain help text associated with this node.
     /// </summary>
+    /// <remarks>
+    /// This text should represent semantic help content (for example command/option/argument descriptions)
+    /// and should not contain renderer-specific markup.
+    /// </remarks>
     string? Description { get; }
-}
+}

src/XenoAtom.CommandLine/IHelpPreformattedContent.cs

@@ -9,6 +9,11 @@ namespace XenoAtom.CommandLine;
 /// <summary>
 /// Provides preformatted help content that should be written verbatim.
 /// </summary>
+/// <remarks>
+/// When a node implements both <see cref="IHelpPreformattedContent"/> and <see cref="ICommandNodeDescriptor"/>,
+/// text outputs should prefer <see cref="WriteTo"/> and use descriptor text as fallback only when preformatted
+/// rendering is not supported.
+/// </remarks>
 public interface IHelpPreformattedContent
 {
     /// <summary>