docs(cli): clarify AddBranch shared settings

Author: meiranzheng

Spectre.Docs.Cli.Examples/DemoApps/CommandHierarchies/Main.cs

@@ -72,6 +72,13 @@ public class RemoteRemoveSettings : RemoteSettings
     public string Name { get; init; } = string.Empty;
 }
 
+/// <summary>
+/// Settings for listing remotes.
+/// </summary>
+public class RemoteListSettings : RemoteSettings
+{
+}
+
 internal class RemoteAddCommand : Command<RemoteAddSettings>
 {
     protected override int Execute(CommandContext context, RemoteAddSettings settings, CancellationToken cancellation)
@@ -94,9 +101,9 @@ protected override int Execute(CommandContext context, RemoteRemoveSettings sett
     }
 }
 
-internal class RemoteListCommand : Command<RemoteSettings>
+internal class RemoteListCommand : Command<RemoteListSettings>
 {
-    protected override int Execute(CommandContext context, RemoteSettings settings, CancellationToken cancellation)
+    protected override int Execute(CommandContext context, RemoteListSettings settings, CancellationToken cancellation)
     {
         System.Console.WriteLine("Listing remotes...");
         if (settings.Verbose)

Spectre.Docs/Content/cli/how-to/working-with-multiple-command-hierarchies.md

@@ -15,7 +15,7 @@ A git-style CLI with nested `remote` subcommands—`add`, `remove`, and `list`
 
 ## Create a Command Branch
 
-Use `AddBranch<TSettings>("name", ...)` to define a parent command with nested subcommands:
+Use `AddBranch` to define a parent command with nested subcommands. Use the generic overload when you want shared settings/options for the branch:
 
 ```csharp:xmldocid,bodyonly
 M:Spectre.Docs.Cli.Examples.DemoApps.CommandHierarchies.Demo.RunAsync(System.String[])
@@ -30,13 +30,16 @@ Define a base settings class for the branch, then inherit from it in subcommand
 ```csharp:xmldocid
 T:Spectre.Docs.Cli.Examples.DemoApps.CommandHierarchies.RemoteSettings
 T:Spectre.Docs.Cli.Examples.DemoApps.CommandHierarchies.RemoteAddSettings
+T:Spectre.Docs.Cli.Examples.DemoApps.CommandHierarchies.RemoteListSettings
 ```
 
-The `--verbose` flag is now available on all remote subcommands: `myapp remote add origin https://... --verbose`.
+The `--verbose` flag is now available on all remote subcommands, and can be specified either before or after the subcommand name: `myapp remote --verbose add origin https://...` or `myapp remote add origin https://... --verbose`.
+
+Tip: even if a subcommand doesn't add any extra arguments/options (like `list`), give it a dedicated settings type that inherits from the branch settings (for example, `RemoteListSettings : RemoteSettings`).
 
 ## Nest Multiple Levels
 
-For complex CLIs, branches can contain other branches:
+For complex CLIs, branches can contain other branches (use the non-generic overload when you just want grouping):
 
 ```csharp
 config.AddBranch("cloud", cloud =>
@@ -54,4 +57,4 @@ This creates deeply nested commands like `myapp cloud storage upload`.
 ## See Also
 
 - <xref:cli-app-configuration> - Basic command registration
-- <xref:cli-commands-arguments> - Settings class patterns
+- <xref:cli-commands-arguments> - Settings class patterns