Document invocation reporting contracts

docs/releases/v0.3.0.md

@@ -2,9 +2,11 @@
 
 ## Summary
 
-CommandKit v0.3.0 adds application-owned command and flag aliases. This
-pre-1.0 minor release also updates the installation declaration type and
-Invocation struct shape; review the migration guidance before upgrading.
+CommandKit v0.3.0 adds application-owned command and flag aliases and shared
+invocation reporting. This pre-1.0 minor release also updates the installation
+declaration type and Invocation struct shape, replaces the error-first outcome
+and diagnostic-delivery APIs, and reserves reporting flag names; review the
+migration guidance before upgrading.
 
 ## Changes
 
@@ -17,6 +19,14 @@ Invocation struct shape; review the migration guidance before upgrading.
   `EnteredPath` and `CanonicalPath`.
 - Interpret a canonical short value flag such as `-c=` as an explicitly
   supplied empty value, consistent with `--color=` and `-c ""`.
+- Obtain an invocation-scoped `Reporter` from each handler's `Invocation` for
+  substantive output, Warning/Info/Progress/Debug messages, deferred messages,
+  and managed report rendering. The shared `--quiet`, `--verbose`, `--debug`,
+  and `--progress` flags apply across core and integration commands.
+- Return terminal explanation text with `Failure`, `Usage`, or
+  `Outcome.WithExplanation`; attach an optional operation error separately with
+  `Outcome.WithCause`. Returned `Outcome.Presentation` records output and
+  diagnostic delivery observations without changing the operation cause.
 
 ## Compatibility and migration
 
@@ -29,10 +39,26 @@ values whose parameter type is `...Command`, including wrappers assigned from
 `New` or `Register`, must update their signature to `...Declaration`.
 
 Adding private route fields to `Invocation` means positional struct literals no
-longer compile. Use keyed fields, for example
-`commandkit.Invocation{Context: ctx, Streams: streams}`, when constructing an
-Invocation outside command execution. CommandKit populates the route fields for
-executed handlers.
+longer compile. `Invocation` no longer contains `Streams`; `App.Execute` supplies
+the reporter and route paths to handlers. `Streams` remains the argument to
+`App.Execute`, where the caller owns the result and diagnostic writers.
+
+Handlers that used `invocation.Streams.Out` or `.Err` should use
+`invocation.Reporter().Output()` or the categorized reporting methods. Replace
+`Failure(err)` and `Usage(err)` with an operator-facing explanation and an
+optional `.WithCause(err)`; causes alone are not rendered. Replace
+`Outcome.Diagnostics` submissions and terminal `SeverityError` records with
+reporter messages and an `Outcome` explanation. Provider-returned
+`Acquired.Diagnostics` remain passive data for the owning integration to
+submit. Replace `ReportIncomplete`, `DiagnosticDelivery`, and `DeliveryError`
+with `Outcome.Presentation.Output` and `.Diagnostics`, whose `DeliveryResult`
+contains a state plus first render and write errors.
+
+The long flags `--quiet`, `--verbose`, `--debug`, and `--progress` are reserved
+for CommandKit reporting and cannot be declared by applications. Application
+aliases may target them. See the current [CLI reporting contract](../cli.md#reporting)
+and [consumer migration guide](../consumers/guide.md#invocation-reporting) for
+their behavior and API examples.
 
 The consumer minimum remains Go 1.26.0 and the maintainer release toolchain
 remains Go 1.26.8. Core v0.3.0 must be published before preparing dependent