# CommandKit v0.3.0

## Summary

CommandKit v0.3.0 moves core to `go.maximumdirect.net/commandkit`, adds
application-owned command and flag aliases, shared invocation reporting, and
shell completion. 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

- Declare command shortcuts and global or canonical-command-scoped flag
  spellings with `Alias`, `FlagAlias`, and `FlagAliasFor`. Install routing rules
  beside canonical commands through `New` or `App.Register`. Aliases route to
  existing handlers and preserve the target command's operand and binding
  behavior.
- Read the entered and canonical command paths from `Invocation` with
  `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.
- Install the optional `Completion` command and declare static choices or
  path hints for interactive shell completion. Bash, Zsh, and Fish scripts
  use the application's captured commands and routing metadata.
- Maintainer release tooling now uses the root-selected ReleaseKit v0.9.0 tool,
  with separate source publication and optional page-only hosted delivery.

## Compatibility and migration

Change core imports from `gitea.maximumdirect.net/eric/CommandKit` to
`go.maximumdirect.net/commandkit` and select v0.3.0. These paths identify
different Go packages, so their types cannot be mixed. Applications using the
integrations should migrate together to the forthcoming matched
`go.maximumdirect.net/ckconfig v0.2.0` and
`go.maximumdirect.net/ckprompt v0.2.0` releases, which depend on the new core;
the existing integration releases retain their old identities.

`New` and `App.Register` now accept `...Declaration` instead of `...Command`.
Command, group, and integration command factories still return `Command`, so
individual factory calls can be passed directly. A `[]Command` cannot be
expanded into `...Declaration`; use a `[]Declaration` for mixed reusable
collections or convert each command element before expanding it. Function
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. `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
integration releases that adopt it and record downloaded dependency sums; this
release does not change their v0.1.0 release records.

See the [consumer guide](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/v0.3.0/docs/consumers/guide.md),
[CLI reference](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/v0.3.0/docs/cli.md),
and [maintainer release procedure](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/v0.3.0/docs/release.md).

[COPYRIGHT](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/v0.3.0/COPYRIGHT) |
[LICENSE](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/v0.3.0/LICENSE) |
[ATTRIBUTION](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/v0.3.0/docs/oss/attribution.md)