Add shared report format flag

docs/cli.md

@@ -46,7 +46,7 @@ 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. |
+| `--format` | `text`, `yaml`, `json` | automatic | Select the output format; automatic uses text for version. |
 
 Text output is `NAME VERSION`, followed by ` (REVISION)` when the selected
 identity has a revision. An empty application version is displayed as `dev`;
@@ -58,7 +58,7 @@ 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 and JSON output use these fields, including an empty revision:
 
 ```yaml
 name: ExampleApp
@@ -111,6 +111,14 @@ caller passes result and diagnostic writers to `App.Execute`; substantive
 results go to `Streams.Out`, and categorized messages, terminal explanations,
 and usage guidance go to `Streams.Err`.
 
+The shared `--format` flag selects `text`, `yaml`, or `json` for reports
+submitted through the core reporter. When omitted, a report's text template
+selects text; otherwise scalar values and nonempty string lists use text, while
+structured values and empty collections use YAML. Explicit text without a
+template uses YAML for structured values. Invalid or empty format values are
+usage errors. Raw output, help, completion, and diagnostics are not encoded as
+reports.
+
 ### Modes and visibility
 
 Each invocation starts in ordinary mode. `--quiet`, `--verbose`, and `--debug`
@@ -154,9 +162,9 @@ example version --quiet
 Reporting flags do not go before or between command-path components. Tokens
 consumed as values and tokens after `--` retain their normal meaning.
 
-The reserved long spellings are `--quiet`, `--verbose`, `--debug`, and
-`--progress`; application declarations cannot reuse them. There are no built-in
-short spellings. Applications may define aliases such as `-q → --quiet`,
+The reserved long spellings are `--quiet`, `--verbose`, `--debug`,
+`--progress`, and `--format`; application declarations cannot reuse them. There
+are no built-in short spellings. Applications may define aliases such as `-q → --quiet`,
 `-v → --verbose`, and `-d → --debug`; canonical and aliased occurrences share
 the same ordering. Thus `example export --verbose -q` selects quiet mode.
 

docs/consumers/guide.md

@@ -135,7 +135,8 @@ installation alongside aliases and integration commands.
 ## Invocation reporting
 
 `Invocation.Reporter()` supplies the reporter for the current handler. Use
-`Output()` or `RenderOutput()` for substantive results; use `Warn`, `Info`,
+`Report()` for formatted substantive values and optional text templates;
+use `Output()` or `RenderOutput()` for deliberate raw output. Use `Warn`, `Info`,
 `Progress`, and `Debug` for categorized messages. Queue a summary with
 `AtEnd().Info` when it belongs after the handler returns. The
 [CLI reference](../cli.md#reporting) owns flag grammar, visibility, prefixes,

docs/roadmap/implementation.md

@@ -1,6 +1,6 @@
 # Shared reporting and PromptKit v0.20.0 implementation plan
 
-Status: implementation in progress; Stages 1–3 complete.
+Status: implementation in progress; Stages 1–4 complete.
 
 ## Scope, authority, and execution
 
@@ -160,6 +160,11 @@ boundary in GoDoc.
 
 ## Stage 4: Universal format input, core version, and a core consumer
 
+**Complete.** Core format selection, version reporting, and a maintained core
+consumer use the shared report path. Focused parser, routing, completion, and
+reporting tests and the root workspace suite (`GOTOOLCHAIN=local go test ./...`
+with Go 1.27.0) passed. Integration migrations remain in later stages.
+
 Extend neutral core flag metadata and parser selection in
 [metadata.go](../../internal/commandmeta/metadata.go),
 [parser.go](../../parser.go), and the internal Cobra adapter. Add core-owned