Add generated help and version commands

docs/cli.md

@@ -0,0 +1,91 @@
+# Command line reference
+
+CommandKit owns command routing and syntax for commands registered with its
+`App`. The caller supplies argv without the executable name, a context, and the
+output and diagnostic writers. `App.Execute` returns an `Outcome`; it does not
+exit the process.
+
+## Help
+
+The root help command lists registered commands and their summaries. Help is
+available through a bare invocation, `--help`, `-h`, and `help`:
+
+```text
+example
+example --help
+example -h
+example help
+example help config show
+example config --help
+```
+
+`help [COMMAND...]` resolves an exact registered path. A command group without
+an execution handler displays its help when invoked by itself. A runnable
+command with children runs its handler when invoked without help; add `--help`
+to inspect that command and its children.
+
+Help uses registered descriptions, command summaries, local flags, defaults,
+required and repeatable flag metadata, and operand names and counts. It does not
+construct the selected command's input or invoke its handler. Supplied flag and
+operand values are still parsed so malformed values and unknown flags remain
+usage errors. Missing execution-required values and input-combination checks
+are skipped for help.
+
+## Version
+
+`version` reports the application identity by default:
+
+```text
+example version
+example version --scope commandkit
+example version --format yaml
+```
+
+The supported flags are:
+
+| Flag | Values | Default | Meaning |
+| --- | --- | --- | --- |
+| `--scope` | `app`, `commandkit` | `app` | Select the caller's application identity or the embedded CommandKit module identity. |
+| `--format` | `text`, `yaml` | `text` | Select the output format. |
+
+Text output is `NAME VERSION`, followed by ` (REVISION)` when the selected
+identity has a revision. An empty application version is displayed as `dev`;
+the revision remains empty when omitted.
+
+CommandKit identity uses the version of its module in build information. A
+versioned module replacement supplies the effective version. A local or
+versionless replacement, an untagged module, or missing build information
+displays `dev`. The CommandKit identity name is `CommandKit`; dependency build
+metadata does not supply a revision.
+
+YAML output uses these explicit fields, including an empty revision:
+
+```yaml
+name: ExampleApp
+version: dev
+revision: ""
+```
+
+## Registered command syntax
+
+Options are parsed after the complete command path and may be interspersed with
+declared operands. Flags are local to the selected command. Use `--` to end
+option parsing; all later tokens are operands.
+
+Value flags accept `--name value` and `--name=value`. Boolean flags accept
+presence as true and explicit values such as `--enabled=false`. A singleton
+flag accepts repeated occurrences; the last successfully parsed occurrence
+supplies its value. Every supplied occurrence is converted, so an earlier
+malformed value remains an error. Repeatable flags preserve occurrence order,
+with each occurrence treated as one value, including strings containing commas.
+
+Typed inputs keep supplied state separate from defaults. An explicit empty,
+false, or zero value is supplied. Help and version are available without
+constructing application command inputs.
+
+## Outcome status
+
+CommandKit usage failures use status `2`; operational failures use status `1`.
+Successful operations use status `0`. Application handlers may return a domain
+classification and status of their choice, which `Execute` preserves. The caller
+chooses how to map an outcome to process exit.