Some updates to the docs, including subsystem flow

src/System.CommandLine.Subsystems/docs-for-cli-authors.md

@@ -1,6 +1,13 @@
 # Docs for CLI authors
 
-This is a space for tentative aspirational documentation
+The "grow-up" story for CLIs. 
+
+* A CLI author may begin a project thinking they will never need more than simply parsing, and won't have subcommands. That's great, they can use the core parser without the subsystem layer. They will retrieve data from the ParseResult and features, including default values, will not be available
+* The CLI author decides they want one or a couple of features of the subsystem layer - we think it will probably be help or default values, but it might be tab completion (see note on Validation below). They can explicitly call a subsystem, although the current API will be simplified.
+* The CLI author decides that they want all available functionality. They can use the pipeline without invocation if they would prefer to map values to parameters and invoke themselves. 
+* The CLI author winds up with several subcommands and determining which code to call and mapping becomes a bit messy or a burden. At this point, they can add invocation.
+
+Of course folks may jump into this flow anywhere, and all four scenarios will be supported. The need for this flexibilty is one of the things we learned from feedback on existing main (the current preview of System.CommandLine that we are replacing).
 
 ## Basic usage for full featured parser
 

src/System.CommandLine.Subsystems/docs-for-cli-extenders.md

@@ -1,6 +1,4 @@
-# Docs for folks extending Systemm.CommandLine subsystem 
-
-This is a space for tentative aspirational documentation
+# Docs for folks extending System.CommandLine subsystem
 
 There are a few ways to extend System.CommandLine subsystems
 
@@ -16,6 +14,118 @@ This design is based on the following assumptions:
 * Some folks will want extreme extensibility.
 * Data needs to be exchanged between subsystems (this is the area of most significant change from prior versions).
 
+We believe the space is fairly well understood, and that the subsystems we supply will cover most scenarios. However, we know of additional scenarios, such as prompting for required data.
+
+Subsystems can be used with or outside the pipeline.
+
+## Calling a subsystem without the pipeline
+
+```mermaid
+sequenceDiagram
+  actor Author as CLI author
+  participant Parser as Core parser
+  participant Subsystem as Help subsystem
+  participant App as Application
+
+  Author->>Author: Creates CLI,<br/>includes Help option
+  Author->>Parser: Creates parser
+  Parser->>Author: returns parser
+  Author->>Parser: Calls parser 'Parse', passing command line
+  Parser->>Author: 'ParseResult'
+  Author->>Author: Checks for '-h'
+  alt Help requested
+    Author->>Subsystem: Calls help
+    Subsystem->>Author: 
+  else Continue processing
+    Author->>App: Calls application code
+    App->>Author: Exit code
+  end
+```
+
+## Subsystem calls with the pipeline, without invocation
+
+```mermaid
+sequenceDiagram
+  actor Author as CLI author
+  participant Pipeline as Pipeline
+  participant Parser as Core parser
+  participant Subsystem as Help subsystem
+  participant OtherSubsystem as Other subsystems
+  participant App as Application
+
+  Author->>Author: Creates CLI,<br/>does not include Help option
+  Author->>Pipeline: Creates pipeline
+  Pipeline->>Author: 
+  Author->>Pipeline: Calls parser 'Parse',<br/>passing command line
+  Pipeline->>Subsystem: 'Initialize'
+  Subsystem->>Subsystem: Adds '-h' to CLI
+  Subsystem->>Pipeline: returns
+  Pipeline->>Parser: Calls 'Parse'
+  Parser->>Pipeline: returns 'ParseResult'
+  Pipeline->>Subsystem: 'CheckIfActivated'
+  Subsystem->>Subsystem: Checks for '-h'
+  Subsystem->>Pipeline: True if '-h', otherwise false
+  opt '-h', help requested
+    Pipeline->>Subsystem: 'Execute'
+    Subsystem->>Subsystem: Display help
+    Subsystem->>Pipeline: Updated PipelineResult<br/>'AlreadyHandled' set to true
+  end  
+  loop For all configured subsystems
+      Pipeline->>OtherSubsystem: `ExecuteIfNeeded`
+      OtherSubsystem->>Pipeline: 
+  end
+  Pipeline->>Author: 'PipelineResult'
+  Author->>Author: Check if  `AlreadyHandled`
+  opt `AlreadyHandled` is false
+    Author->>App: Calls application code
+    App->>Author: Exit code
+  end
+```
+
+
+## Subsystem calls with the pipeline, with invocation
+
+```mermaid
+sequenceDiagram
+  actor Author as CLI author
+  participant Pipeline as Pipeline
+  participant Parser as Core parser
+  participant Subsystem as Help subsystem
+  participant Invoke as Invocation subsystem
+  participant OtherSubsystem as Other subsystems
+  participant App as Application
+
+  Author->>Author: Creates CLI,<br/>does not include Help option
+  Author->>Pipeline: Creates pipeline
+  Pipeline->>Author: 
+  Author->>Pipeline: Calls parser 'Parse',<br/>passing command line
+  Pipeline->>Subsystem: 'Initialize'
+  Subsystem->>Subsystem: Adds '-h' to CLI
+  Subsystem->>Pipeline: returns
+  Pipeline->>Parser: Calls 'Parse'
+  Parser->>Pipeline: returns 'ParseResult'
+  Pipeline->>Subsystem: 'CheckIfActivated'
+  Subsystem->>Subsystem: Checks for '-h'
+  Subsystem->>Pipeline: True if '-h', otherwise false
+  opt '-h', help requested
+    Pipeline->>Subsystem: 'Execute'
+    Subsystem->>Subsystem: Display help
+    Subsystem->>Pipeline: Updated PipelineResult<br/>'AlreadyHandled' set to true
+  end  
+  loop For all configured subsystems
+      Pipeline->>OtherSubsystem: `ExecuteIfNeeded`
+      OtherSubsystem->>Pipeline: 
+  end
+  Pipeline->>Pipeline: Check if  `AlreadyHandled`
+  opt `AlreadyHandled` is false
+    Pipeline->>Invoke: 'Execute'
+    Invoke->>App: Runs application
+    App->>Invoke: Exit code
+    Invoke->>Pipeline: Updated 'PipelineResult'
+  end
+  Pipeline->>Author: 'PipelineResult'
+```
+
 ## Replacing an existing subsystem or adding a new one
 
 * Inherit from the existing subsystem or CliSubsystem