Migrate ckconfig to the vanity module path

.gitignore

@@ -31,7 +31,7 @@ go.work.sum
 # temporary files which can be created if a process still has a handle open of a deleted file
 .fuse_hidden*
 
-# Local ReleaseKit bootstrap executable
+# Local ReleaseKit credentials
 /.releasekit/
 
 # KDE directory preferences

README.md

@@ -1,19 +1,37 @@
 # CommandKit
 
-CommandKit is a Go library project for consistent CLI inspection, command syntax,
-and shared command infrastructure across related applications.
+CommandKit is a Go library for typed command declarations, shared CLI behavior,
+and application-owned execution. The core `commandkit` module is usable by
+itself. ConfigKit and PromptKit support lives in separately versioned optional
+modules, so applications choose which upstream libraries they add.
 
-The current Go library provides an instance-owned command registry, typed flag
-and operand bindings, Cobra-backed routing, invocation outcomes, generated help,
-application or CommandKit version reporting, configuration scope discovery,
-ConfigKit-backed validation, native effective YAML display, source inventory,
-and path explanation reports. Applications can register a PromptKit engine
-configuration scope independently of PromptKit definition commands, and can
-install optional prompt and profile inspection commands.
+The core captures reusable command declarations, validates installation batches
+before changing an application's registry, converts typed inputs before
+constructing them, and returns outcomes without exiting the process. Its
+[consumer guide](docs/consumers/guide.md) covers declaration, invocation
+reporting, and migration. Each handler receives one invocation reporter for
+substantive output, categorized messages, and terminal explanations; `Execute`
+returns delivery observations with the outcome. The [CLI reference](docs/cli.md)
+defines the shared visibility policy.
 
-The [consumer guide](docs/consumers/guide.md) links to two maintained examples:
-[simple](examples/simple/README.md) and
-[composed](examples/composed/README.md).
+## Modules
+
+| Module | Package | Provides |
+| --- | --- | --- |
+| `go.maximumdirect.net/commandkit` | `commandkit` | Typed commands, bindings, execution reporting and outcomes, help, and version. |
+| `go.maximumdirect.net/ckconfig` | `ckconfig` | ConfigKit-backed `config` scopes, including configuration source evidence. |
+| `gitea.maximumdirect.net/eric/CommandKit/integrations/ckprompt` | `ckprompt` | PromptKit engine configuration/comparison, five catalogs, named inspection, requirements discovery, concrete request validation, and native smoke tests. |
+
+Importing an integration does not install commands. The ckconfig v0.2.0
+candidate uses core v0.3.0; ckprompt still uses the old core identity and cannot
+be composed with the new core path until its planned v0.2.0 release. See the
+[consumer guide](docs/consumers/guide.md#module-selection) for migration details.
+
+## Examples
+
+- [Core-only example](examples/core/README.md)
+- [ConfigKit example](integrations/ckconfig/examples/simple/README.md)
+- [Composed ConfigKit and PromptKit example](integrations/ckprompt/examples/composed/README.md)
 
 ## Documentation
 
@@ -24,11 +42,7 @@ The [consumer guide](docs/consumers/guide.md) links to two maintained examples:
 - [Maintainer release procedure](docs/release.md)
 - [Architecture policy](docs/policy/architecture.md)
 - [Policy provenance](docs/policy/meta.md)
-
-## Future work and history
-
 - [Deferred capabilities and proposals](docs/roadmap/deferred.md)
-- [Completed planning and implementation records in Git history](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/6bc37e7ba64ca0920b4d0cc77039a18d4006b24e/docs/roadmap)
 
 CommandKit is licensed under the [LGPL v3.0 or later](COPYRIGHT).
 

app.go

@@ -3,47 +3,60 @@ package commandkit
 import (
 	"fmt"
 
-	internalcobra "gitea.maximumdirect.net/eric/CommandKit/internal/cobra"
+	"go.maximumdirect.net/commandkit/internal/alias"
+	commandmeta "go.maximumdirect.net/commandkit/internal/commandmeta"
 )
 
-// App owns one command registry and its application identity.
+// App owns one command registry and its application identity. Each App has an
+// independent registry; command declarations may be reused across Apps.
 type App struct {
-	identity         Identity
-	commands         map[string]*commandNode
-	commandTree      *internalcobra.Command
-	configRegistered bool
+	identity       Identity
+	commands       map[string]*commandNode
+	routingRules   []RoutingRule
+	aliases        *alias.Resolver
+	flagAliases    map[string]resolvedFlagAliases
+	discoveryFlags map[string]resolvedFlagAliases
+	snapshot       *routingSnapshot
+}
+
+type routingSnapshot struct {
+	metadata       *commandmeta.Command
+	runners        map[commandmeta.Key]commandPayload
+	aliases        *alias.Resolver
+	canonical      map[string]*canonicalNode
+	commandAliases []commandmeta.CommandAlias
+	flagAliases    map[string]resolvedFlagAliases
+	discoveryFlags map[string]resolvedFlagAliases
+	completion     bool
 }
 
 type commandNode struct {
-	command  Command
-	reserved bool
+	command Command
 }
 
-// New creates an application with the supplied identity and initial commands.
-// The identity name must not be empty. The root help and version names are
-// reserved for generated commands.
-func New(identity Identity, commands ...Command) (*App, error) {
+// New creates an application with the supplied identity and initial canonical
+// commands and routing rules. Use []Declaration to expand a mixed declaration
+// collection; []Command cannot be expanded as ...Declaration without
+// converting its elements.
+//
+// The identity name must not be empty. New installs its generated help and
+// version commands and caller declarations as one batch; an invalid, nil, or
+// zero declaration returns an error without exposing an App. Factory issues
+// retained in Command and RoutingRule values are reported during installation.
+// Identical duplicate routing mappings are accepted; conflicting mappings
+// fail the batch. The root help and version names are reserved for generated
+// commands.
+func New(identity Identity, declarations ...Declaration) (*App, error) {
 	if identity.Name == "" {
 		return nil, fmt.Errorf("application identity name must not be empty")
 	}
 
-	app := &App{
-		identity: identity,
-		commands: map[string]*commandNode{
-			"help": {
-				command:  Command{name: "help", summary: "Show help for commands."},
-				reserved: true,
-			},
-			"version": {
-				command:  Command{name: "version", summary: "Show application version."},
-				reserved: true,
-			},
-		},
-	}
-	if err := app.installBuiltins(); err != nil {
-		return nil, err
-	}
-	if err := app.Register(commands...); err != nil {
+	app := &App{identity: identity, commands: make(map[string]*commandNode)}
+	builtins := app.builtinCommands()
+	all := make([]Declaration, 0, len(builtins)+len(declarations))
+	all = append(all, builtins...)
+	all = append(all, declarations...)
+	if err := app.installBatch(all...); err != nil {
 		return nil, err
 	}
 	return app, nil

binding.go

@@ -1,167 +1,195 @@
 package commandkit
 
 import (
+	"errors"
 	"fmt"
 	"strconv"
+
+	commandmeta "go.maximumdirect.net/commandkit/internal/commandmeta"
 )
 
 // ValueFlag declares a singleton flag with a typed parser, optional default,
-// and setter. Every supplied occurrence is parsed; the last parsed value is
-// applied with Set=true.
+// and setter. The default value is captured at construction. Every supplied
+// occurrence is parsed before input construction; the last parsed value is
+// applied with Set=true. A malformed earlier occurrence remains an error.
 func ValueFlag[I, V any](meta FlagMeta, defaultValue *V, parse func(string) (V, error), set func(*I, Supplied[V])) Flag[I] {
 	var fallback V
 	if defaultValue != nil {
 		fallback = *defaultValue
 	}
-	binding := flagBinding[I]{meta: meta, defaultText: fmt.Sprint(fallback)}
+	binding := flagBinding[I]{identity: newBindingIdentity(), meta: meta, defaultText: fmt.Sprint(fallback)}
 	if parse == nil || set == nil {
 		return Flag[I]{binding: binding}
 	}
 	binding.valid = true
-	binding.clear = func(input *I) { set(input, Supplied[V]{}) }
-	binding.prepare = func(values []string) (func(*I), error) {
+	binding.prepare = func(values []string) (preparedValue[I], error) {
 		value := fallback
 		supplied := len(values) > 0
-		for _, raw := range values {
+		for index, raw := range values {
 			parsed, err := parse(raw)
 			if err != nil {
-				return nil, err
+				return preparedValue[I]{}, &flagOccurrenceError{index: index, cause: err}
 			}
 			value = parsed
 		}
 		result := Supplied[V]{Value: value, Set: supplied}
-		return func(input *I) { set(input, result) }, nil
+		return preparedValue[I]{identity: binding.identity, supplied: supplied, apply: func(input *I) { set(input, result) }}, nil
 	}
 	return Flag[I]{binding: binding}
 }
 
 // BoolFlag declares a boolean flag. A bare flag is supplied by the parser as
-// "true"; explicit values are converted with strconv.ParseBool.
+// "true"; explicit values are converted with strconv.ParseBool. Set distinguishes
+// an omitted flag from an explicit false value.
 func BoolFlag[I any](meta FlagMeta, defaultValue bool, set func(*I, Supplied[bool])) Flag[I] {
-	binding := flagBinding[I]{meta: meta, defaultText: fmt.Sprint(defaultValue), boolean: true}
+	binding := flagBinding[I]{identity: newBindingIdentity(), meta: meta, defaultText: fmt.Sprint(defaultValue), boolean: true}
 	if set == nil {
 		return Flag[I]{binding: binding}
 	}
 	binding.valid = true
-	binding.clear = func(input *I) { set(input, Supplied[bool]{}) }
-	binding.prepare = func(values []string) (func(*I), error) {
+	binding.prepare = func(values []string) (preparedValue[I], error) {
 		value := defaultValue
 		supplied := len(values) > 0
-		for _, raw := range values {
+		for index, raw := range values {
 			parsed, err := strconv.ParseBool(raw)
 			if err != nil {
-				return nil, err
+				return preparedValue[I]{}, &flagOccurrenceError{index: index, cause: err}
 			}
 			value = parsed
 		}
 		result := Supplied[bool]{Value: value, Set: supplied}
-		return func(input *I) { set(input, result) }, nil
+		return preparedValue[I]{identity: binding.identity, supplied: supplied, apply: func(input *I) { set(input, result) }}, nil
 	}
 	return Flag[I]{binding: binding}
 }
 
-// RepeatFlag declares a repeatable flag. Supplied occurrences replace defaults
-// and are parsed in argv order, with each occurrence treated as one value.
+// RepeatFlag declares a repeatable flag. It captures a copy of defaults. Supplied
+// occurrences replace defaults and are parsed in argv order, with each
+// occurrence treated as one value. The core-owned result slice is copied when
+// applied to input.
 func RepeatFlag[I, V any](meta FlagMeta, defaults []V, parse func(string) (V, error), set func(*I, Supplied[[]V])) Flag[I] {
 	fallback := append([]V(nil), defaults...)
-	binding := flagBinding[I]{meta: meta, defaultText: fmt.Sprint(fallback), repeated: true}
+	binding := flagBinding[I]{identity: newBindingIdentity(), meta: meta, defaultText: fmt.Sprint(fallback), repeated: true}
 	if parse == nil || set == nil {
 		return Flag[I]{binding: binding}
 	}
 	binding.valid = true
-	binding.clear = func(input *I) { set(input, Supplied[[]V]{}) }
-	binding.prepare = func(values []string) (func(*I), error) {
+	binding.prepare = func(values []string) (preparedValue[I], error) {
 		parsedValues := append([]V(nil), fallback...)
 		supplied := len(values) > 0
 		if supplied {
 			parsedValues = make([]V, 0, len(values))
-			for _, raw := range values {
+			for index, raw := range values {
 				parsed, err := parse(raw)
 				if err != nil {
-					return nil, err
+					return preparedValue[I]{}, &flagOccurrenceError{index: index, cause: err}
 				}
 				parsedValues = append(parsedValues, parsed)
 			}
 		}
-		return func(input *I) {
+		return preparedValue[I]{identity: binding.identity, supplied: supplied, apply: func(input *I) {
 			result := Supplied[[]V]{Value: append([]V(nil), parsedValues...), Set: supplied}
 			set(input, result)
-		}, nil
+		}}, nil
 	}
 	return Flag[I]{binding: binding}
 }
 
-// ValueArgument declares an optional or required singleton positional
-// argument.
+// ValueArgument declares an optional or required singleton positional argument.
+// Required cardinality is enforced for execution, while help can be rendered
+// without a supplied operand. Parsing completes before input construction.
 func ValueArgument[I, V any](meta ArgumentMeta, required bool, parse func(string) (V, error), set func(*I, Supplied[V])) Argument[I] {
 	min := 0
 	if required {
 		min = 1
 	}
-	binding := argumentBinding[I]{meta: meta, min: min, max: 1}
+	binding := argumentBinding[I]{identity: newBindingIdentity(), meta: meta, min: min, max: 1}
 	if parse == nil || set == nil {
 		return Argument[I]{binding: binding}
 	}
 	binding.valid = true
-	binding.prepare = func(values []string) (func(*I), error) {
+	binding.prepare = func(values []string) (preparedValue[I], error) {
 		if len(values) > 1 {
-			return nil, fmt.Errorf("received %d values; maximum is 1", len(values))
+			return preparedValue[I]{}, fmt.Errorf("received %d values; maximum is 1", len(values))
 		}
 		var value V
 		supplied := len(values) == 1
 		if supplied {
 			parsed, err := parse(values[0])
 			if err != nil {
-				return nil, err
+				return preparedValue[I]{}, err
 			}
 			value = parsed
 		}
 		result := Supplied[V]{Value: value, Set: supplied}
-		return func(input *I) { set(input, result) }, nil
+		return preparedValue[I]{identity: binding.identity, supplied: supplied, apply: func(input *I) { set(input, result) }}, nil
 	}
 	return Argument[I]{binding: binding}
 }
 
-// RepeatArgument declares a positional argument that accepts a bounded number
-// of values. A maximum of -1 means unbounded.
+// RepeatArgument declares a positional argument that accepts at least min and
+// at most max values. A maximum of -1 means unbounded. Parsing completes before
+// input construction, and the core-owned result slice is copied when applied.
 func RepeatArgument[I, V any](meta ArgumentMeta, min, max int, parse func(string) (V, error), set func(*I, Supplied[[]V])) Argument[I] {
-	binding := argumentBinding[I]{meta: meta, min: min, max: max}
+	binding := argumentBinding[I]{identity: newBindingIdentity(), meta: meta, min: min, max: max}
 	if parse == nil || set == nil {
 		return Argument[I]{binding: binding}
 	}
 	binding.valid = true
-	binding.prepare = func(values []string) (func(*I), error) {
+	binding.prepare = func(values []string) (preparedValue[I], error) {
 		if max >= 0 && len(values) > max {
-			return nil, fmt.Errorf("received %d values; maximum is %d", len(values), max)
+			return preparedValue[I]{}, fmt.Errorf("received %d values; maximum is %d", len(values), max)
 		}
 		parsedValues := make([]V, 0, len(values))
 		for _, raw := range values {
 			parsed, err := parse(raw)
 			if err != nil {
-				return nil, err
+				return preparedValue[I]{}, err
 			}
 			parsedValues = append(parsedValues, parsed)
 		}
-		return func(input *I) {
+		return preparedValue[I]{identity: binding.identity, supplied: len(values) > 0, apply: func(input *I) {
 			result := Supplied[[]V]{Value: append([]V(nil), parsedValues...), Set: len(values) > 0}
 			set(input, result)
-		}, nil
+		}}, nil
 	}
 	return Argument[I]{binding: binding}
 }
 
 type preparedInput[I any] struct {
 	newInput func() I
-	setters  []func(*I)
+	values   []preparedValue[I]
 }
 
+type flagOccurrenceError struct {
+	index int
+	cause error
+}
+
+func (err *flagOccurrenceError) Error() string { return err.cause.Error() }
+
+func (err *flagOccurrenceError) Unwrap() error { return err.cause }
+
+type flagConversionError struct {
+	binding    string
+	spelling   string
+	occurrence int
+	cause      error
+}
+
+func (err *flagConversionError) Error() string {
+	return fmt.Sprintf("flag %s occurrence %d: %v", err.spelling, err.occurrence, err.cause)
+}
+
+func (err *flagConversionError) Unwrap() error { return err.cause }
+
 func (p preparedInput[I]) build() I {
 	var input I
 	if p.newInput != nil {
 		input = p.newInput()
 	}
-	for _, setter := range p.setters {
-		setter(&input)
+	for _, value := range p.values {
+		value.apply(&input)
 	}
 	return input
 }
@@ -170,91 +198,135 @@ func (p preparedInput[I]) build() I {
 // creates an input value. When enforceRequired is false, missing required flags
 // and operands are allowed so metadata help can validate supplied syntax.
 func prepareInput[I any](spec CommandSpec[I], flagValues [][]string, operands []string, enforceRequired bool) (preparedInput[I], error) {
+	return prepareInputWithSpellings(spec, flagValues, nil, operands, enforceRequired)
+}
+
+func prepareInputWithSpellings[I any](spec CommandSpec[I], flagValues, flagSpellings [][]string, operands []string, enforceRequired bool) (preparedInput[I], error) {
 	if len(flagValues) != len(spec.Flags) {
 		return preparedInput[I]{}, fmt.Errorf("received %d flag value sets for %d bindings", len(flagValues), len(spec.Flags))
 	}
-	setters := make([]func(*I), 0, len(spec.Flags)+len(spec.Arguments))
+	if flagSpellings == nil {
+		flagSpellings = make([][]string, len(spec.Flags))
+	}
+	if len(flagSpellings) != len(spec.Flags) {
+		return preparedInput[I]{}, fmt.Errorf("received %d flag spelling sets for %d bindings", len(flagSpellings), len(spec.Flags))
+	}
+	preparedFlags := make([]preparedValue[I], len(spec.Flags))
+	missingRequired := ""
 	for i, flag := range spec.Flags {
 		binding := flag.binding
-		if enforceRequired && binding.meta.Required && len(flagValues[i]) == 0 {
-			return preparedInput[I]{}, fmt.Errorf("required flag --%s was not supplied", binding.meta.Name)
-		}
-		setter, err := binding.prepare(flagValues[i])
+		value, err := binding.prepare(flagValues[i])
 		if err != nil {
+			var occurrenceErr *flagOccurrenceError
+			if errors.As(err, &occurrenceErr) {
+				spelling := "--" + binding.meta.Name
+				if occurrenceErr.index >= 0 && occurrenceErr.index < len(flagSpellings[i]) && flagSpellings[i][occurrenceErr.index] != "" {
+					spelling = flagSpellings[i][occurrenceErr.index]
+				}
+				return preparedInput[I]{}, &flagConversionError{
+					binding: binding.meta.Name, spelling: spelling,
+					occurrence: occurrenceErr.index + 1, cause: occurrenceErr.cause,
+				}
+			}
 			return preparedInput[I]{}, fmt.Errorf("flag --%s: %w", binding.meta.Name, err)
 		}
-		setters = append(setters, setter)
+		preparedFlags[i] = value
+		if enforceRequired && binding.meta.Required && !binding.deferredRequired && !value.supplied && missingRequired == "" {
+			missingRequired = binding.meta.Name
+		}
+	}
+	if missingRequired != "" {
+		return preparedInput[I]{}, fmt.Errorf("required flag --%s was not supplied", missingRequired)
 	}
 	argumentValues, err := allocateOperands(operands, spec.Arguments, enforceRequired)
 	if err != nil {
 		return preparedInput[I]{}, err
 	}
+	preparedValues := append([]preparedValue[I](nil), preparedFlags...)
 	for i, argument := range spec.Arguments {
 		binding := argument.binding
-		setter, err := binding.prepare(argumentValues[i])
+		value, err := binding.prepare(argumentValues[i])
 		if err != nil {
 			return preparedInput[I]{}, fmt.Errorf("argument %q: %w", binding.meta.Name, err)
 		}
-		setters = append(setters, setter)
+		preparedValues = append(preparedValues, value)
 	}
-	return preparedInput[I]{newInput: spec.NewInput, setters: setters}, nil
+	return preparedInput[I]{newInput: spec.NewInput, values: preparedValues}, nil
 }
 
+func newBindingIdentity() *bindingIdentity { return &bindingIdentity{marker: 1} }
+
 func allocateOperands[I any](operands []string, definitions []Argument[I], enforceRequired bool) ([][]string, error) {
+	arguments := make([]commandmeta.Argument, len(definitions))
+	for i, definition := range definitions {
+		arguments[i] = commandmeta.Argument{Name: definition.binding.meta.Name, Min: definition.binding.min, Max: definition.binding.max}
+	}
+	counts, err := allocateOperandCounts(len(operands), arguments, enforceRequired)
+	if err != nil {
+		return nil, err
+	}
+	allocated := make([][]string, len(definitions))
+	position := 0
+	for i, count := range counts {
+		allocated[i] = operands[position : position+count]
+		position += count
+	}
+	return allocated, nil
+}
+
+func allocateOperandCounts(total int, definitions []commandmeta.Argument, enforceRequired bool) ([]int, error) {
 	for _, argument := range definitions {
-		binding := argument.binding
-		if binding.min < 0 || binding.max < -1 || (binding.max >= 0 && binding.min > binding.max) {
-			return nil, fmt.Errorf("argument %q has invalid bounds %d..%d", binding.meta.Name, binding.min, binding.max)
+		if argument.Min < 0 || argument.Max < -1 || (argument.Max >= 0 && argument.Min > argument.Max) {
+			return nil, fmt.Errorf("argument %q has invalid bounds %d..%d", argument.Name, argument.Min, argument.Max)
 		}
 	}
 	if enforceRequired {
 		minimum := 0
 		for _, argument := range definitions {
-			if argument.binding.min > len(operands)-minimum {
+			if argument.Min > total-minimum {
 				return nil, fmt.Errorf("not enough positional arguments")
 			}
-			minimum += argument.binding.min
+			minimum += argument.Min
 		}
 	}
 
 	suffixMinimum := make([]int, len(definitions)+1)
 	for i := len(definitions) - 1; i >= 0; i-- {
-		minimum := definitions[i].binding.min
-		remaining := len(operands) - suffixMinimum[i+1]
+		minimum := definitions[i].Min
+		remaining := total - suffixMinimum[i+1]
 		if minimum > remaining {
-			suffixMinimum[i] = len(operands)
+			suffixMinimum[i] = total
 		} else {
 			suffixMinimum[i] = suffixMinimum[i+1] + minimum
 		}
 	}
 
-	allocated := make([][]string, len(definitions))
+	counts := make([]int, len(definitions))
 	position := 0
 	for i, argument := range definitions {
-		binding := argument.binding
-		remaining := len(operands) - position
+		remaining := total - position
 		available := remaining - suffixMinimum[i+1]
 		if available < 0 {
 			available = 0
 		}
 		count := available
-		if binding.max >= 0 && count > binding.max {
-			count = binding.max
+		if argument.Max >= 0 && count > argument.Max {
+			count = argument.Max
 		}
-		if !enforceRequired && count < binding.min && remaining > 0 {
+		if !enforceRequired && count < argument.Min && remaining > 0 {
 			count = remaining
-			if binding.max >= 0 && count > binding.max {
-				count = binding.max
+			if argument.Max >= 0 && count > argument.Max {
+				count = argument.Max
 			}
 		}
-		if enforceRequired && count < binding.min {
-			return nil, fmt.Errorf("not enough values for argument %q", binding.meta.Name)
+		if enforceRequired && count < argument.Min {
+			return nil, fmt.Errorf("not enough values for argument %q", argument.Name)
 		}
-		allocated[i] = operands[position : position+count]
+		counts[i] = count
 		position += count
 	}
-	if position < len(operands) {
-		return nil, fmt.Errorf("received %d extra positional arguments", len(operands)-position)
+	if position < total {
+		return nil, fmt.Errorf("received %d extra positional arguments", total-position)
 	}
-	return allocated, nil
+	return counts, nil
 }

binding_test.go

@@ -1,7 +1,9 @@
 package commandkit
 
 import (
+	"context"
 	"errors"
+	"io"
 	"reflect"
 	"strconv"
 	"testing"
@@ -30,7 +32,7 @@ func TestScalarBindingsKeepDefaultsSeparateFromPresence(t *testing.T) {
 			BoolFlag(FlagMeta{Name: "enabled"}, true, func(input *bindingInput, value Supplied[bool]) { input.enabled = value }),
 		},
 	}
-	if _, err := NewCommand(spec); err != nil {
+	if err := validateCommandDeclaration(NewCommand(spec)); err != nil {
 		t.Fatal(err)
 	}
 	defaultMessage = "changed after declaration"
@@ -104,8 +106,7 @@ func TestBoolFlagRejectsExplicitEmptyValue(t *testing.T) {
 
 func TestRepeatFlagUsesFreshDefaultsAndWholeOccurrenceValues(t *testing.T) {
 	defaults := []string{"base"}
-	var captured Supplied[[]string]
-	flag := RepeatFlag(FlagMeta{Name: "tag"}, defaults, func(value string) (string, error) { return value, nil }, func(_ *bindingInput, value Supplied[[]string]) { captured = value })
+	flag := RepeatFlag(FlagMeta{Name: "tag"}, defaults, func(value string) (string, error) { return value, nil }, func(input *bindingInput, value Supplied[[]string]) { input.tags = value })
 	defaults[0] = "changed after declaration"
 
 	applyDefault, err := flag.binding.prepare(nil)
@@ -113,25 +114,25 @@ func TestRepeatFlagUsesFreshDefaultsAndWholeOccurrenceValues(t *testing.T) {
 		t.Fatal(err)
 	}
 	first := &bindingInput{}
-	applyDefault(first)
+	applyDefault.apply(first)
 	second := &bindingInput{}
-	applyDefault(second)
-	if !reflect.DeepEqual(captured.Value, []string{"base"}) || captured.Set {
-		t.Fatalf("omitted repeat value = %#v, want copied default with Set=false", captured)
+	applyDefault.apply(second)
+	if !reflect.DeepEqual(first.tags.Value, []string{"base"}) || first.tags.Set {
+		t.Fatalf("omitted repeat value = %#v, want copied default with Set=false", first.tags)
 	}
-	captured.Value[0] = "changed one input"
-	applyDefault(second)
-	if !reflect.DeepEqual(captured.Value, []string{"base"}) {
-		t.Fatalf("repeat default collection was reused: %#v", captured.Value)
+	first.tags.Value[0] = "changed one input"
+	if !reflect.DeepEqual(second.tags.Value, []string{"base"}) {
+		t.Fatalf("repeat default collection was reused: %#v", second.tags.Value)
 	}
 
 	applyValues, err := flag.binding.prepare([]string{"a,b", "c"})
 	if err != nil {
 		t.Fatal(err)
 	}
-	applyValues(&bindingInput{})
-	if !reflect.DeepEqual(captured.Value, []string{"a,b", "c"}) || !captured.Set {
-		t.Fatalf("supplied repeat values = %#v, want two ordered occurrences", captured)
+	third := &bindingInput{}
+	applyValues.apply(third)
+	if !reflect.DeepEqual(third.tags.Value, []string{"a,b", "c"}) || !third.tags.Set {
+		t.Fatalf("supplied repeat values = %#v, want two ordered occurrences", third.tags)
 	}
 }
 
@@ -149,6 +150,46 @@ func TestSingletonParsesEveryOccurrenceAndPreservesCallerCause(t *testing.T) {
 	}
 }
 
+func TestPreparedScalarConvertsEveryOccurrenceOnceBeforeInputCreation(t *testing.T) {
+	parseCalls := 0
+	var received Supplied[string]
+	flag := ValueFlag(FlagMeta{Name: "value"}, (*string)(nil), func(value string) (string, error) {
+		parseCalls++
+		return value, nil
+	}, func(input *bindingInput, value Supplied[string]) { input.message = value })
+	prepared, err := flag.binding.prepare([]string{"earlier", "last"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if parseCalls != 2 || prepared.identity != flag.binding.identity || !prepared.supplied {
+		t.Fatalf("prepared scalar = %#v, parse calls = %d", prepared, parseCalls)
+	}
+	copy := flag
+	lookalike := ValueFlag(FlagMeta{Name: "value"}, (*string)(nil), func(value string) (string, error) { return value, nil }, func(*bindingInput, Supplied[string]) {})
+	if copy.binding.identity != flag.binding.identity || lookalike.binding.identity == flag.binding.identity {
+		t.Fatal("binding identity was not preserved by copying or distinct across constructors")
+	}
+	input := &bindingInput{}
+	prepared.apply(input)
+	received = input.message
+	if parseCalls != 2 || received.Value != "last" || !received.Set {
+		t.Fatalf("applied value = %#v, parse calls = %d", received, parseCalls)
+	}
+}
+
+func TestInvalidBindingConstructionIsReportedAtInstallation(t *testing.T) {
+	badFlag := ValueFlag[struct{}, string](FlagMeta{Name: "broken"}, nil, nil, func(*struct{}, Supplied[string]) {})
+	badArgument := RepeatArgument[struct{}, string](ArgumentMeta{Name: "items"}, 2, 1, func(value string) (string, error) { return value, nil }, func(*struct{}, Supplied[[]string]) {})
+	command := NewCommand(CommandSpec[struct{}]{Name: "run", Flags: []Flag[struct{}]{badFlag}, Arguments: []Argument[struct{}]{badArgument}})
+	app, err := New(Identity{Name: "example"}, command)
+	if err == nil {
+		t.Fatal("installation accepted nil parser wiring and invalid argument cardinality")
+	}
+	if app != nil {
+		t.Fatal("failed installation returned a usable app")
+	}
+}
+
 func TestRepeatArgumentAllocationReservesLaterMinimums(t *testing.T) {
 	type operandsInput struct {
 		prefix Supplied[[]string]
@@ -163,7 +204,7 @@ func TestRepeatArgumentAllocationReservesLaterMinimums(t *testing.T) {
 			RepeatArgument(ArgumentMeta{Name: "suffix"}, 1, -1, func(value string) (string, error) { return value, nil }, func(input *operandsInput, value Supplied[[]string]) { input.suffix = value }),
 		},
 	}
-	if _, err := NewCommand(spec); err != nil {
+	if err := validateCommandDeclaration(NewCommand(spec)); err != nil {
 		t.Fatal(err)
 	}
 	prepared, err := prepareInput(spec, nil, []string{"a", "b", "id-1", "x", "y"}, true)
@@ -193,7 +234,7 @@ func TestIncompletePreparationSkipsMissingRequirementsAndInputFactory(t *testing
 		Flags:     []Flag[struct{}]{ValueFlag(FlagMeta{Name: "required", Required: true}, (*string)(nil), func(value string) (string, error) { return value, nil }, func(*struct{}, Supplied[string]) {})},
 		Arguments: []Argument[struct{}]{ValueArgument(ArgumentMeta{Name: "id"}, true, func(value string) (string, error) { return value, nil }, func(*struct{}, Supplied[string]) {})},
 	}
-	if _, err := NewCommand(spec); err != nil {
+	if err := validateCommandDeclaration(NewCommand(spec)); err != nil {
 		t.Fatal(err)
 	}
 	if _, err := prepareInput(spec, [][]string{nil}, nil, true); err == nil {
@@ -206,3 +247,90 @@ func TestIncompletePreparationSkipsMissingRequirementsAndInputFactory(t *testing
 		t.Fatalf("preparation invoked NewInput %d times", factoryCalls)
 	}
 }
+
+func TestExecuteBindsMixedFlagSpellingsWithFreshPresence(t *testing.T) {
+	type input struct {
+		count    Supplied[int]
+		enabled  Supplied[bool]
+		message  Supplied[string]
+		tags     Supplied[[]string]
+		required Supplied[string]
+		instance int
+	}
+	type observed struct {
+		count    Supplied[int]
+		enabled  Supplied[bool]
+		message  Supplied[string]
+		tags     Supplied[[]string]
+		required Supplied[string]
+		instance int
+	}
+	defaultCount := 9
+	defaultMessage := "fallback"
+	defaultTags := []string{"base"}
+	countParses, inputFactories := 0, 0
+	var calls []observed
+	command := NewCommand(CommandSpec[input]{
+		Name: "run",
+		NewInput: func() input {
+			inputFactories++
+			return input{instance: inputFactories}
+		},
+		Flags: []Flag[input]{
+			ValueFlag(FlagMeta{Name: "count"}, &defaultCount, func(value string) (int, error) {
+				countParses++
+				return strconv.Atoi(value)
+			}, func(target *input, value Supplied[int]) { target.count = value }),
+			BoolFlag(FlagMeta{Name: "enabled"}, true, func(target *input, value Supplied[bool]) { target.enabled = value }),
+			ValueFlag(FlagMeta{Name: "message"}, &defaultMessage, func(value string) (string, error) { return value, nil }, func(target *input, value Supplied[string]) { target.message = value }),
+			RepeatFlag(FlagMeta{Name: "tag"}, defaultTags, func(value string) (string, error) { return value, nil }, func(target *input, value Supplied[[]string]) { target.tags = value }),
+			ValueFlag(FlagMeta{Name: "required", Required: true}, (*string)(nil), func(value string) (string, error) { return value, nil }, func(target *input, value Supplied[string]) { target.required = value }),
+		},
+		Run: func(_ Invocation, value input) Outcome {
+			value.tags.Value = append([]string(nil), value.tags.Value...)
+			calls = append(calls, observed(value))
+			return Success()
+		},
+	})
+	app, err := New(Identity{Name: "Example"}, command,
+		Alias("shortcut", "run"),
+		FlagAliasFor("run", "--number", "--count"),
+		FlagAliasFor("run", "--active", "--enabled"),
+		FlagAliasFor("run", "--text", "--message"),
+		FlagAliasFor("run", "--label", "--tag"),
+	)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	for _, args := range [][]string{
+		{"shortcut", "--number=0", "--count=5", "--active=false", "--enabled=true", "--text=", "--message=last", "--label=a", "--tag=b", "--required=first"},
+		{"run", "--number=0", "--active=false", "--text=", "--label=c", "--required=second"},
+	} {
+		if outcome := app.Execute(context.Background(), args, Streams{Out: io.Discard, Err: io.Discard}); outcome.Kind != OutcomeSuccess {
+			t.Fatalf("Execute(%q) = %#v, want success", args, outcome)
+		}
+	}
+	if countParses != 3 {
+		t.Fatalf("count conversions = %d, want every one of three occurrences", countParses)
+	}
+	if len(calls) != 2 || calls[0].count != (Supplied[int]{Value: 5, Set: true}) || calls[0].enabled != (Supplied[bool]{Value: true, Set: true}) || calls[0].message != (Supplied[string]{Value: "last", Set: true}) || !reflect.DeepEqual(calls[0].tags, Supplied[[]string]{Value: []string{"a", "b"}, Set: true}) || calls[0].required != (Supplied[string]{Value: "first", Set: true}) {
+		t.Fatalf("first mixed-spelling invocation = %#v", calls)
+	}
+	if calls[1].count != (Supplied[int]{Value: 0, Set: true}) || calls[1].enabled != (Supplied[bool]{Value: false, Set: true}) || calls[1].message != (Supplied[string]{Value: "", Set: true}) || !reflect.DeepEqual(calls[1].tags, Supplied[[]string]{Value: []string{"c"}, Set: true}) || calls[1].required != (Supplied[string]{Value: "second", Set: true}) || calls[0].instance == calls[1].instance {
+		t.Fatalf("second mixed-spelling invocation = %#v", calls[1])
+	}
+
+	if outcome := app.Execute(context.Background(), []string{"shortcut", "--count=7"}, Streams{Out: io.Discard, Err: io.Discard}); outcome.Kind != OutcomeUsage {
+		t.Fatalf("missing required flag outcome = %#v, want usage", outcome)
+	}
+	if inputFactories != 2 || len(calls) != 2 {
+		t.Fatalf("missing required flag created or ran input: factories=%d calls=%d", inputFactories, len(calls))
+	}
+	if outcome := app.Execute(context.Background(), []string{"shortcut", "--required=defaults"}, Streams{Out: io.Discard, Err: io.Discard}); outcome.Kind != OutcomeSuccess {
+		t.Fatalf("defaulted invocation = %#v, want success", outcome)
+	}
+	if len(calls) != 3 || calls[2].count != (Supplied[int]{Value: 9}) || calls[2].enabled != (Supplied[bool]{Value: true}) || calls[2].message != (Supplied[string]{Value: "fallback"}) || !reflect.DeepEqual(calls[2].tags, Supplied[[]string]{Value: []string{"base"}}) || calls[2].required != (Supplied[string]{Value: "defaults", Set: true}) || calls[2].instance == calls[1].instance {
+		t.Fatalf("omitted values reused prior invocation state: %#v", calls[2])
+	}
+}

builtins.go

@@ -1,18 +1,16 @@
 package commandkit
 
 import (
-	"bytes"
-	"errors"
 	"fmt"
 	"io"
 	"runtime/debug"
-	"strings"
 
-	internalcobra "gitea.maximumdirect.net/eric/CommandKit/internal/cobra"
+	internalcobra "go.maximumdirect.net/commandkit/internal/cobra"
+	commandmeta "go.maximumdirect.net/commandkit/internal/commandmeta"
 	yaml "go.yaml.in/yaml/v4"
 )
 
-const commandKitModulePath = "gitea.maximumdirect.net/eric/CommandKit"
+const commandKitModulePath = "go.maximumdirect.net/commandkit"
 
 type helpInput struct {
 	Targets Supplied[[]string]
@@ -29,30 +27,26 @@ type versionDocument struct {
 	Revision string `yaml:"revision"`
 }
 
-func (a *App) installBuiltins() error {
-	help, err := NewCommand(CommandSpec[helpInput]{
+func (a *App) builtinCommands() []Declaration {
+	help := captureCommand(CommandSpec[helpInput]{
 		Name:        "help",
 		Summary:     "Show help for commands.",
 		Description: "Describe registered commands and their inputs.",
 		Arguments: []Argument[helpInput]{RepeatArgument(ArgumentMeta{Name: "COMMAND", Usage: "registered command path"}, 0, -1,
 			func(value string) (string, error) { return value, nil },
 			func(input *helpInput, value Supplied[[]string]) { input.Targets = value })},
-		Run: func(invocation Invocation, input helpInput) Outcome {
-			return a.renderHelpTargets(input.Targets.Value, invocation.Streams)
-		},
+	}, func(current commandExecution, input helpInput) Outcome {
+		return current.renderHelpTargets(input.Targets.Value)
 	})
-	if err != nil {
-		return fmt.Errorf("create built-in help command: %w", err)
-	}
 	scopeDefault := "app"
 	formatDefault := "text"
-	version, err := NewCommand(CommandSpec[versionInput]{
+	version := NewCommand(CommandSpec[versionInput]{
 		Name:        "version",
 		Summary:     "Show application or CommandKit version.",
 		Description: "Report identity and build metadata without loading application configuration.",
 		Flags: []Flag[versionInput]{
-			ValueFlag(FlagMeta{Name: "scope", Usage: "version subject"}, &scopeDefault, parseVersionScope, func(input *versionInput, value Supplied[string]) { input.Scope = value.Value }),
-			ValueFlag(FlagMeta{Name: "format", Usage: "output format"}, &formatDefault, parseVersionFormat, func(input *versionInput, value Supplied[string]) { input.Format = value.Value }),
+			ValueFlag(FlagMeta{Name: "scope", Usage: "version subject", Completion: CompleteChoices(CompletionChoice{Value: "app"}, CompletionChoice{Value: "commandkit"})}, &scopeDefault, parseVersionScope, func(input *versionInput, value Supplied[string]) { input.Scope = value.Value }),
+			ValueFlag(FlagMeta{Name: "format", Usage: "output format", Completion: CompleteChoices(CompletionChoice{Value: "text"}, CompletionChoice{Value: "yaml"})}, &formatDefault, parseVersionFormat, func(input *versionInput, value Supplied[string]) { input.Format = value.Value }),
 		},
 		Run: func(invocation Invocation, input versionInput) Outcome {
 			identity := a.identity
@@ -62,15 +56,10 @@ func (a *App) installBuiltins() error {
 			if identity.Version == "" {
 				identity.Version = "dev"
 			}
-			return renderVersionOutcome(identity, input.Format, invocation.Streams)
+			return renderVersionOutcome(identity, input.Format, invocation.Reporter())
 		},
 	})
-	if err != nil {
-		return fmt.Errorf("create built-in version command: %w", err)
-	}
-	a.commands["help"] = &commandNode{command: help, reserved: true}
-	a.commands["version"] = &commandNode{command: version, reserved: true}
-	return nil
+	return []Declaration{help, version}
 }
 
 func parseVersionScope(value string) (string, error) {
@@ -87,67 +76,41 @@ func parseVersionFormat(value string) (string, error) {
 	return value, nil
 }
 
-func (a *App) renderHelpOutcome(path []string, streams Streams) Outcome {
-	session := internalcobra.Prepare(a.bridgeTree(), internalcobra.ParseOptions{})
-	return a.renderHelpOutcomeWithSession(path, streams, session)
-}
-
-func (a *App) renderHelpTargets(targets []string, streams Streams) Outcome {
-	session := internalcobra.Prepare(a.bridgeTree(), internalcobra.ParseOptions{})
-	return a.renderHelpTargetsWithSession(targets, streams, session)
-}
-
-func (a *App) renderHelpTargetsWithSession(targets []string, streams Streams, session *internalcobra.Session) Outcome {
-	target, err := a.helpCommandTarget(targets)
-	if err != nil {
-		return Usage(err)
-	}
-	return a.renderHelpOutcomeWithSession(target, streams, session)
-}
-
-func (a *App) renderHelpOutcomeWithSession(path []string, streams Streams, session *internalcobra.Session) Outcome {
-	if len(path) > 0 {
-		if _, ok := a.commandAt(path); !ok {
-			return Usage(fmt.Errorf("unknown help path %q", strings.Join(path, " ")))
-		}
-	}
-	content, failure := session.RenderHelp(path)
+func (a *App) renderHelpViewOutcomeWithSession(view commandmeta.HelpView, reporter *Reporter, session *internalcobra.Session) Outcome {
+	content, failure := session.RenderHelpView(view)
 	if failure != nil {
-		return Failure(errors.New(failure.Message))
-	}
-	if err := writeReport(streams.Out, []byte(content)); err != nil {
-		return incompleteReport(err)
+		if failure.Usage {
+			return Usage(failure.Message)
+		}
+		return Failure(failure.Message)
 	}
+	_ = reporter.RenderOutput(func(w io.Writer) error {
+		_, err := io.WriteString(w, content)
+		return err
+	})
 	return Success()
 }
 
-func renderVersionOutcome(identity Identity, format string, streams Streams) Outcome {
-	var content []byte
+func renderVersionOutcome(identity Identity, format string, reporter *Reporter) Outcome {
+	if identity.Version == "" {
+		identity.Version = "dev"
+	}
 	switch format {
 	case "text":
-		name := identity.Name
-		if identity.Version == "" {
-			identity.Version = "dev"
-		}
-		line := name + " " + identity.Version
+		line := identity.Name + " " + identity.Version
 		if identity.Revision != "" {
 			line += " (" + identity.Revision + ")"
 		}
-		content = []byte(line + "\n")
+		_ = reporter.RenderOutput(func(w io.Writer) error {
+			_, err := io.WriteString(w, line+"\n")
+			return err
+		})
 	case "yaml":
-		if identity.Version == "" {
-			identity.Version = "dev"
-		}
-		var buffer bytes.Buffer
-		if err := encodeYAML(&buffer, versionDocument{Name: identity.Name, Version: identity.Version, Revision: identity.Revision}); err != nil {
-			return Failure(err)
-		}
-		content = buffer.Bytes()
+		_ = reporter.RenderOutput(func(w io.Writer) error {
+			return encodeYAML(w, versionDocument{Name: identity.Name, Version: identity.Version, Revision: identity.Revision})
+		})
 	default:
-		return Usage(fmt.Errorf("unsupported version format %q", format))
-	}
-	if err := writeReport(streams.Out, content); err != nil {
-		return incompleteReport(err)
+		return Usage(fmt.Sprintf("unsupported version format %q", format))
 	}
 	return Success()
 }
@@ -158,22 +121,6 @@ func encodeYAML(writer io.Writer, document any) error {
 	return encoder.Encode(document)
 }
 
-func writeReport(writer io.Writer, content []byte) error {
-	checked := &checkedWriter{writer: writer}
-	_, err := checked.Write(content)
-	if err == nil {
-		err = checked.failure
-	}
-	return err
-}
-
-func incompleteReport(err error) Outcome {
-	outcome := Failure(err)
-	outcome.ReportIncomplete = true
-	outcome.DeliveryError = err
-	return outcome
-}
-
 func readBuildInfo() *debug.BuildInfo {
 	info, ok := debug.ReadBuildInfo()
 	if !ok {
@@ -210,13 +157,3 @@ func commandKitBuildIdentity(info *debug.BuildInfo) Identity {
 	}
 	return identity
 }
-
-func (a *App) helpCommandTarget(targets []string) ([]string, error) {
-	if len(targets) == 0 {
-		return nil, nil
-	}
-	if _, ok := a.commandAt(targets); !ok {
-		return nil, fmt.Errorf("unknown help path %q", strings.Join(targets, " "))
-	}
-	return append([]string(nil), targets...), nil
-}

builtins_reporting_test.go

@@ -0,0 +1,110 @@
+package commandkit
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"io"
+	"strings"
+	"testing"
+)
+
+func builtinReportingTestApp(t *testing.T) *App {
+	t.Helper()
+	command := NewCommand(CommandSpec[struct{}]{
+		Name: "run",
+		Run:  func(Invocation, struct{}) Outcome { return Success() },
+	})
+	app, err := New(Identity{Name: "Example", Version: "1.2.3"}, command,
+		Group("promptkit", "PromptKit", Group("list", "List", simpleRunnable("collections"))),
+		Alias("r", "run"), Alias("list collections", "promptkit list collections"),
+	)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return app
+}
+
+func TestHelpAndVersionUseManagedOutput(t *testing.T) {
+	app := builtinReportingTestApp(t)
+	for _, args := range [][]string{{"help", "--quiet"}, {"version", "--quiet"}, {"list", "--help", "--quiet"}} {
+		var output, diagnostics bytes.Buffer
+		outcome := app.Execute(context.Background(), args, Streams{Out: &output, Err: &diagnostics})
+		if outcome.Kind != OutcomeSuccess || outcome.Status != 0 {
+			t.Errorf("Execute(%q) = %#v", args, outcome)
+		}
+		if output.Len() != 0 || diagnostics.Len() != 0 {
+			t.Errorf("Execute(%q) wrote output %q or diagnostics %q", args, output.String(), diagnostics.String())
+		}
+		if outcome.Presentation.Output.State != DeliverySuppressed {
+			t.Errorf("Execute(%q) output presentation = %#v", args, outcome.Presentation.Output)
+		}
+	}
+
+	for _, test := range []struct {
+		args []string
+		want string
+	}{
+		{args: []string{"help", "run"}, want: "run"},
+		{args: []string{"help", "r"}, want: "Alias for: Example run"},
+		{args: []string{"list", "--help"}, want: "Reporting Flags"},
+		{args: []string{"version"}, want: "Example 1.2.3"},
+		{args: []string{"version", "--format=yaml"}, want: "version: 1.2.3"},
+	} {
+		var output, diagnostics bytes.Buffer
+		outcome := app.Execute(context.Background(), test.args, Streams{Out: &output, Err: &diagnostics})
+		if outcome.Kind != OutcomeSuccess || !strings.Contains(output.String(), test.want) {
+			t.Errorf("Execute(%q) = %#v, output %q", test.args, outcome, output.String())
+		}
+	}
+}
+
+func TestHelpAndVersionDestinationFailuresUseReporterObservations(t *testing.T) {
+	app := builtinReportingTestApp(t)
+	writeErr := errors.New("help/version destination failed")
+	for _, args := range [][]string{{"help", "run"}, {"version"}} {
+		var diagnostics bytes.Buffer
+		outcome := app.Execute(context.Background(), args, Streams{
+			Out: executeReportingFailureWriter{err: writeErr}, Err: &diagnostics,
+		})
+		if outcome.Kind != OutcomeOperational || outcome.Status != 1 {
+			t.Errorf("Execute(%q) = %#v", args, outcome)
+		}
+		if !errors.Is(outcome.Presentation.Output.WriteError, writeErr) || outcome.Presentation.Output.State != DeliveryIncomplete {
+			t.Errorf("Execute(%q) presentation = %#v", args, outcome.Presentation)
+		}
+		if !strings.Contains(diagnostics.String(), "deliver") || !strings.Contains(diagnostics.String(), "output") {
+			t.Errorf("Execute(%q) diagnostics = %q", args, diagnostics.String())
+		}
+	}
+}
+
+func TestInvalidHelpAndVersionRequestsRemainUsageOutcomes(t *testing.T) {
+	app := builtinReportingTestApp(t)
+	for _, args := range [][]string{{"help", "unknown"}, {"version", "--scope=unknown"}, {"version", "--format=unknown"}} {
+		var output, diagnostics bytes.Buffer
+		outcome := app.Execute(context.Background(), args, Streams{Out: &output, Err: &diagnostics})
+		if outcome.Kind != OutcomeUsage || outcome.Status != 2 {
+			t.Errorf("Execute(%q) = %#v", args, outcome)
+		}
+		if !strings.Contains(diagnostics.String(), "Usage: Example") {
+			t.Errorf("Execute(%q) diagnostics = %q", args, diagnostics.String())
+		}
+	}
+}
+
+func TestQuietBuiltinRenderingSuppressesDestinationWrites(t *testing.T) {
+	app := builtinReportingTestApp(t)
+
+	// A quiet successful run must not touch its supplied result destination.
+	var diagnostics bytes.Buffer
+	outcome := app.Execute(context.Background(), []string{"version", "--quiet"}, Streams{
+		Out: executeReportingFailureWriter{err: io.ErrClosedPipe}, Err: &diagnostics,
+	})
+	if outcome.Kind != OutcomeSuccess || outcome.Presentation.Output.State != DeliverySuppressed {
+		t.Fatalf("quiet version outcome = %#v", outcome)
+	}
+	if diagnostics.Len() != 0 {
+		t.Fatalf("quiet version diagnostics = %q", diagnostics.String())
+	}
+}

builtins_test.go

@@ -13,7 +13,7 @@ func TestCommandKitBuildIdentityProjectsEffectiveModuleVersion(t *testing.T) {
 	}{
 		{
 			name: "main module tag",
-			info: &debug.BuildInfo{Main: debug.Module{Path: commandKitModulePath, Version: "v1.2.3"}},
+			info: &debug.BuildInfo{Main: debug.Module{Path: "go.maximumdirect.net/commandkit", Version: "v1.2.3"}},
 			want: "v1.2.3",
 		},
 		{

cancellation_test.go

@@ -1,120 +0,0 @@
-package commandkit_test
-
-import (
-	"bytes"
-	"context"
-	"errors"
-	"fmt"
-	commandkit "gitea.maximumdirect.net/eric/CommandKit"
-	configkit "gitea.maximumdirect.net/eric/ConfigKit"
-	"gitea.maximumdirect.net/eric/promptkit"
-	"strings"
-	"testing"
-)
-
-func TestStandardConfigurationCancellationBoundaries(t *testing.T) {
-	for _, operation := range []string{"validate", "show", "sources", "explain"} {
-		for _, before := range []bool{true, false} {
-			t.Run(fmt.Sprintf("%s/before=%t", operation, before), func(t *testing.T) {
-				ctx, cancel := context.WithCancel(context.Background())
-				defer cancel()
-				if before {
-					cancel()
-				}
-				loads, contexts := 0, 0
-				scope, err := commandkit.NewConfigKitScope[struct{}, struct{}]("app", "", func(context.Context, commandkit.Selection, struct{}) (*configkit.Result[struct{}], error) {
-					loads++
-					cancel()
-					return configkit.Load(configkit.NoSource(), configkit.Options[struct{}]{})
-				})
-				if err != nil {
-					t.Fatal(err)
-				}
-				app, _ := commandkit.New(commandkit.Identity{Name: "example"})
-				if err := commandkit.RegisterConfig(app, commandkit.ConfigSuite[struct{}]{Scopes: []commandkit.ConfigScope[struct{}]{scope}, NewContext: func() struct{} { contexts++; return struct{}{} }}); err != nil {
-					t.Fatal(err)
-				}
-				args := []string{"config", operation}
-				if operation == "explain" {
-					args = append(args, "--path", "")
-				}
-				var out bytes.Buffer
-				result := app.Execute(ctx, args, commandkit.Streams{Out: &out})
-				want := 1
-				if before {
-					want = 0
-				}
-				if result.Kind != commandkit.OutcomeOperational || result.Status != 1 || !errors.Is(result.Cause, context.Canceled) || loads != want || contexts != want || out.Len() != 0 {
-					t.Fatalf("result=%#v loads=%d contexts=%d out=%q", result, loads, contexts, out.String())
-				}
-			})
-		}
-	}
-}
-
-func TestAggregateCancellationRetainsCompletedValidationAndDiagnostics(t *testing.T) {
-	ctx, cancel := context.WithCancel(context.Background())
-	defer cancel()
-	app, _ := commandkit.New(commandkit.Identity{Name: "example"})
-	calls := 0
-	acquire := func(context.Context, commandkit.ConfigRequest, struct{}) (commandkit.Acquired[commandkit.ConfigView], error) {
-		calls++
-		if calls == 2 {
-			cancel()
-		}
-		return commandkit.Acquired[commandkit.ConfigView]{Diagnostics: []commandkit.Diagnostic{commandkit.MessageDiagnostic(configkit.SeverityWarning, "acquired warning")}}, nil
-	}
-	if err := commandkit.RegisterConfig(app, commandkit.ConfigSuite[struct{}]{Scopes: []commandkit.ConfigScope[struct{}]{
-		{Name: "app", Operations: []commandkit.ConfigOperation{commandkit.ConfigValidate}, Acquire: acquire},
-		{Name: "promptkit", Operations: []commandkit.ConfigOperation{commandkit.ConfigValidate}, Acquire: acquire},
-		{Name: "zeta", Operations: []commandkit.ConfigOperation{commandkit.ConfigValidate}, Acquire: acquire},
-	}}); err != nil {
-		t.Fatal(err)
-	}
-	var out, diagnostics bytes.Buffer
-	result := app.Execute(ctx, []string{"config", "validate", "--scope", "all"}, commandkit.Streams{Out: &out, Err: &diagnostics})
-	if !errors.Is(result.Cause, context.Canceled) || !result.ReportIncomplete || calls != 2 || out.String() != "app: valid\n" || strings.Count(diagnostics.String(), "acquired warning") != 2 {
-		t.Fatalf("result=%#v calls=%d out=%q diagnostics=%q", result, calls, out.String(), diagnostics.String())
-	}
-}
-
-func TestDefinitionInspectionCancellationBoundaries(t *testing.T) {
-	for _, resource := range []string{"prompt", "profile"} {
-		for _, before := range []bool{true, false} {
-			t.Run(fmt.Sprintf("%s/before=%t", resource, before), func(t *testing.T) {
-				ctx, cancel := context.WithCancel(context.Background())
-				defer cancel()
-				if before {
-					cancel()
-				}
-				calls, contexts := 0, 0
-				diagnostics := []commandkit.Diagnostic{commandkit.MessageDiagnostic(configkit.SeverityWarning, "acquired warning")}
-				suite := commandkit.PromptKitSuite[struct{}]{NewContext: func() struct{} { contexts++; return struct{}{} },
-					InspectPrompt: func(context.Context, commandkit.Selection, struct{}, string, string) (commandkit.Acquired[*promptkit.PromptInspection], error) {
-						calls++
-						cancel()
-						return commandkit.Acquired[*promptkit.PromptInspection]{Value: &promptkit.PromptInspection{}, Diagnostics: diagnostics}, nil
-					},
-					InspectProfile: func(context.Context, commandkit.Selection, struct{}, string) (commandkit.Acquired[*promptkit.ProfileInspection], error) {
-						calls++
-						cancel()
-						return commandkit.Acquired[*promptkit.ProfileInspection]{Value: &promptkit.ProfileInspection{}, Diagnostics: diagnostics}, nil
-					},
-				}
-				app, _ := commandkit.New(commandkit.Identity{Name: "example"})
-				if err := commandkit.RegisterPromptKit(app, suite); err != nil {
-					t.Fatal(err)
-				}
-				var out, errs bytes.Buffer
-				result := app.Execute(ctx, []string{"promptkit", "show", resource, "example"}, commandkit.Streams{Out: &out, Err: &errs})
-				want := 1
-				if before {
-					want = 0
-				}
-				if result.Kind != commandkit.OutcomeOperational || !errors.Is(result.Cause, context.Canceled) || calls != want || contexts != want || out.Len() != 0 || (!before && !strings.Contains(errs.String(), "acquired warning")) {
-					t.Fatalf("result=%#v calls=%d contexts=%d out=%q diagnostics=%q", result, calls, contexts, out.String(), errs.String())
-				}
-			})
-		}
-	}
-}

command.go

@@ -1,24 +1,86 @@
 package commandkit
 
 import (
+	"errors"
 	"fmt"
 	"strings"
 	"unicode"
 
-	internalcobra "gitea.maximumdirect.net/eric/CommandKit/internal/cobra"
+	commandmeta "go.maximumdirect.net/commandkit/internal/commandmeta"
+	"go.maximumdirect.net/commandkit/internal/commandpath"
 )
 
-// Command is an opaque command declaration. Use NewCommand or Group to create
-// declarations and WithChildren to compose them.
-type Command struct {
+// Command is an opaque, reusable declaration of canonical commands and groups.
+// NewCommand, Group, RootGroup, and integration command factories return
+// Command values. Capture copies declaration slices but retains callback and
+// caller-owned object references. Installation validates the declaration
+// before changing an App registry.
+type Command struct{ record *commandRecord }
+
+// Declaration is a captured canonical command or application routing rule
+// accepted by New and App.Register. Use []Declaration when collecting both
+// kinds. Group and RootGroup children remain Commands; install routing rules
+// alongside the completed command tree through New or Register. Only
+// CommandKit declaration types implement Declaration.
+//
+// A zero Command, zero RoutingRule, nil declaration, or typed nil declaration
+// pointer is invalid. Use NoCommand to represent an intentionally absent
+// optional command.
+type Declaration interface {
+	commandkitDeclaration()
+}
+
+func (Command) commandkitDeclaration() {}
+
+// RoutingRule is an opaque, reusable command or flag alias declaration. Alias,
+// FlagAlias, and FlagAliasFor capture routing rules eagerly and retain any
+// construction issues for New or App.Register to report. Identical duplicate
+// mappings are accepted; competing targets for the same source are errors.
+type RoutingRule struct{ record *routingRuleRecord }
+
+func (RoutingRule) commandkitDeclaration() {}
+
+type routingRuleKind uint8
+
+const (
+	commandAliasRule routingRuleKind = iota + 1
+	globalFlagAliasRule
+	scopedFlagAliasRule
+)
+
+type capturedFlagSpelling struct {
+	name  string
+	short bool
+}
+
+type routingRuleRecord struct {
+	kind       routingRuleKind
+	sourcePath commandpath.Path
+	targetPath commandpath.Path
+	scopePath  commandpath.Path
+	sourceFlag capturedFlagSpelling
+	targetFlag capturedFlagSpelling
+	sourceText string
+	targetText string
+	scopeText  string
+	issues     []error
+}
+
+type commandRecord struct {
 	name        string
 	summary     string
 	description string
 	children    []Command
 	payload     commandPayload
+	issues      []error
+	rootOnly    bool
+	completion  bool
+	absent      bool
+	invalid     bool
 }
 
-// Supplied carries a value and whether it was explicitly provided.
+// Supplied carries a value and whether it was explicitly provided. Defaults can
+// have Set=false; an explicitly supplied empty, false, or zero value has Set=true.
 type Supplied[T any] struct {
 	// Value is the associated value.
 	Value T
@@ -26,7 +88,8 @@ type Supplied[T any] struct {
 	Set bool
 }
 
-// FlagMeta describes a command flag.
+// FlagMeta describes a command flag. Required applies when execution prepares
+// the selected command; help reports the metadata without requiring the value.
 type FlagMeta struct {
 	// Name is the flag name without leading dashes.
 	Name string
@@ -36,29 +99,45 @@ type FlagMeta struct {
 	Usage string
 	// Required reports whether execution requires the flag to be supplied.
 	Required bool
+	// Completion describes optional value suggestions.
+	Completion CompletionHint
 }
 
-// ArgumentMeta describes a positional command argument.
+// ArgumentMeta describes a positional command argument. Its name and usage are
+// used in generated help.
 type ArgumentMeta struct {
 	// Name is the argument name shown in command help.
 	Name string
 	// Usage briefly describes the argument.
 	Usage string
+	// Completion describes optional value suggestions.
+	Completion CompletionHint
 }
 
-// Flag represents a typed binding for a command flag.
+// Flag represents a typed binding for a command flag. Copies retain binding
+// identity; separately constructed flags are distinct even when their metadata
+// and callbacks are equivalent.
 type Flag[I any] struct {
 	binding flagBinding[I]
 }
 
+type bindingIdentity struct{ marker byte }
+
+type preparedValue[I any] struct {
+	identity *bindingIdentity
+	supplied bool
+	apply    func(*I)
+}
+
 type flagBinding[I any] struct {
-	meta        FlagMeta
-	defaultText string
-	repeated    bool
-	boolean     bool
-	prepare     func([]string) (func(*I), error)
-	clear       func(*I)
-	valid       bool
+	identity         *bindingIdentity
+	meta             FlagMeta
+	deferredRequired bool
+	defaultText      string
+	repeated         bool
+	boolean          bool
+	prepare          func([]string) (preparedValue[I], error)
+	valid            bool
 }
 
 // Argument represents a typed binding for a positional command argument.
@@ -67,14 +146,19 @@ type Argument[I any] struct {
 }
 
 type argumentBinding[I any] struct {
-	meta    ArgumentMeta
-	min     int
-	max     int
-	prepare func([]string) (func(*I), error)
-	valid   bool
+	identity *bindingIdentity
+	meta     ArgumentMeta
+	min      int
+	max      int
+	prepare  func([]string) (preparedValue[I], error)
+	valid    bool
 }
 
 // CommandSpec declares one command using typed input and handler callbacks.
+// Capture copies its Flags, Arguments, and Children slices. NewInput runs only
+// when execution reaches input construction; a nil factory yields a fresh zero
+// value. CheckInput runs after supplied values are converted and applied, before
+// Run. Run may be nil for a parent that only groups child commands.
 type CommandSpec[I any] struct {
 	// Name is one command path component.
 	Name string
@@ -82,6 +166,8 @@ type CommandSpec[I any] struct {
 	Summary string
 	// Description provides additional command detail.
 	Description string
+	// Children are relative child declarations captured with this command.
+	Children []Command
 	// NewInput creates an input value for execution. A nil factory uses a fresh
 	// zero value.
 	NewInput func() I
@@ -98,15 +184,14 @@ type CommandSpec[I any] struct {
 type commandPayload interface {
 	validate() error
 	hasRun() bool
-	bridgeFlags() []internalcobra.Flag
-	bridgeArguments() []internalcobra.Argument
-	prepare([][]string, []string, bool) (func() any, error)
-	checkInput(any) error
-	run(Invocation, any) Outcome
+	bridgeFlags() []commandmeta.Flag
+	bridgeArguments() []commandmeta.Argument
+	prepare([][]string, [][]string, []string, bool) (func(*execution) Outcome, error)
 }
 
 type typedCommand[I any] struct {
-	spec CommandSpec[I]
+	spec       CommandSpec[I]
+	privateRun func(commandExecution, I) Outcome
 }
 
 func (c typedCommand[I]) validate() error {
@@ -114,158 +199,272 @@ func (c typedCommand[I]) validate() error {
 }
 
 func (c typedCommand[I]) hasRun() bool {
-	return c.spec.Run != nil
+	return c.spec.Run != nil || c.privateRun != nil
 }
 
-func (c typedCommand[I]) bridgeFlags() []internalcobra.Flag {
-	flags := make([]internalcobra.Flag, len(c.spec.Flags))
+func (c typedCommand[I]) bridgeFlags() []commandmeta.Flag {
+	flags := make([]commandmeta.Flag, len(c.spec.Flags))
 	for index, flag := range c.spec.Flags {
 		binding := flag.binding
-		flags[index] = internalcobra.Flag{
-			Name:     binding.meta.Name,
-			Short:    binding.meta.Short,
-			Usage:    binding.meta.Usage,
-			Default:  binding.defaultText,
-			Boolean:  binding.boolean,
-			Repeated: binding.repeated,
-			Required: binding.meta.Required,
+		flags[index] = commandmeta.Flag{
+			Name:       binding.meta.Name,
+			Short:      binding.meta.Short,
+			Usage:      binding.meta.Usage,
+			Default:    binding.defaultText,
+			Boolean:    binding.boolean,
+			Repeated:   binding.repeated,
+			Required:   binding.meta.Required,
+			Completion: bridgeCompletion(binding.meta.Completion),
 		}
 	}
 	return flags
 }
 
-func (c typedCommand[I]) bridgeArguments() []internalcobra.Argument {
-	arguments := make([]internalcobra.Argument, len(c.spec.Arguments))
+func (c typedCommand[I]) bridgeArguments() []commandmeta.Argument {
+	arguments := make([]commandmeta.Argument, len(c.spec.Arguments))
 	for index, argument := range c.spec.Arguments {
 		binding := argument.binding
-		arguments[index] = internalcobra.Argument{
-			Name:  binding.meta.Name,
-			Usage: binding.meta.Usage,
-			Min:   binding.min,
-			Max:   binding.max,
+		arguments[index] = commandmeta.Argument{
+			Name:       binding.meta.Name,
+			Usage:      binding.meta.Usage,
+			Min:        binding.min,
+			Max:        binding.max,
+			Completion: bridgeCompletion(binding.meta.Completion),
 		}
 	}
 	return arguments
 }
 
-func (c typedCommand[I]) prepare(flagValues [][]string, operands []string, enforceRequired bool) (func() any, error) {
-	prepared, err := prepareInput(c.spec, flagValues, operands, enforceRequired)
+func (c typedCommand[I]) prepare(flagValues, flagSpellings [][]string, operands []string, enforceRequired bool) (func(*execution) Outcome, error) {
+	prepared, err := prepareInputWithSpellings(c.spec, flagValues, flagSpellings, operands, enforceRequired)
 	if err != nil {
 		return nil, err
 	}
-	return func() any {
+	return func(current *execution) Outcome {
 		input := prepared.build()
-		return &input
+		if c.spec.CheckInput != nil {
+			if err := c.spec.CheckInput(input); err != nil {
+				return classifyInputError(err)
+			}
+		}
+		if c.privateRun != nil {
+			return c.privateRun(current.commandContext(), input)
+		}
+		return c.spec.Run(current.invocation(), input)
 	}, nil
 }
 
-func (c typedCommand[I]) run(invocation Invocation, input any) Outcome {
-	return c.spec.Run(invocation, *input.(*I))
+// NewCommand captures a typed canonical command declaration without
+// constructing its input or running callbacks. It copies the spec's flags,
+// arguments, and children slices. Construction issues are retained and
+// reported when the declaration is installed; NewCommand itself does not
+// return an error. The returned declaration can be reused across Apps.
+func NewCommand[I any](spec CommandSpec[I]) Command {
+	return captureCommand(spec, nil)
 }
 
-func (c typedCommand[I]) checkInput(input any) error {
-	if c.spec.CheckInput == nil {
-		return nil
-	}
-	return c.spec.CheckInput(*input.(*I))
-}
-
-// NewCommand validates and creates a typed command declaration. It retains
-// callbacks without invoking them and copies the declarative flag and argument
-// slices.
-func NewCommand[I any](spec CommandSpec[I]) (Command, error) {
-	if err := validateCommandName(spec.Name); err != nil {
-		return Command{}, err
-	}
+func captureCommand[I any](spec CommandSpec[I], privateRun func(commandExecution, I) Outcome) Command {
 	copySpec := spec
 	copySpec.Flags = append([]Flag[I](nil), spec.Flags...)
 	copySpec.Arguments = append([]Argument[I](nil), spec.Arguments...)
-	payload := typedCommand[I]{spec: copySpec}
+	copySpec.Children = append([]Command(nil), spec.Children...)
+	payload := typedCommand[I]{spec: copySpec, privateRun: privateRun}
+	record := &commandRecord{
+		name: spec.Name, summary: spec.Summary, description: spec.Description,
+		children: copySpec.Children, payload: payload,
+	}
 	if err := payload.validate(); err != nil {
-		return Command{}, fmt.Errorf("command %q: %w", spec.Name, err)
+		record.issues = append(record.issues, fmt.Errorf("command %q: %w", spec.Name, err))
 	}
-	return Command{
-		name:        spec.Name,
-		summary:     spec.Summary,
-		description: spec.Description,
-		payload:     payload,
-	}, nil
+	captureComposition(record)
+	return Command{record: record}
 }
 
-// Group creates a non-runnable command group with the supplied children.
-func Group(name, summary string, children ...Command) (Command, error) {
-	if err := validateCommandName(name); err != nil {
-		return Command{}, err
-	}
-	group := Command{name: name, summary: summary, children: cloneCommands(children)}
-	if err := validateCommandDeclaration(group); err != nil {
-		return Command{}, err
-	}
-	return group, nil
+// Group captures a non-runnable canonical command group and a copy of its
+// relative Command child slice. Child declarations remain reusable and are not
+// recursively copied. Routing rules cannot be children; install them alongside
+// the root command tree through New or App.Register.
+func Group(name, summary string, children ...Command) Command {
+	record := &commandRecord{name: name, summary: summary, children: append([]Command(nil), children...)}
+	captureComposition(record)
+	return Command{record: record}
 }
 
-// WithChildren returns a copy of parent with the supplied relative child
-// declarations. The parent's optional handler and input bindings are retained.
-func WithChildren(parent Command, children ...Command) (Command, error) {
-	if err := validateCommandDeclaration(parent); err != nil {
-		return Command{}, fmt.Errorf("parent command: %w", err)
-	}
-	combined := make([]Command, 0, len(parent.children)+len(children))
-	combined = append(combined, parent.children...)
-	combined = append(combined, children...)
-	result := parent
-	result.children = cloneCommands(combined)
-	if err := validateCommandDeclaration(result); err != nil {
-		return Command{}, err
-	}
-	return result, nil
-}
-
-func cloneCommands(commands []Command) []Command {
-	if len(commands) == 0 {
-		return nil
-	}
-	cloned := make([]Command, len(commands))
-	for i, command := range commands {
-		cloned[i] = cloneCommand(command)
-	}
-	return cloned
-}
-
-func cloneCommand(command Command) Command {
-	command.children = cloneCommands(command.children)
+// RootGroup captures a group that may only be installed at the application
+// root. Installation rejects it below any other command, including through
+// wrappers. Its children are canonical Commands; install routing rules at the
+// application root separately.
+func RootGroup(name, summary string, children ...Command) Command {
+	command := Group(name, summary, children...)
+	command.record.rootOnly = true
 	return command
 }
 
-func validateCommandDeclaration(command Command) error {
-	if err := validateCommandName(command.name); err != nil {
-		return err
+// WithError returns a new Command declaration that also retains a non-nil err
+// for installation. Earlier declaration and child errors remain available,
+// and wrapped error identity is preserved. A nil err returns command unchanged.
+func WithError(command Command, err error) Command {
+	if err == nil {
+		return command
 	}
-	if command.payload != nil {
-		if err := command.payload.validate(); err != nil {
-			return fmt.Errorf("command %q: %w", command.name, err)
-		}
+	var record commandRecord
+	if command.record == nil {
+		record.invalid = true
+	} else {
+		record = *command.record
+		record.issues = append([]error(nil), record.issues...)
 	}
+	record.issues = append(record.issues, err)
+	return Command{record: &record}
+}
 
-	children := make(map[string]struct{}, len(command.children))
-	for _, child := range command.children {
-		if err := validateCommandDeclaration(child); err != nil {
-			return err
-		}
-		if _, exists := children[child.name]; exists {
-			return fmt.Errorf("duplicate child command %q under %q", child.name, command.name)
-		}
-		children[child.name] = struct{}{}
+// NoCommand explicitly represents an absent optional command declaration.
+// Installation skips it, but reports errors attached to it; a zero Command is
+// invalid and is not an absence marker. Routing rules have no absence marker.
+func NoCommand() Command { return Command{record: &commandRecord{absent: true}} }
+
+// Alias captures a command-path alias from path to target. Paths are
+// whitespace-separated sequences of command names relative to the application
+// root. The target must resolve to a canonical command or group; aliases do not
+// add operands or transform flag values. Construction issues are retained for
+// New or App.Register to report. Identical mappings are accepted, while
+// different targets for the same source path are installation errors.
+func Alias(path, target string) RoutingRule {
+	record := &routingRuleRecord{
+		kind:       commandAliasRule,
+		sourceText: path,
+		targetText: target,
+	}
+	record.sourcePath = captureRoutingPath("source", path, &record.issues)
+	record.targetPath = captureRoutingPath("target", target, &record.issues)
+	return RoutingRule{record: record}
+}
+
+// FlagAlias captures an application-wide flag spelling alias. Spellings must
+// be one long flag name or one individual short spelling. The mapping applies
+// wherever its canonical target flag is available and contributes nothing on
+// commands without that flag. Identical mappings are accepted; different
+// targets for the same source spelling in this scope are installation errors.
+func FlagAlias(spelling, target string) RoutingRule {
+	record := &routingRuleRecord{
+		kind:       globalFlagAliasRule,
+		sourceText: spelling,
+		targetText: target,
+	}
+	record.sourceFlag = captureFlagSpelling("source", spelling, &record.issues)
+	record.targetFlag = captureFlagSpelling("target", target, &record.issues)
+	return RoutingRule{record: record}
+}
+
+// FlagAliasFor captures a flag spelling alias scoped to a canonical command
+// path, not an alias path. The command and canonical target flag must be
+// available in the complete installation. Scoped mappings take precedence over
+// application-wide mappings with the same source spelling. Identical mappings
+// are accepted; competing targets in the same scope are installation errors.
+func FlagAliasFor(commandPath, spelling, target string) RoutingRule {
+	record := &routingRuleRecord{
+		kind:       scopedFlagAliasRule,
+		sourceText: spelling,
+		targetText: target,
+		scopeText:  commandPath,
+	}
+	record.scopePath = captureRoutingPath("command scope", commandPath, &record.issues)
+	record.sourceFlag = captureFlagSpelling("source", spelling, &record.issues)
+	record.targetFlag = captureFlagSpelling("target", target, &record.issues)
+	return RoutingRule{record: record}
+}
+
+func captureRoutingPath(label, value string, issues *[]error) commandpath.Path {
+	path, err := commandpath.ParseDeclaration(value)
+	if err != nil {
+		*issues = append(*issues, fmt.Errorf("invalid %s path: %w", label, err))
+	}
+	return path
+}
+
+func captureFlagSpelling(label, value string, issues *[]error) capturedFlagSpelling {
+	spelling, err := parseFlagSpelling(value)
+	if err != nil {
+		*issues = append(*issues, fmt.Errorf("invalid %s flag spelling %q: %w", label, value, err))
+	}
+	return spelling
+}
+
+func parseFlagSpelling(value string) (capturedFlagSpelling, error) {
+	if strings.HasPrefix(value, "--") {
+		name := value[2:]
+		if validFlagName(name) {
+			return capturedFlagSpelling{name: name}, nil
+		}
+	}
+	if len(value) == 2 && value[0] == '-' && value[1] != '-' {
+		return capturedFlagSpelling{name: value[1:], short: true}, nil
+	}
+	return capturedFlagSpelling{}, fmt.Errorf("must be a long flag or one-byte short flag spelling")
+}
+
+func captureComposition(record *commandRecord) {
+	if err := validateCommandName(record.name); err != nil {
+		record.issues = append(record.issues, err)
+	}
+	seen := make(map[string]struct{}, len(record.children))
+	for _, child := range record.children {
+		if child.record == nil {
+			record.issues = append(record.issues, fmt.Errorf("command %q has an invalid child declaration", record.name))
+			continue
+		}
+		if child.record.absent {
+			continue
+		}
+		name := child.record.name
+		if _, exists := seen[name]; exists {
+			record.issues = append(record.issues, fmt.Errorf("duplicate child command %q under %q", name, record.name))
+		}
+		seen[name] = struct{}{}
+	}
+}
+
+func validateCommandDeclaration(command Command) error {
+	return validateCommandPlacement(command)
+}
+
+func validateCommandPlacement(command Command) error {
+	var issues []error
+	collectDeclarationIssues(command, nil, true, &issues)
+	return errors.Join(issues...)
+}
+
+func collectDeclarationIssues(command Command, parents []string, root bool, issues *[]error) {
+	if command.record == nil {
+		*issues = append(*issues, errors.New("invalid zero command declaration"))
+		return
+	}
+	record := command.record
+	path := append(append([]string(nil), parents...), record.name)
+	label := commandpath.FromTokens(path).String()
+	for _, issue := range record.issues {
+		if label != "" {
+			*issues = append(*issues, fmt.Errorf("command %q: %w", label, issue))
+		} else {
+			*issues = append(*issues, issue)
+		}
+	}
+	if record.rootOnly && !root {
+		*issues = append(*issues, fmt.Errorf("root-only command %q is nested beneath another command", label))
+	}
+	if record.invalid || record.absent {
+		return
+	}
+	for _, child := range record.children {
+		if child.record == nil {
+			continue
+		}
+		collectDeclarationIssues(child, path, false, issues)
 	}
-	return nil
 }
 
 func validateCommandName(name string) error {
-	fields := strings.Fields(name)
-	if len(fields) != 1 || fields[0] != name || strings.HasPrefix(name, "-") || name == "--" {
-		return fmt.Errorf("command name %q must be one non-option token", name)
-	}
-	return nil
+	return commandpath.ValidateComponent(name)
 }
 
 func validateBindings[I any](flags []Flag[I], arguments []Argument[I]) error {
@@ -279,6 +478,9 @@ func validateBindings[I any](flags []Flag[I], arguments []Argument[I]) error {
 		if binding.meta.Name == "help" {
 			return fmt.Errorf("flag name %q is reserved for help", binding.meta.Name)
 		}
+		if commandmeta.IsReportingFlag(binding.meta.Name) {
+			return fmt.Errorf("flag name %q is reserved for reporting", binding.meta.Name)
+		}
 		if _, exists := flagNames[binding.meta.Name]; exists {
 			return fmt.Errorf("duplicate flag name %q", binding.meta.Name)
 		}
@@ -295,7 +497,7 @@ func validateBindings[I any](flags []Flag[I], arguments []Argument[I]) error {
 			}
 			shortNames[binding.meta.Short] = struct{}{}
 		}
-		if !binding.valid || binding.prepare == nil {
+		if binding.identity == nil || !binding.valid || binding.prepare == nil {
 			return fmt.Errorf("flag %q is missing parser or setter wiring", binding.meta.Name)
 		}
 	}
@@ -308,7 +510,7 @@ func validateBindings[I any](flags []Flag[I], arguments []Argument[I]) error {
 		if binding.min < 0 || binding.max < -1 || (binding.max >= 0 && binding.min > binding.max) {
 			return fmt.Errorf("argument %q has invalid bounds %d..%d", binding.meta.Name, binding.min, binding.max)
 		}
-		if !binding.valid || binding.prepare == nil {
+		if binding.identity == nil || !binding.valid || binding.prepare == nil {
 			return fmt.Errorf("argument %q is missing parser or setter wiring", binding.meta.Name)
 		}
 	}

completion.go

@@ -0,0 +1,119 @@
+package commandkit
+
+import (
+	"fmt"
+	"io"
+	"strings"
+	"unicode"
+
+	internalcobra "go.maximumdirect.net/commandkit/internal/cobra"
+	commandmeta "go.maximumdirect.net/commandkit/internal/commandmeta"
+)
+
+// Completion declares opt-in shell script generation for the executable
+// basename used to invoke the application. Install it at the application root.
+// Generated shell identifiers support letters, digits, underscores, dots,
+// hyphens, and colons; a leading hyphen is not supported.
+func Completion(executable string) Command {
+	children := make([]Command, 0, 3)
+	for _, shell := range []string{"bash", "zsh", "fish"} {
+		shell := shell
+		children = append(children, NewCommand(CommandSpec[struct{}]{
+			Name: shell, Summary: "Generate " + shell + " completion script.",
+			Run: func(invocation Invocation, _ struct{}) Outcome {
+				_ = invocation.Reporter().RenderOutput(func(writer io.Writer) error {
+					return internalcobra.CompletionScript(writer, executable, shell)
+				})
+				return Success()
+			},
+		}))
+	}
+	command := RootGroup("completion", "Generate shell completion scripts.", children...)
+	command.record.completion = true
+	if !validCompletionExecutable(executable) {
+		return WithError(command, fmt.Errorf("unsupported completion executable basename %q", executable))
+	}
+	return command
+}
+
+// Cobra emits the basename into shell identifiers and unquoted command words.
+func validCompletionExecutable(name string) bool {
+	if name == "" || name == "." || name == ".." || strings.HasPrefix(name, "-") {
+		return false
+	}
+	for _, ch := range name {
+		if !(unicode.IsLetter(ch) || unicode.IsDigit(ch) || ch == '_' || ch == '-' || ch == ':' || ch == '.') {
+			return false
+		}
+	}
+	return true
+}
+
+// CompletionChoice is a literal suggested value and its optional description.
+type CompletionChoice struct {
+	// Value is inserted as data; it is not interpreted as shell source.
+	Value string
+	// Description is optional context displayed by shells that support it.
+	Description string
+}
+
+// CompletionHint selects suggestions for a flag or positional value. Its zero
+// value requests no value suggestions; hints do not constrain accepted input.
+type CompletionHint struct {
+	kind    completionHintKind
+	choices *completionChoicesData
+}
+
+// Keep the public metadata structs comparable without exposing mutable choices.
+type completionChoicesData struct {
+	values []CompletionChoice
+}
+
+type completionHintKind uint8
+
+const (
+	completionNone completionHintKind = iota
+	completionChoices
+	completionFiles
+	completionDirectories
+)
+
+// CompleteChoices suggests literal values matching the current value prefix.
+// The supplied slice is copied. An empty list produces no suggestions. Empty
+// values and values containing a newline, tab, or NUL cannot be presented as
+// suggestions, but remain valid input if the command's converter accepts them.
+func CompleteChoices(choices ...CompletionChoice) CompletionHint {
+	hint := CompletionHint{kind: completionChoices}
+	if len(choices) != 0 {
+		hint.choices = &completionChoicesData{values: append([]CompletionChoice(nil), choices...)}
+	}
+	return hint
+}
+
+// CompleteFiles requests shell filename completion.
+func CompleteFiles() CompletionHint { return CompletionHint{kind: completionFiles} }
+
+// CompleteDirectories requests shell directory completion.
+func CompleteDirectories() CompletionHint { return CompletionHint{kind: completionDirectories} }
+
+// NoCompletion requests no value suggestions.
+func NoCompletion() CompletionHint { return CompletionHint{} }
+
+func bridgeCompletion(hint CompletionHint) commandmeta.CompletionHint {
+	result := commandmeta.CompletionHint{}
+	switch hint.kind {
+	case completionChoices:
+		result.Kind = commandmeta.CompletionChoices
+		if hint.choices == nil {
+			break
+		}
+		for _, choice := range hint.choices.values {
+			result.Choices = append(result.Choices, commandmeta.CompletionChoice{Value: choice.Value, Description: choice.Description})
+		}
+	case completionFiles:
+		result.Kind = commandmeta.CompletionFiles
+	case completionDirectories:
+		result.Kind = commandmeta.CompletionDirectories
+	}
+	return result
+}

completion_context.go

@@ -0,0 +1,78 @@
+package commandkit
+
+import (
+	"strings"
+
+	internalcobra "go.maximumdirect.net/commandkit/internal/cobra"
+	commandmeta "go.maximumdirect.net/commandkit/internal/commandmeta"
+	"go.maximumdirect.net/commandkit/internal/commandpath"
+)
+
+type completionContext struct {
+	route           routeResult
+	command         *commandmeta.Command
+	aliases         []commandmeta.FlagAlias
+	completed       []string
+	tail            []string
+	current         string
+	commandPosition bool
+}
+
+func resolveCompletionContext(snapshot *routingSnapshot, completed []string, current string) completionContext {
+	context := completionContext{completed: append([]string(nil), completed...), current: current}
+	if snapshot == nil {
+		return context
+	}
+	context.route = resolveEnteredRoute(completed, snapshot)
+	switch context.route.kind {
+	case routeCanonical:
+		context.command = completionCommand(snapshot, context.route.canonicalPath)
+		if context.command == nil || len(context.route.args) < len(context.route.canonicalPath) {
+			context.command = nil
+			return context
+		}
+		context.tail = append([]string(nil), context.route.args[len(context.route.canonicalPath):]...)
+		context.aliases = snapshot.flagAliases[context.route.canonicalPath.Key()].lookupRecords()
+		context.commandPosition = len(context.tail) == 0
+	case routeDiscovery:
+		context.command = &commandmeta.Command{CoreFlags: commandmeta.ReportingFlags()}
+		context.tail = append([]string(nil), context.route.args...)
+		context.aliases = snapshot.discoveryFlags[context.route.discoveryPath.Key()].lookupRecords()
+	}
+	return context
+}
+
+func completionCommand(snapshot *routingSnapshot, path commandpath.Path) *commandmeta.Command {
+	if len(path) == 0 {
+		return snapshot.metadata
+	}
+	children := snapshot.canonical
+	var node *canonicalNode
+	for _, name := range path {
+		node = children[name]
+		if node == nil {
+			return nil
+		}
+		children = node.children
+	}
+	return node.metadata
+}
+
+func completionChildren(snapshot *routingSnapshot, context completionContext) []commandmeta.CompletionChoice {
+	if snapshot == nil || context.command == nil || !context.commandPosition {
+		return nil
+	}
+	var choices []commandmeta.CompletionChoice
+	for _, child := range context.command.Children {
+		if !strings.HasPrefix(child.Name, context.current) || (len(context.route.canonicalPath) == 0 && child.Name == internalcobra.CompletionQueryToken) {
+			continue
+		}
+		entered := append(append([]string(nil), context.completed...), child.Name)
+		route := resolveEnteredRoute(entered, snapshot)
+		intended := append(context.route.canonicalPath.Clone(), child.Name)
+		if route.kind == routeCanonical && route.canonicalPath.Equal(intended) {
+			choices = append(choices, commandmeta.CompletionChoice{Value: child.Name, Description: child.Summary})
+		}
+	}
+	return choices
+}

completion_context_test.go

@@ -0,0 +1,89 @@
+package commandkit
+
+import (
+	"cmp"
+	"reflect"
+	"slices"
+	"testing"
+
+	commandmeta "go.maximumdirect.net/commandkit/internal/commandmeta"
+)
+
+func TestCompletionCommandContext(t *testing.T) {
+	parse := func(value string) (string, error) { return value, nil }
+	mixed := NewCommand(CommandSpec[struct{}]{
+		Name: "mixed", Children: []Command{simpleRunnable("child")},
+		Arguments: []Argument[struct{}]{ValueArgument(ArgumentMeta{Name: "item"}, false, parse, func(*struct{}, Supplied[string]) {})},
+		Run:       func(Invocation, struct{}) Outcome { return Success() },
+	})
+	app, err := New(Identity{Name: "example"},
+		Group("workspace", "", Group("list", "", simpleRunnable("shadow"), simpleRunnable("show"))),
+		simpleRunnable("other"), mixed, Completion("example"),
+		Alias("ws", "workspace"), Alias("w", "ws"), Alias("ws list shadow", "other"),
+		Alias("legacy inspect", "workspace list"), FlagAlias("--silent", "--quiet"),
+		FlagAliasFor("workspace list", "--detail", "--verbose"),
+	)
+	if err != nil {
+		t.Fatal(err)
+	}
+	snapshot := app.routeSnapshot()
+	for _, tc := range []struct {
+		name      string
+		completed []string
+		current   string
+		path      string
+		position  bool
+		choices   []string
+		kind      routeKind
+	}{
+		{"root", nil, "work", "", true, []string{"workspace"}, routeCanonical},
+		{"group", []string{"workspace"}, "li", "workspace", true, []string{"list"}, routeCanonical},
+		{"entered alias", []string{"ws", "list"}, "sh", "workspace list", true, []string{"show"}, routeCanonical},
+		{"alias chain", []string{"w", "list"}, "sh", "workspace list", true, []string{"show"}, routeCanonical},
+		{"discovery", []string{"legacy"}, "in", "", false, nil, routeDiscovery},
+		{"complete alias", []string{"legacy", "inspect"}, "sh", "workspace list", true, []string{"shadow", "show"}, routeCanonical},
+		{"runnable child", []string{"mixed"}, "ch", "mixed", true, []string{"child"}, routeCanonical},
+		{"unmatched child", []string{"mixed"}, "other", "mixed", true, nil, routeCanonical},
+		{"runnable operand", []string{"mixed", "value"}, "ch", "mixed", false, nil, routeCanonical},
+		{"flag ends path", []string{"mixed", "--quiet"}, "ch", "mixed", false, nil, routeCanonical},
+		{"flag before child", []string{"workspace", "--quiet"}, "li", "workspace", false, nil, routeCanonical},
+		{"unknown", []string{"missing"}, "x", "", false, nil, routeUnknown},
+		{"hidden endpoint", nil, "__comp", "", true, nil, routeCanonical},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			original := append([]string(nil), tc.completed...)
+			context := resolveCompletionContext(snapshot, tc.completed, tc.current)
+			if context.route.kind != tc.kind || context.route.canonicalPath.String() != tc.path || context.commandPosition != tc.position || !reflect.DeepEqual(tc.completed, original) {
+				t.Fatalf("context=%#v completed=%q", context, tc.completed)
+			}
+			var names []string
+			for _, choice := range completionChildren(snapshot, context) {
+				names = append(names, choice.Value)
+			}
+			if !reflect.DeepEqual(names, tc.choices) {
+				t.Fatalf("children=%q, want %q", names, tc.choices)
+			}
+			if tc.kind == routeDiscovery && !reflect.DeepEqual(context.aliases, []commandmeta.FlagAlias{{Source: "--silent", Target: "--quiet"}}) {
+				t.Fatalf("discovery aliases=%#v", context.aliases)
+			}
+			if (tc.name == "runnable child" || tc.name == "unmatched child") && (context.command == nil || len(context.command.Arguments) != 1) {
+				t.Fatalf("runnable operand metadata missing: %#v", context.command)
+			}
+			if tc.name == "entered alias" {
+				actual := slices.Clone(context.aliases)
+				expected := []commandmeta.FlagAlias{{Source: "--detail", Target: "--verbose"}, {Source: "--silent", Target: "--quiet"}}
+				compare := func(a, b commandmeta.FlagAlias) int {
+					if result := cmp.Compare(a.Source, b.Source); result != 0 {
+						return result
+					}
+					return cmp.Compare(a.Target, b.Target)
+				}
+				slices.SortFunc(actual, compare)
+				slices.SortFunc(expected, compare)
+				if !slices.Equal(actual, expected) {
+					t.Fatalf("canonical aliases=%#v, want %#v", actual, expected)
+				}
+			}
+		})
+	}
+}

completion_flags.go

@@ -0,0 +1,217 @@
+package commandkit
+
+import (
+	"strings"
+
+	commandmeta "go.maximumdirect.net/commandkit/internal/commandmeta"
+)
+
+type completionTargetKind uint8
+
+const (
+	completionTargetNone completionTargetKind = iota
+	completionTargetCommands
+	completionTargetFlags
+	completionTargetValue
+	completionTargetOperand
+)
+
+type completionTarget struct {
+	kind        completionTargetKind
+	choices     []commandmeta.CompletionChoice
+	hint        commandmeta.CompletionHint
+	prefix      string
+	valuePrefix string
+}
+
+type completionFlagState struct {
+	supplied map[string]bool
+	operands []string
+	pending  *commandmeta.Flag
+	ended    bool
+	invalid  bool
+}
+
+func completionFlags(context completionContext) []commandmeta.Flag {
+	flags := make([]commandmeta.Flag, 0, len(context.command.Flags)+len(context.command.CoreFlags)+1)
+	flags = append(flags, commandmeta.HelpFlag())
+	flags = append(flags, context.command.CoreFlags...)
+	flags = append(flags, context.command.Flags...)
+	return flags
+}
+
+func walkCompletionFlags(tokens []string, lookup commandmeta.FlagLookup) completionFlagState {
+	state := completionFlagState{supplied: make(map[string]bool)}
+	for index := 0; index < len(tokens); index++ {
+		token := tokens[index]
+		if state.ended {
+			state.operands = append(state.operands, token)
+			continue
+		}
+		switch commandmeta.ClassifyFlagToken(token) {
+		case commandmeta.TerminatorToken:
+			state.ended = true
+		case commandmeta.OperandToken:
+			state.operands = append(state.operands, token)
+		case commandmeta.LongFlagToken:
+			spelling, _, attached := commandmeta.SplitLongFlag(token)
+			flag, ok := lookup.Find(spelling)
+			if !ok {
+				state.invalid = true
+				return state
+			}
+			state.supplied[flag.Name] = true
+			if !flag.Boolean && !attached {
+				if index+1 == len(tokens) {
+					state.pending = &flag
+					return state
+				}
+				index++
+			}
+		case commandmeta.ShortFlagToken:
+			for offset := 1; offset < len(token); offset++ {
+				flag, ok := lookup.Find("-" + token[offset:offset+1])
+				if !ok {
+					state.invalid = true
+					return state
+				}
+				state.supplied[flag.Name] = true
+				suffix := token[offset+1:]
+				if flag.Boolean {
+					if strings.HasPrefix(suffix, "=") {
+						break
+					}
+					continue
+				}
+				if suffix == "" {
+					if index+1 == len(tokens) {
+						state.pending = &flag
+						return state
+					}
+					index++
+				}
+				break
+			}
+		}
+	}
+	return state
+}
+
+func completionTargetFor(snapshot *routingSnapshot, context completionContext) completionTarget {
+	if context.command == nil {
+		return completionTarget{}
+	}
+	flags := completionFlags(context)
+	lookup := commandmeta.NewFlagLookup(flags, context.aliases)
+	state := walkCompletionFlags(context.tail, lookup)
+	if state.invalid {
+		return completionTarget{}
+	}
+	if state.pending != nil {
+		return completionTarget{kind: completionTargetValue, hint: state.pending.Completion, valuePrefix: context.current}
+	}
+	if !state.ended && context.commandPosition {
+		if children := completionChildren(snapshot, context); len(children) > 0 {
+			return completionTarget{kind: completionTargetCommands, choices: children}
+		}
+	}
+	if !state.ended && strings.HasPrefix(context.current, "-") {
+		return completionOptionTarget(context.current, flags, lookup, state.supplied)
+	}
+	if hint, ok := completionOperandHint(context.command.Arguments, len(state.operands)); ok {
+		return completionTarget{kind: completionTargetOperand, hint: hint, valuePrefix: context.current}
+	}
+	if !state.ended && context.current == "" {
+		return completionTarget{kind: completionTargetFlags, choices: completionFlagNames(flags, state.supplied, "")}
+	}
+	return completionTarget{}
+}
+
+func completionOptionTarget(current string, flags []commandmeta.Flag, lookup commandmeta.FlagLookup, supplied map[string]bool) completionTarget {
+	if current == "-" {
+		return completionTarget{kind: completionTargetFlags, choices: completionFlagNames(flags, supplied, current)}
+	}
+	if strings.HasPrefix(current, "--") {
+		spelling, value, attached := commandmeta.SplitLongFlag(current)
+		if attached {
+			if flag, ok := lookup.Find(spelling); ok {
+				return completionTarget{kind: completionTargetValue, hint: flag.Completion, prefix: spelling + "=", valuePrefix: value}
+			}
+			return completionTarget{}
+		}
+		return completionTarget{kind: completionTargetFlags, choices: completionFlagNames(flags, supplied, current)}
+	}
+	used := make(map[string]bool, len(supplied))
+	for name, value := range supplied {
+		used[name] = value
+	}
+	for offset := 1; offset < len(current); offset++ {
+		flag, ok := lookup.Find("-" + current[offset:offset+1])
+		if !ok {
+			return completionTarget{}
+		}
+		used[flag.Name] = true
+		suffix := current[offset+1:]
+		if flag.Boolean {
+			if strings.HasPrefix(suffix, "=") {
+				return completionTarget{kind: completionTargetValue, hint: flag.Completion, prefix: current[:offset+2], valuePrefix: suffix[1:]}
+			}
+			continue
+		}
+		prefix := current[:offset+1]
+		if strings.HasPrefix(suffix, "=") {
+			prefix += "="
+			suffix = suffix[1:]
+		}
+		return completionTarget{kind: completionTargetValue, hint: flag.Completion, prefix: prefix, valuePrefix: suffix}
+	}
+	var choices []commandmeta.CompletionChoice
+	for _, flag := range flags {
+		if flag.Short != "" && completionFlagEligible(flag, used) {
+			choices = append(choices, commandmeta.CompletionChoice{Value: current + flag.Short, Description: flag.Usage})
+		}
+	}
+	return completionTarget{kind: completionTargetFlags, choices: choices}
+}
+
+func completionFlagNames(flags []commandmeta.Flag, supplied map[string]bool, prefix string) []commandmeta.CompletionChoice {
+	var choices []commandmeta.CompletionChoice
+	for _, flag := range flags {
+		if !completionFlagEligible(flag, supplied) {
+			continue
+		}
+		for _, spelling := range []string{"--" + flag.Name, shortCompletionSpelling(flag.Short)} {
+			if spelling != "" && strings.HasPrefix(spelling, prefix) {
+				choices = append(choices, commandmeta.CompletionChoice{Value: spelling, Description: flag.Usage})
+			}
+		}
+	}
+	return choices
+}
+
+func completionFlagEligible(flag commandmeta.Flag, supplied map[string]bool) bool {
+	return !supplied[flag.Name] || flag.Repeated || commandmeta.IsReportingFlag(flag.Name)
+}
+
+func shortCompletionSpelling(short string) string {
+	if short == "" {
+		return ""
+	}
+	return "-" + short
+}
+
+func completionOperandHint(arguments []commandmeta.Argument, completed int) (commandmeta.CompletionHint, bool) {
+	total := completed + 1
+	counts, err := allocateOperandCounts(total, arguments, false)
+	if err != nil {
+		return commandmeta.CompletionHint{}, false
+	}
+	position := 0
+	for index, count := range counts {
+		position += count
+		if position >= total {
+			return arguments[index].Completion, true
+		}
+	}
+	return commandmeta.CompletionHint{}, false
+}

completion_flags_test.go

@@ -0,0 +1,146 @@
+package commandkit
+
+import (
+	"reflect"
+	"testing"
+
+	commandmeta "go.maximumdirect.net/commandkit/internal/commandmeta"
+)
+
+func TestCompletionFlagAndValuePositions(t *testing.T) {
+	parse := func(value string) (string, error) { return value, nil }
+	choice := CompleteChoices(CompletionChoice{Value: "blue"}, CompletionChoice{Value: "green"})
+	command := NewCommand(CommandSpec[struct{}]{
+		Name: "run",
+		Flags: []Flag[struct{}]{
+			ValueFlag(FlagMeta{Name: "color", Short: "c", Completion: choice}, (*string)(nil), parse, func(*struct{}, Supplied[string]) {}),
+			RepeatFlag(FlagMeta{Name: "tag", Short: "t", Completion: choice}, nil, parse, func(*struct{}, Supplied[[]string]) {}),
+			BoolFlag(FlagMeta{Name: "switch", Short: "s"}, false, func(*struct{}, Supplied[bool]) {}),
+		},
+		Run: func(Invocation, struct{}) Outcome { return Success() },
+	})
+	app, err := New(Identity{Name: "example"}, command,
+		FlagAliasFor("run", "--colour", "--color"), FlagAliasFor("run", "-C", "--color"), FlagAlias("-v", "--verbose"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	snapshot := app.routeSnapshot()
+	for _, tc := range []struct {
+		name, current, prefix, value string
+		completed                    []string
+		kind                         completionTargetKind
+		hint                         commandmeta.CompletionKind
+	}{
+		{"pending takes option", "--quiet", "", "--quiet", []string{"run", "--color"}, completionTargetValue, commandmeta.CompletionChoices},
+		{"terminator consumed as value", "-x", "", "-x", []string{"run", "--color", "--", "--tag"}, completionTargetValue, commandmeta.CompletionChoices},
+		{"repeated singleton value", "--color=gr", "--color=", "gr", []string{"run", "--color=blue"}, completionTargetValue, commandmeta.CompletionChoices},
+		{"long alias value", "--colour=bl", "--colour=", "bl", []string{"run"}, completionTargetValue, commandmeta.CompletionChoices},
+		{"long empty value", "--color=", "--color=", "", []string{"run"}, completionTargetValue, commandmeta.CompletionChoices},
+		{"short alias value", "-sCbl", "-sC", "bl", []string{"run"}, completionTargetValue, commandmeta.CompletionChoices},
+		{"short equals", "-sC=bl", "-sC=", "bl", []string{"run"}, completionTargetValue, commandmeta.CompletionChoices},
+		{"reporting boolean", "--verbose=f", "--verbose=", "f", []string{"run"}, completionTargetValue, commandmeta.CompletionChoices},
+		{"short boolean alias", "-v=f", "-v=", "f", []string{"run"}, completionTargetValue, commandmeta.CompletionChoices},
+		{"application boolean", "--switch=f", "--switch=", "f", []string{"run"}, completionTargetValue, commandmeta.CompletionNone},
+		{"scoped alias unavailable at root", "--colour=bl", "", "", nil, completionTargetNone, commandmeta.CompletionNone},
+		{"unknown completed", "--c", "", "", []string{"run", "--unknown"}, completionTargetNone, commandmeta.CompletionNone},
+		{"unknown attached", "--unknown=x", "", "", []string{"run"}, completionTargetNone, commandmeta.CompletionNone},
+		{"terminator", "--color", "", "", []string{"run", "--"}, completionTargetNone, commandmeta.CompletionNone},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			target := completionTargetFor(snapshot, resolveCompletionContext(snapshot, tc.completed, tc.current))
+			if target.kind != tc.kind || target.hint.Kind != tc.hint || target.prefix != tc.prefix || target.valuePrefix != tc.value {
+				t.Fatalf("target=%#v", target)
+			}
+		})
+	}
+
+	context := resolveCompletionContext(snapshot, []string{"run", "--colour=blue", "--tag=one", "--verbose"}, "--")
+	target := completionTargetFor(snapshot, context)
+	names := completionChoiceNames(target.choices)
+	if containsCompletionName(names, "--color") || !containsCompletionName(names, "--tag") || !containsCompletionName(names, "--verbose") {
+		t.Fatalf("flag suggestions=%q", names)
+	}
+	cluster := completionTargetFor(snapshot, resolveCompletionContext(snapshot, []string{"run"}, "-sv"))
+	if cluster.kind != completionTargetFlags || !containsCompletionName(completionChoiceNames(cluster.choices), "-svc") || containsCompletionName(completionChoiceNames(cluster.choices), "-svs") {
+		t.Fatalf("short cluster=%#v", cluster)
+	}
+	dash := completionTargetFor(snapshot, resolveCompletionContext(snapshot, []string{"run"}, "-"))
+	if !containsCompletionName(completionChoiceNames(dash.choices), "--color") || !containsCompletionName(completionChoiceNames(dash.choices), "-c") {
+		t.Fatalf("dash suggestions=%#v", dash)
+	}
+}
+
+func TestCompletionOperandAllocation(t *testing.T) {
+	arguments := []commandmeta.Argument{
+		{Name: "optional", Min: 0, Max: 1, Completion: commandmeta.CompletionHint{Kind: commandmeta.CompletionFiles}},
+		{Name: "repeated", Min: 0, Max: -1, Completion: commandmeta.CompletionHint{Kind: commandmeta.CompletionDirectories}},
+		{Name: "required", Min: 1, Max: 1, Completion: commandmeta.BooleanCompletion()},
+	}
+	for _, tc := range []struct {
+		completed int
+		want      commandmeta.CompletionKind
+	}{
+		{0, commandmeta.CompletionChoices},
+		{1, commandmeta.CompletionChoices},
+		{2, commandmeta.CompletionChoices},
+	} {
+		hint, ok := completionOperandHint(arguments, tc.completed)
+		if !ok || hint.Kind != tc.want {
+			t.Fatalf("%d operands: %#v, %v", tc.completed, hint, ok)
+		}
+	}
+	bounded := []commandmeta.Argument{{Name: "only", Max: 1, Completion: commandmeta.BooleanCompletion()}}
+	if _, ok := completionOperandHint(bounded, 1); ok {
+		t.Fatal("excess operand received a hint")
+	}
+	trailing := []commandmeta.Argument{{Name: "first", Min: 1, Max: 1, Completion: commandmeta.BooleanCompletion()}, {Name: "rest", Min: 0, Max: -1, Completion: commandmeta.CompletionHint{Kind: commandmeta.CompletionDirectories}}}
+	if hint, ok := completionOperandHint(trailing, 1); !ok || hint.Kind != commandmeta.CompletionDirectories {
+		t.Fatalf("repeated trailing operand: %#v, %v", hint, ok)
+	}
+	if got, want := completionChoiceNames(commandmeta.BooleanCompletion().Choices), []string{"true", "false"}; !reflect.DeepEqual(got, want) {
+		t.Fatalf("boolean choices=%q", got)
+	}
+}
+
+func TestCompletionOperandAndFlagContexts(t *testing.T) {
+	command := &commandmeta.Command{
+		Arguments: []commandmeta.Argument{{Name: "item", Min: 0, Max: 1, Completion: commandmeta.CompletionHint{Kind: commandmeta.CompletionFiles}}},
+		Flags:     []commandmeta.Flag{{Name: "name", Completion: commandmeta.BooleanCompletion()}},
+	}
+	for _, tc := range []struct {
+		name, current string
+		tail          []string
+		kind          completionTargetKind
+		hint          commandmeta.CompletionKind
+	}{
+		{"empty chooses operand", "", nil, completionTargetOperand, commandmeta.CompletionFiles},
+		{"dash chooses flag", "--n", nil, completionTargetFlags, commandmeta.CompletionNone},
+		{"after terminator", "--n", []string{"--"}, completionTargetOperand, commandmeta.CompletionFiles},
+		{"interspersed flag value", "value", []string{"--name", "--quiet"}, completionTargetOperand, commandmeta.CompletionFiles},
+		{"excess operand", "value", []string{"already"}, completionTargetNone, commandmeta.CompletionNone},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			target := completionTargetFor(nil, completionContext{command: command, tail: tc.tail, current: tc.current})
+			if target.kind != tc.kind || target.hint.Kind != tc.hint {
+				t.Fatalf("target=%#v", target)
+			}
+		})
+	}
+}
+
+func completionChoiceNames(choices []commandmeta.CompletionChoice) []string {
+	var names []string
+	for _, choice := range choices {
+		names = append(names, choice.Value)
+	}
+	return names
+}
+
+func containsCompletionName(names []string, want string) bool {
+	for _, name := range names {
+		if name == want {
+			return true
+		}
+	}
+	return false
+}

completion_install_test.go

@@ -0,0 +1,108 @@
+package commandkit
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"io"
+	"strings"
+	"testing"
+)
+
+func TestCompletionDeclarationGeneratesScripts(t *testing.T) {
+	for _, name := range []string{"app", "my-app", "tool.exe", "café"} {
+		if !validCompletionExecutable(name) {
+			t.Fatalf("supported executable rejected: %q", name)
+		}
+	}
+	app, err := New(Identity{Name: "Human Readable Name"}, Completion("my-app"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !app.routeSnapshot().completion {
+		t.Fatal("completion not present in snapshot")
+	}
+	for _, shell := range []string{"bash", "zsh", "fish"} {
+		var output, diagnostics bytes.Buffer
+		outcome := app.Execute(context.Background(), []string{"completion", shell}, Streams{Out: &output, Err: &diagnostics})
+		if outcome.Status != 0 || !strings.Contains(output.String(), "my-app") || strings.Contains(output.String(), "Human Readable Name") {
+			t.Fatalf("%s outcome=%#v output=%q diagnostics=%q", shell, outcome, output.String(), diagnostics.String())
+		}
+		output.Reset()
+		outcome = app.Execute(context.Background(), []string{"completion", shell, "--quiet"}, Streams{Out: &output, Err: &diagnostics})
+		if outcome.Status != 0 || output.Len() != 0 {
+			t.Fatalf("quiet %s outcome=%#v output=%q", shell, outcome, output.String())
+		}
+	}
+	var help bytes.Buffer
+	outcome := app.Execute(context.Background(), []string{"--help"}, Streams{Out: &help})
+	if outcome.Status != 0 || !strings.Contains(help.String(), "completion") || strings.Contains(help.String(), "__complete") {
+		t.Fatalf("help outcome=%#v output=%q", outcome, help.String())
+	}
+	writeErr := errors.New("destination failed")
+	outcome = app.Execute(context.Background(), []string{"completion", "bash"}, Streams{Out: completionErrorWriter{writeErr}, Err: io.Discard})
+	if outcome.Status != 1 || !errors.Is(outcome.Presentation.Output.WriteError, writeErr) {
+		t.Fatalf("script delivery failure: %#v", outcome)
+	}
+}
+
+type completionErrorWriter struct{ err error }
+
+func (w completionErrorWriter) Write([]byte) (int, error) { return 0, w.err }
+
+func TestCompletionInstallationCollisionsAndRollback(t *testing.T) {
+	run := NewCommand(CommandSpec[struct{}]{Name: "run", Run: func(Invocation, struct{}) Outcome { return Success() }})
+	query := NewCommand(CommandSpec[struct{}]{Name: "__complete", Run: func(Invocation, struct{}) Outcome { return Success() }})
+	for _, declarations := range [][]Declaration{
+		{Completion("app"), query},
+		{query, Completion("app")},
+		{Completion("app"), run, Alias("__complete nested", "run")},
+		{run, Alias("__complete nested", "run"), Completion("app")},
+		{Completion("app"), Group("completion", "collision")},
+		{Group("outer", "", Completion("app"))},
+		{Completion("dir/app")},
+		{Completion("two words")},
+	} {
+		if _, err := New(Identity{Name: "example"}, declarations...); err == nil {
+			t.Fatalf("accepted conflicting declarations: %#v", declarations)
+		}
+	}
+	app, err := New(Identity{Name: "example"}, run)
+	if err != nil {
+		t.Fatal(err)
+	}
+	before := app.routeSnapshot()
+	if err := app.Register(Completion("app"), query); err == nil || app.routeSnapshot() != before {
+		t.Fatalf("failed batch changed snapshot: %v", err)
+	}
+	if err := app.Register(Completion("app")); err != nil {
+		t.Fatal(err)
+	}
+	if app.routeSnapshot() == before || !app.routeSnapshot().completion {
+		t.Fatal("late completion installation did not refresh snapshot")
+	}
+	if err := app.Register(query); err == nil {
+		t.Fatal("query command accepted after completion installation")
+	}
+	if err := app.Register(Alias("__complete nested", "run")); err == nil {
+		t.Fatal("query alias accepted after completion installation")
+	}
+
+	withoutCompletion, err := New(Identity{Name: "example"}, query)
+	if err != nil || withoutCompletion.routeSnapshot().completion {
+		t.Fatalf("ordinary query-named command: %v", err)
+	}
+	if outcome := withoutCompletion.Execute(context.Background(), []string{"__complete"}, Streams{}); outcome.Status != 0 {
+		t.Fatalf("ordinary command outcome: %#v", outcome)
+	}
+	if err := withoutCompletion.Register(Completion("app")); err == nil || withoutCompletion.routeSnapshot().completion {
+		t.Fatal("completion accepted an existing query command")
+	}
+	aliased, err := New(Identity{Name: "example"}, run, Alias("__complete nested", "run"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := aliased.Register(Completion("app")); err == nil || aliased.routeSnapshot().completion {
+		t.Fatal("completion accepted an existing query alias")
+	}
+}

completion_query.go

@@ -0,0 +1,53 @@
+package commandkit
+
+import (
+	"errors"
+	"io"
+	"strings"
+
+	internalcobra "go.maximumdirect.net/commandkit/internal/cobra"
+	commandmeta "go.maximumdirect.net/commandkit/internal/commandmeta"
+)
+
+func completeRequest(snapshot *routingSnapshot, words []string) (commandmeta.CompletionResult, error) {
+	if len(words) == 0 {
+		return commandmeta.CompletionResult{}, errors.New("completion request has no current word")
+	}
+	context := resolveCompletionContext(snapshot, words[:len(words)-1], words[len(words)-1])
+	target := completionTargetFor(snapshot, context)
+	result := commandmeta.CompletionResult{Prefix: target.prefix}
+	switch target.kind {
+	case completionTargetCommands, completionTargetFlags:
+		result.Kind = commandmeta.CompletionChoices
+		result.Choices = target.choices
+	case completionTargetValue, completionTargetOperand:
+		result.Kind = target.hint.Kind
+		if target.hint.Kind == commandmeta.CompletionChoices {
+			for _, choice := range target.hint.Choices {
+				if strings.HasPrefix(choice.Value, target.valuePrefix) {
+					result.Choices = append(result.Choices, choice)
+				}
+			}
+		}
+	}
+	return result, nil
+}
+
+func (current *execution) complete(words []string) Outcome {
+	result, err := completeRequest(current.snapshot, words)
+	var reply string
+	if err == nil {
+		reply, err = internalcobra.CompletionReply(result)
+	}
+	if err != nil {
+		reply = internalcobra.CompletionErrorReply()
+	}
+	_ = current.reporter.RenderOutput(func(writer io.Writer) error {
+		_, writeErr := io.WriteString(writer, reply)
+		return writeErr
+	})
+	if err != nil {
+		return current.reporter.finalize(Failure("Could not complete the shell request.").WithCause(err), nil)
+	}
+	return current.reporter.finalize(Success(), nil)
+}

completion_query_test.go

@@ -0,0 +1,121 @@
+package commandkit
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"io"
+	"strings"
+	"testing"
+
+	internalcobra "go.maximumdirect.net/commandkit/internal/cobra"
+	commandmeta "go.maximumdirect.net/commandkit/internal/commandmeta"
+)
+
+func TestCompletionQueryDispatch(t *testing.T) {
+	var factories, converters, handlers int
+	command := NewCommand(CommandSpec[struct{}]{
+		Name: "run", Summary: "Run a command.",
+		NewInput: func() struct{} { factories++; return struct{}{} },
+		Flags: []Flag[struct{}]{
+			ValueFlag(FlagMeta{Name: "color", Short: "c", Completion: CompleteChoices(CompletionChoice{Value: "blue", Description: "cool\ncolor"}, CompletionChoice{Value: "green"}, CompletionChoice{Value: "foo=bar"})}, (*string)(nil),
+				func(value string) (string, error) { converters++; return value, nil }, func(*struct{}, Supplied[string]) {}),
+			ValueFlag(FlagMeta{Name: "file", Short: "f", Completion: CompleteFiles()}, (*string)(nil),
+				func(value string) (string, error) { converters++; return value, nil }, func(*struct{}, Supplied[string]) {}),
+		},
+		Run: func(Invocation, struct{}) Outcome { handlers++; return Success() },
+	})
+	app, err := New(Identity{Name: "example"}, command, Completion("example"), Alias("shortcut", "run"), FlagAliasFor("run", "--colour", "--color"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	emptyReply, err := internalcobra.CompletionReply(commandmeta.CompletionResult{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, tc := range []struct {
+		name  string
+		args  []string
+		want  string
+		empty bool
+	}{
+		{"empty word", []string{"__complete", ""}, "run\tRun a command.", false},
+		{"alias value", []string{"__complete", "shortcut", "--colour=bl"}, "blue\tcool color\n", false},
+		{"quiet is data", []string{"__complete", "run", "--quiet", "--color=bl"}, "blue\tcool color\n", false},
+		{"debug is data", []string{"__complete", "run", "--debug", "--color=bl"}, "blue\tcool color\n", false},
+		{"short attached choice", []string{"__complete", "run", "-cfoo=ba"}, "foo=bar\n", false},
+		{"unknown route", []string{"__complete", "missing", ""}, emptyReply, true},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			var output, diagnostic bytes.Buffer
+			outcome := app.Execute(context.Background(), tc.args, Streams{Out: &output, Err: &diagnostic})
+			if outcome.Status != 0 || diagnostic.Len() != 0 || (tc.empty && output.String() != tc.want) || (!tc.empty && !strings.Contains(output.String(), tc.want)) {
+				t.Fatalf("outcome=%#v output=%q diagnostics=%q", outcome, output.String(), diagnostic.String())
+			}
+		})
+	}
+	fileReply, err := internalcobra.CompletionReply(commandmeta.CompletionResult{Kind: commandmeta.CompletionFiles, Prefix: "-f"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	var fileOutput bytes.Buffer
+	fileOutcome := app.Execute(context.Background(), []string{"__complete", "run", "-f./part"}, Streams{Out: &fileOutput})
+	if fileOutcome.Status != 0 || fileOutput.String() != fileReply {
+		t.Fatalf("file query outcome=%#v reply=%q", fileOutcome, fileOutput.String())
+	}
+	if factories != 0 || converters != 0 || handlers != 0 {
+		t.Fatalf("query invoked application callbacks: %d %d %d", factories, converters, handlers)
+	}
+	if err := app.Register(simpleRunnable("later")); err != nil {
+		t.Fatal(err)
+	}
+	var output bytes.Buffer
+	if outcome := app.Execute(context.Background(), []string{"__complete", "lat"}, Streams{Out: &output}); outcome.Status != 0 || !strings.Contains(output.String(), "later") {
+		t.Fatalf("later command outcome=%#v reply=%q", outcome, output.String())
+	}
+	output.Reset()
+	if outcome := app.Execute(context.Background(), []string{"__complete", "later", "--qui"}, Streams{Out: &output}); outcome.Status != 0 || !strings.Contains(output.String(), "--quiet") {
+		t.Fatalf("later command flag outcome=%#v reply=%q", outcome, output.String())
+	}
+}
+
+func TestCompletionQueryErrorsAndDelivery(t *testing.T) {
+	app, err := New(Identity{Name: "example"}, Completion("example"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	var output, diagnostics bytes.Buffer
+	outcome := app.Execute(context.Background(), []string{"__complete"}, Streams{Out: &output, Err: &diagnostics})
+	if outcome.Status != 1 || outcome.Cause == nil || output.String() != internalcobra.CompletionErrorReply() || diagnostics.Len() == 0 {
+		t.Fatalf("malformed query outcome=%#v reply=%q diagnostics=%q", outcome, output.String(), diagnostics.String())
+	}
+	writeErr := errors.New("reply destination failed")
+	writer := &completionCountingWriter{err: writeErr}
+	outcome = app.Execute(context.Background(), []string{"__complete", ""}, Streams{Out: writer, Err: io.Discard})
+	if outcome.Status != 1 || !errors.Is(outcome.Presentation.Output.WriteError, writeErr) || writer.calls != 1 {
+		t.Fatalf("reply write failure: %#v", outcome)
+	}
+}
+
+type completionCountingWriter struct {
+	err   error
+	calls int
+}
+
+func (writer *completionCountingWriter) Write([]byte) (int, error) {
+	writer.calls++
+	return 0, writer.err
+}
+
+func TestCompletionQueryDiscovery(t *testing.T) {
+	app, err := New(Identity{Name: "example"}, Completion("example"),
+		Group("workspace", "", simpleRunnable("inspect")), Alias("legacy inspect", "workspace inspect"), FlagAlias("--silent", "--quiet"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	var output bytes.Buffer
+	outcome := app.Execute(context.Background(), []string{"__complete", "legacy", "--"}, Streams{Out: &output})
+	if outcome.Status != 0 || !strings.Contains(output.String(), "--quiet") || strings.Contains(output.String(), "inspect") || strings.Contains(output.String(), "--silent") {
+		t.Fatalf("discovery outcome=%#v reply=%q", outcome, output.String())
+	}
+}

completion_shell_test.go

@@ -0,0 +1,93 @@
+package commandkit
+
+import (
+	"encoding/json"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"reflect"
+	"strings"
+	"testing"
+)
+
+func TestCompletionConsumerInShells(t *testing.T) {
+	if os.Getenv("COMMANDKIT_COMPLETION_SHELLS") != "1" {
+		t.Skip("set COMMANDKIT_COMPLETION_SHELLS=1 to run shell completion checks")
+	}
+	dir := t.TempDir()
+	app := filepath.Join(dir, "probe")
+	build := exec.Command("go", "build", "-o", app, "./testdata/completion")
+	if output, err := build.CombinedOutput(); err != nil {
+		t.Fatalf("build completion fixture: %v\n%s", err, output)
+	}
+	if err := os.Mkdir(filepath.Join(dir, "partial dir"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(dir, "partial file"), nil, 0o644); err != nil {
+		t.Fatal(err)
+	}
+	tests := []struct {
+		name, line string
+		want       []string
+		directory  bool
+	}{
+		{"canonical command", "probe ru", []string{"run"}, false},
+		{"entered alias", "probe shortcut --format=ya", []string{"shortcut", "--format=yaml"}, false},
+		{"choice", "probe run --format=te", []string{"run", "--format=text"}, false},
+		{"no file fallback", `probe run --format=./partial\ f`, []string{"run", "--format=./partial f"}, false},
+		{"separated file", `probe run --config ./partial\ f`, []string{"run", "--config", "./partial file"}, false},
+		{"attached file", `probe run --config=./partial\ f`, []string{"run", "--config=./partial file"}, false},
+		{"short attached file", `probe run -c./partial\ f`, []string{"run", "-c./partial file"}, false},
+		{"short cluster equals file", `probe run -sc=./partial\ f`, []string{"run", "-sc=./partial file"}, false},
+		{"separated directory", "probe run --directory ./partial", []string{"run", "--directory", "./partial dir"}, true},
+		{"attached directory", "probe run --directory=./partial", []string{"run", "--directory=./partial dir"}, true},
+		{"empty operand", "probe run ", []string{"run", "alpha"}, false},
+		{"leading dash", "probe run --for", []string{"run", "--format"}, false},
+	}
+	for _, shell := range []string{"bash", "zsh", "fish"} {
+		generator := exec.Command(app, "completion", shell)
+		script, err := generator.CombinedOutput()
+		if err != nil {
+			t.Fatalf("generate %s script: %v\n%s", shell, err, script)
+		}
+		scriptPath := filepath.Join(dir, shell+".completion")
+		if err := os.WriteFile(scriptPath, script, 0o600); err != nil {
+			t.Fatal(err)
+		}
+		for _, tc := range tests {
+			t.Run(shell+"/"+tc.name, func(t *testing.T) {
+				log := filepath.Join(dir, "log")
+				if err := os.WriteFile(log, nil, 0o600); err != nil {
+					t.Fatal(err)
+				}
+				terminal := exec.Command("python3", "internal/cobra/testdata/completion_terminal.py", shell, scriptPath, tc.line)
+				terminal.Env = append(os.Environ(), "PATH="+dir+string(os.PathListSeparator)+os.Getenv("PATH"), "HOME="+dir, "TERM=xterm", "PROBE_LOG="+log, "PROBE_DIR="+dir)
+				if output, err := terminal.CombinedOutput(); err != nil {
+					t.Fatalf("shell completion: %v\n%s", err, output)
+				}
+				content, err := os.ReadFile(log)
+				if err != nil {
+					t.Fatal(err)
+				}
+				var got []string
+				if err := json.Unmarshal(content, &got); err != nil {
+					t.Fatalf("fixture output %q: %v", content, err)
+				}
+				if tc.directory && len(got) > 0 {
+					got[len(got)-1] = strings.TrimSuffix(got[len(got)-1], "/")
+				}
+				if !reflect.DeepEqual(got, tc.want) {
+					t.Fatalf("edited arguments=%q, want %q", got, tc.want)
+				}
+			})
+		}
+		t.Run(shell+"/descriptions", func(t *testing.T) {
+			terminal := exec.Command("python3", "internal/cobra/testdata/completion_terminal.py", shell, scriptPath, "probe run --format=")
+			terminal.Env = append(os.Environ(), "PATH="+dir+string(os.PathListSeparator)+os.Getenv("PATH"), "HOME="+dir, "TERM=xterm", "PROBE_LOG="+filepath.Join(dir, "log"), "PROBE_DIR="+dir, "PROBE_LIST=1")
+			output, err := terminal.CombinedOutput()
+			if err != nil || !strings.Contains(string(output), "Readable text") || !strings.Contains(string(output), "YAML output") {
+				t.Fatalf("completion descriptions: %v\n%s", err, output)
+			}
+		})
+	}
+}

completion_test.go

@@ -0,0 +1,81 @@
+package commandkit
+
+import (
+	"context"
+	"reflect"
+	"testing"
+
+	commandmeta "go.maximumdirect.net/commandkit/internal/commandmeta"
+)
+
+// Existing consumer code can compare these metadata values or use them as keys.
+var (
+	_ map[FlagMeta]struct{}
+	_ map[ArgumentMeta]struct{}
+	_ = (FlagMeta{}) == (FlagMeta{})
+	_ = (ArgumentMeta{}) == (ArgumentMeta{})
+)
+
+func TestCompletionHintsFollowCapturedBindings(t *testing.T) {
+	type inner struct{ values Supplied[[]string] }
+	type outer struct{ flags FlagValues[inner] }
+	choices := []CompletionChoice{{Value: "alpha", Description: "first"}}
+	hint := CompleteChoices(choices...)
+	choices[0] = CompletionChoice{Value: "changed"}
+	parse := func(value string) (string, error) { return value, nil }
+	repeated := RepeatFlag(FlagMeta{Name: "tag", Completion: hint}, nil, parse,
+		func(input *inner, value Supplied[[]string]) { input.values = value })
+	captured := CaptureFlags([]Flag[inner]{repeated}, func(input *outer) *FlagValues[inner] { return &input.flags })
+	command := NewCommand(CommandSpec[outer]{
+		Name: "run",
+		Flags: append(captured,
+			ValueFlag(FlagMeta{Name: "file", Completion: CompleteFiles()}, (*string)(nil), parse, func(*outer, Supplied[string]) {}),
+			BoolFlag(FlagMeta{Name: "enabled"}, false, func(*outer, Supplied[bool]) {}),
+			ValueFlag(FlagMeta{Name: "empty", Completion: CompleteChoices()}, (*string)(nil), parse, func(*outer, Supplied[string]) {})),
+		Arguments: []Argument[outer]{
+			ValueArgument(ArgumentMeta{Name: "directory", Completion: CompleteDirectories()}, false, parse, func(*outer, Supplied[string]) {}),
+			RepeatArgument(ArgumentMeta{Name: "values", Completion: hint}, 0, -1, parse, func(*outer, Supplied[[]string]) {}),
+		},
+	})
+	flags := command.record.payload.bridgeFlags()
+	arguments := command.record.payload.bridgeArguments()
+	want := commandmeta.CompletionHint{Kind: commandmeta.CompletionChoices, Choices: []commandmeta.CompletionChoice{{Value: "alpha", Description: "first"}}}
+	if !flags[0].Repeated || !reflect.DeepEqual(flags[0].Completion, want) || !reflect.DeepEqual(arguments[1].Completion, want) {
+		t.Fatalf("captured hints: flags=%#v arguments=%#v", flags, arguments)
+	}
+	if flags[1].Completion.Kind != commandmeta.CompletionFiles || flags[2].Completion.Kind != commandmeta.CompletionNone || flags[3].Completion.Kind != commandmeta.CompletionChoices || len(flags[3].Completion.Choices) != 0 || arguments[0].Completion.Kind != commandmeta.CompletionDirectories {
+		t.Fatalf("hint strategies: flags=%#v arguments=%#v", flags, arguments)
+	}
+	flags[0].Completion.Choices[0].Value = "mutated"
+	if got := command.record.payload.bridgeFlags()[0].Completion; !reflect.DeepEqual(got, want) {
+		t.Fatalf("bridged choices changed captured hint: %#v", got)
+	}
+	if got := bridgeCompletion(NoCompletion()); got.Kind != commandmeta.CompletionNone || !reflect.DeepEqual(got, bridgeCompletion(CompletionHint{})) {
+		t.Fatalf("no completion: %#v", got)
+	}
+	for _, flag := range append(commandmeta.ReportingFlags(), commandmeta.HelpFlag()) {
+		if !reflect.DeepEqual(flag.Completion.Choices, []commandmeta.CompletionChoice{{Value: "true"}, {Value: "false"}}) {
+			t.Fatalf("reporting flag choices: %#v", flag)
+		}
+	}
+}
+
+func TestCompletionChoicesDoNotRestrictExecution(t *testing.T) {
+	type input struct{ mode Supplied[string] }
+	var received input
+	command := NewCommand(CommandSpec[input]{
+		Name: "run",
+		Flags: []Flag[input]{ValueFlag(FlagMeta{Name: "mode", Completion: CompleteChoices(CompletionChoice{Value: "suggested"})}, (*string)(nil),
+			func(value string) (string, error) { return value, nil },
+			func(i *input, value Supplied[string]) { i.mode = value })},
+		Run: func(_ Invocation, value input) Outcome { received = value; return Success() },
+	})
+	app, err := New(Identity{Name: "example"}, command)
+	if err != nil {
+		t.Fatal(err)
+	}
+	outcome := app.Execute(context.Background(), []string{"run", "--mode=other"}, Streams{})
+	if outcome.Status != 0 || !received.mode.Set || received.mode.Value != "other" {
+		t.Fatalf("outcome=%#v input=%#v", outcome, received)
+	}
+}

config.go

@@ -1,461 +0,0 @@
-package commandkit
-
-import (
-	"context"
-	"errors"
-	"fmt"
-	"io"
-	"sort"
-	"strconv"
-	"strings"
-
-	configkit "gitea.maximumdirect.net/eric/ConfigKit"
-	"go.yaml.in/yaml/v4"
-)
-
-// Selection identifies the application configuration inputs supplied to a
-// configuration scope.
-type Selection struct {
-	Config  Supplied[string]
-	Overlay Supplied[string]
-}
-
-// ConfigOperation identifies a supported configuration inspection operation.
-type ConfigOperation string
-
-const (
-	ConfigValidate ConfigOperation = "validate"
-	ConfigShow     ConfigOperation = "show"
-	ConfigSources  ConfigOperation = "sources"
-	ConfigExplain  ConfigOperation = "explain"
-)
-
-// ConfigRequest describes one configuration operation and its selected inputs.
-type ConfigRequest struct {
-	Operation ConfigOperation
-	Selection Selection
-}
-
-// EffectiveWriter writes an owning library's native effective configuration.
-type EffectiveWriter interface {
-	WriteEffective(io.Writer) error
-}
-
-// SourceReader reports the sources used to construct a configuration.
-type SourceReader interface {
-	Sources() []configkit.SourceInfo
-}
-
-// ExplanationReader writes an owning library's path explanation.
-type ExplanationReader interface {
-	Explain(configkit.Path) (configkit.Explanation, bool)
-	WriteExplanation(io.Writer, configkit.Path) error
-}
-
-// ConfigView contains optional views relevant to supported operations.
-type ConfigView struct {
-	Effective   EffectiveWriter
-	Sources     SourceReader
-	Explanation ExplanationReader
-}
-
-// Acquired contains a configuration view and diagnostics from its acquisition.
-type Acquired[T any] struct {
-	Value       T
-	Diagnostics []Diagnostic
-}
-
-// ConfigScope declares one named configuration and its supported operations.
-type ConfigScope[C any] struct {
-	Name       string
-	Summary    string
-	Operations []ConfigOperation
-	Acquire    func(context.Context, ConfigRequest, C) (Acquired[ConfigView], error)
-}
-
-// Selector binds one typed command flag to selected configuration scopes.
-// A required binding is required only when a selected scope uses it.
-type Selector[C any] struct {
-	Binding Flag[C]
-	Scopes  []string
-}
-
-// ConfigSuite declares selectors and configuration scopes for an App.
-type ConfigSuite[C any] struct {
-	NewContext func() C
-	Selectors  []Selector[C]
-	CheckInput func(Selection, C) error
-	Scopes     []ConfigScope[C]
-}
-
-type configScopeInfo struct {
-	Name       string            `yaml:"name"`
-	Operations []ConfigOperation `yaml:"operations"`
-}
-
-type scopesInventory struct {
-	Scopes []configScopeInfo `yaml:"scopes"`
-}
-
-type preparedConfigSuite[C any] struct {
-	suite     ConfigSuite[C]
-	ordered   []ConfigScope[C]
-	byName    map[string]ConfigScope[C]
-	installed []ConfigOperation
-	inventory scopesInventory
-}
-
-type configScopesInput struct {
-	Format string
-}
-
-type selectorState[C any] struct {
-	name     string
-	required bool
-	scopes   []string
-	supplied bool
-	apply    func(*C)
-	clear    func(*C)
-}
-
-type configInput[C any] struct {
-	Selection       Selection
-	Scope           string
-	Format          string
-	Path            Supplied[string]
-	SelectorContext C
-	selectors       []selectorState[C]
-}
-
-// RegisterConfig installs the available config handlers and the scope discovery
-// command. Its registration and discovery paths do not invoke scope loaders.
-func RegisterConfig[C any](app *App, suite ConfigSuite[C]) error {
-	if app == nil {
-		return fmt.Errorf("cannot register configuration on a nil app")
-	}
-	if app.configRegistered {
-		return fmt.Errorf("configuration suite is already registered")
-	}
-	normalized, err := normalizeConfigSuite(suite)
-	if err != nil {
-		return err
-	}
-	if _, exists := app.commands["config"]; exists {
-		return fmt.Errorf("command path %q is already registered", "config")
-	}
-	prepared := prepareConfigSuite(normalized)
-
-	commands := make([]Command, 0, 5)
-	for _, operation := range prepared.installed {
-		var command Command
-		switch operation {
-		case ConfigValidate:
-			command, err = newConfigValidateCommand(prepared)
-		case ConfigShow:
-			command, err = newConfigShowCommand(prepared)
-		case ConfigSources:
-			command, err = newConfigSourcesCommand(prepared)
-		case ConfigExplain:
-			command, err = newConfigExplainCommand(prepared)
-		}
-		if err != nil {
-			return err
-		}
-		commands = append(commands, command)
-	}
-	command, err := newConfigScopesCommandWithPrepared(prepared)
-	if err != nil {
-		return err
-	}
-	commands = append(commands, command)
-	root, err := Group("config", "Inspect configuration.", commands...)
-	if err != nil {
-		return err
-	}
-	if err := app.Register(root); err != nil {
-		return err
-	}
-	app.configRegistered = true
-	return nil
-}
-
-// NewConfigKitScope adapts a ConfigKit loader into a scope with validation,
-// effective display, source listing, and path explanation capabilities. The
-// loader runs once per selected operation. Successful loads expose the result's
-// public facets directly; ConfigKit LoadError records become CommandKit
-// diagnostics while the original error is returned.
-func NewConfigKitScope[C, T any](name, summary string, load func(context.Context, Selection, C) (*configkit.Result[T], error)) (ConfigScope[C], error) {
-	if load == nil {
-		return ConfigScope[C]{}, fmt.Errorf("ConfigKit scope loader must not be nil")
-	}
-	return ConfigScope[C]{
-		Name:       name,
-		Summary:    summary,
-		Operations: []ConfigOperation{ConfigValidate, ConfigShow, ConfigSources, ConfigExplain},
-		Acquire: func(ctx context.Context, request ConfigRequest, contextValue C) (Acquired[ConfigView], error) {
-			result, err := load(ctx, request.Selection, contextValue)
-			if err != nil {
-				var loadError *configkit.LoadError
-				if errors.As(err, &loadError) {
-					return Acquired[ConfigView]{Diagnostics: ConfigKitDiagnostics(name, loadError.Sources(), loadError.Diagnostics())}, err
-				}
-				return Acquired[ConfigView]{}, err
-			}
-			if result == nil {
-				return Acquired[ConfigView]{}, fmt.Errorf("ConfigKit scope %q returned a nil result", name)
-			}
-			return Acquired[ConfigView]{
-				Value:       ConfigView{Effective: result, Sources: result, Explanation: result},
-				Diagnostics: ConfigKitDiagnostics(name, result.Sources(), result.Diagnostics()),
-			}, nil
-		},
-	}, nil
-}
-
-// ConfigKitDiagnostics groups ConfigKit records with their scope and source legend.
-func ConfigKitDiagnostics(scope string, sources []configkit.SourceInfo, records []configkit.Diagnostic) []Diagnostic {
-	if len(records) == 0 {
-		return nil
-	}
-	severity := configkit.SeverityWarning
-	for _, record := range records {
-		if record.Severity == configkit.SeverityError {
-			severity = configkit.SeverityError
-			break
-		}
-	}
-	return []Diagnostic{{
-		Severity: severity,
-		Write: func(writer io.Writer) error {
-			if err := writeDiagnosticText(writer, "Configuration scope "+strconv.Quote(scope)+":\n"); err != nil {
-				return err
-			}
-			if len(sources) > 0 {
-				if err := writeDiagnosticText(writer, "Source IDs:\n"); err != nil {
-					return err
-				}
-				for _, source := range sources {
-					line := "  " + strconv.Quote(source.ID) + ": label=" + strconv.Quote(source.Label) + ", path=" + strconv.Quote(source.Path) + "\n"
-					if err := writeDiagnosticText(writer, line); err != nil {
-						return err
-					}
-				}
-			}
-			return configkit.WriteDiagnostics(writer, records)
-		},
-	}}
-}
-
-func writeDiagnosticText(writer io.Writer, value string) error {
-	written, err := io.WriteString(writer, value)
-	if err != nil {
-		return err
-	}
-	if written != len(value) {
-		return io.ErrShortWrite
-	}
-	return nil
-}
-
-func normalizeConfigSuite[C any](suite ConfigSuite[C]) (ConfigSuite[C], error) {
-	normalized := suite
-	normalized.Selectors = append([]Selector[C](nil), suite.Selectors...)
-	normalized.Scopes = make([]ConfigScope[C], 0, len(suite.Scopes))
-	scopeNames := make(map[string]struct{}, len(suite.Scopes))
-	for _, scope := range suite.Scopes {
-		if scope.Name == "" {
-			return ConfigSuite[C]{}, fmt.Errorf("configuration scope name must not be empty")
-		}
-		if scope.Name == "all" {
-			return ConfigSuite[C]{}, fmt.Errorf("configuration scope name %q is reserved", scope.Name)
-		}
-		if _, exists := scopeNames[scope.Name]; exists {
-			return ConfigSuite[C]{}, fmt.Errorf("duplicate configuration scope %q", scope.Name)
-		}
-		scopeNames[scope.Name] = struct{}{}
-		operations, err := normalizeConfigOperations(scope.Operations)
-		if err != nil {
-			return ConfigSuite[C]{}, fmt.Errorf("configuration scope %q: %w", scope.Name, err)
-		}
-		if len(operations) > 0 && scope.Acquire == nil {
-			return ConfigSuite[C]{}, fmt.Errorf("configuration scope %q declares operations without an acquisition callback", scope.Name)
-		}
-		scope.Operations = operations
-		normalized.Scopes = append(normalized.Scopes, scope)
-	}
-	seenNames := make(map[string]struct{}, len(normalized.Selectors))
-	seenShorts := make(map[string]struct{}, len(normalized.Selectors))
-	for index := range normalized.Selectors {
-		selector := &normalized.Selectors[index]
-		binding := selector.Binding.binding
-		if !binding.valid || binding.clear == nil || binding.meta.Name == "" {
-			return ConfigSuite[C]{}, fmt.Errorf("configuration selector %d has an invalid flag binding", index)
-		}
-		if !validFlagName(binding.meta.Name) {
-			return ConfigSuite[C]{}, fmt.Errorf("configuration selector flag name %q is invalid", binding.meta.Name)
-		}
-		if binding.meta.Name == "config" || binding.meta.Name == "overlay" || binding.meta.Name == "scope" || binding.meta.Name == "format" || binding.meta.Name == "help" {
-			return ConfigSuite[C]{}, fmt.Errorf("configuration selector flag --%s conflicts with a standard flag", binding.meta.Name)
-		}
-		if binding.meta.Short == "h" {
-			return ConfigSuite[C]{}, fmt.Errorf("configuration selector short flag -%s conflicts with help", binding.meta.Short)
-		}
-		if binding.meta.Short != "" && (len(binding.meta.Short) != 1 || binding.meta.Short == "-") {
-			return ConfigSuite[C]{}, fmt.Errorf("configuration selector short spelling %q must be one byte", binding.meta.Short)
-		}
-		seen := make(map[string]struct{}, len(selector.Scopes))
-		unique := make([]string, 0, len(selector.Scopes))
-		for _, scopeName := range selector.Scopes {
-			if _, exists := scopeNames[scopeName]; !exists {
-				return ConfigSuite[C]{}, fmt.Errorf("selector --%s references unknown configuration scope %q", binding.meta.Name, scopeName)
-			}
-			if _, exists := seen[scopeName]; exists {
-				continue
-			}
-			seen[scopeName] = struct{}{}
-			unique = append(unique, scopeName)
-		}
-		selector.Scopes = append([]string(nil), unique...)
-		if _, exists := seenNames[binding.meta.Name]; exists {
-			return ConfigSuite[C]{}, fmt.Errorf("duplicate configuration selector flag --%s", binding.meta.Name)
-		}
-		if binding.meta.Short != "" {
-			if _, exists := seenShorts[binding.meta.Short]; exists {
-				return ConfigSuite[C]{}, fmt.Errorf("duplicate configuration selector flag --%s", binding.meta.Name)
-			}
-			seenShorts[binding.meta.Short] = struct{}{}
-		}
-		seenNames[binding.meta.Name] = struct{}{}
-	}
-	return normalized, nil
-}
-
-func prepareConfigSuite[C any](suite ConfigSuite[C]) *preparedConfigSuite[C] {
-	prepared := &preparedConfigSuite[C]{
-		suite:     suite,
-		ordered:   orderedConfigScopes(suite.Scopes),
-		byName:    make(map[string]ConfigScope[C], len(suite.Scopes)),
-		installed: make([]ConfigOperation, 0, 4),
-		inventory: scopesInventory{Scopes: make([]configScopeInfo, 0, len(suite.Scopes))},
-	}
-	for _, scope := range suite.Scopes {
-		prepared.byName[scope.Name] = scope
-	}
-	for _, operation := range []ConfigOperation{ConfigValidate, ConfigShow, ConfigSources, ConfigExplain} {
-		if configOperationDeclared(suite.Scopes, operation) {
-			prepared.installed = append(prepared.installed, operation)
-		}
-	}
-	for _, scope := range prepared.ordered {
-		operations := make([]ConfigOperation, 0, len(scope.Operations))
-		for _, operation := range scope.Operations {
-			if containsOperation(prepared.installed, operation) {
-				operations = append(operations, operation)
-			}
-		}
-		prepared.inventory.Scopes = append(prepared.inventory.Scopes, configScopeInfo{Name: scope.Name, Operations: operations})
-	}
-	return prepared
-}
-
-func normalizeConfigOperations(operations []ConfigOperation) ([]ConfigOperation, error) {
-	seen := make(map[ConfigOperation]struct{}, len(operations))
-	for _, operation := range operations {
-		switch operation {
-		case ConfigValidate, ConfigShow, ConfigSources, ConfigExplain:
-		default:
-			return nil, fmt.Errorf("unknown operation %q", operation)
-		}
-		seen[operation] = struct{}{}
-	}
-	ordered := make([]ConfigOperation, 0, len(seen))
-	for _, operation := range []ConfigOperation{ConfigValidate, ConfigShow, ConfigSources, ConfigExplain} {
-		if _, exists := seen[operation]; exists {
-			ordered = append(ordered, operation)
-		}
-	}
-	return ordered, nil
-}
-
-func newConfigScopesCommandWithPrepared[C any](prepared *preparedConfigSuite[C]) (Command, error) {
-	formatDefault := "text"
-	spec := CommandSpec[configScopesInput]{
-		Name:    "scopes",
-		Summary: "List configuration scopes and supported operations.",
-		Flags: []Flag[configScopesInput]{ValueFlag[configScopesInput](FlagMeta{
-			Name: "format", Usage: "Output format: text or yaml.",
-		}, &formatDefault, parseConfigFormat, func(input *configScopesInput, value Supplied[string]) {
-			input.Format = value.Value
-		})},
-		CheckInput: func(input configScopesInput) error { return checkConfigFormat(input.Format) },
-		Run: func(invocation Invocation, input configScopesInput) Outcome {
-			var output []byte
-			var err error
-			if input.Format == "yaml" {
-				output, err = yaml.Marshal(prepared.inventory)
-			} else {
-				output = []byte(formatScopeInventory(prepared.inventory))
-			}
-			if err != nil {
-				return Failure(err)
-			}
-			if err := writeReport(invocation.Streams.Out, output); err != nil {
-				return incompleteReport(err)
-			}
-			return Success()
-		},
-	}
-	return NewCommand(spec)
-}
-
-func orderedConfigScopes[C any](scopes []ConfigScope[C]) []ConfigScope[C] {
-	ordered := append([]ConfigScope[C](nil), scopes...)
-	sort.SliceStable(ordered, func(i, j int) bool {
-		return configScopeOrder(ordered[i].Name) < configScopeOrder(ordered[j].Name)
-	})
-	return ordered
-}
-
-func configScopeOrder(name string) string {
-	switch name {
-	case "app":
-		return "\x00"
-	case "promptkit":
-		return "\x01"
-	default:
-		return "\x02" + name
-	}
-}
-
-func formatScopeInventory(inventory scopesInventory) string {
-	var output strings.Builder
-	for _, scope := range inventory.Scopes {
-		output.WriteString(scope.Name)
-		output.WriteString(":")
-		if len(scope.Operations) > 0 {
-			output.WriteString(" ")
-			for index, operation := range scope.Operations {
-				if index > 0 {
-					output.WriteString(", ")
-				}
-				output.WriteString(string(operation))
-			}
-		}
-		output.WriteByte('\n')
-	}
-	return output.String()
-}
-
-func parseConfigFormat(value string) (string, error) {
-	if err := checkConfigFormat(value); err != nil {
-		return "", err
-	}
-	return value, nil
-}
-
-func checkConfigFormat(value string) error {
-	if value != "text" && value != "yaml" {
-		return fmt.Errorf("format must be text or yaml")
-	}
-	return nil
-}

config_test.go

@@ -1,359 +0,0 @@
-package commandkit
-
-import (
-	"bytes"
-	"context"
-	"reflect"
-	"strconv"
-	"strings"
-	"testing"
-)
-
-func TestConfigScopeDiscoveryOrdersAndDeduplicatesCapabilities(t *testing.T) {
-	app, err := New(Identity{Name: "example"})
-	if err != nil {
-		t.Fatal(err)
-	}
-	newContextCalls := 0
-	acquireCalls := 0
-	suite := ConfigSuite[struct{}]{
-		NewContext: func() struct{} { newContextCalls++; return struct{}{} },
-		Scopes: []ConfigScope[struct{}]{
-			{Name: "zeta", Operations: []ConfigOperation{ConfigExplain, ConfigShow, ConfigExplain}, Acquire: func(context.Context, ConfigRequest, struct{}) (Acquired[ConfigView], error) {
-				acquireCalls++
-				return Acquired[ConfigView]{}, nil
-			}},
-			{Name: "promptkit", Operations: []ConfigOperation{ConfigSources}, Acquire: noopConfigAcquire[struct{}]},
-			{Name: "app", Operations: []ConfigOperation{ConfigShow, ConfigValidate, ConfigShow}, Acquire: func(context.Context, ConfigRequest, struct{}) (Acquired[ConfigView], error) {
-				acquireCalls++
-				return Acquired[ConfigView]{}, nil
-			}},
-			{Name: "metadata", Summary: "No provider is required."},
-		},
-	}
-	normalized, err := normalizeConfigSuite(suite)
-	if err != nil {
-		t.Fatal(err)
-	}
-	if !reflect.DeepEqual(normalized.Scopes[0].Operations, []ConfigOperation{ConfigShow, ConfigExplain}) || !reflect.DeepEqual(normalized.Scopes[2].Operations, []ConfigOperation{ConfigValidate, ConfigShow}) {
-		t.Fatalf("normalized capabilities = %#v", normalized.Scopes)
-	}
-	if err := RegisterConfig(app, suite); err != nil {
-		t.Fatal(err)
-	}
-
-	var textOutput bytes.Buffer
-	outcome := app.Execute(context.Background(), []string{"config", "scopes"}, Streams{Out: &textOutput})
-	if outcome.Kind != OutcomeSuccess {
-		t.Fatalf("text inventory outcome = %#v", outcome)
-	}
-	wantText := "app: validate, show\npromptkit: sources\nmetadata:\nzeta: show, explain\n"
-	if textOutput.String() != wantText {
-		t.Fatalf("text inventory = %q, want %q", textOutput.String(), wantText)
-	}
-
-	var yamlOutput bytes.Buffer
-	outcome = app.Execute(context.Background(), []string{"config", "scopes", "--format", "yaml"}, Streams{Out: &yamlOutput})
-	if outcome.Kind != OutcomeSuccess {
-		t.Fatalf("YAML inventory outcome = %#v", outcome)
-	}
-	if got := yamlOutput.String(); !strings.Contains(got, "scopes:") || strings.Index(got, "name: app") > strings.Index(got, "name: promptkit") || !strings.Contains(got, "operations: []") {
-		t.Fatalf("YAML inventory = %q", got)
-	}
-	outcome = app.Execute(context.Background(), []string{"config", "scopes", "--help"}, Streams{})
-	if outcome.Kind != OutcomeSuccess {
-		t.Fatalf("scope help outcome = %#v", outcome)
-	}
-	outcome = app.Execute(context.Background(), []string{"config", "scopes", "--format", "json"}, Streams{})
-	if outcome.Kind != OutcomeUsage {
-		t.Fatalf("invalid format outcome = %#v", outcome)
-	}
-	if newContextCalls != 0 || acquireCalls != 0 {
-		t.Fatalf("discovery called runtime callbacks: NewContext=%d Acquire=%d", newContextCalls, acquireCalls)
-	}
-}
-
-func TestConfigInputDefaultsToAppAndRetainsAbsentSelections(t *testing.T) {
-	suite := ConfigSuite[struct{}]{Scopes: []ConfigScope[struct{}]{{Name: "app"}}}
-	prepared, err := prepareInput(CommandSpec[configInput[struct{}]]{Flags: configInputFlags(suite, "yaml")}, make([][]string, 4), nil, true)
-	if err != nil {
-		t.Fatal(err)
-	}
-	input := prepared.build()
-	if input.Scope != "app" || input.Format != "yaml" || input.Selection.Config.Set || input.Selection.Overlay.Set {
-		t.Fatalf("configuration defaults = %#v", input)
-	}
-}
-
-func TestRegisterConfigOwnsPreparedScopeAndSelectorMetadata(t *testing.T) {
-	type selectorInput struct{ Region Supplied[string] }
-	var acquired selectorInput
-	suite := ConfigSuite[selectorInput]{
-		Selectors: []Selector[selectorInput]{{
-			Binding: ValueFlag[selectorInput](FlagMeta{Name: "region"}, nil, parseString, func(input *selectorInput, value Supplied[string]) { input.Region = value }),
-			Scopes:  []string{"app"},
-		}},
-		Scopes: []ConfigScope[selectorInput]{{
-			Name:       "app",
-			Operations: []ConfigOperation{ConfigValidate},
-			Acquire: func(_ context.Context, _ ConfigRequest, input selectorInput) (Acquired[ConfigView], error) {
-				acquired = input
-				return Acquired[ConfigView]{}, nil
-			},
-		}},
-	}
-	app, err := New(Identity{Name: "example"})
-	if err != nil {
-		t.Fatal(err)
-	}
-	if err := RegisterConfig(app, suite); err != nil {
-		t.Fatal(err)
-	}
-
-	suite.Scopes[0].Name = "renamed"
-	suite.Scopes[0].Operations[0] = ConfigShow
-	suite.Selectors[0].Scopes[0] = "renamed"
-
-	var inventory bytes.Buffer
-	if result := app.Execute(context.Background(), []string{"config", "scopes"}, Streams{Out: &inventory}); result.Kind != OutcomeSuccess {
-		t.Fatalf("scope inventory outcome = %#v", result)
-	}
-	if got := inventory.String(); got != "app: validate\n" {
-		t.Fatalf("scope inventory after caller mutation = %q", got)
-	}
-	if result := app.Execute(context.Background(), []string{"config", "validate", "--scope=app", "--region=west"}, Streams{}); result.Kind != OutcomeSuccess {
-		t.Fatalf("registered scope execution after caller mutation = %#v", result)
-	}
-	if acquired.Region != (Supplied[string]{Value: "west", Set: true}) {
-		t.Fatalf("acquired selector after caller mutation = %#v", acquired)
-	}
-}
-
-func TestRegisterConfigRejectsDuplicateSelectorNamesAndShorts(t *testing.T) {
-	type selectorInput struct{ First, Second string }
-	tests := []struct {
-		name       string
-		firstMeta  FlagMeta
-		secondMeta FlagMeta
-	}{
-		{name: "name", firstMeta: FlagMeta{Name: "region", Short: "r"}, secondMeta: FlagMeta{Name: "region", Short: "g"}},
-		{name: "short", firstMeta: FlagMeta{Name: "region", Short: "r"}, secondMeta: FlagMeta{Name: "group", Short: "r"}},
-	}
-	for _, test := range tests {
-		t.Run(test.name, func(t *testing.T) {
-			app, err := New(Identity{Name: "example"})
-			if err != nil {
-				t.Fatal(err)
-			}
-			suite := ConfigSuite[selectorInput]{Selectors: []Selector[selectorInput]{
-				{Binding: ValueFlag[selectorInput](test.firstMeta, nil, parseString, func(input *selectorInput, value Supplied[string]) { input.First = value.Value })},
-				{Binding: ValueFlag[selectorInput](test.secondMeta, nil, parseString, func(input *selectorInput, value Supplied[string]) { input.Second = value.Value })},
-			}}
-			if err := RegisterConfig(app, suite); err == nil || !strings.Contains(err.Error(), "duplicate configuration selector flag") {
-				t.Fatalf("RegisterConfig error = %v", err)
-			}
-		})
-	}
-}
-
-func TestRegisterConfigRejectsInvalidSuitesAndCollisions(t *testing.T) {
-	tests := []struct {
-		name  string
-		scope ConfigScope[struct{}]
-		want  string
-	}{
-		{name: "empty name", scope: ConfigScope[struct{}]{}, want: "name must not be empty"},
-		{name: "all name", scope: ConfigScope[struct{}]{Name: "all"}, want: "reserved"},
-		{name: "unknown operation", scope: ConfigScope[struct{}]{Name: "app", Operations: []ConfigOperation{"diff"}}, want: "unknown operation"},
-		{name: "missing acquisition", scope: ConfigScope[struct{}]{Name: "app", Operations: []ConfigOperation{ConfigValidate}}, want: "without an acquisition"},
-	}
-	for _, test := range tests {
-		t.Run(test.name, func(t *testing.T) {
-			app, _ := New(Identity{Name: "example"})
-			err := RegisterConfig(app, ConfigSuite[struct{}]{Scopes: []ConfigScope[struct{}]{test.scope}})
-			if err == nil || !strings.Contains(err.Error(), test.want) {
-				t.Fatalf("RegisterConfig error = %v, want %q", err, test.want)
-			}
-		})
-	}
-
-	app, _ := New(Identity{Name: "example"})
-	custom, err := NewCommand(CommandSpec[struct{}]{Name: "config", Run: func(Invocation, struct{}) Outcome { return Success() }})
-	if err != nil {
-		t.Fatal(err)
-	}
-	if err := app.Register(custom); err != nil {
-		t.Fatal(err)
-	}
-	if err := RegisterConfig(app, ConfigSuite[struct{}]{}); err == nil {
-		t.Fatal("replaced a pre-existing config command")
-	}
-}
-
-func TestConfigSelectorPreflightAndScopedContextProjection(t *testing.T) {
-	type selectorInput struct {
-		Count   Supplied[int]
-		Enabled Supplied[bool]
-		Other   Supplied[int]
-		Runtime string
-	}
-	baseContextCalls := 0
-	checkCalls := 0
-	var checked selectorInput
-	countDefault := 9
-	suite := ConfigSuite[selectorInput]{
-		NewContext: func() selectorInput { baseContextCalls++; return selectorInput{Runtime: "invocation cache"} },
-		Selectors: []Selector[selectorInput]{
-			{Binding: ValueFlag[selectorInput](FlagMeta{Name: "count"}, &countDefault, strconv.Atoi, func(input *selectorInput, value Supplied[int]) { input.Count = value }), Scopes: []string{"app"}},
-			{Binding: BoolFlag[selectorInput](FlagMeta{Name: "enabled"}, true, func(input *selectorInput, value Supplied[bool]) { input.Enabled = value }), Scopes: []string{"promptkit"}},
-			{Binding: ValueFlag[selectorInput](FlagMeta{Name: "other"}, nil, strconv.Atoi, func(input *selectorInput, value Supplied[int]) { input.Other = value })},
-		},
-		CheckInput: func(_ Selection, input selectorInput) error { checkCalls++; checked = input; return nil },
-		Scopes: []ConfigScope[selectorInput]{
-			{Name: "app", Operations: []ConfigOperation{ConfigValidate}, Acquire: noopConfigAcquire[selectorInput]},
-			{Name: "promptkit", Operations: []ConfigOperation{ConfigValidate}, Acquire: noopConfigAcquire[selectorInput]},
-		},
-	}
-	normalized, err := normalizeConfigSuite(suite)
-	if err != nil {
-		t.Fatal(err)
-	}
-	preparedSuite := prepareConfigSuite(normalized)
-	spec := CommandSpec[configInput[selectorInput]]{Flags: configInputFlags(normalized, "text")}
-	prepared, err := prepareInput(spec, [][]string{{"all"}, {"text"}, {""}, nil, {"0"}, {"false"}, nil}, nil, true)
-	if err != nil {
-		t.Fatal(err)
-	}
-	input := prepared.build()
-	scopeNames, err := preflightConfig(preparedSuite, input, ConfigValidate)
-	if err != nil {
-		t.Fatal(err)
-	}
-	if !reflect.DeepEqual(scopeNames, []string{"app", "promptkit"}) || checkCalls != 1 || checked.Count != (Supplied[int]{Value: 0, Set: true}) || checked.Enabled != (Supplied[bool]{Value: false, Set: true}) {
-		t.Fatalf("preflight result=%v checked=%#v calls=%d", scopeNames, checked, checkCalls)
-	}
-	if !input.Selection.Config.Set || input.Selection.Config.Value != "" || input.Selection.Overlay.Set {
-		t.Fatalf("configuration selection presence = %#v", input.Selection)
-	}
-	if baseContextCalls != 0 {
-		t.Fatalf("NewContext called during preflight %d times", baseContextCalls)
-	}
-
-	contexts := contextsForScopes(preparedSuite, input, scopeNames)
-	if baseContextCalls != 1 {
-		t.Fatalf("NewContext calls = %d, want one", baseContextCalls)
-	}
-	if contexts["app"].Count != (Supplied[int]{Value: 0, Set: true}) || contexts["app"].Enabled != (Supplied[bool]{}) || contexts["app"].Other != (Supplied[int]{}) {
-		t.Fatalf("app selectors = %#v", contexts["app"])
-	}
-	if contexts["promptkit"].Count != (Supplied[int]{}) || contexts["promptkit"].Enabled != (Supplied[bool]{Value: false, Set: true}) || contexts["promptkit"].Runtime != "invocation cache" {
-		t.Fatalf("promptkit selectors = %#v", contexts["promptkit"])
-	}
-}
-
-func TestConfigPreflightRejectsUnsupportedAggregateAndInapplicableSelector(t *testing.T) {
-	type selectorInput struct{ Region Supplied[string] }
-	newContextCalls := 0
-	suite := ConfigSuite[selectorInput]{
-		NewContext: func() selectorInput { newContextCalls++; return selectorInput{} },
-		Selectors:  []Selector[selectorInput]{{Binding: ValueFlag[selectorInput](FlagMeta{Name: "region"}, nil, parseString, func(input *selectorInput, value Supplied[string]) { input.Region = value }), Scopes: []string{"promptkit"}}},
-		Scopes: []ConfigScope[selectorInput]{
-			{Name: "app", Operations: []ConfigOperation{ConfigValidate}, Acquire: noopConfigAcquire[selectorInput]},
-			{Name: "promptkit", Operations: []ConfigOperation{ConfigShow}, Acquire: noopConfigAcquire[selectorInput]},
-		},
-	}
-	normalized, err := normalizeConfigSuite(suite)
-	if err != nil {
-		t.Fatal(err)
-	}
-	preparedSuite := prepareConfigSuite(normalized)
-	prepared, err := prepareInput(CommandSpec[configInput[selectorInput]]{Flags: configInputFlags(normalized, "text")}, [][]string{{"all"}, {"text"}, nil, nil, nil}, nil, true)
-	if err != nil {
-		t.Fatal(err)
-	}
-	if _, err := preflightConfig(preparedSuite, prepared.build(), ConfigValidate); err == nil || !strings.Contains(err.Error(), "does not support validate") {
-		t.Fatalf("unsupported aggregate error = %v", err)
-	}
-	if newContextCalls != 0 {
-		t.Fatalf("unsupported aggregate created context %d times", newContextCalls)
-	}
-
-	prepared, err = prepareInput(CommandSpec[configInput[selectorInput]]{Flags: configInputFlags(normalized, "text")}, [][]string{{"app"}, {"text"}, nil, nil, {"west"}}, nil, true)
-	if err != nil {
-		t.Fatal(err)
-	}
-	if _, err := preflightConfig(preparedSuite, prepared.build(), ConfigValidate); err == nil || !strings.Contains(err.Error(), "not applicable") {
-		t.Fatalf("inapplicable selector error = %v", err)
-	}
-}
-
-func noopConfigAcquire[C any](context.Context, ConfigRequest, C) (Acquired[ConfigView], error) {
-	return Acquired[ConfigView]{}, nil
-}
-
-func TestRequiredConfigSelectorOnlyAppliesToSelectedScopes(t *testing.T) {
-	app, _ := New(Identity{Name: "example"})
-	calls := 0
-	acquire := func(context.Context, ConfigRequest, string) (Acquired[ConfigView], error) {
-		calls++
-		return Acquired[ConfigView]{}, nil
-	}
-	err := RegisterConfig(app, ConfigSuite[string]{
-		Selectors: []Selector[string]{{Scopes: []string{"app"}, Binding: ValueFlag[string](FlagMeta{Name: "campaign", Required: true}, nil, parseString, func(c *string, v Supplied[string]) { *c = v.Value })}},
-		Scopes:    []ConfigScope[string]{{Name: "app", Operations: []ConfigOperation{ConfigValidate}, Acquire: acquire}, {Name: "promptkit", Operations: []ConfigOperation{ConfigValidate}, Acquire: acquire}},
-	})
-	if err != nil {
-		t.Fatal(err)
-	}
-	for _, tc := range []struct {
-		args  []string
-		kind  OutcomeKind
-		calls int
-	}{
-		{[]string{"--scope", "promptkit"}, OutcomeSuccess, 1},
-		{nil, OutcomeUsage, 0},
-		{[]string{"--scope", "all"}, OutcomeUsage, 0},
-		{[]string{"--scope", "all", "--campaign", "spring"}, OutcomeSuccess, 2},
-		{[]string{"--scope", "promptkit", "--campaign", "spring"}, OutcomeUsage, 0},
-		{[]string{"--help"}, OutcomeSuccess, 0},
-	} {
-		calls = 0
-		var out bytes.Buffer
-		result := app.Execute(context.Background(), append([]string{"config", "validate"}, tc.args...), Streams{Out: &out})
-		if result.Kind != tc.kind || calls != tc.calls {
-			t.Fatalf("%v: result=%#v calls=%d", tc.args, result, calls)
-		}
-		if len(tc.args) > 0 && tc.args[0] == "--help" && !strings.Contains(out.String(), "required where applicable") {
-			t.Fatalf("help=%q", out.String())
-		}
-	}
-}
-
-func TestUnknownConfigScopeReportsChoicesWithoutRuntimeWork(t *testing.T) {
-	for _, tc := range []struct {
-		names   []string
-		scope   []string
-		choices string
-	}{
-		{[]string{"promptkit"}, nil, "available: promptkit"},
-		{[]string{"zeta", "alpha", "promptkit", "app"}, []string{"--scope", "unknown"}, "available: app, promptkit, alpha, zeta"},
-	} {
-		runtimeCalls := 0
-		suite := ConfigSuite[struct{}]{NewContext: func() struct{} { runtimeCalls++; return struct{}{} }}
-		for _, name := range tc.names {
-			suite.Scopes = append(suite.Scopes, ConfigScope[struct{}]{Name: name, Operations: []ConfigOperation{ConfigValidate}, Acquire: func(context.Context, ConfigRequest, struct{}) (Acquired[ConfigView], error) {
-				runtimeCalls++
-				return Acquired[ConfigView]{}, nil
-			}})
-		}
-		app, _ := New(Identity{Name: "example"})
-		if err := RegisterConfig(app, suite); err != nil {
-			t.Fatal(err)
-		}
-		var out, diagnostics bytes.Buffer
-		result := app.Execute(context.Background(), append([]string{"config", "validate"}, tc.scope...), Streams{Out: &out, Err: &diagnostics})
-		if result.Kind != OutcomeUsage || runtimeCalls != 0 || out.Len() != 0 || !strings.Contains(diagnostics.String(), tc.choices) {
-			t.Fatalf("result=%#v calls=%d out=%q diagnostics=%q", result, runtimeCalls, out.String(), diagnostics.String())
-		}
-	}
-}

configkit_test.go

@@ -1,720 +0,0 @@
-package commandkit_test
-
-import (
-	"bytes"
-	"context"
-	"errors"
-	"io"
-	"reflect"
-	"strings"
-	"testing"
-	"testing/fstest"
-
-	commandkit "gitea.maximumdirect.net/eric/CommandKit"
-	configkit "gitea.maximumdirect.net/eric/ConfigKit"
-	"go.yaml.in/yaml/v4"
-)
-
-type effectiveYAML string
-
-func (document effectiveYAML) WriteEffective(writer io.Writer) error {
-	_, err := io.WriteString(writer, string(document))
-	return err
-}
-
-type capturedSourceReader struct {
-	entries []configkit.SourceInfo
-	calls   int
-}
-
-func TestConfigExplainPreservesConfigKitProvenanceAndRedaction(t *testing.T) {
-	type entry struct {
-		Enabled    bool             `yaml:"enabled"`
-		Credential configkit.Secret `yaml:"credential"`
-	}
-	type configuration struct {
-		Entries    map[string]entry  `yaml:"entries"`
-		Odd        map[string]string `yaml:"odd"`
-		Value      string            `yaml:"value"`
-		Dependency string            `yaml:"dependency"`
-		Secret     configkit.Secret  `yaml:"secret"`
-	}
-	const secretValue = "EXPLAIN_TEST_SECRET_VALUE"
-	t.Setenv("EXPLAIN_TEST_SECRET", secretValue)
-	input := []byte("entries:\n  parent:\n    enabled: false\n    credential: EXPLAIN_TEST_SECRET\n  child:\n    extends: parent\nodd:\n  \"key/name~\": escaped\nvalue: original\ndependency: source\nsecret: EXPLAIN_TEST_SECRET\n")
-	result, err := configkit.Load[configuration](configkit.Bytes("explanation.yml", input), configkit.Options[configuration]{Definition: configkit.Definition[configuration]{
-		Secret: func(path configkit.Path) bool { return path.String() == "/entries/parent/credential" },
-		Resolve: func(value *configuration, resolution *configkit.Resolution) error {
-			resolution.Record(configkit.Keys("value"), configkit.ChangeNormalization, "upper case", configkit.Keys("dependency"))
-			value.Value = strings.ToUpper(value.Value)
-			return nil
-		},
-	}})
-	if err != nil {
-		t.Fatal(err)
-	}
-	loads, contexts := 0, 0
-	scope, err := commandkit.NewConfigKitScope[struct{}, configuration]("app", "", func(context.Context, commandkit.Selection, struct{}) (*configkit.Result[configuration], error) {
-		loads++
-		return result, nil
-	})
-	if err != nil {
-		t.Fatal(err)
-	}
-	app, err := commandkit.New(commandkit.Identity{Name: "example"})
-	if err != nil {
-		t.Fatal(err)
-	}
-	if err := commandkit.RegisterConfig(app, commandkit.ConfigSuite[struct{}]{NewContext: func() struct{} { contexts++; return struct{}{} }, Scopes: []commandkit.ConfigScope[struct{}]{scope}}); err != nil {
-		t.Fatal(err)
-	}
-	runYAML := func(pointer string) (map[string]any, commandkit.Outcome, string) {
-		var output bytes.Buffer
-		argv := []string{"config", "explain", "--path", pointer, "--format", "yaml"}
-		if pointer == "" {
-			argv = []string{"config", "explain", "--path=", "--format", "yaml"}
-		}
-		outcome := app.Execute(context.Background(), argv, commandkit.Streams{Out: &output, Err: io.Discard})
-		var report map[string]any
-		if outcome.Kind == commandkit.OutcomeSuccess {
-			if err := yaml.Unmarshal(output.Bytes(), &report); err != nil {
-				t.Fatalf("decode explanation YAML: %v; output=%q", err, output.String())
-			}
-		}
-		return report, outcome, output.String()
-	}
-
-	path := "/entries/child/enabled"
-	var native bytes.Buffer
-	if err := result.WriteExplanation(&native, configkit.Keys("entries", "child", "enabled")); err != nil {
-		t.Fatal(err)
-	}
-	var textOutput bytes.Buffer
-	outcome := app.Execute(context.Background(), []string{"config", "explain", "--path", path}, commandkit.Streams{Out: &textOutput, Err: io.Discard})
-	if outcome.Kind != commandkit.OutcomeSuccess || textOutput.String() != native.String() {
-		t.Fatalf("native text outcome=%#v output=%q want=%q", outcome, textOutput.String(), native.String())
-	}
-	var inherited map[string]any
-	inherited, outcome, _ = runYAML(path)
-	if outcome.Kind != commandkit.OutcomeSuccess || inherited["path"] != path {
-		t.Fatalf("inherited explanation outcome=%#v report=%#v", outcome, inherited)
-	}
-	effective := inherited["effective"].(map[string]any)
-	if effective["present"] != true || effective["yaml"] != "false\n" {
-		t.Fatalf("inherited effective snapshot = %#v", effective)
-	}
-	origin := inherited["origin"].(map[string]any)
-	steps := origin["inheritance"].([]any)
-	step := steps[0].(map[string]any)
-	if step["from"] != "/entries/parent/enabled" || step["to"] != path || step["reference"] != "/entries/child/extends" {
-		t.Fatalf("inheritance paths = %#v", step)
-	}
-
-	escaped, outcome, _ := runYAML("/odd/key~1name~0")
-	if outcome.Kind != commandkit.OutcomeSuccess || escaped["path"] != "/odd/key~1name~0" || escaped["effective"].(map[string]any)["yaml"] != "escaped\n" {
-		t.Fatalf("escaped path outcome=%#v report=%#v", outcome, escaped)
-	}
-	historical, outcome, _ := runYAML("/entries/child/extends")
-	if outcome.Kind != commandkit.OutcomeSuccess || historical["effective"].(map[string]any)["present"] != false || len(historical["history"].([]any)) == 0 {
-		t.Fatalf("historical path outcome=%#v report=%#v", outcome, historical)
-	}
-	resolved, outcome, _ := runYAML("/value")
-	if outcome.Kind != commandkit.OutcomeSuccess || resolved["effective"].(map[string]any)["yaml"] != "ORIGINAL\n" {
-		t.Fatalf("resolved snapshot outcome=%#v report=%#v", outcome, resolved)
-	}
-	changes := resolved["history"].([]any)
-	last := changes[len(changes)-1].(map[string]any)
-	if last["reasons"].([]any)[0] != "upper case" || last["dependencies"].([]any)[0] != "/dependency" {
-		t.Fatalf("resolution change = %#v", last)
-	}
-	secretReport, outcome, secretText := runYAML("/entries/child/credential")
-	secretEffective := secretReport["effective"].(map[string]any)
-	if outcome.Kind != commandkit.OutcomeSuccess || secretEffective["redacted"] != true || strings.Contains(secretText, secretValue) {
-		t.Fatalf("secret report outcome=%#v report=%#v", outcome, secretReport)
-	}
-	for _, change := range secretReport["history"].([]any) {
-		entry := change.(map[string]any)
-		for _, key := range []string{"before", "after"} {
-			snapshot := entry[key].(map[string]any)
-			if snapshot["present"] == true && snapshot["redacted"] != true {
-				t.Fatalf("secret history was not redacted: %#v", entry)
-			}
-		}
-	}
-	directSecret, outcome, directSecretText := runYAML("/secret")
-	secretRef, refPresent := directSecret["secret_reference"].(map[string]any)
-	if !refPresent {
-		t.Fatalf("secret reference was absent: %#v", directSecret)
-	}
-	if outcome.Kind != commandkit.OutcomeSuccess || secretRef["name"] != "EXPLAIN_TEST_SECRET" || strings.Contains(directSecretText, secretValue) {
-		t.Fatalf("direct secret reference outcome=%#v report=%#v", outcome, directSecret)
-	}
-	root, outcome, _ := runYAML("")
-	if outcome.Kind != commandkit.OutcomeSuccess || root["path"] != "" {
-		t.Fatalf("root path outcome=%#v report=%#v", outcome, root)
-	}
-
-	loadsBeforeInvalid, contextsBeforeInvalid := loads, contexts
-	outcome = app.Execute(context.Background(), []string{"config", "explain"}, commandkit.Streams{Out: io.Discard, Err: io.Discard})
-	if outcome.Kind != commandkit.OutcomeUsage || loads != loadsBeforeInvalid || contexts != contextsBeforeInvalid {
-		t.Fatalf("missing path outcome=%#v loads=%d contexts=%d", outcome, loads, contexts)
-	}
-	outcome = app.Execute(context.Background(), []string{"config", "explain", "--path", "/bad~2path"}, commandkit.Streams{Out: io.Discard, Err: io.Discard})
-	if outcome.Kind != commandkit.OutcomeUsage || outcome.Status != 2 || loads != loadsBeforeInvalid || contexts != contextsBeforeInvalid {
-		t.Fatalf("malformed path outcome=%#v loads=%d contexts=%d", outcome, loads, contexts)
-	}
-	outcome = app.Execute(context.Background(), []string{"config", "explain", "--path", "/does-not-exist"}, commandkit.Streams{Out: io.Discard, Err: io.Discard})
-	if outcome.Kind != commandkit.OutcomeOperational || outcome.Status != 1 {
-		t.Fatalf("unknown path outcome = %#v", outcome)
-	}
-	partial := &configKitShowPartialWriter{failure: io.ErrClosedPipe}
-	outcome = app.Execute(context.Background(), []string{"config", "explain", "--path", path}, commandkit.Streams{Out: partial, Err: io.Discard})
-	if outcome.Kind != commandkit.OutcomeOperational || !outcome.ReportIncomplete || !errors.Is(outcome.DeliveryError, io.ErrClosedPipe) {
-		t.Fatalf("explanation writer failure = %#v", outcome)
-	}
-}
-
-func (reader *capturedSourceReader) Sources() []configkit.SourceInfo {
-	reader.calls++
-	return reader.entries
-}
-
-func TestConfigSourcesReportsCapturedConfigKitSourceInventory(t *testing.T) {
-	type configuration struct {
-		Value     string `yaml:"value"`
-		Shared    string `yaml:"shared"`
-		Synthetic string `yaml:"synthetic"`
-	}
-	filesystem := configkit.NewFilesystem("fixture", fstest.MapFS{
-		"root/config/main.yml":  &fstest.MapFile{Data: []byte("configkit: {imports: [{path: ../shared.yml}]}\nvalue: base\n")},
-		"root/shared.yml":       &fstest.MapFile{Data: []byte("shared: imported\n")},
-		"root/overlays/dev.yml": &fstest.MapFile{Data: []byte("value: overlay\n")},
-	})
-	filesystemContext := &configkit.FilesystemContext{Root: "root", FS: &filesystem}
-	overlayFilesystemContext := &configkit.FilesystemContext{Root: "root", BaseDir: "root/config", FS: &filesystem}
-	loaderCalls := 0
-	reader := &capturedSourceReader{}
-	scope, err := commandkit.NewConfigKitScope[struct{}, configuration]("app", "", func(context.Context, commandkit.Selection, struct{}) (*configkit.Result[configuration], error) {
-		loaderCalls++
-		result, err := configkit.LoadLayered(configkit.Input{
-			Source:     filesystem.File("root/config/main.yml"),
-			Imports:    true,
-			Filesystem: filesystemContext,
-		}, configkit.LayeredOptions[configuration]{
-			Definition:        configkit.Definition[configuration]{},
-			Underlays:         []configkit.Underlay{{Inputs: []configkit.Input{{Source: configkit.Mapping("synthetic source", map[string]any{"synthetic": "underlay"})}}}},
-			Overlay:           "dev",
-			OverlayFilesystem: overlayFilesystemContext,
-		})
-		if err != nil {
-			return nil, err
-		}
-		reader.entries = result.Sources()
-		return result, nil
-	})
-	if err != nil {
-		t.Fatal(err)
-	}
-	// Replace the result's reader after the owning loader has captured its source inventory.
-	originalAcquire := scope.Acquire
-	scope.Acquire = func(ctx context.Context, request commandkit.ConfigRequest, input struct{}) (commandkit.Acquired[commandkit.ConfigView], error) {
-		acquired, err := originalAcquire(ctx, request, input)
-		if err == nil {
-			acquired.Value.Sources = reader
-		}
-		return acquired, err
-	}
-	// Register the wrapped scope so the command reads the captured public facet once.
-	app, _ := commandkit.New(commandkit.Identity{Name: "example"})
-	if err := commandkit.RegisterConfig(app, commandkit.ConfigSuite[struct{}]{Scopes: []commandkit.ConfigScope[struct{}]{scope}}); err != nil {
-		t.Fatal(err)
-	}
-	var output bytes.Buffer
-	outcome := app.Execute(context.Background(), []string{"config", "sources", "--format", "yaml"}, commandkit.Streams{Out: &output, Err: io.Discard})
-	if outcome.Kind != commandkit.OutcomeSuccess || loaderCalls != 1 || reader.calls != 1 {
-		var details bytes.Buffer
-		for _, diagnostic := range outcome.Diagnostics {
-			_ = diagnostic.Write(&details)
-		}
-		t.Fatalf("sources outcome=%#v cause=%v details=%q loader calls=%d reader calls=%d", outcome, outcome.Cause, details.String(), loaderCalls, reader.calls)
-	}
-	var report struct {
-		Scope   string `yaml:"scope"`
-		Sources []struct {
-			ID            string `yaml:"id"`
-			Label         string `yaml:"label"`
-			Path          string `yaml:"path"`
-			Layer         string `yaml:"layer"`
-			Kind          string `yaml:"kind"`
-			UnderlayIndex int    `yaml:"underlay_index"`
-			ImportedFrom  *struct {
-				SourceID string `yaml:"source_id"`
-				Line     int    `yaml:"line"`
-				Column   int    `yaml:"column"`
-			} `yaml:"imported_from"`
-		} `yaml:"sources"`
-	}
-	if err := yaml.Unmarshal(output.Bytes(), &report); err != nil {
-		t.Fatal(err)
-	}
-	if report.Scope != "app" || len(report.Sources) != 4 {
-		t.Fatalf("source report = %#v", report)
-	}
-	if report.Sources[0].Path != "root/config/main.yml" || report.Sources[0].ID != "source-1" {
-		t.Fatalf("main source = %#v", report.Sources[0])
-	}
-	if report.Sources[0].ImportedFrom != nil {
-		t.Fatalf("root source imported_from = %#v, want null", report.Sources[0].ImportedFrom)
-	}
-	imported := report.Sources[1]
-	if imported.Path != "root/shared.yml" || imported.ImportedFrom == nil || imported.ImportedFrom.SourceID != report.Sources[0].ID || imported.ImportedFrom.Line == 0 {
-		t.Fatalf("import source correlation = %#v", imported)
-	}
-	synthetic := report.Sources[2]
-	if synthetic.Kind != string(configkit.SourceKindMapping) || synthetic.Path != "" || synthetic.Layer != string(configkit.LayerUnderlay) || synthetic.UnderlayIndex != 1 {
-		t.Fatalf("synthetic underlay source = %#v", synthetic)
-	}
-	if report.Sources[3].Layer != string(configkit.LayerOverlay) || report.Sources[3].Path != "root/overlays/dev.yml" {
-		t.Fatalf("overlay source = %#v", report.Sources[3])
-	}
-}
-
-func TestConfigSourcesHandlesEmptyInventoryAllPreflightAndWriterFailure(t *testing.T) {
-	reader := &capturedSourceReader{}
-	newContextCalls, acquireCalls := 0, 0
-	app, err := commandkit.New(commandkit.Identity{Name: "example"})
-	if err != nil {
-		t.Fatal(err)
-	}
-	suite := commandkit.ConfigSuite[string]{
-		NewContext: func() string { newContextCalls++; return "context" },
-		Scopes: []commandkit.ConfigScope[string]{{Name: "app", Operations: []commandkit.ConfigOperation{commandkit.ConfigSources}, Acquire: func(context.Context, commandkit.ConfigRequest, string) (commandkit.Acquired[commandkit.ConfigView], error) {
-			acquireCalls++
-			return commandkit.Acquired[commandkit.ConfigView]{Value: commandkit.ConfigView{Sources: reader}}, nil
-		}}},
-	}
-	if err := commandkit.RegisterConfig(app, suite); err != nil {
-		t.Fatal(err)
-	}
-	var output bytes.Buffer
-	outcome := app.Execute(context.Background(), []string{"config", "sources", "--scope", "all"}, commandkit.Streams{Out: &output, Err: io.Discard})
-	if outcome.Kind != commandkit.OutcomeUsage || newContextCalls != 0 || acquireCalls != 0 || output.Len() != 0 {
-		t.Fatalf("all preflight outcome=%#v contexts=%d acquires=%d output=%q", outcome, newContextCalls, acquireCalls, output.String())
-	}
-	outcome = app.Execute(context.Background(), []string{"config", "sources", "--format", "yaml"}, commandkit.Streams{Out: &output, Err: io.Discard})
-	if outcome.Kind != commandkit.OutcomeSuccess || output.String() != "scope: app\nsources: []\n" || reader.calls != 1 {
-		t.Fatalf("empty source report outcome=%#v output=%q reader calls=%d", outcome, output.String(), reader.calls)
-	}
-	reader.entries = []configkit.SourceInfo{{ID: "source-1", Label: "label with \"quotes\"", Path: "path with spaces.yml", Layer: configkit.LayerBase, Kind: configkit.SourceKindFile}}
-	var textOutput bytes.Buffer
-	outcome = app.Execute(context.Background(), []string{"config", "sources"}, commandkit.Streams{Out: &textOutput, Err: io.Discard})
-	if outcome.Kind != commandkit.OutcomeSuccess || !strings.Contains(textOutput.String(), `label: "label with \"quotes\""`) || !strings.Contains(textOutput.String(), `path: "path with spaces.yml"`) {
-		t.Fatalf("quoted text source output outcome=%#v output=%q", outcome, textOutput.String())
-	}
-	partial := &configKitShowPartialWriter{failure: io.ErrClosedPipe}
-	outcome = app.Execute(context.Background(), []string{"config", "sources"}, commandkit.Streams{Out: partial, Err: io.Discard})
-	if outcome.Kind != commandkit.OutcomeOperational || !outcome.ReportIncomplete || !errors.Is(outcome.DeliveryError, io.ErrClosedPipe) {
-		t.Fatalf("source writer failure = %#v", outcome)
-	}
-}
-
-func TestConfigShowWritesNativeSingleScopeAndFramesAggregateYAML(t *testing.T) {
-	const native = "%YAML 1.1\n# authored comment\n---\nvalue: null\nitems: []\nmissing: {}\n"
-	app, err := commandkit.New(commandkit.Identity{Name: "example"})
-	if err != nil {
-		t.Fatal(err)
-	}
-	var calls []string
-	suite := commandkit.ConfigSuite[struct{}]{Scopes: []commandkit.ConfigScope[struct{}]{
-		{Name: "zeta", Operations: []commandkit.ConfigOperation{commandkit.ConfigShow}, Acquire: func(context.Context, commandkit.ConfigRequest, struct{}) (commandkit.Acquired[commandkit.ConfigView], error) {
-			calls = append(calls, "zeta")
-			return commandkit.Acquired[commandkit.ConfigView]{Value: commandkit.ConfigView{Effective: effectiveYAML("%YAML 1.1\n# zeta comment\nvalue: zeta\n")}}, nil
-		}},
-		{Name: "app", Operations: []commandkit.ConfigOperation{commandkit.ConfigShow}, Acquire: func(context.Context, commandkit.ConfigRequest, struct{}) (commandkit.Acquired[commandkit.ConfigView], error) {
-			calls = append(calls, "app")
-			return commandkit.Acquired[commandkit.ConfigView]{Value: commandkit.ConfigView{Effective: effectiveYAML(native)}}, nil
-		}},
-	}}
-	if err := commandkit.RegisterConfig(app, suite); err != nil {
-		t.Fatal(err)
-	}
-	var single bytes.Buffer
-	outcome := app.Execute(context.Background(), []string{"config", "show"}, commandkit.Streams{Out: &single, Err: io.Discard})
-	if outcome.Kind != commandkit.OutcomeSuccess || single.String() != native {
-		t.Fatalf("single show outcome=%#v output=%q", outcome, single.String())
-	}
-	calls = nil
-	outcome = app.Execute(context.Background(), []string{"config", "show", "--format", "text"}, commandkit.Streams{Out: &single, Err: io.Discard})
-	if outcome.Kind != commandkit.OutcomeUsage || len(calls) != 0 {
-		t.Fatalf("text format outcome=%#v acquisitions=%v", outcome, calls)
-	}
-
-	calls = nil
-	var aggregate bytes.Buffer
-	outcome = app.Execute(context.Background(), []string{"config", "show", "--scope", "all"}, commandkit.Streams{Out: &aggregate, Err: io.Discard})
-	if outcome.Kind != commandkit.OutcomeSuccess || !reflect.DeepEqual(calls, []string{"app", "zeta"}) {
-		t.Fatalf("aggregate outcome=%#v acquisitions=%v", outcome, calls)
-	}
-	if !strings.Contains(aggregate.String(), "%YAML 1.1\n# authored comment\n---\n# scope: app\n") || !strings.Contains(aggregate.String(), "...\n%YAML 1.1\n# zeta comment\n---\n# scope: zeta\nvalue: zeta\n") {
-		t.Fatalf("aggregate framing = %q", aggregate.String())
-	}
-	decoder := yaml.NewDecoder(bytes.NewReader(aggregate.Bytes()))
-	var first, second map[string]any
-	if err := decoder.Decode(&first); err != nil {
-		t.Fatal(err)
-	}
-	if err := decoder.Decode(&second); err != nil {
-		t.Fatal(err)
-	}
-	var extra any
-	if err := decoder.Decode(&extra); err != io.EOF {
-		t.Fatalf("third YAML document decode error = %v, value=%#v", err, extra)
-	}
-	if first["value"] != nil || first["items"] == nil || first["missing"] == nil || second["value"] != "zeta" {
-		t.Fatalf("decoded documents = %#v and %#v", first, second)
-	}
-	if _, exists := first["absent"]; exists {
-		t.Fatalf("absent field was added to native document: %#v", first)
-	}
-}
-
-func TestConfigShowAcquiresAllBeforeOutputAndTracksWriterFailures(t *testing.T) {
-	failure := errors.New("second scope failed")
-	app, err := commandkit.New(commandkit.Identity{Name: "example"})
-	if err != nil {
-		t.Fatal(err)
-	}
-	calls := 0
-	suite := commandkit.ConfigSuite[struct{}]{Scopes: []commandkit.ConfigScope[struct{}]{
-		{Name: "app", Operations: []commandkit.ConfigOperation{commandkit.ConfigShow}, Acquire: func(context.Context, commandkit.ConfigRequest, struct{}) (commandkit.Acquired[commandkit.ConfigView], error) {
-			calls++
-			return commandkit.Acquired[commandkit.ConfigView]{Value: commandkit.ConfigView{Effective: effectiveYAML("value: app\n")}}, nil
-		}},
-		{Name: "promptkit", Operations: []commandkit.ConfigOperation{commandkit.ConfigShow}, Acquire: func(context.Context, commandkit.ConfigRequest, struct{}) (commandkit.Acquired[commandkit.ConfigView], error) {
-			calls++
-			return commandkit.Acquired[commandkit.ConfigView]{Diagnostics: []commandkit.Diagnostic{commandkit.MessageDiagnostic(configkit.SeverityWarning, "provider warning")}}, failure
-		}},
-	}}
-	if err := commandkit.RegisterConfig(app, suite); err != nil {
-		t.Fatal(err)
-	}
-	var output bytes.Buffer
-	outcome := app.Execute(context.Background(), []string{"config", "show", "--scope", "all"}, commandkit.Streams{Out: &output, Err: io.Discard})
-	if !errors.Is(outcome.Cause, failure) || outcome.ReportIncomplete || output.Len() != 0 || calls != 2 || len(outcome.Diagnostics) < 1 || outcome.Diagnostics[0].Severity != configkit.SeverityWarning {
-		t.Fatalf("acquisition failure outcome=%#v output=%q calls=%d", outcome, output.String(), calls)
-	}
-
-	app, _ = commandkit.New(commandkit.Identity{Name: "example"})
-	if err := commandkit.RegisterConfig(app, commandkit.ConfigSuite[struct{}]{Scopes: []commandkit.ConfigScope[struct{}]{{Name: "app", Operations: []commandkit.ConfigOperation{commandkit.ConfigShow}, Acquire: func(context.Context, commandkit.ConfigRequest, struct{}) (commandkit.Acquired[commandkit.ConfigView], error) {
-		return commandkit.Acquired[commandkit.ConfigView]{Value: commandkit.ConfigView{Effective: effectiveYAML("value: app\n")}}, nil
-	}}}}); err != nil {
-		t.Fatal(err)
-	}
-	partial := &configKitShowPartialWriter{failure: io.ErrClosedPipe}
-	outcome = app.Execute(context.Background(), []string{"config", "show", "--scope", "all"}, commandkit.Streams{Out: partial, Err: io.Discard})
-	if outcome.Kind != commandkit.OutcomeOperational || !outcome.ReportIncomplete || !errors.Is(outcome.Cause, io.ErrClosedPipe) || !errors.Is(outcome.DeliveryError, io.ErrClosedPipe) || len(partial.written) == 0 {
-		t.Fatalf("writer failure outcome = %#v", outcome)
-	}
-}
-
-type configKitShowPartialWriter struct {
-	written []byte
-	failure error
-}
-
-func (writer *configKitShowPartialWriter) Write(data []byte) (int, error) {
-	n := len(data)
-	if n > 4 {
-		n = 4
-	}
-	writer.written = append(writer.written, data[:n]...)
-	return n, writer.failure
-}
-
-func TestConfigKitScopeUsesDefaultsOverlayAndRecordedResolution(t *testing.T) {
-	type configuration struct {
-		Mode      string `yaml:"mode"`
-		Defaulted string `yaml:"defaulted"`
-	}
-	filesystem := configkit.NewFilesystem("fixture", fstest.MapFS{
-		"config/main.yml":         &fstest.MapFile{Data: []byte("mode: base\n")},
-		"config/overlays/dev.yml": &fstest.MapFile{Data: []byte("mode: overlay\n")},
-	})
-	definition := configkit.Definition[configuration]{
-		Defaults: func() configuration { return configuration{Defaulted: "from default"} },
-		Resolve: func(input *configuration, resolution *configkit.Resolution) error {
-			resolution.Record(configkit.Keys("mode"), configkit.ChangeNormalization, "normalized for use")
-			input.Mode = strings.ToUpper(input.Mode)
-			return nil
-		},
-	}
-	var received commandkit.Selection
-	scope, err := commandkit.NewConfigKitScope[struct{}, configuration]("app", "Application settings.", func(_ context.Context, selection commandkit.Selection, _ struct{}) (*configkit.Result[configuration], error) {
-		received = selection
-		return configkit.LoadLayered(configkit.Input{Source: filesystem.File(selection.Config.Value)}, configkit.LayeredOptions[configuration]{
-			Definition:        definition,
-			Overlay:           selection.Overlay.Value,
-			OverlayFilesystem: &configkit.FilesystemContext{Root: "config", BaseDir: "config", FS: &filesystem},
-		})
-	})
-	if err != nil {
-		t.Fatal(err)
-	}
-	selection := commandkit.Selection{
-		Config:  commandkit.Supplied[string]{Value: "config/main.yml", Set: true},
-		Overlay: commandkit.Supplied[string]{Value: "dev", Set: true},
-	}
-	acquired, err := scope.Acquire(context.Background(), commandkit.ConfigRequest{Operation: commandkit.ConfigValidate, Selection: selection}, struct{}{})
-	if err != nil {
-		t.Fatal(err)
-	}
-	if !reflect.DeepEqual(received, selection) {
-		t.Fatalf("loader selection = %#v, want %#v", received, selection)
-	}
-	if acquired.Value.Effective == nil || acquired.Value.Sources == nil || acquired.Value.Explanation == nil {
-		t.Fatalf("ConfigKit result facets = %#v", acquired.Value)
-	}
-	if got := acquired.Value.Sources.Sources(); len(got) < 2 {
-		t.Fatalf("sources = %#v, want base and overlay", got)
-	}
-	var effective bytes.Buffer
-	if err := acquired.Value.Effective.WriteEffective(&effective); err != nil {
-		t.Fatal(err)
-	}
-	if !strings.Contains(effective.String(), "mode: OVERLAY") || !strings.Contains(effective.String(), "defaulted: from default") {
-		t.Fatalf("effective configuration = %q", effective.String())
-	}
-	if explanation, ok := acquired.Value.Explanation.Explain(configkit.Keys("mode")); !ok || len(explanation.History) == 0 {
-		t.Fatalf("resolution explanation = %#v, present=%t", explanation, ok)
-	}
-}
-
-func TestConfigKitScopePreservesAbsentAndEmptySelections(t *testing.T) {
-	type configuration struct {
-		Value string `yaml:"value"`
-	}
-	var seen []commandkit.Selection
-	scope, err := commandkit.NewConfigKitScope[struct{}, configuration]("app", "", func(_ context.Context, selection commandkit.Selection, _ struct{}) (*configkit.Result[configuration], error) {
-		seen = append(seen, selection)
-		return configkit.Load(configkit.NoSource(), configkit.Options[configuration]{Definition: configkit.Definition[configuration]{Defaults: func() configuration { return configuration{Value: "default"} }}})
-	})
-	if err != nil {
-		t.Fatal(err)
-	}
-	_, err = scope.Acquire(context.Background(), commandkit.ConfigRequest{}, struct{}{})
-	if err != nil {
-		t.Fatal(err)
-	}
-	empty := commandkit.Selection{Config: commandkit.Supplied[string]{Set: true}, Overlay: commandkit.Supplied[string]{Set: true}}
-	_, err = scope.Acquire(context.Background(), commandkit.ConfigRequest{Selection: empty}, struct{}{})
-	if err != nil {
-		t.Fatal(err)
-	}
-	want := []commandkit.Selection{{}, empty}
-	if !reflect.DeepEqual(seen, want) {
-		t.Fatalf("loader selections = %#v, want %#v", seen, want)
-	}
-}
-
-func TestConfigKitScopeRequiresLoaderAndNonNilResult(t *testing.T) {
-	if _, err := commandkit.NewConfigKitScope[struct{}, struct{}]("app", "", nil); err == nil {
-		t.Fatal("accepted a nil ConfigKit loader")
-	}
-	scope, err := commandkit.NewConfigKitScope[struct{}, struct{}]("app", "", func(context.Context, commandkit.Selection, struct{}) (*configkit.Result[struct{}], error) {
-		return nil, nil
-	})
-	if err != nil {
-		t.Fatal(err)
-	}
-	if _, err := scope.Acquire(context.Background(), commandkit.ConfigRequest{}, struct{}{}); err == nil || !strings.Contains(err.Error(), "nil result") {
-		t.Fatalf("nil result error = %v", err)
-	}
-}
-
-func TestConfigKitLoadErrorRetainsIdentityAndStructuredDiagnostics(t *testing.T) {
-	type configuration struct {
-		Name string `yaml:"name"`
-	}
-	var loadError error
-	scope, err := commandkit.NewConfigKitScope[struct{}, configuration]("app", "", func(context.Context, commandkit.Selection, struct{}) (*configkit.Result[configuration], error) {
-		_, loadError = configkit.Load(configkit.Mapping("bad source", map[string]any{"unknown": true}), configkit.Options[configuration]{Definition: configkit.Definition[configuration]{}})
-		return nil, loadError
-	})
-	if err != nil {
-		t.Fatal(err)
-	}
-	acquired, acquireError := scope.Acquire(context.Background(), commandkit.ConfigRequest{}, struct{}{})
-	var publicLoadError *configkit.LoadError
-	if acquireError != loadError || !errors.As(acquireError, &publicLoadError) {
-		t.Fatalf("load error identity = %v (original %v), public type=%T", acquireError, loadError, acquireError)
-	}
-	if len(acquired.Diagnostics) != 1 || acquired.Diagnostics[0].Severity != configkit.SeverityError {
-		t.Fatalf("structured diagnostics = %#v", acquired.Diagnostics)
-	}
-	var rendered bytes.Buffer
-	if err := acquired.Diagnostics[0].Write(&rendered); err != nil {
-		t.Fatal(err)
-	}
-	if !strings.Contains(rendered.String(), `Configuration scope "app":`) || !strings.Contains(rendered.String(), `"bad source"`) {
-		t.Fatalf("grouped diagnostics = %q", rendered.String())
-	}
-
-	app, _ := commandkit.New(commandkit.Identity{Name: "example"})
-	if err := commandkit.RegisterConfig(app, commandkit.ConfigSuite[struct{}]{Scopes: []commandkit.ConfigScope[struct{}]{scope}}); err != nil {
-		t.Fatal(err)
-	}
-	var output, diagnostic bytes.Buffer
-	outcome := app.Execute(context.Background(), []string{"config", "validate"}, commandkit.Streams{Out: &output, Err: &diagnostic})
-	if outcome.Cause != loadError || len(outcome.Diagnostics) != 1 || strings.Count(diagnostic.String(), `Configuration scope "app":`) != 1 || output.Len() != 0 {
-		t.Fatalf("presented load failure outcome=%#v output=%q diagnostics=%q", outcome, output.String(), diagnostic.String())
-	}
-}
-
-func TestConfigValidationEmitsSuccessAsScopesCompleteAndStopsAtFailure(t *testing.T) {
-	app, err := commandkit.New(commandkit.Identity{Name: "example"})
-	if err != nil {
-		t.Fatal(err)
-	}
-	var calls []string
-	newContextCalls := 0
-	failure := errors.New("promptkit could not load")
-	suite := commandkit.ConfigSuite[string]{
-		NewContext: func() string { newContextCalls++; return "runtime" },
-		Scopes: []commandkit.ConfigScope[string]{
-			{Name: "zeta", Operations: []commandkit.ConfigOperation{commandkit.ConfigValidate}, Acquire: func(context.Context, commandkit.ConfigRequest, string) (commandkit.Acquired[commandkit.ConfigView], error) {
-				calls = append(calls, "zeta")
-				return commandkit.Acquired[commandkit.ConfigView]{}, nil
-			}},
-			{Name: "promptkit", Operations: []commandkit.ConfigOperation{commandkit.ConfigValidate}, Acquire: func(context.Context, commandkit.ConfigRequest, string) (commandkit.Acquired[commandkit.ConfigView], error) {
-				calls = append(calls, "promptkit")
-				return commandkit.Acquired[commandkit.ConfigView]{}, failure
-			}},
-			{Name: "app", Operations: []commandkit.ConfigOperation{commandkit.ConfigValidate}, Acquire: func(context.Context, commandkit.ConfigRequest, string) (commandkit.Acquired[commandkit.ConfigView], error) {
-				calls = append(calls, "app")
-				return commandkit.Acquired[commandkit.ConfigView]{}, nil
-			}},
-		},
-	}
-	if err := commandkit.RegisterConfig(app, suite); err != nil {
-		t.Fatal(err)
-	}
-	var output, diagnostic bytes.Buffer
-	outcome := app.Execute(context.Background(), []string{"config", "validate", "--scope", "all"}, commandkit.Streams{Out: &output, Err: &diagnostic})
-	if outcome.Kind != commandkit.OutcomeOperational || !errors.Is(outcome.Cause, failure) || !outcome.ReportIncomplete {
-		t.Fatalf("validation outcome = %#v", outcome)
-	}
-	if !reflect.DeepEqual(calls, []string{"app", "promptkit"}) || newContextCalls != 1 {
-		t.Fatalf("acquisitions = %v, NewContext calls=%d", calls, newContextCalls)
-	}
-	if output.String() != "app: valid\n" || !strings.Contains(diagnostic.String(), failure.Error()) {
-		t.Fatalf("output=%q diagnostics=%q", output.String(), diagnostic.String())
-	}
-}
-
-func TestConfigValidationYAMLWarningsAndShortWrites(t *testing.T) {
-	type configuration struct {
-		Name string `yaml:"name"`
-	}
-	warningScope, err := commandkit.NewConfigKitScope[struct{}, configuration]("app", "", func(context.Context, commandkit.Selection, struct{}) (*configkit.Result[configuration], error) {
-		return configkit.Load(configkit.NoSource(), configkit.Options[configuration]{Definition: configkit.Definition[configuration]{
-			Validate: func(_ *configuration, validation *configkit.Validation) {
-				validation.Warning(configkit.Keys("name"), "uses a demonstration name")
-			},
-		}})
-	})
-	if err != nil {
-		t.Fatal(err)
-	}
-	app, _ := commandkit.New(commandkit.Identity{Name: "example"})
-	if err := commandkit.RegisterConfig(app, commandkit.ConfigSuite[struct{}]{Scopes: []commandkit.ConfigScope[struct{}]{warningScope}}); err != nil {
-		t.Fatal(err)
-	}
-	var output, diagnostic bytes.Buffer
-	outcome := app.Execute(context.Background(), []string{"config", "validate", "--format", "yaml"}, commandkit.Streams{Out: &output, Err: &diagnostic})
-	if outcome.Kind != commandkit.OutcomeSuccess || outcome.Status != 0 || outcome.DiagnosticDelivery != commandkit.DeliveryComplete {
-		t.Fatalf("warning validation outcome = %#v", outcome)
-	}
-	if output.String() != "scopes:\n  - name: app\n    valid: true\n" || !strings.Contains(diagnostic.String(), "uses a demonstration name") {
-		t.Fatalf("output=%q diagnostics=%q", output.String(), diagnostic.String())
-	}
-
-	outcome = app.Execute(context.Background(), []string{"config", "validate"}, commandkit.Streams{Out: configKitPartialWriter{}, Err: io.Discard})
-	if outcome.Kind != commandkit.OutcomeOperational || !outcome.ReportIncomplete || !errors.Is(outcome.Cause, io.ErrShortWrite) || !errors.Is(outcome.DeliveryError, io.ErrShortWrite) {
-		t.Fatalf("report short write outcome = %#v", outcome)
-	}
-	var delivered bytes.Buffer
-	outcome = app.Execute(context.Background(), []string{"config", "validate"}, commandkit.Streams{Out: &delivered, Err: configKitPartialWriter{}})
-	if outcome.DiagnosticDelivery != commandkit.DeliveryIncomplete || !errors.Is(outcome.DeliveryError, io.ErrShortWrite) {
-		t.Fatalf("diagnostic short write outcome = %#v", outcome)
-	}
-}
-
-type configKitPartialWriter struct{}
-
-func (configKitPartialWriter) Write(data []byte) (int, error) {
-	if len(data) == 0 {
-		return 0, nil
-	}
-	return len(data) - 1, nil
-}
-
-func TestValidationReportDeliveryErrorsAtEachWriteBoundary(t *testing.T) {
-	reportErr := errors.New("report failed")
-	diagnosticErr := errors.New("diagnostic failed")
-	app, _ := commandkit.New(commandkit.Identity{Name: "example"})
-	acquire := func(context.Context, commandkit.ConfigRequest, struct{}) (commandkit.Acquired[commandkit.ConfigView], error) {
-		return commandkit.Acquired[commandkit.ConfigView]{}, nil
-	}
-	if err := commandkit.RegisterConfig(app, commandkit.ConfigSuite[struct{}]{Scopes: []commandkit.ConfigScope[struct{}]{
-		{Name: "app", Operations: []commandkit.ConfigOperation{commandkit.ConfigValidate}, Acquire: acquire},
-		{Name: "promptkit", Operations: []commandkit.ConfigOperation{commandkit.ConfigValidate}, Acquire: acquire},
-	}}); err != nil {
-		t.Fatal(err)
-	}
-	for _, format := range []string{"text", "yaml"} {
-		writes := 2
-		if format == "yaml" {
-			writes = 3
-		}
-		for at := 1; at <= writes; at++ {
-			for _, brokenErr := range []bool{false, true} {
-				out := &validationBoundaryWriter{failAt: at, err: reportErr}
-				errStream := io.Writer(io.Discard)
-				if brokenErr {
-					errStream = failingWriter{diagnosticErr}
-				}
-				result := app.Execute(context.Background(), []string{"config", "validate", "--scope", "all", "--format", format}, commandkit.Streams{Out: out, Err: errStream})
-				if result.Kind != commandkit.OutcomeOperational || !result.ReportIncomplete || !errors.Is(result.Cause, reportErr) || !errors.Is(result.DeliveryError, reportErr) || (brokenErr && !errors.Is(result.DeliveryError, diagnosticErr)) {
-					t.Fatalf("format=%s at=%d brokenErr=%t result=%#v", format, at, brokenErr, result)
-				}
-				if at > 1 && out.written.Len() == 0 {
-					t.Fatal("lost completed prefix")
-				}
-			}
-		}
-	}
-	failedApp, _ := commandkit.New(commandkit.Identity{Name: "example"})
-	if err := commandkit.RegisterConfig(failedApp, commandkit.ConfigSuite[struct{}]{Scopes: []commandkit.ConfigScope[struct{}]{{Name: "app", Operations: []commandkit.ConfigOperation{commandkit.ConfigValidate}, Acquire: func(context.Context, commandkit.ConfigRequest, struct{}) (commandkit.Acquired[commandkit.ConfigView], error) {
-		return commandkit.Acquired[commandkit.ConfigView]{}, reportErr
-	}}}}); err != nil {
-		t.Fatal(err)
-	}
-	result := failedApp.Execute(context.Background(), []string{"config", "validate"}, commandkit.Streams{})
-	if !errors.Is(result.Cause, reportErr) || result.DeliveryError != nil {
-		t.Fatalf("acquisition failure=%#v", result)
-	}
-}
-
-type validationBoundaryWriter struct {
-	failAt, calls int
-	err           error
-	written       bytes.Buffer
-}
-
-func (w *validationBoundaryWriter) Write(p []byte) (int, error) {
-	w.calls++
-	if w.calls == w.failAt {
-		return 0, w.err
-	}
-	return w.written.Write(p)
-}

debug_events_test.go

@@ -0,0 +1,118 @@
+package commandkit
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"strings"
+	"testing"
+)
+
+func TestDebugEventsFollowModeAndFinalizationOrder(t *testing.T) {
+	cause := errors.New("private operation cause")
+	command := NewCommand(CommandSpec[struct{}]{
+		Name: "run",
+		Run: func(inv Invocation, _ struct{}) Outcome {
+			if err := inv.Reporter().AtEnd().Info("deferred summary"); err != nil {
+				t.Errorf("queue summary: %v", err)
+			}
+			return Failure("operation failed").WithCause(cause)
+		},
+	})
+	app, err := New(Identity{Name: "Example"}, command, Alias("shortcut", "run"), FlagAlias("--trace", "--debug"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	var diagnostics bytes.Buffer
+	outcome := app.Execute(context.Background(), []string{"shortcut", "--verbose", "--trace"}, Streams{Err: &diagnostics})
+	if outcome.Kind != OutcomeOperational || !errors.Is(outcome.Cause, cause) {
+		t.Fatalf("outcome = %#v", outcome)
+	}
+	got := diagnostics.String()
+	for _, fragment := range []string{
+		"resolved command alias \"shortcut\" to \"run\"",
+		"selected debug reporting mode using --trace (alias for --debug)",
+		"deferred summary",
+		"handler completed for \"run\" with operational outcome and status 1",
+		"ERROR: operation failed",
+	} {
+		if !strings.Contains(got, fragment) {
+			t.Errorf("diagnostics %q omit %q", got, fragment)
+		}
+	}
+	if strings.Contains(got, cause.Error()) {
+		t.Fatalf("diagnostics exposed the operation cause: %q", got)
+	}
+	ordered := []string{
+		"resolved command alias",
+		"selected debug reporting mode",
+		"deferred summary",
+		"handler completed",
+		"ERROR: operation failed",
+	}
+	previous := -1
+	for _, fragment := range ordered {
+		index := strings.Index(got, fragment)
+		if index <= previous {
+			t.Fatalf("diagnostic event %q out of order in %q", fragment, got)
+		}
+		previous = index
+	}
+}
+
+func TestDebugEventsRespectFinalQuietSelection(t *testing.T) {
+	command := NewCommand(CommandSpec[struct{}]{
+		Name: "run",
+		Run:  func(Invocation, struct{}) Outcome { return Success() },
+	})
+	app, err := New(Identity{Name: "Example"}, command)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var diagnostics bytes.Buffer
+	outcome := app.Execute(context.Background(), []string{"run", "--debug", "--quiet"}, Streams{Err: &diagnostics})
+	if outcome.Kind != OutcomeSuccess || diagnostics.Len() != 0 {
+		t.Fatalf("outcome = %#v, diagnostics = %q", outcome, diagnostics.String())
+	}
+}
+
+func TestDebugCompletionRequiresAHandler(t *testing.T) {
+	command := NewCommand(CommandSpec[struct{}]{
+		Name: "run",
+		Run:  func(Invocation, struct{}) Outcome { return Success() },
+	})
+	app, err := New(Identity{Name: "Example"}, command)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var diagnostics bytes.Buffer
+	app.Execute(context.Background(), []string{"unknown", "--debug"}, Streams{Err: &diagnostics})
+	if strings.Contains(diagnostics.String(), "handler completed") {
+		t.Fatalf("no-handler diagnostics include completion: %q", diagnostics.String())
+	}
+}
+
+func TestDebugDeliveryFailureAffectsInvocationOutcome(t *testing.T) {
+	ran := false
+	command := NewCommand(CommandSpec[struct{}]{
+		Name: "run",
+		Run: func(Invocation, struct{}) Outcome {
+			ran = true
+			return Success()
+		},
+	})
+	app, err := New(Identity{Name: "Example"}, command)
+	if err != nil {
+		t.Fatal(err)
+	}
+	writeErr := errors.New("debug destination failed")
+	outcome := app.Execute(context.Background(), []string{"run", "--debug"}, Streams{
+		Err: executeReportingFailureWriter{err: writeErr},
+	})
+	if !ran {
+		t.Fatal("debug delivery failure prevented handler execution")
+	}
+	if outcome.Kind != OutcomeOperational || outcome.Status != 1 || !errors.Is(outcome.Presentation.Diagnostics.WriteError, writeErr) {
+		t.Fatalf("outcome = %#v", outcome)
+	}
+}

declaration_external_test.go

@@ -0,0 +1,241 @@
+package commandkit_test
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"reflect"
+	"strings"
+	"testing"
+
+	commandkit "go.maximumdirect.net/commandkit"
+)
+
+func TestPublicInstallationAcceptsMixedDeclarations(t *testing.T) {
+	command := commandkit.NewCommand(commandkit.CommandSpec[struct{}]{
+		Name:    "show",
+		Summary: "Show a value.",
+		Flags: []commandkit.Flag[struct{}]{
+			commandkit.ValueFlag(commandkit.FlagMeta{Name: "format"}, (*string)(nil), func(value string) (string, error) { return value, nil }, func(*struct{}, commandkit.Supplied[string]) {}),
+		},
+		Run: func(commandkit.Invocation, struct{}) commandkit.Outcome { return commandkit.Success() },
+	})
+	declarations := []commandkit.Declaration{
+		command,
+		commandkit.Alias("inspect", "show"),
+		commandkit.FlagAlias("--fmt", "--format"),
+		commandkit.FlagAliasFor("show", "-f", "--format"),
+	}
+	app, err := commandkit.New(commandkit.Identity{Name: "Example"}, declarations...)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if app == nil {
+		t.Fatal("New() returned a nil app")
+	}
+}
+
+func TestPublicAliasesPreserveCommandsAcrossDeclarationOrders(t *testing.T) {
+	for _, test := range []struct {
+		name       string
+		rulesFirst bool
+	}{
+		{name: "commands first"},
+		{name: "routing rules first", rulesFirst: true},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			type runInput struct{ words commandkit.Supplied[[]string] }
+			type inspectInput struct{ id commandkit.Supplied[string] }
+			type showInput struct {
+				profile commandkit.Supplied[string]
+				format  commandkit.Supplied[string]
+			}
+			var runParses, inspectParses, optionalParses int
+			var runValues [][]string
+			var inspectValues []string
+			var showValues []string
+			run := commandkit.NewCommand(commandkit.CommandSpec[runInput]{
+				Name: "run",
+				Arguments: []commandkit.Argument[runInput]{commandkit.RepeatArgument(commandkit.ArgumentMeta{Name: "words"}, 0, -1,
+					func(value string) (string, error) { runParses++; return value, nil },
+					func(target *runInput, value commandkit.Supplied[[]string]) { target.words = value },
+				)},
+				Run: func(_ commandkit.Invocation, value runInput) commandkit.Outcome {
+					runValues = append(runValues, append([]string(nil), value.words.Value...))
+					return commandkit.Success()
+				},
+			})
+			inspect := commandkit.NewCommand(commandkit.CommandSpec[inspectInput]{
+				Name: "inspect",
+				Arguments: []commandkit.Argument[inspectInput]{commandkit.ValueArgument(commandkit.ArgumentMeta{Name: "id"}, true,
+					func(value string) (string, error) { inspectParses++; return value, nil },
+					func(target *inspectInput, value commandkit.Supplied[string]) { target.id = value },
+				)},
+				Run: func(_ commandkit.Invocation, value inspectInput) commandkit.Outcome {
+					inspectValues = append(inspectValues, value.id.Value)
+					return commandkit.Success()
+				},
+			})
+			show := commandkit.NewCommand(commandkit.CommandSpec[showInput]{
+				Name: "show",
+				Arguments: []commandkit.Argument[showInput]{commandkit.ValueArgument(commandkit.ArgumentMeta{Name: "profile"}, false,
+					func(value string) (string, error) { optionalParses++; return value, nil },
+					func(target *showInput, value commandkit.Supplied[string]) { target.profile = value },
+				)},
+				Flags: []commandkit.Flag[showInput]{commandkit.ValueFlag(commandkit.FlagMeta{Name: "format"}, (*string)(nil),
+					func(value string) (string, error) { return value, nil },
+					func(target *showInput, value commandkit.Supplied[string]) { target.format = value },
+				)},
+				Run: func(_ commandkit.Invocation, value showInput) commandkit.Outcome {
+					showValues = append(showValues, value.profile.Value+":"+value.format.Value)
+					return commandkit.Success()
+				},
+			})
+			commands := []commandkit.Declaration{run, inspect, show}
+			rules := []commandkit.Declaration{
+				commandkit.Alias("r", "run"),
+				commandkit.Alias("r full", "inspect"),
+				commandkit.Alias("inspect-shortcut", "inspect"),
+				commandkit.Alias("i", "inspect-shortcut"),
+				commandkit.FlagAlias("--fmt", "--format"),
+			}
+			declarations := append([]commandkit.Declaration(nil), commands...)
+			if test.rulesFirst {
+				declarations = append(append([]commandkit.Declaration(nil), rules...), commands...)
+			} else {
+				declarations = append(declarations, rules...)
+			}
+
+			app, err := commandkit.New(commandkit.Identity{Name: "Example"}, declarations...)
+			if err != nil {
+				t.Fatal(err)
+			}
+			if runParses != 0 || inspectParses != 0 || optionalParses != 0 {
+				t.Fatalf("installation invoked operand converters: %d/%d/%d", runParses, inspectParses, optionalParses)
+			}
+			for _, args := range [][]string{{"run", "full"}, {"r", "full", "item-1"}, {"i", "item-2"}, {"show", "profile", "--fmt=json"}} {
+				if outcome := app.Execute(context.Background(), args, commandkit.Streams{Out: io.Discard, Err: io.Discard}); outcome.Kind != commandkit.OutcomeSuccess {
+					t.Fatalf("Execute(%q) = %#v, want success", args, outcome)
+				}
+			}
+			if !reflect.DeepEqual(runValues, [][]string{{"full"}}) {
+				t.Fatalf("canonical run operands = %#v, want [[full]]", runValues)
+			}
+			if !reflect.DeepEqual(inspectValues, []string{"item-1", "item-2"}) {
+				t.Fatalf("routed required operands = %#v", inspectValues)
+			}
+			if !reflect.DeepEqual(showValues, []string{"profile:json"}) || optionalParses != 1 {
+				t.Fatalf("optional operand/flag values = %#v, converter calls %d", showValues, optionalParses)
+			}
+
+			parsesBeforeReuse := [3]int{runParses, inspectParses, optionalParses}
+			secondApp, err := commandkit.New(commandkit.Identity{Name: "Second"}, declarations...)
+			if err != nil {
+				t.Fatalf("reusing declarations: %v", err)
+			}
+			if got := [3]int{runParses, inspectParses, optionalParses}; got != parsesBeforeReuse {
+				t.Fatalf("reinstalling declarations invoked operand converters: %v -> %v", parsesBeforeReuse, got)
+			}
+			if outcome := secondApp.Execute(context.Background(), []string{"run", "again"}, commandkit.Streams{Out: io.Discard, Err: io.Discard}); outcome.Kind != commandkit.OutcomeSuccess {
+				t.Fatalf("reused declaration execution = %#v", outcome)
+			}
+			if !reflect.DeepEqual(runValues, [][]string{{"full"}, {"again"}}) {
+				t.Fatalf("reused command declaration values = %#v", runValues)
+			}
+		})
+	}
+}
+
+func TestPublicRootGroupRegistrationAndFailedBatchRecovery(t *testing.T) {
+	type showInput struct{ format commandkit.Supplied[string] }
+	var formatParses, lateRuns int
+	var formats []string
+	show := commandkit.NewCommand(commandkit.CommandSpec[showInput]{
+		Name: "show",
+		Flags: []commandkit.Flag[showInput]{commandkit.ValueFlag(commandkit.FlagMeta{Name: "format"}, (*string)(nil),
+			func(value string) (string, error) { formatParses++; return value, nil },
+			func(target *showInput, value commandkit.Supplied[string]) { target.format = value },
+		)},
+		Run: func(_ commandkit.Invocation, value showInput) commandkit.Outcome {
+			formats = append(formats, value.format.Value)
+			return commandkit.Success()
+		},
+	})
+	family := commandkit.RootGroup("config", "Configuration", show)
+	constructionFailure := errors.New("family construction failed")
+	if _, err := commandkit.New(commandkit.Identity{Name: "Broken"}, commandkit.WithError(family, fmt.Errorf("adapter: %w", constructionFailure))); !errors.Is(err, constructionFailure) {
+		t.Fatalf("New() error = %v, want retained family construction failure", err)
+	}
+
+	app, err := commandkit.New(commandkit.Identity{Name: "Example"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	var before bytes.Buffer
+	app.Execute(context.Background(), []string{"--help"}, commandkit.Streams{Out: &before, Err: io.Discard})
+	if strings.Contains(before.String(), "config") {
+		t.Fatalf("root help showed an unregistered family: %q", before.String())
+	}
+	if err := app.Register(family,
+		commandkit.Alias("cfg-show", "config show"),
+		commandkit.Alias("cs", "cfg-show"),
+		commandkit.FlagAlias("--fmt", "--format"),
+	); err != nil {
+		t.Fatal(err)
+	}
+	if formatParses != 0 {
+		t.Fatalf("registration invoked flag converter %d times", formatParses)
+	}
+	var after bytes.Buffer
+	app.Execute(context.Background(), []string{"--help"}, commandkit.Streams{Out: &after, Err: io.Discard})
+	for _, fragment := range []string{"config", "Aliases:", "cfg-show", "cs"} {
+		if !strings.Contains(after.String(), fragment) {
+			t.Errorf("updated root help %q does not contain %q", after.String(), fragment)
+		}
+	}
+	if outcome := app.Execute(context.Background(), []string{"cs", "--fmt=yaml"}, commandkit.Streams{Out: io.Discard, Err: io.Discard}); outcome.Kind != commandkit.OutcomeSuccess {
+		t.Fatalf("registered alias execution = %#v", outcome)
+	}
+	if !reflect.DeepEqual(formats, []string{"yaml"}) || formatParses != 1 {
+		t.Fatalf("registered family values = %#v, converter calls %d", formats, formatParses)
+	}
+	if err := app.Register(commandkit.NewCommand(commandkit.CommandSpec[struct{}]{Name: "cfg-show", Run: func(commandkit.Invocation, struct{}) commandkit.Outcome { return commandkit.Success() }})); err == nil {
+		t.Fatal("registration accepted a canonical command that conflicts with an existing alias")
+	}
+	var afterConflict bytes.Buffer
+	app.Execute(context.Background(), []string{"--help"}, commandkit.Streams{Out: &afterConflict, Err: io.Discard})
+	if !strings.Contains(afterConflict.String(), "cfg-show") {
+		t.Fatalf("failed relationship validation changed registered aliases: %q", afterConflict.String())
+	}
+
+	late := commandkit.NewCommand(commandkit.CommandSpec[struct{}]{Name: "late", Run: func(commandkit.Invocation, struct{}) commandkit.Outcome {
+		lateRuns++
+		return commandkit.Success()
+	}})
+	registrationFailure := errors.New("retained registration failure")
+	err = app.Register(commandkit.WithError(late, fmt.Errorf("family: %w", registrationFailure)))
+	if !errors.Is(err, registrationFailure) {
+		t.Fatalf("Register() error = %v, want retained failure", err)
+	}
+	if err := app.Register(late, commandkit.Alias("late-shortcut", "missing")); err == nil {
+		t.Fatal("registration accepted a batch whose alias target is absent")
+	}
+	var afterFailure bytes.Buffer
+	app.Execute(context.Background(), []string{"--help"}, commandkit.Streams{Out: &afterFailure, Err: io.Discard})
+	if strings.Contains(afterFailure.String(), "late-shortcut") || strings.Contains(afterFailure.String(), " late ") {
+		t.Fatalf("failed batch changed root help: %q", afterFailure.String())
+	}
+	if err := app.Register(late, commandkit.Alias("late-shortcut", "late")); err != nil {
+		t.Fatalf("registration after failed batch: %v", err)
+	}
+	var recovered bytes.Buffer
+	app.Execute(context.Background(), []string{"--help"}, commandkit.Streams{Out: &recovered, Err: io.Discard})
+	if !strings.Contains(recovered.String(), "late-shortcut") {
+		t.Fatalf("recovered root help omitted alias: %q", recovered.String())
+	}
+	if outcome := app.Execute(context.Background(), []string{"late-shortcut"}, commandkit.Streams{Out: io.Discard, Err: io.Discard}); outcome.Kind != commandkit.OutcomeSuccess || lateRuns != 1 {
+		t.Fatalf("recovered alias execution = %#v, runs %d", outcome, lateRuns)
+	}
+}

doc.go

@@ -1,3 +1,8 @@
-// Package commandkit provides an instance-owned CLI dispatcher with typed
-// command declarations, configuration scopes, and PromptKit inspection.
+// Package commandkit provides the core instance-owned CLI dispatcher, typed
+// command declarations, application-owned command and flag aliases, input
+// bindings, invocation-scoped reporting, and outcomes with separate operation
+// causes and presentation observations. New and App.Register accept canonical
+// Command declarations and RoutingRule declarations together. Optional
+// integration modules provide ConfigKit and PromptKit-specific commands;
+// importing those modules does not install their commands.
 package commandkit

docs/adr/0001-command-dispatch-and-inputs.md

@@ -4,6 +4,10 @@
 
 Accepted.
 
+[ADR 0011](0011-captured-declarations-and-installation.md) refines
+declaration construction, installation, optional-family namespace reservation,
+and integration input/state lifetimes.
+
 ## Date
 
 2026-10-06

docs/adr/0003-public-facade.md

@@ -2,7 +2,11 @@
 
 ## Status
 
-Accepted.
+Partially superseded by [ADR 0010](0010-optional-integration-modules.md).
+
+ADR 0010 narrows the root facade and public-type ownership decision to the core
+module and places optional library dependencies in integration modules. The
+remaining principles continue to apply; this record's decision text is retained.
 
 ## Date
 

docs/adr/0004-standard-inspection-surface.md

@@ -71,8 +71,8 @@ schemas for implemented operations.
 
 CommandKit supplies shared handlers with predictable meanings and discovers their
 availability from registration. Each enabled operation needs its own data
-contract: comparison needs safe snapshots, catalogs need enumeration, and profile
-display needs safe execution-target inspection.
+contract: comparison needs supported native comparison results, catalogs need
+enumeration, and profile display needs safe execution-target inspection.
 
 The [scope model](0009-configuration-scopes.md) and
 [comparison policy](0008-semantic-configuration-diff.md) describe related

docs/adr/0005-invocation-outcomes.md

@@ -55,7 +55,7 @@ A writer failure can leave a partial report and returns operational failure. The
 outcome identifies incomplete delivery. Custom handler output remains
 application-owned. [ADR 0007](0007-native-yaml-reports.md) covers `config show` report
 preparation; [ADR 0008](0008-semantic-configuration-diff.md) defines successful
-comparison, including differences and coverage gaps.
+comparison outcomes.
 
 ## Alternatives considered
 

docs/adr/0007-native-yaml-reports.md

@@ -68,6 +68,6 @@ allows a failure in one scope to prevent combined display. Explicit single-scope
 display remains available for a narrower view.
 
 Additional structured schemas are compatibility contracts owned by CommandKit.
-Native concatenation can use existing writers; semantic comparison separately
-requires the safe structured data described in
+Native concatenation can use existing writers; semantic comparison uses the owning
+library's supported comparison API under
 [ADR 0008](0008-semantic-configuration-diff.md).

docs/adr/0008-semantic-configuration-diff.md

@@ -1,4 +1,4 @@
-# ADR 0008: Compare semantic snapshots with explicit sensitivity gaps
+# ADR 0008: Delegate effective configuration comparison to owning libraries
 
 ## Status
 
@@ -6,72 +6,79 @@ Accepted.
 
 ## Date
 
-2026-10-06
+2026-10-06; revised 2026-10-11.
 
 ## Context
 
-Configuration comparison helps operators understand changes in final effective
-values across roots and overlays. Formatting, authored file layout, and provenance
-identifiers are different properties from effective-value equality. Sensitivity
-classification also limits the values available for inspection.
-
-Meaningful comparison requires structured effective snapshots with per-path
-sensitivity data from the owning libraries. The comparison policy must preserve
-value semantics while making limited coverage visible to operators.
+ConfigKit provides a native configuration comparison capability. Exposing it
+through CommandKit gives applications a consistent operator interface and reduces
+repeated command, selection, and reporting infrastructure. ConfigKit remains the
+authority for the meaning and disclosure of its comparison results.
 
 ## Decision
 
-For a scope declaring safe comparison support, `config diff` compares two
-independently resolved effective configurations. CommandKit checks that capability
-before acquisition. Providers supply captured results through the owning
-libraries' supported public inspection APIs.
+### Comparison ownership
 
-Compare values using the owning library's safe structured inspection semantics,
-including defaults and recorded domain resolution. Preserve the distinctions
-among absent values, null, empty mappings, and empty sequences. Mappings are
-compared recursively; ordered sequences are compared as whole values.
+For ConfigKit-backed scopes declaring comparison support, `config diff` exposes
+ConfigKit's native comparison API. CommandKit checks capability availability before
+acquisition and coordinates selection, acquisition, adaptation, presentation,
+and invocation outcomes.
 
-For each path, use the union of the two sides' sensitivity classifications to
-protect both before and after presentation. A value classified on either side
-receives the corresponding safe treatment in both snapshots. Hidden values
-produce explicit comparison gaps with their paths and supported reasons.
+Integrations delegate comparison to their owning libraries' supported public
+APIs. ConfigKit owns its comparison semantics and disclosure rules. CommandKit
+follows the public contract of the ConfigKit version it adopts. When an adopted
+upstream revision changes those semantics, the changes flow through to
+CommandKit's integration. Upstream remains authoritative as the capability evolves.
 
-Equality conclusions cover the comparable data. A comparison with gaps reports
-its limited coverage alongside observed differences. A complete comparison with
-an empty difference set supports an equality conclusion for the inspected
-selection. Redaction masks are presentation data; classification metadata
-determines comparison coverage.
+Application-supplied providers retain ownership of their implementation and
+loading effects. [ADR 0012](0012-typed-configuration-comparison-pairs.md) governs
+paired selections, provider contracts, and typed input/shared-state lifetimes.
 
-Text and YAML reports include differences and coverage gaps. The exact report
-schema belongs in the [CLI reference](../cli.md) when implemented. Selection
-syntax, inheritance rules, and detailed change records are outside the scope
-of this decision.
+### Safe disclosure and presentation
 
-A completed comparison returns success whether it finds differences or gaps;
-load, comparison, and writer failures use the operational failure classification in
-[ADR 0005](0005-invocation-outcomes.md).
+Adapt and present native comparison results in accordance with the adopted
+upstream API's disclosure contract. The integration carries the upstream results
+and relevant metadata through its public provider boundary.
+
+CommandKit owns report presentation and may summarize or transform the returned
+safe comparison data for different operator needs. Reports may vary in format,
+organization, and detail while respecting safe disclosure and the evidence
+provided by the comparison. Each report's documented meaning defines the
+conclusions an operator can draw from it.
+
+Report formats, schemas, and rendering choices belong in the
+[CLI reference](../cli.md) when implemented. They can evolve independently of
+this ownership decision under the [release policy](../policy/release.md).
+
+### Invocation outcomes
+
+A completed comparison returns success regardless of whether differences are
+reported. Load, comparison, and writer
+failures use the operational failure classification in
+[ADR 0005](0005-invocation-outcomes.md). Applications may use comparison results
+to make their own domain decisions.
 
 ## Alternatives considered
 
 | Alternative | Analysis |
 | --- | --- |
-| Rendered YAML line comparison | Reuses native display output. Formatting and masking become part of change interpretation. |
-| Compare masks as literal strings | Uses visible snapshot bytes directly. Equal masks express equal presentation while hidden values remain uncertain. |
-| Use one side's sensitivity policy | Simplifies classification selection. A value's disclosure treatment depends on which snapshot supplies that policy. |
-| Fetch secret values for comparison | Gives access to additional equality evidence. Comparison acquires sensitive material and additional confidentiality responsibilities. |
-| Element-by-element sequence diff | Gives detailed collection changes. Stable element identity and alignment need another comparison contract. |
-| A distinct status for observed differences | Supports assertion-oriented scripts. Inspection completion and change detection share an outcome signal. |
+| Compare safe snapshots in CommandKit | Gives CommandKit direct control over comparison, but requires it to maintain equality and sensitivity logic and account for values already withheld from snapshots. Native comparison keeps those responsibilities with the owning library. |
+| Compare rendered configuration text | Reuses existing output, but formatting and masking affect the apparent differences. Native comparison supplies evidence grounded in the library's effective-value model. |
+| Leave comparison commands entirely to applications | Preserves application flexibility, but repeats selection, acquisition coordination, and presentation infrastructure across consumers. Integration providers retain application control within the common command system. |
+| Return a distinct status when differences are found | Supports assertion-oriented scripts, but couples successful inspection with a policy judgment about the result. The selected outcome model leaves that judgment to consumers. |
 
 ## Consequences
 
-Operators receive meaningful effective-value changes with explicit uncertainty
-where sensitivity limits comparison. Whole-sequence comparison keeps
-implementation scope focused at the cost of less detailed collection changes.
+CommandKit supplies consistent comparison commands while relying on owning
+libraries for comparison semantics and safe disclosure. Dependency adoption
+includes adapting the integration and its documentation to upstream changes.
+New library integrations
+are assessed through their supported comparison contracts; each scope can expose
+its available capabilities independently under
+[ADR 0009](0009-configuration-scopes.md).
 
-Diff support depends on safe snapshots preserving value semantics and sensitivity.
-CommandKit applies this comparison policy to scopes declaring that capability.
-Other operations and families can be integrated independently under
-[ADR 0004](0004-standard-inspection-surface.md).
-
-Applications can use the successful report as input to domain decisions or future
-assertion workflows.
+Reports can serve different operator needs using the same native comparison
+data. Their level of detail may differ, and sensitivity rules may limit what
+can be shown. Maintaining the boundary between comparison evidence and report
+presentation allows those reports to evolve while preserving library ownership
+and consumer control.

docs/adr/0010-optional-integration-modules.md

@@ -0,0 +1,100 @@
+# ADR 0010: Separate the core facade from optional integration modules
+
+## Status
+
+Accepted. Partially supersedes
+[ADR 0003](0003-public-facade.md) as described below.
+Partially superseded by [ADR 0011](0011-captured-declarations-and-installation.md)
+for the consumer-migration consequence during the unreleased prototype
+transition. It also supplies the registration and invocation-lifetime
+decisions left open here. The module
+boundary and remaining principles continue to apply; this record's decision
+text is retained.
+
+## Date
+
+2026-10-09
+
+## Context
+
+CommandKit serves consumers that need its command infrastructure with different
+combinations of library integrations, including none. A consumer using only the
+core should not acquire dependencies belonging to optional integrations.
+
+ADR 0003 establishes deliberate public contracts and an internal CLI backend
+boundary. Those principles remain appropriate. Its initial single root facade,
+however, combines core and integration responsibilities. Separate packages within
+one module would separate imports while retaining shared module requirements.
+
+## Decision
+
+Retain the root `commandkit` package as the core module's public facade. It owns
+core command declarations, registration, typed inputs, dispatch, help/version,
+shared syntax, diagnostics, and invocation outcomes.
+
+Provide optional library integrations as separate Go modules with their own
+public package contracts. Each integration owns the standard command handlers,
+provider contracts, reports, and adapters appropriate to its responsibility.
+Applications select integrations and explicitly register their commands; importing
+an integration does not install a command family.
+
+Integrations provide convenient registration of their standard command families,
+with standard declarations and handlers supplied by the integration. Applications
+provide acquisition and domain-specific context without assembling individual
+standard commands or repeating adapter plumbing. More specialized composition
+remains available where concrete consumer needs justify it.
+
+Dependencies point from integrations toward the core. The core's public API,
+implementation, and module requirements remain independent of optional
+integration libraries. An integration may depend on another integration when
+its responsibility requires that relationship. Document such dependencies so
+consumers can understand the modules they select.
+
+Integrations compose through supported public core contracts and preserve
+CommandKit's standard grammar, command ownership, help, and outcome conventions.
+They do not access private core state or backend structures. Add public contracts
+where concrete integration needs justify them, without requiring a general plugin
+or backend-selection framework.
+
+### Relationship to ADR 0003
+
+The root-facade and public-type ownership provisions of ADR 0003 now apply to
+the core module. Integration-owned public types and operations belong in their
+respective public packages. The permission to expose deliberately selected
+upstream library types applies within the integrations that depend on them;
+it does not justify optional integration dependencies in the core.
+
+ADR 0003's remaining principles continue to apply across the core and
+integrations: deliberate exports, private implementation state, proportionate
+internal layering, no exposure of internal or backend types, and preservation of
+documented ownership, presence, callback lifetime, and error semantics. Application
+input types and caller-supplied values and errors retain their existing handling.
+Cobra/pflag remain behind the core's internal adapter.
+
+This decision changes the scope of the single-facade decision rather than
+replacing its contract discipline. ADR 0003 is partially superseded and its
+original decision text remains intact.
+
+## Alternatives considered
+
+| Alternative | Analysis |
+| --- | --- |
+| Keep integrations in the root package | Preserves existing imports and simplifies releases, but core consumers acquire optional library dependencies. |
+| Use separate packages within one module | Separates compiled imports and retains one release unit, but keeps integration requirements in the shared module graph. |
+| Have applications implement integration handlers | Keeps the core independent, but recreates duplicated inspection commands and weakens consistent operator behavior. |
+| Introduce universal provider contracts in the core | Could support several libraries through a common model, but adds abstractions and conversion obligations before concrete needs justify them. |
+
+## Consequences
+
+Consumers can adopt the core independently and add supported integrations as
+needed. Integrations remain maintained parts of CommandKit, with shared CLI
+conventions and owning-library semantics. Dependency independence does not mean
+the core has no external implementation dependencies.
+
+Moving existing integration APIs requires a documented consumer migration.
+Integration modules add module-specific dependency, validation, and release work.
+Core tests, examples, and tools must not reintroduce the optional dependencies
+that this boundary removes.
+
+Exact registration mechanics and release cadence are not selected here.
+Current GoDoc and CLI contracts continue to own implemented behavior.

docs/adr/0011-captured-declarations-and-installation.md

@@ -0,0 +1,172 @@
+# ADR 0011: Capture command declarations and install optional families explicitly
+
+## Status
+
+Accepted. Refines [ADR 0001](0001-command-dispatch-and-inputs.md) for declaration
+construction, installation, optional-family namespace reservation, and integration
+input/state lifetimes. Partially supersedes
+[ADR 0010](0010-optional-integration-modules.md) only for its consumer-migration
+consequence during the unreleased prototype transition, and refines its
+convenient composition principle.
+
+Refined by [ADR 0012](0012-typed-configuration-comparison-pairs.md) for
+two-selection configuration comparison and its input/state lifetime. The
+single-selection lifecycle and other decisions remain in force.
+
+## Date
+
+2026-10-10
+
+## Context
+
+Applications declare domain commands, while optional integrations assemble
+standard command families. A common construction and installation model reduces
+repeated error checks and registration plumbing. Integrations need public typed
+composition contracts to assemble those families while preserving core and
+backend boundaries.
+
+Declaration and installation have different responsibilities. An optional family
+claims a namespace when installed; selecting a dependency alone should leave the
+application's command surface unchanged. During execution, scope-specific CLI
+inputs and application-owned shared state also have distinct lifetimes. Making
+those lifetimes explicit avoids accidental aliasing between selected scopes.
+
+At the time of this decision, the implementation was an unreleased prototype
+with no downstream consumers. Its API shapes carried no compatibility obligations
+that would constrain the selected design.
+
+## Decision
+
+### Declaration capture and reuse
+
+Applications and integrations construct the same opaque core command declarations
+and install them through core application construction or registration. Initial
+integrations provide complete-family factories and focused conveniences through
+that common installation API. Suite and provider types remain integration-owned.
+
+Factories eagerly capture metadata, bindings, capability selections, selector
+applicability, and callback references. They copy the declaration collections
+needed to isolate returned commands from later edits to source metadata.
+Construction errors remain attached for installation to report. This model uses
+eager declarations with public typed composition; a deferred preparation lifecycle
+and untyped integration payload are outside the selected API.
+
+Declarations may be reused across applications with independent registry and
+invocation state. Callback references and captured application objects retain
+caller ownership. Reuse provides no deep-copy or concurrent-dispatch guarantee.
+Application helpers performing other fallible work may still return errors.
+
+### Installation and retained errors
+
+Core validates each installation batch before registry mutation, checking
+retained errors, bindings, placement, and collisions. Failed application
+construction returns no usable application; failed later registration preserves
+the existing registry. Atomicity covers one installation call. Separate calls
+and arbitrary callback effects retain their own lifetimes.
+
+Report retained errors with useful command context and preserve supported wrapped
+error identity. The aggregate-error representation remains an implementation
+choice.
+
+An explicit absence declaration contributes no command, help entry, or namespace.
+Installation checks attached errors before skipping it. A zero command declaration
+remains invalid. Integrations define their own empty-suite semantics: the initial
+configuration suite needs at least one named scope, and metadata-only scopes
+remain discoverable. A definition suite with no capabilities contributes nothing.
+
+Binding validation applies to generated command declarations. Unused selector
+bindings in an absent family are ignored; explicitly retained adapter-construction
+errors still reach installation. A nil loader supplied to an adapter remains
+invalid wiring even if its capabilities are subsequently cleared.
+
+### Namespace ownership and placement
+
+Core construction reserves help and version. An optional standard family owns
+its complete root namespace upon installation. Imports and absent declarations
+claim nothing. An application may occupy an uninstalled family name; installing
+a conflicting declaration then fails in either registration order. Installation
+preserves existing handlers and group ownership. Private application operations
+remain outside installed standard families.
+
+Standard families carry root-only placement metadata, which core enforces when
+they are nested beneath another group. Placement is a public declaration property;
+its enforcement is independent of package identity or a list of integration names.
+A real empty root-only group claims its namespace and obeys placement checks.
+Explicit absence contributes no node to place.
+
+### Input and shared-state lifetimes
+
+Integration suites distinguish typed CLI input from typed shared acquisition
+state. Ordinary configuration inspection initializes one input per selected scope,
+applies its applicable selector bindings, and initializes shared state once for
+the inspection invocation. Input validation receives the scope identity and its
+typed input. Named definition inspection uses one input and one shared state.
+Providers receive both explicitly. ADR 0012 refines this lifecycle for comparison
+pairs with two selections of one scope.
+
+Availability preflight and applicable input checks precede shared-state
+initialization and acquisition. Failures may stop later input factories.
+Construction, installation, help, version, and scope discovery leave suite
+input/state factories and acquisition providers uninvoked.
+
+An omitted factory supplies its type's zero value, including nil pointers.
+Applications provide initialization needed by their accessors and providers;
+providers may intentionally accept nil. Allocation of application objects,
+cloning, and aliases returned by factories remain caller responsibilities.
+Core-owned parsed collections stay independent when applied to separate inputs.
+Caller-owned objects and callback effects retain their own lifetimes.
+
+### Typed binding composition
+
+Core provides a narrow typed contract to capture converted values and apply a
+selected binding subset to initialized input. It preserves binding identity,
+defaults, and presence while keeping private setters, parser state, and backend
+objects behind their existing boundaries. A copied binding retains its identity;
+a newly constructed lookalike has its own identity.
+
+Execution-required checks apply to the selected subset. Missing required input
+is a usage failure; invalid binding selection or destination is a wiring failure
+with operational classification at invocation. These categories remain identifiable
+through supported wrapping and stop execution before shared-state initialization
+and acquisition. Metadata defects detectable during assembly of generated
+commands remain installation errors under the validation boundary above.
+
+### Relationship to earlier decisions
+
+For the unreleased prototype transition covered by this decision, compatibility
+wrappers and a downstream migration guide were unnecessary. This exception to
+ADR 0010's migration consequence is limited to that transition. Changes to
+published contracts follow the [release policy](../policy/release.md).
+
+ADR 0001 retains dispatcher, registry, typed-input, and application-ownership
+principles. ADR 0010 governs module boundaries and dependency direction, with
+[ADR 0003](0003-public-facade.md) governing deliberate exports and backend isolation
+within that scope. ADRs 0004 through 0009 retain their operation, grammar, report,
+and outcome decisions. Go declarations and GoDoc own exact implemented signatures.
+
+## Alternatives considered
+
+| Alternative | Analysis |
+| --- | --- |
+| Fallible constructors plus integration-specific registration helpers | Makes each construction failure immediate, but creates several assembly conventions and repeated consumer checks. Captured errors keep one installation boundary. |
+| Deferred preparation callbacks | Allows installation to construct a family, but adds lifecycle and error timing beyond eager capture. No demonstrated assembly need requires it. |
+| Reserve all known optional family names at core construction | Prevents later name conflicts, but consumes namespaces for integrations the application has not selected. Installed-family ownership keeps conflicts explicit without that restriction. |
+| Separate family/plugin registration framework | Could encode ownership and composition, but a captured command with root-only placement and batch validation expresses the required behavior without another installation model. |
+| One shared input/state object | Uses fewer type parameters and can share a cache through references in separate input values, but leaves the distinct lifetimes implicit and scope-input isolation to application conventions. Explicit input and state types make those lifetimes visible. |
+| Clone hooks or automatic pointer allocation | Can hide input construction, but adds object-graph and initialization responsibilities that belong to the application. Explicit factories keep those choices visible. |
+| Public binding getters/setters or an untyped value bag | Enables integration assembly, but exposes private mechanics or returns typed-input assembly to string lookup. Narrow typed composition addresses the actual need. |
+
+## Consequences
+
+Consumers assemble domain commands and optional families through one installation
+boundary. Eager assembly errors reach that boundary before provider acquisition.
+Namespace collisions remain explicit choices for the application to resolve.
+
+Separate input and state types make initialization and sharing visible. Focused
+conveniences support simple applications, while typed composition gives
+integrations the public contracts needed to assemble their families.
+
+The [architecture policy](../policy/architecture.md) owns normative boundaries;
+roadmaps own implementation status and sequencing. Application loading, cache
+design, startup, domain validation, callback effects, and process exit remain
+consumer responsibilities.

docs/adr/0012-typed-configuration-comparison-pairs.md

@@ -0,0 +1,108 @@
+# ADR 0012: Prepare typed selection pairs for configuration comparison
+
+## Status
+
+Accepted. Refines [ADR 0011](0011-captured-declarations-and-installation.md) for
+two-selection configuration comparison; its other decisions remain in force.
+[ADR 0008](0008-semantic-configuration-diff.md) governs native comparison and
+report presentation.
+
+## Date
+
+2026-10-11
+
+## Context
+
+Native effective-configuration comparison needs two completed loads. ConfigKit
+requires results of the same configuration type, which an ordinary inspection
+view does not expose for pairwise comparison. A generic adapter can retain that
+type without introducing result assertions or a universal core provider model.
+
+ADR 0011 separates a selected scope's typed input from shared acquisition state.
+A comparison selects the same scope twice, potentially with different roots or
+overlays. Reusing one input obscures which selection a provider receives; creating
+separate shared state loses the invocation-wide lifetime chosen for inspection.
+
+## Decision
+
+### Selections and provider ownership
+
+Comparison selects one scope and prepares an earlier/left selection and a
+later/right selection. Omitted right selection fields inherit the corresponding
+left field and supplied state. An explicit right override, including an empty
+value, replaces that field. Providers retain interpretation of omitted defaults
+and explicit empty values. Applicable domain selector values are shared between
+the two sides initially; independent per-side domain selectors may be considered
+for a concrete consumer need.
+
+Equal selections are allowed. CommandKit does not skip acquisition merely because
+their selection values are equal: caller-owned loading may produce different
+effective results. Exact flag spellings belong in the CLI reference when
+implemented.
+
+Use a narrow optional comparison provider owned by the integration. Its request
+groups each side's selection with its typed input and supplies one shared state
+value separately. The provider returns acquired native comparison results
+with diagnostics and an error through the existing acquisition convention.
+Reuse useful upstream public record types rather than duplicating them solely
+to rename fields. Exact exported signatures belong in Go declarations and GoDoc.
+
+The typed ConfigKit adapter invokes the supplied loader for each reached side
+and passes the successful typed results to `configkit.Diff`. It retains the
+configuration type inside that adapter, without reflection, result type
+assertions, private core access, or a comparison-facet framework. Applications
+may supply their own pair provider through the same integration contract.
+
+Declared capabilities determine required wiring. A comparison-only scope needs
+its comparison provider, without an unrelated ordinary acquisition callback.
+Ordinary operations continue to use their ordinary acquisition provider.
+Retained adapter construction errors still apply when capabilities are narrowed.
+Other scopes and families need not support comparison under
+[ADR 0009](0009-configuration-scopes.md).
+
+### Typed input and shared state lifetime
+
+Capture comparison declarations and applicable selector bindings under ADR 0011.
+Convert supplied flag values through core once, including on help paths; applying
+the values to both inputs does not parse them again.
+
+After availability preflight, initialize each reached side's typed input
+separately, apply the same applicable captured selector values, and check that
+input with the selected scope identity and that side's selection. Finish both
+input checks before initializing shared state once and invoking the pair
+provider. Failures may stop later factories or loads. Construction, installation,
+help, version, and scope discovery invoke neither input/state factories nor
+acquisition/comparison providers.
+
+Existing factory ownership rules remain unchanged: an omitted factory supplies
+its type's zero value, including nil pointers. Separate factory calls do not
+guarantee distinct caller-owned objects. CommandKit does not allocate arbitrary
+pointer types, clone application graphs, repair caller aliases, or supply or
+repair application caches. Core-owned parsed collections remain independent
+when applied to the two inputs; callback effects remain caller-owned.
+
+## Alternatives considered
+
+| Alternative | Analysis |
+| --- | --- |
+| Symmetric independently resolved left/right selectors | Makes each side explicit and avoids inheritance. It adds vocabulary and repetition for common base-versus-overlay comparisons. |
+| One typed input for both sides | Requires fewer factory calls, but obscures side-specific selection checks and leaves mutation isolation implicit. |
+| Acquire a comparison facet with each ordinary view | Shares single-side acquisition across operations, but requires a public compatibility contract between heterogeneous facets and additional handle or assertion machinery. |
+| Separate shared state for each side | Isolates acquisition state, but loses the invocation-wide sharing already selected for inspection. Applications can choose isolation within their own pair provider if needed. |
+
+## Consequences
+
+Pair preparation has explicit input and state lifetimes while ordinary inspection
+keeps its existing lifecycle. Generic result handling stays inside the integration
+adapter; core gains no owning-library dependency or universal comparison model.
+
+Shared state permits application-owned caches. A cache used by a pair provider
+should distinguish selections and any input values affecting loading to avoid
+reusing the left result for a different right selection. This is integration
+guidance, not a CommandKit cache policy or guarantee about caller callbacks.
+
+The [architecture policy](../policy/architecture.md) owns normative boundaries.
+ADR 0008 governs delegation to upstream comparison semantics, safe disclosure,
+and CommandKit's presentation responsibility. This decision does not add a new
+equality engine or strengthen application
+loading, object ownership, or concurrency contracts.

docs/adr/0013-application-alias-routing.md

@@ -0,0 +1,68 @@
+# ADR 0013: Separate application alias routing from canonical command ownership
+
+## Status
+
+Accepted. Refines [ADR 0011](0011-captured-declarations-and-installation.md)
+by extending its shared installation boundary to application routing rules.
+Its canonical command ownership and declaration principles remain in force.
+
+## Date
+
+2026-10-19
+
+## Context
+
+Applications need alternate command paths and flag spellings that suit their
+operator vocabulary. These conveniences should reuse the behavior supplied by
+application commands and optional integrations. Canonical command families
+already establish ownership of handlers, namespaces, inputs, and invocation
+behavior.
+
+A routing layer allows applications to choose alternate spellings while
+preserving those ownership boundaries. Commands and routing rules have distinct
+roles, and their relationships require validation during application assembly.
+
+## Decision
+
+CommandKit core owns alias declaration, resolution, and coordination with parsing
+and help. Applications choose their alias mappings. Alias infrastructure is
+available independently of optional integrations under the module boundaries
+established by [ADR 0010](0010-optional-integration-modules.md).
+
+Aliases belong to an application routing layer that directs invocations to
+canonical commands and flags. Canonical definitions retain ownership of their
+handlers, inputs, and namespaces. An alternate path within an integration's
+namespace remains an application routing rule; the integration continues to own
+the canonical command family and its operations.
+
+Canonical commands and routing rules are distinct declaration kinds installed
+through a common core assembly boundary. Installation validates their
+relationships together, preserves canonical definitions and namespace ownership,
+and applies the batch-atomicity and retained-error model of ADR 0011 to both
+layers. Declaration capture and reuse follow that existing model.
+
+An invocation through an alias uses the canonical target's parsing, typed
+bindings, validation, and ordinary invocation lifecycle. Execution behavior
+remains with the canonical command and its owning application or integration.
+Core coordinates alternate routing and presentation through the same command
+infrastructure.
+
+## Alternatives considered
+
+| Alternative | Analysis |
+| --- | --- |
+| Install aliases as wrapper commands | Reuses the command tree for discovery, but introduces additional command nodes and handler delegation into namespace ownership and invocation lifetimes. |
+| Have applications rewrite arguments before dispatch | Gives applications direct control over shortcuts, but repeats routing infrastructure and separates alias handling from target validation, parsing, and help. |
+| Register aliases through a separate assembly API | Makes routing declarations explicit, but splits validation of commands and their alternate routes across installation boundaries. Distinct declaration kinds express the separation within one atomic batch. |
+
+## Consequences
+
+Applications can tailor operator vocabulary while reusing canonical behavior.
+Core maintains the relationship between routing rules and canonical definitions
+as declarations are installed. Optional integrations continue to supply their
+command families through the existing ownership model.
+
+Routing, parsing, and help must coordinate across the two layers. Exact API
+shapes, resolution rules, and presentation choices belong in GoDoc and the
+[CLI reference](../cli.md) when implemented. Those details can evolve within
+this architectural separation.

docs/adr/0014-invocation-reporting.md

@@ -0,0 +1,79 @@
+# ADR 0014: Share command-line presentation within each invocation
+
+## Status
+
+Accepted. Extends [ADR 0005](0005-invocation-outcomes.md) with shared reporting
+for each invocation. Its outcome classifications, standard status meanings,
+output channels, error-cause preservation, and application ownership of process
+exit remain in force.
+
+## Date
+
+2026-10-25
+
+## Context
+
+Applications need consistent control over command results, messages shown during
+a run, and messages shown at its end. Sharing that control reduces repeated
+output code across applications and integrations.
+
+An application decides what an error means for its work. It may recover silently,
+show a warning, or end the invocation. CommandKit needs the chosen outcome and
+messages to present that decision to the operator.
+
+## Decision
+
+CommandKit core provides one reporting facility for each invocation. Application
+commands, integration commands, and core commands use it for results, immediate
+messages, and deferred messages. Core applies shared rules for visibility,
+formatting, and delivery, and completes reporting when the invocation ends.
+Callers choose the output destinations.
+
+Applications decide how to respond to domain-specific errors and choose their
+outcomes and messages. CommandKit may provide shared helpers for carrying,
+inspecting, and presenting errors while leaving those decisions with the
+application.
+
+Applications supply explicit outcomes and explanations for failures. They may
+also supply a Go error cause. CommandKit keeps that error unchanged for the caller
+to inspect. Supplying a cause alone does not select an outcome or generate an
+operator-facing message. CommandKit remains responsible for handling its own
+errors, including routing, parsing, and presentation failures.
+
+Integrations adapt upstream results and diagnostics into command outcomes and
+messages. The upstream libraries retain ownership of their meanings and rules
+for safe disclosure.
+
+An Error message explains a failed invocation with a non-zero status. Its
+explanation is presented at the end of the invocation, after normal reporting
+finishes. The returned outcome carries that explanation. The application entry
+point decides how to exit the process.
+
+CommandKit reports rendering and delivery failures separately from the command's
+explanation. A presentation failure produces an operational failure for standard
+outcomes under ADR 0005. Application-defined domain classifications are preserved,
+along with an already non-zero domain status. A successful domain outcome receives
+a non-zero status if presentation fails. The original explanation and any supplied
+cause remain available to the caller. Intentionally suppressed output is not a
+delivery failure.
+
+Reporting keeps the state needed to deliver messages and return the invocation
+outcome. Logging and message history remain application concerns.
+
+## Alternatives considered
+
+| Alternative | Analysis |
+| --- | --- |
+| Let each application manage all presentation | Gives applications full control, but repeats visibility and delivery code across commands and integrations. |
+| Have core decide whether domain-specific errors require recovery, a warning, or failure | Reduces some caller code, but gives core decisions that depend on application behavior. |
+| Use separate facilities for results, immediate messages, and deferred messages | Lets each facility serve one purpose, but spreads visibility and final delivery across several paths. |
+
+## Consequences
+
+Applications and integrations share presentation behavior while choosing their
+own results and messages. Core handles reporting failures consistently and keeps
+them visible in the returned outcome.
+
+GoDoc and the [CLI reference](../cli.md) define the implemented API, flags,
+message formats, and delivery details. Those details can evolve within this
+ownership model.

docs/cli.md

@@ -66,6 +66,130 @@ version: dev
 revision: ""
 ```
 
+## Shell completion
+
+Applications may install shell completion explicitly. When installed, generate
+and load the script for the executable name chosen by the application:
+
+```sh
+# Bash, after initializing bash-completion
+source <(app completion bash)
+# Zsh, after initializing its completion system with compinit
+source <(app completion zsh)
+# Fish
+app completion fish | source
+```
+
+Bash requires the `bash-completion` package and its helpers in the current
+shell. If your startup files do not initialize it, source the package's
+initialization file before loading the generated script. For example, on
+systems that install it at the following path:
+
+```sh
+source /usr/share/bash-completion/bash_completion
+source <(app completion bash)
+```
+
+Use the path provided by your Bash completion installation.
+
+The application selects the executable basename at installation; use that same
+name to invoke the generated script. Completion offers canonical command and
+flag names, static values, and file or directory paths where declarations
+provide hints. A fully entered alias is resolved to its canonical command;
+alias spellings and partial alias paths are not suggested. Completion queries
+do not invoke input factories, providers, or the selected command; application
+startup remains application-owned. See the
+[consumer guide](consumers/guide.md#shell-completion) for installation and
+hint declarations. Script generation follows the [reporting policy](#reporting),
+including quiet mode.
+
+## Reporting
+
+CommandKit applies one shared reporting policy to application handlers,
+integrations, help, version, and CommandKit's own invocation diagnostics. The
+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`.
+
+### Modes and visibility
+
+Each invocation starts in ordinary mode. `--quiet`, `--verbose`, and `--debug`
+are mutually exclusive; the last enabled occurrence selects the mode. They
+accept presence or an explicit boolean value. A `false` occurrence clears the
+selected mode only when it names the current mode, returning to ordinary mode;
+it does not restore an earlier selection. Invalid boolean values are usage
+errors, even if a later flag would select another mode.
+
+| Category | `--quiet` | No mode flag | `--verbose` | `--debug` |
+| --- | --- | --- | --- | --- |
+| Substantive result | Suppressed | Shown | Shown | Shown |
+| Terminal failure | Shown | Shown | Shown | Shown |
+| Warning | Suppressed | Suppressed | Shown | Shown |
+| Info | Suppressed | Suppressed | Shown | Shown |
+| Debug | Suppressed | Suppressed | Suppressed | Shown |
+| Progress, unless enabled explicitly | Suppressed | Suppressed | Suppressed | Shown |
+
+`--progress` independently enables Progress; `--progress=false` disables it.
+Both accept the existing boolean syntax, and the last occurrence wins. An
+explicit setting overrides the mode default, except quiet always suppresses
+Progress. Without an explicit setting, debug enables Progress; ordinary and
+verbose modes leave it disabled. Progress does not enable Info, Warning, or
+Debug.
+
+### Placement and aliases
+
+Reporting flags are available on application commands, the root, canonical
+groups, help, version, and alias-only discovery help. Place them after the
+complete command path; they may be interspersed with operands after that path.
+For example:
+
+```text
+example export --quiet
+example config show --verbose
+example promptkit test all --debug --progress=false
+example help config show --quiet
+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`,
+`-v → --verbose`, and `-d → --debug`; canonical and aliased occurrences share
+the same ordering. Thus `example export --verbose -q` selects quiet mode.
+
+### Channels and messages
+
+Substantive reports use the result destination. Warnings, Info, Progress,
+Debug, terminal explanations, and usage guidance use the diagnostic destination.
+Simple Warning, Debug, and terminal failure messages begin with `WARN:`,
+`DEBUG:`, and `ERROR:` respectively. Info, Progress, and substantive results
+have no prefix. For multiline messages, the prefix appears on the opening line;
+native structured details keep their own formatting without duplicate labels.
+Progress is streamed as unprefixed lines; terminal redraw and progress bars are
+not provided. A failed outcome with no message or detail uses the fallback
+`ERROR: Command failed.`.
+
+Quiet mode suppresses successful help and version output, as it does other
+substantive results. Usage guidance and routing, parsing, and operational
+failures remain visible in every mode. A recovered problem is reported only if
+the application chooses to submit a Warning; an error cause by itself does not
+create a message.
+
+### Presentation failures
+
+CommandKit continues rendering substantive output under quiet mode through a
+discard destination. This suppresses writes to the caller's result writer while
+still detecting report preparation, encoding, or rendering failures. An
+intentional suppression is not a delivery failure. A failure while rendering or
+writing requested content is retained in the returned `Outcome` and makes an
+otherwise successful or usage invocation operational with status `1`. A domain
+classification and its nonzero status are preserved; a zero-status domain
+outcome becomes status `1` when presentation fails. Earlier bytes already
+written remain visible.
+
 ## Registered command syntax
 
 Options are parsed after the complete command path and may be interspersed with
@@ -83,11 +207,82 @@ 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.
 
+## Application-owned aliases
+
+Applications can install command and flag aliases alongside their canonical
+commands. Aliases route an invocation to existing behavior; they do not add
+handlers, commands, or flags to a canonical command family.
+
+Command alias paths are sequences of command tokens relative to the application
+root. The executable name, flags, flag values, and operands are not part of an
+alias path. Matching uses complete tokens and chooses the longest matching
+path. A group alias preserves its remaining command tokens, and aliases can
+compose through chains. For example, `list collections` can route to
+`promptkit list collections`, while `pk` can route to the `promptkit` group.
+The target must resolve to a canonical command or group.
+
+Aliases do not rewrite operands or supply arguments. In particular,
+`promptkit test KIND` remains one canonical command whose `KIND` is an operand;
+`all` is an operand value, not a child command. `smoke → promptkit test` is a
+valid shortcut because it preserves the caller's `KIND` value.
+
+Flag aliases can be application-wide or scoped to a canonical command path.
+An application-wide alias is effective wherever its canonical target flag is
+available and is ignored elsewhere. A scoped alias requires its canonical
+command and target flag to be installed. The selected canonical command
+determines applicable scoped aliases, so the alias also works when that
+command is reached through another command path. A scoped mapping takes
+precedence over an application-wide mapping with the same spelling.
+
+Only tokens parsed as flag names participate in flag aliasing. Values, operands,
+and tokens following `--` remain unchanged. This includes values that look like
+flags, such as `--message=--hlep`. Aliased flags use the target's canonical
+binding, conversion, default, required-value check, presence, and repetition
+behavior. Mixed spellings preserve occurrence order: singleton flags use the
+last successfully parsed occurrence, every supplied occurrence is converted,
+and repeatable flags accumulate values in order.
+
+Flag aliases accept one long spelling or one individual short spelling. Short
+aliases use the canonical short-option cluster and attached-value grammar:
+
+| Input | Interpretation |
+| --- | --- |
+| `-vq` | Two boolean flags, `--verbose` and `--quiet`. |
+| `-cblue` or `-c blue` | Value `blue` for a value-taking `-c` flag. |
+| `-vqcblue` | `-v`, `-q`, then `--color=blue`. |
+| `-cvq` | Value `vq` for a value-taking `-c` flag. |
+| `-v=false` | Explicit false for the boolean flag `-v`. |
+| `-c=` | An explicitly supplied empty string. |
+
+Boolean flags use presence as true; an explicit boolean value requires `=`.
+The first value-taking short flag consumes the remaining cluster suffix or the
+next argument. A consumed value is never interpreted as an alias. The canonical
+short-option empty-value form `-c=` supplies an empty value, consistently with
+`--color=` and `-c ""`.
+
+Help reached through an alias describes the canonical command's flags and
+operands while using the entered route in usage. It identifies the canonical
+target, lists applicable aliases separately, and supports global help aliases
+such as `--hlep → --help`. Help for an alias-only prefix lists its routes
+without creating a command group; the bare incomplete prefix points to that
+help. Help and alias registration do not construct command inputs or invoke
+acquisition callbacks.
+
+Usage diagnostics preserve the command path and flag spelling the caller used.
+When a command alias resolved successfully, usage identifies its canonical
+target while retaining the entered path in the diagnostic. An unresolved route
+receives no invented canonical label. A flag conversion error identifies the
+entered flag spelling and the failing occurrence while preserving the original
+cause.
+
 ## Configuration scopes
 
-An application installs one configuration suite with `RegisterConfig`. Its
+An application installs the declaration returned by
+`ckconfig.Command(ckconfig.Suite[Input, State]{...})` through
+`commandkit.New` or `App.Register`. For the common single application scope,
+`ckconfig.AppCommand` returns a convenience declaration. The installed
 `config scopes` command lists scope names and the configuration operations
-currently installed for those scopes:
+currently available for those scopes:
 
 ```text
 example config scopes
@@ -102,10 +297,10 @@ runtime context or acquire configuration. It reports the intersection between
 declared scope capabilities and installed handlers, so an operation is listed
 only when the corresponding command is available.
 
-Applications can register the `promptkit` scope with `NewPromptKitScope` to
-expose PromptKit engine configuration through these handlers. This configuration
-scope can be installed without registering PromptKit prompt or profile
-definition commands.
+Applications can add `ckprompt.ConfigScope(loadEngine)` to the ConfigKit suite
+to expose PromptKit engine configuration through these handlers. The scope
+declares validate, show, sources, explain, and native diff. It does not install
+PromptKit prompt or profile definition commands.
 
 ### Validate configuration
 
@@ -152,8 +347,8 @@ interrupt the native value. Existing native markers and leading comments are
 retained; documents without a marker receive one. Scope labels containing line
 control characters are quoted to keep them on one comment line. A provider
 failure leaves the output stream empty. A rendering or output failure may leave
-an aggregate prefix, and the outcome reports
-incomplete report delivery.
+an aggregate prefix; `Outcome.Presentation.Output` records incomplete delivery
+and the destination or rendering error.
 
 ### List configuration sources
 
@@ -172,14 +367,36 @@ sources:
     kind: file
     underlay_index: 0
     imported_from: null
+    destination: /server
+    placement: mapping
+    destination_unresolved: false
+    version_check:
+      path: /version
+      version:
+        present: true
+        null: false
+        text: "1"
+      location:
+        source_id: source-1
+        line: 2
+        column: 1
+      redacted: false
 ```
 
 Each source includes `id`, `label`, `path`, `layer`, `kind`, `underlay_index`,
-and `imported_from`. The import location is null when absent; otherwise it has
-`source_id`, `line`, and `column`. Owning values and source order are preserved,
-including empty fields, zero coordinates, and synthetic sources without paths.
-An empty inventory is `sources: []`. Text output begins with the scope heading
-and then prints the same source fields, quoting labels and paths.
+and `imported_from`, plus the native destination pointer, placement, unresolved
+destination flag, and nullable `version_check`. Placement is `mapping` or
+`sequence_item`. The import location is null when absent; otherwise it has
+`source_id`, `line`, and `column`. Version evidence preserves `path`, `present`,
+`null`, `text`, optional source `location`, and `redacted` as returned by
+ConfigKit. Owning values and source order are preserved, including empty fields,
+zero coordinates, false and null observations, and synthetic sources without
+paths. An absent version check is null. An empty inventory is `sources: []`.
+Text output begins with the scope heading and prints the same source fields,
+quoting labels and paths. These fields project the selected ConfigKit source
+records; CommandKit does not reload files or rerun version checks. See the
+[ConfigKit v0.8.0 inspection API](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/137769f3f18a370c68444242fb5d88e620e307e5/inspection.go)
+for native evidence definitions.
 
 ### Explain a configuration path
 
@@ -228,41 +445,111 @@ environment-variable name; effective and historical secret fragments remain
 redacted. Empty location, inheritance, history, reason, and dependency lists are
 serialized as `[]`.
 
+### Compare configuration selections
+
+`config diff` prepares two selections for one scope that declares comparison
+and invokes its comparison provider after input checks pass. The default scope
+is `app`; `--scope all` is unsupported.
+When an application installs `ckprompt.ConfigScope(loadEngine)`, the PromptKit
+scope declares comparison and delegates it to PromptKit's captured
+configuration inspection API. PromptKit owns the meaning of that native
+comparison; CommandKit uses the existing `config diff` preparation and report
+path.
+`--config` and `--overlay` select the left side. `--against-config` and
+`--against-overlay` independently override the right side. When a right-side
+field is omitted, it inherits the corresponding left value and supplied state;
+an explicit empty string overrides it and remains supplied. Equal selections are
+allowed; their equality alone does not cause CommandKit to skip the provider.
+
+YAML is the only format and the default. Explicit `--format yaml` is accepted;
+`text` and other formats are usage errors. For example:
+
+```text
+example config diff --config before.yml --against-config after.yml
+example config diff --config base.yml --against-overlay candidate
+example config diff --config base.yml --overlay current --against-overlay ""
+example config diff --scope promptkit --config before.yml --against-config after.yml
+```
+
+For ConfigKit-backed scopes, ConfigKit compares frozen effective typed values
+after defaults and resolution; source or provenance differences alone do not
+create a change. PromptKit delegates its native comparison to ConfigKit. The
+report is one YAML document with `additions`, `changes`, and `deletions` in that
+order. Additions and changes preserve semantic paths and contain right-side
+values provided by the native comparison. Deletions contain canonical JSON
+Pointer paths. Explicit null is a value; it is not a deletion. Changed sequences
+and native structural replacement regions stay atomic.
+
+ConfigKit pairs sensitivity across both loads. A concealed change can therefore
+appear even when its two safe snapshots are equal. For those ConfigKit-backed
+comparisons, the report omits separate redaction and hidden-change metadata: a
+reported masked region changed, but that does not mean every member inside it
+changed. Marker-looking public strings stay ordinary YAML values. An empty
+comparison succeeds with this shape:
+
+```yaml
+additions: {}
+changes: {}
+deletions: []
+```
+
+The reduced report is a partial safe view, not a reloadable configuration or an
+automatically applicable patch. Exceptional whole-root empty/null transitions
+can be ambiguous because the report has no root envelope; ordinary field-level
+null values and deletions retain their distinction.
+
+Successful comparisons return status `0`, including empty results.
+Unsupported scopes and format errors are usage errors; input checks retain the
+existing usage/operational classification. Load and native comparison failures
+are operational and preserve supported error identity.
+
+The bundled `FromConfigKit` and `AppCommand` adapters invoke the supplied loader
+for each reached side, left before right, then call native comparison. They label
+native diagnostics with their left/right side and source legend, retain left
+diagnostics if right loading fails, and gather both loads' diagnostics before
+native comparison. Custom pair providers own their loading and diagnostics;
+application loaders and caches determine whether a loader call reads sources
+again.
+
+The complete report is prepared before writing. Report preparation failures and
+cancellation observed before report delivery starts leave CommandKit's report
+output empty. Once writing starts, CommandKit does not interrupt the supplied
+writer or roll back delivered bytes. A write error or short write is recorded
+as incomplete delivery in `Outcome.Presentation.Output` and can leave partial
+output.
+
 ## PromptKit definition inspection
 
 Applications can install prompt and profile inspection independently with
-`RegisterPromptKit`. When acquisition is reached, the handler invokes its
-registered inspection callback once with the caller's selection and context.
-The bundled `NewPromptKitSuite` helper acquires an engine through the application
-loader and asks PromptKit to inspect its captured named definition. The loader
-can construct or reuse an engine; direct suite callbacks retain their own
+`ckprompt.Command(suite)`. The `ckprompt.FromEngine(loadEngine)` adapter
+supplies these callbacks alongside native requirements discovery and the five
+catalogs. Its loader receives invocation context, configuration selection,
+typed input, and shared state. Direct suite callbacks retain their own
 implementation and lifecycle.
 
-CommandKit's inspection path does not execute prompts, contact model providers,
-or resolve provider credential values. Application acquisition and direct
-callback effects remain application-owned. Prompt definitions and profile
-resolution remain owned by
-[PromptKit's inspection API](https://gitea.maximumdirect.net/eric/promptkit/src/commit/4b8169da286917fde7875425bb32b799b12c6af3/engine.go).
+Prompt inspection uses an ID only. PromptKit returns any descriptive version
+metadata as an optional report field; there is no `--version` flag for selecting
+a prompt version. The prompt format and native selection behavior remain owned by
+[PromptKit v0.16.0](https://gitea.maximumdirect.net/eric/promptkit/src/commit/9178f3eb91c2b2138caa78e22be93c048b4bc992/docs/consumers/pkg-promptkit.md).
 
 ```text
-example promptkit show prompt customer/summary --version 2 --format yaml
+example promptkit show prompt customer/summary --format yaml
 example promptkit show prompt customer/summary
 example promptkit show profile customer-support --format yaml
 ```
 
 Both commands require one ID operand and accept `--config`, `--overlay`, and
-`--format text|yaml` (default `text`). Prompt inspection also accepts singleton
-`--version`, defaulting to the empty string. PromptKit owns version selection:
-an omitted version works for a single-version ID, while an ambiguous ID is an
-operational error. These commands have no built-in `--scope` selection; their
-namespace is `promptkit`.
+`--format text|yaml` (default `text`). These commands have no built-in
+`--scope` selection; their namespace is `promptkit`.
 
-Prompt YAML has these fields. Input order is preserved and an empty input list is
-`[]`. The prompt hash is an opaque owning-library equality value.
+Prompt YAML preserves native input order and uses an optional `version` field.
+The key is omitted when PromptKit returns no version and is retained when the
+version is present, including an empty string. The prompt hash is an opaque
+owning-library equality value.
 
 ```yaml
 prompt_id: customer/summary
-prompt_version: "2"
+version: "2"
 prompt_hash: opaque-value
 default_profile_id: customer-support
 inputs:
@@ -301,15 +588,363 @@ api_key_required: true
 ```
 
 Text uses labeled fields and includes nested `extra_params` values. A missing ID
-is a usage error. Blank, unknown, and ambiguous definition selections reach the
-owning inspection API and produce operational results with supported public
-error identity. Cancellation is also operational: standard handlers check the
-caller's context at inspection boundaries, and PromptKit can return cancellation
-from its own inspection methods. Supported cancellation identity is preserved.
+is a usage error. Definition selection reaches the owning inspection API and
+preserves supported error identity and cancellation.
+
+## PromptKit requirements
+
+When `Suite.InspectRequirements` is present, `ckprompt.Command(suite)` installs
+`promptkit requirements show`. It accepts one prompt ID and uses PromptKit's
+native selection and discovery rules:
+
+```text
+example promptkit requirements show briefing --campaign spring
+example promptkit requirements show briefing --profile editorial --var mode=full
+example promptkit requirements show briefing --session-id session-42 --var note= --format yaml
+```
+
+The command accepts:
+
+| Flag | Values | Default | Meaning |
+| --- | --- | --- | --- |
+| `--config` | path string | omitted | Select the configuration input; explicit presence is retained. |
+| `--overlay` | path string | omitted | Select one overlay; explicit presence is retained. Repeated occurrences use the last value. |
+| Suite selectors | application-defined | per selector | The flags captured from `Suite.Selectors`. |
+| `--profile` | string | empty | Pass the profile ID to PromptKit; empty uses its native selection rule. |
+| `--session-id` | string | empty | Pass session context to PromptKit. |
+| `--var` | repeatable `KEY=VALUE` | none | Supply caller-variable context for native discovery. |
+| `--format` | `yaml` | `yaml` | Select the requirements report format. Other formats are usage errors for this operation. |
+
+The `promptkit` namespace identifies the operation, so there is no built-in
+`--scope` flag. An explicitly empty profile or session value retains PromptKit's
+native empty-string meaning. Requirements inspection does not require a profile
+to be execution-ready. See the
+[PromptKit v0.16.0 consumer guide](https://gitea.maximumdirect.net/eric/promptkit/src/commit/9178f3eb91c2b2138caa78e22be93c048b4bc992/docs/consumers/pkg-promptkit.md)
+for native configuration, selection, and requirements behavior. The built-in
+flags other than `--var` are singleton bindings; when repeated, the last value
+is used. Suite selectors retain their declared binding behavior.
+
+Each `--var` occurrence must contain `=`. CommandKit splits at the first
+separator and preserves the exact key and remaining value. Empty keys and
+values, whitespace, commas, and additional `=` characters are retained. All
+occurrences are parsed; duplicate keys use the last value, while any malformed
+occurrence is a usage error even if a later assignment is valid.
+
+The YAML report contains selected identities, native completeness, and input,
+variable, and issue inventories. False values and empty inventories are
+retained. Input metadata preserves null versus an empty string. Variable entries
+contain `name`, `kind`, `supplied`, and `explanation`. `supplied` reports native
+exact-key presence, including an explicitly empty value, independently of
+`kind` and `complete`. Explanations and issue descriptions are upstream-owned
+human-readable summaries, not machine-readable details. The optional `version`
+key is omitted when absent and retained when supplied by PromptKit.
+
+For a prompt with the template `{{if .mode}}{{input "notes"}}{{end}}` and no
+input declarations, omitting `mode` can produce a partial report:
+
+```yaml
+prompt_id: briefing
+version: "2"
+profile_id: editorial
+complete: false
+inputs:
+  - name: notes
+    kind: conditional
+    declared: false
+    content_type: null
+    description: null
+    explanation: This reference is not known to be reached on every execution path.
+variables:
+  - name: mode
+    kind: required
+    supplied: false
+    explanation: ""
+issues:
+  - code: missing_variable
+    input_name: ""
+    variable_name: mode
+    description: A missing variable prevents selecting a dependency-bearing branch.
+```
+
+PromptKit owns the inventory, classifications, explanations, completeness, and
+structured issues. Successfully acquired and delivered partial reports return
+status `0`; structured issues do not independently fail the command. Provider
+errors, native selection errors, cancellation, and report delivery failures use
+the operational path (status `1`) with supported cause identity. Syntax,
+operand, variable-assignment, and format errors use usage status `2`.
+
+### Concrete request validation
+
+When `Suite.ValidateRequest` is present, `ckprompt.Command(suite)` also installs
+`promptkit requirements validate`. It can be installed without discovery, and
+discovery can remain installed without validation. The command accepts one
+prompt ID and passes a concrete request to PromptKit's native
+`Engine.ValidateRequest` preparation path:
+
+```text
+example promptkit requirements validate briefing --campaign spring --input topic=topic.txt
+example promptkit requirements validate briefing --profile editorial --session-id session-42 --var mode=full --input notes=notes.txt
+```
+
+The command accepts:
+
+| Flag | Values | Default | Meaning |
+| --- | --- | --- | --- |
+| `--config` | path string | omitted | Select the configuration input; explicit presence is retained. |
+| `--overlay` | path string | omitted | Select one overlay; explicit presence is retained. Repeated occurrences use the last value. |
+| Suite selectors | application-defined | per selector | The flags captured from `Suite.Selectors`. |
+| `--profile` | string | empty | Pass the profile ID to PromptKit. |
+| `--session-id` | string | empty | Pass session context to PromptKit. |
+| `--var` | repeatable `KEY=VALUE` | none | Supply caller variables for the concrete request. |
+| `--input` | repeatable `NAME=PATH` | none | Bind a file-backed PromptKit artifact. |
+| `--format` | `yaml` | `yaml` | Select the success confirmation format. Other formats are usage errors. |
+
+The built-in flags other than repeatable `--var` and `--input` are singleton
+bindings; when repeated, the last value is used. Explicit empty `--config` or
+`--overlay` values keep their supplied-presence information. The profile and
+session fields use native empty-string semantics. PromptKit owns their
+interpretation and selection errors.
+
+Each `--var` and `--input` occurrence must contain `=`. CommandKit splits at the
+first separator and preserves the exact key/name and remaining value/path.
+Empty variable keys and values and empty input names and paths are passed to
+native validation. File paths become `promptkit.File(PATH)` references without
+being read, normalized, expanded, or rebased during argument binding. Duplicate
+keys or names use the last value, but every occurrence is parsed.
+
+On success, the YAML confirmation contains only the requested prompt ID and
+`valid: true`:
+
+```yaml
+prompt_id: briefing
+valid: true
+```
+
+Validation delegates concrete request preparation to PromptKit. Native
+preparation may resolve prompt/profile resources, load artifact and schema
+resources, render messages and session context, and perform applicable
+configuration and credential checks. It does not make a model call or retain a
+prepared execution snapshot. A successful report describes this preparation
+invocation; it does not certify provider acceptance or guarantee later
+execution. See PromptKit's
+[`Engine.ValidateRequest` API](https://gitea.maximumdirect.net/eric/promptkit/src/commit/9178f3eb91c2b2138caa78e22be93c048b4bc992/engine.go).
+
+Builder, engine-loading, and native validation errors use the operational path
+(status `1`) with supported error identity and acquired diagnostics retained.
+Malformed syntax, missing operands, and unsupported formats use usage status
+`2`. Successful diagnostics use the common reporting policy. Report delivery
+failures are recorded in `Outcome.Presentation.Output`, separately from the
+operation cause.
+
+### PromptKit catalogs
+
+An installed `ckprompt.Command(suite)` exposes each catalog whose callback is
+present:
+
+```text
+example promptkit list prompts
+example promptkit list profiles --config settings.yml --campaign spring
+example promptkit list backends --namespace team
+example promptkit list namespaces --kind prompt --kind profile
+example promptkit list collections
+```
+
+All catalogs accept `--config`, `--overlay`, applicable flags from
+`Suite.Selectors`, and `--format yaml` (the default). Other formats are usage
+errors. Prompt, profile, and backend listings accept namespace selection:
+
+| Binding | Effect |
+| --- | --- |
+| omitted `--namespace` and `--all-namespaces` | Forward PromptKit's native default namespace filter. |
+| `--namespace team` | Forward the named namespace filter. |
+| `--namespace ""` | Select the unqualified namespace. |
+| `--all-namespaces` | Forward the all-namespaces filter. |
+| `--all-namespaces=false` | Do not select an override; a supplied namespace still applies, otherwise native default is used. |
+
+The namespace binding is a singleton and its last occurrence is used.
+Supplying a namespace while `--all-namespaces=true` is active is a usage error
+before provider work. Namespace inventory accepts repeatable `--kind KIND`;
+omitting `--kind` forwards PromptKit's native default kind selection. Repeated
+values are forwarded in order. Collections have no namespace or kind filter.
+
+Each operation writes one bare YAML sequence, retaining provider order and
+native identities:
+
+- Prompt entries are `{id, version?}`. The optional `version` key is omitted
+  when absent and retained for a present empty or nonempty value.
+- Profiles, backends, and namespaces are strings.
+- Collection entries are `{namespace, version?}`, where `version` projects
+  PromptKit's optional release version.
+- Nil and allocated-empty inventories both render as `[]`.
+
+```yaml
+- id: team/briefing
+  version: "2"
+```
+
+```yaml
+- autumn
+- spring
+```
+
+A catalog result is an inventory, not a readiness check or execution result.
+The owning provider controls membership and order. Namespace filters are passed
+to PromptKit without local membership interpretation. See the
+[PromptKit v0.16.0 consumer guide](https://gitea.maximumdirect.net/eric/promptkit/src/commit/9178f3eb91c2b2138caa78e22be93c048b4bc992/docs/consumers/pkg-promptkit.md)
+for native resource and selection definitions.
+
+### PromptKit smoke testing
+
+When `Suite.SmokeTest` is present, `ckprompt.Command(suite)` installs
+`promptkit test KIND`. The special kind `all` runs the four concrete operations
+sequentially in this order: `reachability`, `authentication`, `text_inference`,
+and `structured_output`. Both forms use the same single-operation callback;
+each aggregate call changes the seed kind before invoking it. The command
+accepts:
+
+```text
+example promptkit test text_inference --campaign spring --prompt briefing --profile spring
+example promptkit test all --campaign spring --prompt briefing --profile spring
+example promptkit test authentication --backend local
+```
+
+| Flag | Values | Default | Meaning |
+| --- | --- | --- | --- |
+| `--config`, `--overlay` | path strings | omitted | Select PromptKit configuration; supplied presence is retained. |
+| Suite selectors | application-defined | per selector | Captured flags from `Suite.Selectors`. |
+| `--backend` | string | empty | Native backend ID. |
+| `--prompt` | string | empty | Native prompt ID. |
+| `--profile` | string | empty | Native profile ID. |
+| `--endpoint` | string | omitted | Override the execution endpoint. |
+| `--model` | string | omitted | Override the execution model. |
+| `--temperature` | float | omitted | Override execution temperature. |
+| `--max-tokens` | integer | omitted | Override execution maximum tokens. |
+| `--top-p` | float | omitted | Override execution top-p. |
+| `--timeout-seconds` | integer | omitted | Override the execution timeout. |
+| `--service-tier` | string | omitted | Override the execution service tier. |
+| `--reasoning-effort` | string | omitted | Override execution reasoning effort. |
+| `--api-key-env` | string | omitted | Supply an API-key environment-variable name to native configuration. |
+| `--transient-retries` | integer | omitted | Set the native inference transient retry count. |
+| `--format` | `yaml` | `yaml` | Select the report format. Other formats are usage errors. |
+
+The execution flags populate PromptKit's native execution override. The
+`--api-key-env` value is a variable name, not a credential value. Application
+selectors, loader policy, credentials, and client wiring remain application
+owned. The `WithSmokeTesting` helper accepts an optional typed builder. A nil
+builder forwards the seed; a supplied builder's complete native request is
+authoritative. The helper retains a native report when PromptKit returns both a
+report and an error.
+
+A single report projects the native smoke report into YAML. It preserves native
+false, unknown/null, and incomplete values and does not add a readiness score.
+The report includes `kind`, `supported`, `applicable`, `completed`, `reason`,
+`target`, `facts`, `timing`, `attempts`, `usage`, and `failure`. Its target
+contains selected IDs, optional `version`, selection source, endpoint, effective
+settings, and settings-presence flags. Attempt entries retain their own facts,
+timing, failure, and token-usage evidence. Durations use Go duration strings;
+token counts preserve `value`, `known`, and `complete`.
+
+Here is a native projection as rendered by the command:
+
+```yaml
+kind: reachability
+supported: false
+applicable: null
+completed: true
+reason: http_diagnostics_unavailable
+target:
+  backend_id: ""
+  profile_id: spring
+  prompt_id: briefing
+  version: "1"
+  default_source_backend_id: ""
+  selection_source: profile
+  endpoint: https://example.invalid/v1
+  effective_settings:
+    endpoint: https://example.invalid/v1
+    model: spring-model
+    temperature: 0
+    max_tokens: 0
+    top_p: 0
+    timeout_seconds: 600
+    service_tier: ""
+    reasoning_effort: ""
+    api_key_env: ""
+    extra_params:
+      campaign: spring
+  settings_presence:
+    temperature: false
+    max_tokens: false
+    top_p: false
+    timeout_seconds: false
+facts:
+  credentials_supplied: null
+  endpoint_reachable: null
+  credentials_accepted: null
+  response_received: null
+  generation_completed: null
+  text_returned: null
+  expected_text_matched: null
+  structured_output_requested: null
+  valid_json: null
+  schema_matched: null
+timing:
+  started_at: 2026-10-17T19:05:36Z
+  duration: 35.685µs
+  capacity_wait: null
+  request_duration: null
+  retry_delay: null
+  evaluation_duration: null
+attempts: []
+usage:
+  prompt_tokens: {value: 0, known: true, complete: true}
+  completion_tokens: {value: 0, known: true, complete: true}
+  total_tokens: {value: 0, known: true, complete: true}
+  cached_tokens: {value: 0, known: true, complete: true}
+  cache_write_tokens: {value: 0, known: true, complete: true}
+failure: ""
+```
+
+Aggregate output is one YAML mapping with ordered `tests` entries. Each entry
+has selected `kind`, nullable `report`, and optional `error` text. The inner
+report keeps its native `kind`. This cancellation example shows two attempted
+operations with no reports; later kinds are absent because cancellation stops
+the sequence:
+
+```yaml
+tests:
+  - kind: reachability
+    report: null
+    error: "reachability operation failed"
+  - kind: authentication
+    report: null
+    error: "context canceled"
+```
+
+A successful delivered single operation returns status `0`. For `all`, all
+four callbacks must return without error for status `0`. Native false, unknown,
+unsupported, or incomplete observations do not independently change the
+outcome. Operation errors use operational status `1`; aggregate runs continue
+after individual errors, retain their reports and ordered error text, and join
+causes for supported `errors.Is`/`errors.As` access. Cancellation stops later
+operations and preserves results already acquired. Report encoding or delivery
+failures are recorded in `Outcome.Presentation.Output`, separately from
+operation causes. Syntax, operand, unsupported format, and conflicting
+namespace selection are usage status `2`.
+
+Native configuration, selection, and diagnostic meanings remain owned by
+PromptKit. See the [v0.16.0 consumer guide](https://gitea.maximumdirect.net/eric/promptkit/src/commit/9178f3eb91c2b2138caa78e22be93c048b4bc992/docs/consumers/pkg-promptkit.md),
+[smoke API](https://gitea.maximumdirect.net/eric/promptkit/src/commit/9178f3eb91c2b2138caa78e22be93c048b4bc992/smoke_diagnostics.go),
+and [engine API](https://gitea.maximumdirect.net/eric/promptkit/src/commit/9178f3eb91c2b2138caa78e22be93c048b4bc992/engine.go).
 
 ## 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.
+chooses how to map an outcome to process exit. A rendering or delivery failure
+changes a successful or usage outcome to operational status `1`. A domain
+outcome keeps its classification and nonzero status; a zero-status domain
+outcome becomes `1` if presentation fails. The returned `Outcome.Presentation`
+records output and diagnostic delivery observations separately from its
+operation `Cause`.

docs/consumers/guide.md

@@ -1,88 +1,354 @@
 # Consumer guide
 
-CommandKit's supported Go API is the root `commandkit` package. Start with an
-`App`, register CommandKit's standard inspection families, register application
-commands, and call `App.Execute` with the caller's context and streams. The
-caller retains process startup, signal handling, and exit mapping.
+CommandKit is distributed as three Go modules. Start with the core and add an
+integration module only when the application uses that library. Core and
+compatible integration command factories return canonical `commandkit.Command` values.
+Applications may install those alongside application-owned `RoutingRule`
+declarations through `commandkit.New` or `App.Register`; routing rules are
+installed at the application root, not as group children.
+
+## Module selection
+
+| Import | Use when |
+| --- | --- |
+| `go.maximumdirect.net/commandkit` | The application needs typed command declarations and common CLI behavior. |
+| `go.maximumdirect.net/ckconfig` | The application wants ConfigKit-backed configuration scopes and reports. |
+| `gitea.maximumdirect.net/eric/CommandKit/integrations/ckprompt` | The application wants PromptKit engine configuration/comparison, five catalogs, named inspection, requirements discovery, request validation, or native smoke testing. |
+
+The ckconfig v0.2.0 candidate uses core v0.3.0. The ckprompt source still uses
+the old core and ckconfig identities; its planned matched v0.2.0 release will
+use the new paths. Update application imports and dependency versions together.
+Old and new core paths have distinct Go type identities. Install core with
+`go get go.maximumdirect.net/commandkit@v0.3.0` and the matching integration
+with `go get go.maximumdirect.net/ckconfig@v0.2.0` once it is published.
+
+The two integrations are independent optional imports. `ckprompt` uses the
+public scope and error contracts from `ckconfig`; importing it does not add the
+`config` family. An application that wants both families passes both returned
+declarations to core. The [maintained examples](../../README.md#examples) show
+core-only, ConfigKit-only, and composed applications.
 
 ## Go compatibility
 
-The consumer minimum is declared in [go.mod](../../go.mod): Go 1.26.0.
-ReleaseKit v0.3.0 requires that version and is selected as a tool dependency in
-the same module graph. The minimum therefore applies to library consumers even
-though production packages do not import ReleaseKit. Consumers using Go 1.25
-need a Go 1.26 or newer toolchain to adopt this revision.
+All three modules declare a consumer minimum of Go 1.26.0. The root module also
+selects ReleaseKit v0.9.0 (`go.maximumdirect.net/releasekit`) as a Go tool, which
+makes that tool's module graph part of the root consumer module requirements
+even though production packages do not import ReleaseKit. The
+[release policy](../policy/release.md#consumer-minimum-and-release-toolchain)
+defines the support assumption. Maintainers use Go 1.26.8 for validation and
+publication; see the [release procedure](../release.md#release-toolchain).
 
-The [release policy](../policy/release.md#consumer-minimum-and-release-toolchain)
-defines support assumptions and versioning for changes to that minimum.
-Maintainers select their validation toolchain separately in the
-[release procedure](../release.md#release-toolchain). Updating that toolchain's
-patch version alone leaves the consumer minimum unchanged.
+## Core commands
 
-## A configuration scope
-
-Use [`NewConfigKitScope`](../../config.go) to adapt one ConfigKit loader. The
-loader receives the invocation's explicit `Selection`; the application decides
-how those supplied config and overlay values map to its inputs.
+Declare typed flags and operands with `CommandSpec[I]`, then capture them with
+`NewCommand`. Bindings deliver `Supplied[T]`, which distinguishes an omitted
+default from an explicitly supplied empty, false, or zero value.
 
 ```go
-scope, err := commandkit.NewConfigKitScope[appContext, appConfig](
-	"app",
-	"Application settings.",
-	func(ctx context.Context, selection commandkit.Selection, app appContext) (*configkit.Result[appConfig], error) {
-		return loadAppConfig(ctx, selection, app)
-	},
+package example
+
+import (
+	"fmt"
+	"strconv"
+
+	commandkit "go.maximumdirect.net/commandkit"
 )
-if err != nil {
-	return err
+
+type GreetInput struct {
+	Count commandkit.Supplied[int]
+}
+
+func Greeting() commandkit.Command {
+	countDefault := 1
+	return commandkit.NewCommand(commandkit.CommandSpec[GreetInput]{
+		Name: "greet", Summary: "Write a greeting.",
+		Flags: []commandkit.Flag[GreetInput]{
+			commandkit.ValueFlag(
+				commandkit.FlagMeta{Name: "count", Usage: "Number of greetings."},
+				&countDefault, strconv.Atoi,
+				func(input *GreetInput, value commandkit.Supplied[int]) {
+					input.Count = value
+				},
+			),
+		},
+		Run: func(invocation commandkit.Invocation, input GreetInput) commandkit.Outcome {
+			if _, err := fmt.Fprintln(invocation.Reporter().Output(), input.Count.Value); err != nil {
+				return commandkit.Failure("Could not write the greeting.").WithCause(err)
+			}
+			return commandkit.Success()
+		},
+	})
 }
-err = commandkit.RegisterConfig(app, commandkit.ConfigSuite[appContext]{
-	Scopes: []commandkit.ConfigScope[appContext]{scope},
-})
 ```
 
-`config show`, `config sources`, and `config explain` use the configuration
-captured by that load. A scope can support only the operations it provides.
-When several scopes share invocation-local application state, create it in
-`ConfigSuite.NewContext`; use typed `Selector` bindings to copy only the values
-that apply to each scope. See the [composed example](../../examples/composed/README.md)
-for a cache shared by the `app` and `promptkit` scopes.
+The application supplies `context.Context`, argv without the executable name,
+and output streams to `App.Execute`; it decides how the returned status maps to
+process exit. `New` installs generated help/version and caller declarations as
+one batch. `Register` validates each call as a batch before changing that App.
+Invalid declaration errors retain their wrapped identity for `errors.Is` and
+`errors.As`.
 
-## PromptKit configuration and definitions
+Declarations copy their metadata and slice inputs when captured, retain callback
+references, and can be reused across applications. Copies of a typed binding
+preserve its identity; a separately constructed lookalike does not. Supplied
+values convert before input construction. A command's `NewInput` creates input
+only when execution reaches it; help does not construct caller input or run
+provider callbacks.
 
-Register `NewPromptKitScope` with the config suite when you want the effective
-PromptKit configuration and its ConfigKit provenance available under `config`.
-Register `NewPromptKitSuite` and `RegisterPromptKit` separately to enable
-`promptkit show prompt` and/or `promptkit show profile`. Each adapter calls the
-owning public inspection method and preserves acquisition diagnostics with a
-failed named lookup. Definition inspection does not invoke execution APIs or
-resolve provider credentials.
+## Shell completion
 
-The [composed example](../../examples/composed/README.md) shares its ordinary app and
-engine-loading functions across the configuration and definition suites. It
-also keeps `session restore` as an application-owned typed command, including
-its session data and domain outcome mapping.
+Install `commandkit.Completion("app")` alongside the application's other
+declarations, using the basename operators actually type. The basename accepts
+letters, digits, underscores, dots, hyphens, and colons, except for a leading
+hyphen. Add a hint to a flag or operand's metadata when a value has useful
+static choices or is a filesystem path:
 
-## Typed application commands
+```go
+commandkit.FlagMeta{
+	Name: "format",
+	Completion: commandkit.CompleteChoices(
+		commandkit.CompletionChoice{Value: "text", Description: "Readable text"},
+		commandkit.CompletionChoice{Value: "yaml", Description: "YAML output"},
+	),
+}
+commandkit.FlagMeta{Name: "config", Completion: commandkit.CompleteFiles()}
+commandkit.ArgumentMeta{Name: "directory", Completion: commandkit.CompleteDirectories()}
+```
 
-Declare flags, operands, and a typed input struct with `NewCommand`. Bindings
-preserve whether a value was explicitly supplied, so an explicit zero can differ
-from an omitted default. `RepeatFlag` retains occurrence order. The
-[simple example](../../examples/simple/README.md) combines both features with a typed
-ConfigKit scope.
+Hints are suggestions: converters and input validation still decide which
+values are accepted. An omitted hint or `NoCompletion()` gives no value
+suggestions. `CompleteChoices()` with no choices also gives no suggestions.
+Declarations retain copies of supplied choices. The [CLI reference](../cli.md#shell-completion)
+describes supported shells and loading scripts; the [core example](../../examples/core)
+and [composed example](../../integrations/ckprompt/examples/composed) show
+installation alongside aliases and integration commands.
 
-## Outcomes and process exit
+## Invocation reporting
 
-Handlers return `Success`, `Failure`, or an application-owned `Outcome`. The
-caller chooses how a nonzero status maps to process exit; `Execute` never exits
-the process. It writes CommandKit diagnostics to the supplied error stream and
-returns the resulting classification and delivery information. Applications
-keep their domain meanings and output in their own handlers.
+`Invocation.Reporter()` supplies the reporter for the current handler. Use
+`Output()` or `RenderOutput()` for substantive results; 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,
+and status behavior.
 
-Exact CommandKit contracts are documented on the exported declarations and
-their GoDoc comments. ConfigKit owns configuration decoding and provenance;
-consult its [inspection API](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/dc09959cca4e105f49ec316c6d4ba585bd2340bd/inspection.go).
-PromptKit owns prompt formats and profile resolution; consult its [public
-engine methods](https://gitea.maximumdirect.net/eric/promptkit/src/commit/4b8169da286917fde7875425bb32b799b12c6af3/engine.go),
-[configuration inspection](https://gitea.maximumdirect.net/eric/promptkit/src/commit/4b8169da286917fde7875425bb32b799b12c6af3/configuration_inspection.go),
-and [inspection types](https://gitea.maximumdirect.net/eric/promptkit/src/commit/4b8169da286917fde7875425bb32b799b12c6af3/types.go).
+Return terminal text with `Failure(message, details...)`, `Usage(message,
+details...)`, or `WithExplanation` on a domain outcome. Attach an optional Go
+error separately with `WithCause`. A cause is preserved for inspection, but it
+does not choose the outcome or become user-facing text. Rendering callbacks
+write to their supplied writer only while the callback runs; they must not
+submit another message or start another rendering operation through the same
+reporter.
+
+```go
+Run: func(invocation commandkit.Invocation, input GreetInput) commandkit.Outcome {
+	if _, err := fmt.Fprintln(invocation.Reporter().Output(), input.Count.Value); err != nil {
+		return commandkit.Failure("Could not write the greeting.").WithCause(err)
+	}
+	return commandkit.Success()
+}
+```
+
+After `App.Execute`, inspect the returned `Outcome`. Its `Cause` retains the
+operation error; `Presentation.Output` and `Presentation.Diagnostics` report
+delivery state and the first rendering or write errors for their destinations.
+CommandKit does not retain a message transcript. Reporter operations for one
+invocation are safe concurrently, but concurrent submission order is not
+specified. The caller owns the writers passed to `Execute`; CommandKit does not
+close them.
+
+### Migrating from the previous reporting API
+
+| Previous API | Current API |
+| --- | --- |
+| `invocation.Streams.Out` / `.Err` | `invocation.Reporter().Output()` and categorized reporter methods. `Streams` remains the argument to `App.Execute`. |
+| `Failure(err)` / `Usage(err)` | `Failure("operator-facing explanation").WithCause(err)` / `Usage("usage explanation").WithCause(err)`. Choose the explanation deliberately; the cause alone is not printed. |
+| `Outcome.Diagnostics` or terminal `SeverityError` | Submit independent messages through reporter methods. Put failure context in `Explanation`; provider `Acquired.Diagnostics` remains passive data for the owning integration to submit. |
+| `ReportIncomplete`, `DiagnosticDelivery`, or `DeliveryError` | Inspect `Outcome.Presentation.Output` and `.Diagnostics`, including each `DeliveryResult.State`, `RenderError`, and `WriteError`. |
+
+## Application-owned aliases
+
+Pass commands and aliases together as declarations. Integration factories can
+be called directly in the installation list, and command-scoped flag aliases
+name the canonical command path:
+
+```go
+app, err := commandkit.New(
+	identity,
+	ckprompt.Command(suite),
+	commandkit.Alias("pk", "promptkit"),
+	commandkit.FlagAliasFor("promptkit show prompt", "--fmt", "--format"),
+)
+```
+
+For a reusable collection, use `[]commandkit.Declaration`. Go does not expand a
+`[]commandkit.Command` into `...commandkit.Declaration`, so convert command-only
+slices when composing them with routing rules:
+
+```go
+commands := []commandkit.Command{ckprompt.Command(suite)}
+declarations := make([]commandkit.Declaration, 0, len(commands)+1)
+for _, command := range commands {
+	declarations = append(declarations, command)
+}
+declarations = append(declarations, commandkit.Alias("pk", "promptkit"))
+app, err := commandkit.New(identity, declarations...)
+```
+
+New and Register validate each supplied batch before publishing its commands
+and routing rules. Factories capture their inputs eagerly; malformed or
+conflicting rules are reported at installation. Identical rules are safe to
+contribute from reusable helpers. The [core example](../../examples/core) and
+[composed consumer](../../integrations/ckprompt/examples/composed) show complete
+maintained wiring with ordinary command behavior alongside aliases. The
+[Go declarations and GoDoc](../../command.go) own the public API contracts;
+the [CLI reference](../cli.md#application-owned-aliases) owns routing and
+operator-visible behavior.
+
+## ConfigKit scopes
+
+For an application with one ordinary app configuration loader,
+`ckconfig.AppCommand` supplies the state-free convenience declaration:
+
+```go
+app, err := commandkit.New(
+	commandkit.Identity{Name: "Example", Version: "dev"},
+	ckconfig.AppCommand(loadAppConfig),
+)
+```
+
+`loadAppConfig` has the signature
+`func(context.Context, ckconfig.Selection) (*configkit.Result[T], error)`.
+Construction, installation, and help do not call it. `Selection` preserves
+whether config and overlay paths were explicitly supplied, including empty
+values.
+
+Use `ckconfig.Command(ckconfig.Suite[I, S]{...})` when the application needs
+multiple named scopes, selector flags, scope-aware input checks, or shared
+acquisition state or a custom comparison provider. A declared `Diff` capability
+uses `Scope.Compare`; `ckconfig.FromConfigKit` and `AppCommand` provide the
+ConfigKit-backed implementation. Each comparison side gets its own initialized
+and checked input, while state is shared by the invocation. Factory results
+remain caller-owned, so separate initialization calls do not guarantee distinct
+objects. See
+[ckconfig.Suite's GoDoc](../../integrations/ckconfig/contracts.go) for factory
+timing, omitted-factory zero values (including nil pointers), and ownership.
+The application owns the state type and what it caches. `ckconfig.FromConfigKit`
+adapts a typed ConfigKit loader without calling it during construction.
+
+The `config` family provides scope discovery, validation, native effective YAML,
+source inventory, path explanation, and ConfigKit-backed comparison for the
+capabilities declared by its scopes. The [CLI reference](../cli.md#configuration-scopes)
+owns operator syntax and report details.
+
+## PromptKit configuration, definitions, and requirements
+
+`ckprompt.ConfigScope(loadEngine)` returns a `ckconfig.Scope` for the PromptKit
+engine's captured configuration. Add that scope to a `ckconfig.Suite` to expose
+it under `config` with validate/show/sources/explain and native diff operations;
+it does not install PromptKit catalog, definition, or requirements commands.
+
+`ckprompt.FromEngine(loadEngine)` supplies eight callbacks: prompt, profile,
+backend, namespace, and collection catalogs; named prompt and profile
+inspection; and native requirements discovery. Concrete request validation and
+smoke testing are separate capabilities, added explicitly with
+`ckprompt.WithRequestValidation` and `ckprompt.WithSmokeTesting`. The suite has
+ten independently optional callbacks in total. `ckprompt.Command(suite)` creates
+only operations whose callbacks are present; discovery, validation, and smoke
+testing can be installed independently. A composed suite can enable both
+additional operations:
+
+```go
+suite := ckprompt.FromEngine(loadEngine)
+suite = ckprompt.WithRequestValidation(suite, loadEngine, buildRequest)
+suite = ckprompt.WithSmokeTesting(suite, loadEngine, nil)
+suite.NewInput = newInput
+suite.NewState = newState
+suite.Selectors = selectors
+definitionCommand := ckprompt.Command(suite)
+```
+
+A validation-only suite can start empty. With application types named `Input`
+and `State`, a nil builder forwards the request fields populated by standard
+flags directly to PromptKit:
+
+```go
+suite := ckprompt.WithRequestValidation(
+	ckprompt.Suite[Input, State]{}, loadEngine, nil,
+)
+validationCommand := ckprompt.Command(suite)
+```
+
+If the loader is nil, the returned suite retains a wiring issue for installation
+to report, even if capabilities are narrowed later. A builder runs before the
+engine loader and receives the seed request, selection, typed input, shared
+state, and invocation context. It returns the
+concrete request; the adapter does not merge seed fields back afterward. The
+loader receives the original selection. Builders should start from the seed,
+preserve operator values and bindings, and apply defaults only when a map key is
+absent, so explicitly supplied empty values stay meaningful. Applications that
+validate and then execute a request are encouraged to share their request
+construction logic between those paths.
+
+The eight catalog and inspection callbacks and the two explicit additions are
+independently optional. For catalogs without named or requirements inspection,
+narrow the suite before command capture:
+
+```go
+definitions := ckprompt.FromEngine(loadEngine)
+definitions.InspectPrompt = nil
+definitions.InspectProfile = nil
+definitions.InspectRequirements = nil
+definitionCommand := ckprompt.Command(definitions)
+```
+
+Each selected inspection, requirements, validation, smoke, or catalog operation
+prepares one input, applies its captured selectors, checks that input, and
+initializes one state value when those steps are reached. The bundled validation
+adapter delegates concrete request preparation to PromptKit and carries its
+native errors plus engine-loading diagnostics through the acquisition. It does
+not call the model or retain a prepared execution snapshot. See
+[ckprompt.Suite's GoDoc](../../integrations/ckprompt/adapters.go) for factory
+timing, omitted-factory zero values, and caller-owned objects and effects.
+The loader receives invocation context, explicitly supplied selection, input,
+and state. `FromEngine` uses PromptKit's public listing and inspection methods,
+including `Engine.InspectRequirements`; validation must be opted into separately
+and uses `Engine.ValidateRequest`.
+
+Catalog, named definition inspection, and requirements discovery do not render
+messages or load request artifacts. Concrete request validation follows native
+PromptKit preparation, which can resolve prompt/profile resources, load
+artifacts and schemas, render messages, and perform applicable configuration
+and credential checks. It does not make a model call or certify that a later
+execution will succeed. Application loaders and direct callbacks retain their
+own effects. Smoke testing explicitly invokes one native PromptKit diagnostic
+or all four in order. Native inference checks use the configured public
+`promptkit.LLMClient`; applications retain ownership of client and probe
+configuration. A builder may customize the seeded native request, and its
+complete return value is authoritative. The [CLI reference](../cli.md#promptkit-smoke-testing),
+[definition inspection](../cli.md#promptkit-definition-inspection), and
+[requirements contract](../cli.md#promptkit-requirements) own operator syntax
+and reports.
+
+The [composed example](../../integrations/ckprompt/examples/composed/README.md)
+combines app and PromptKit config scopes, comparison and catalogs, named and
+requirements inspection, request validation, smoke testing, and an
+application-owned `session restore` command.
+
+## Outcomes and ownership
+
+Core classifies usage and operational failures while preserving application
+domain outcomes and supported error identity. Applications choose domain
+classification and status. A terminal explanation is presented separately from
+the optional operation cause, while report and diagnostic delivery observations
+are available in `Outcome.Presentation`. The caller owns process startup,
+signal handling, and exit mapping; `Execute` never exits the process.
+
+Go declarations and GoDoc own exact exported contracts. ConfigKit owns
+configuration decoding, validation, and provenance. PromptKit owns prompt
+formats, profile resolution, and inspection details. See the
+[ConfigKit v0.8.0 inspection API](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/137769f3f18a370c68444242fb5d88e620e307e5/inspection.go),
+[PromptKit engine methods](https://gitea.maximumdirect.net/eric/promptkit/src/commit/9178f3eb91c2b2138caa78e22be93c048b4bc992/engine.go),
+[configuration inspection](https://gitea.maximumdirect.net/eric/promptkit/src/commit/9178f3eb91c2b2138caa78e22be93c048b4bc992/configuration_inspection.go),
+[smoke diagnostics](https://gitea.maximumdirect.net/eric/promptkit/src/commit/9178f3eb91c2b2138caa78e22be93c048b4bc992/smoke_diagnostics.go),
+and [PromptKit v0.16.0 consumer guidance](https://gitea.maximumdirect.net/eric/promptkit/src/commit/9178f3eb91c2b2138caa78e22be93c048b4bc992/docs/consumers/pkg-promptkit.md).

docs/development.md

@@ -1,17 +1,23 @@
 # Developing CommandKit
 
-CommandKit currently contains adopted repository policies, accepted architectural
-decisions, identity and outcome primitives, typed command
-declarations, an instance-owned registry, a Cobra-backed routing and parsing
-adapter, public `App.Execute` coordination, and generated help/version commands.
-Configuration suite registration, scope discovery, ConfigKit validation and
-reports, PromptKit engine configuration inspection, and optional PromptKit
-prompt/profile inspection commands are implemented. The maintained
-[consumer guide](consumers/guide.md) links to maintained examples. The
-[README](../README.md) provides project orientation; the
+CommandKit is distributed as a core Go module and two optional integration
+modules. Core owns captured declarations, typed input preparation, installation,
+dispatch, invocation reporting and outcomes, help, and version.
+`integrations/ckconfig` owns ConfigKit scope adaptation and reports;
+`integrations/ckprompt` owns PromptKit engine,
+definition inspection, requirements discovery, and concrete request validation.
+The maintained [consumer guide](consumers/guide.md) links to the three maintained
+consumers.
+The [README](../README.md) provides project orientation; the
 [documentation policy](policy/documentation.md#canonical-ownership) assigns
 canonical documentation owners.
 
+For application-owned aliases, use the
+[CLI reference](cli.md#application-owned-aliases),
+[Go declarations and GoDoc](../command.go), and
+[ADR 0013](adr/0013-application-alias-routing.md). Keep deferred capabilities in
+[deferred work](roadmap/deferred.md).
+
 ## Initial orientation
 
 1. Inspect the worktree and preserve unrelated staged and unstaged changes.
@@ -48,12 +54,15 @@ canonical documentation owners.
 | Task | Read |
 | --- | --- |
 | Implemented CLI behavior | [CLI reference](cli.md) |
-| Public API usage and standard-suite wiring | [Consumer guide](consumers/guide.md), [configuration declarations](../config.go), [PromptKit declarations](../promptkit.go), and applicable ADRs |
-| Dispatcher, registration, or typed inputs | [Command declarations](../command.go), [bindings](../binding.go), [invocation](../execute.go), and [ADR 0001](adr/0001-command-dispatch-and-inputs.md) |
+| Invocation reporting | [CLI reporting contract](cli.md#reporting), [consumer guide](consumers/guide.md#invocation-reporting), core GoDoc, [reporting roadmap](roadmap/reporting.md), and [ADR 0014](adr/0014-invocation-reporting.md) |
+| Application-owned aliases | [CLI reference](cli.md#application-owned-aliases), [Go declarations and GoDoc](../command.go), [consumer guide](consumers/guide.md#application-owned-aliases), and [ADR 0013](adr/0013-application-alias-routing.md) |
+| Public API usage and standard-suite wiring | [Consumer guide](consumers/guide.md), [ckconfig package](../integrations/ckconfig/doc.go), [ckprompt package](../integrations/ckprompt/doc.go), and applicable ADRs |
+| Dispatcher, registration, or typed inputs | [Command declarations](../command.go), [bindings](../binding.go), [invocation](../execute.go), and [ADR 0001](adr/0001-command-dispatch-and-inputs.md), refined by [ADR 0011](adr/0011-captured-declarations-and-installation.md) |
 | Backend integration | [Internal overview](internal/overview.md), [adapter implementation](../internal/cobra/parse.go), and [ADR 0002](adr/0002-cobra-backend.md) |
-| Public facade or adapter boundaries | [Internal overview](internal/overview.md), [ADR 0003](adr/0003-public-facade.md), and the architecture policy |
+| Public facade or adapter boundaries | [Internal overview](internal/overview.md), [ADR 0003](adr/0003-public-facade.md) as scoped by [ADR 0010](adr/0010-optional-integration-modules.md), and the architecture policy |
+| Module ownership and public contracts | [Consumer guide](consumers/guide.md), [internal overview](internal/overview.md), [core GoDoc](../doc.go), [ckconfig GoDoc](../integrations/ckconfig/doc.go), [ckprompt GoDoc](../integrations/ckprompt/doc.go), and applicable ADRs |
 | Deferred capabilities and proposals | [Deferred work](roadmap/deferred.md) |
-| Completed planning and implementation history | [Retired records in Git history](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/6bc37e7ba64ca0920b4d0cc77039a18d4006b24e/docs/roadmap) |
+| Completed planning and implementation history | [Completed dependency upgrades, PromptKit validation, discovery, smoke testing, and remediation](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/a6278a6d9f940948ec7745955d745523aaff0734/docs/roadmap), [earlier ConfigKit and PromptKit adoption and remediation](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/8a82620dfcd34c0ae56bbecb0d014eb49786bc92/docs/roadmap), [earlier retired records](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/6bc37e7ba64ca0920b4d0cc77039a18d4006b24e/docs/roadmap), and [completed module implementation and remediation](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/bb2528532b78d30e52f5082e491a5e1fd9b0fb99/docs/roadmap) in Git history |
 | Release tooling | [Maintainer release procedure](release.md) |
 | Performance maintenance | [Internal overview](internal/overview.md), existing benchmarks, and [deferred efficiency work](roadmap/deferred.md#possible-further-efficiency-work) |
 | Licensing or incorporated material | [Project grant](../COPYRIGHT), [license texts](../LICENSE), and [attribution](oss/attribution.md) |
@@ -62,8 +71,10 @@ canonical documentation owners.
 Read all applicable rows for cross-cutting work. Go declarations and GoDoc own
 current exported contracts; the CLI reference owns operator behavior. The
 [maintainer release procedure](release.md) owns current release operations.
-Completed roadmaps and implementation evidence remain available in Git history;
-they are not assignments to restart completed work. The
+Completed roadmaps and implementation evidence remain available in Git history,
+including [application-owned alias planning, implementation, and remediation](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/f42aefe02d84e154855ac922173e6f367180929f/docs/roadmap)
+and [PromptKit requirements implementation and remediation](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/40499a43608bf60d1104cd8ee24caf18ac0e9e66/docs/roadmap).
+These records are not assignments to restart completed work. The
 [deferred-work record](roadmap/deferred.md) preserves future capability targets
 and unselected proposals separately from current contracts.
 
@@ -88,21 +99,38 @@ Sibling-checkout references in retired planning records are historical review
 evidence, not build dependencies. Implemented contracts belong in CommandKit
 under their canonical owners.
 
-Run `go test ./...` from the repository root to compile the module and run its
-deterministic tests. Format changed Go files with `gofmt`. The
+The root module does not traverse nested modules. During the vanity-path
+migration, ckprompt still imports the old core and ckconfig identities and
+cannot compose with the migrated modules until its own migration is complete. After
+the matched migrations, during development use a
+local workspace for all three modules; it is ignored and must not be committed.
+If a local `go.work` already exists, preserve it and add these module directories:
+
+```sh
+if [ -f go.work ]; then
+    go work use . ./integrations/ckconfig ./integrations/ckprompt
+else
+    go work init . ./integrations/ckconfig ./integrations/ckprompt
+fi
+go test ./...
+(cd integrations/ckconfig && go test ./...)
+(cd integrations/ckprompt && go test ./...)
+```
+
+The workspace checks package behavior. Workspace-off checks with each module's
+own dependency graph are separate evidence. For unpublished CommandKit dependency
+versions, the [completed integration validation record](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/8a82620dfcd34c0ae56bbecb0d014eb49786bc92/docs/roadmap/implementation.md#stage-12-validate-the-complete-end-state-and-finish)
+describes the disposable module-file procedure used during implementation.
+Format changed Go files with `gofmt`. The
 [maintainer release procedure](release.md) owns candidate preparation and
 publication commands.
 
 ## Release tooling development
 
-The local publication exercise is opt-in and uses disposable Git repositories.
-Prepare the module cache before running it; ordinary tests do not bootstrap or
-publish a release:
-
-```sh
-GOWORK=off GOTOOLCHAIN=local go mod download
-COMMANDKIT_RELEASE_INTEGRATION=1 GOWORK=off GOTOOLCHAIN=local GOPROXY=off GONOPROXY=none GOSUMDB=off go test -mod=readonly -count=1 ./scripts -run '^TestReleaseIntegration$'
-```
+Run the focused launcher wiring tests with `go test ./scripts`. The release
+profiles select upstream checks of committed inputs independently for each
+module; these checks do not replace domain review. See the
+[release procedure](release.md) for publication, delivery, and recovery.
 
 Follow the [local commit policy](policy/agents.md#git-commit-policy). Completed
 units receive local commits by default, subject to explicit user instructions.
@@ -111,16 +139,45 @@ or publishing.
 
 ## Current public examples
 
-The maintained consumers under `examples/` compile with the module suite and
-run without external services:
+The maintained consumers compile with their owning module suites and run without
+external services. The PromptKit smoke examples use local fixtures and the
+example's configured client:
 
 ```sh
-go run ./examples/simple config show
-go run ./examples/simple greet --count=0 --tag=first --tag second
-go run ./examples/composed config validate --scope all --campaign spring
-go run ./examples/composed promptkit show prompt briefing --campaign spring --format yaml
-go run ./examples/composed session restore session-42 --campaign spring
+go run ./examples/core workspace greet --count=0 --tag=first --tag second
+(cd integrations/ckconfig/examples/simple && go run . config show)
+(cd integrations/ckconfig/examples/simple && go run . config diff --config fixtures/before.yml --against-config fixtures/after.yml)
+(cd integrations/ckprompt/examples/composed && go run . config validate --scope all --campaign spring --limit=0)
+(cd integrations/ckprompt/examples/composed && go run . config diff --scope app --config fixtures/before.yml --against-config fixtures/after.yml)
+(cd integrations/ckprompt/examples/composed && go run . config diff --scope promptkit --config fixtures/before.yml --against-config fixtures/after.yml --campaign spring)
+(cd integrations/ckprompt/examples/composed && go run . promptkit list prompts --config fixtures/before.yml --campaign spring)
+(cd integrations/ckprompt/examples/composed && go run . promptkit list profiles --config fixtures/after.yml --campaign autumn --format yaml)
+(cd integrations/ckprompt/examples/composed && go run . promptkit list backends --namespace team)
+(cd integrations/ckprompt/examples/composed && go run . promptkit list namespaces --kind prompt --kind profile)
+(cd integrations/ckprompt/examples/composed && go run . promptkit list collections)
+(cd integrations/ckprompt/examples/composed && go run . promptkit show prompt briefing --campaign spring --format yaml)
+(cd integrations/ckprompt/examples/composed && go run . promptkit requirements show briefing --campaign spring)
+(cd integrations/ckprompt/examples/composed && go run . promptkit requirements show briefing --campaign spring --var mode=full --format yaml)
+(cd integrations/ckprompt/examples/composed && go run . promptkit requirements validate briefing --campaign spring --input topic=fixtures/topic.txt)
+(cd integrations/ckprompt/examples/composed && go run . promptkit requirements validate briefing --campaign spring --input topic=fixtures/topic.txt --var mode=full --input notes=fixtures/notes.txt --format yaml)
+(cd integrations/ckprompt/examples/composed && go run . promptkit test reachability --campaign spring --prompt briefing --profile spring)
+(cd integrations/ckprompt/examples/composed && go run . promptkit test all --campaign spring --prompt briefing --profile spring)
+(cd integrations/ckprompt/examples/composed && go run . session restore session-42 --campaign spring)
 ```
 
 The [consumer guide](consumers/guide.md) explains how their public API usage
 fits together.
+
+
+## Shell completion validation
+
+The opt-in interactive completion checks require Bash, Zsh, Fish, Python with
+`pexpect`, and the Bash completion package. The harness starts a clean Bash
+and sources `/usr/share/bash-completion/bash_completion` by default. Set
+`COMPLETION_BASH_INIT` to your installation's initialization file if it is
+elsewhere. See the [operator setup](cli.md#shell-completion) for ordinary use.
+
+```sh
+COMMANDKIT_COMPLETION_SHELLS=1 go test -count=1 -run '^TestCompletionShells$' ./internal/cobra
+COMMANDKIT_COMPLETION_SHELLS=1 go test -count=1 -run '^TestCompletionConsumerInShells$' .
+```

docs/internal/overview.md

@@ -1,48 +1,123 @@
 # Internal package overview
 
-CommandKit ships one public package, `commandkit`, and one internal package,
-`internal/cobra`. This inventory describes the current implementation; the
-[architecture policy](../policy/architecture.md) owns normative boundaries and
-[ADR 0003](../adr/0003-public-facade.md) records the public package boundary.
+CommandKit's core module contains the public `commandkit` facade, the private
+neutral metadata package, and the internal Cobra adapter. Two nested Go modules
+own the optional ConfigKit and PromptKit integrations. The
+[architecture policy](../policy/architecture.md) owns normative boundaries;
+this page inventories the implemented owners.
 
-## `commandkit`
+The core and ckconfig modules declare `go.maximumdirect.net/commandkit` and
+`go.maximumdirect.net/ckconfig`. Ckprompt retains the old module and import
+identities until its planned matched release; Go treats those identities as
+distinct.
 
-The root package declares the public API and owns the instance registry, typed
-command input preparation, invocation coordination, standard handlers, and
-provider adapters. Configuration reports adapt ConfigKit's public records and
-writers. PromptKit scope and definition handlers use PromptKit's public
-inspection methods and map their results to CommandKit-owned reports.
+## Root `commandkit`
 
-The root lazily caches one immutable neutral bridge tree per `App`, invalidating
-it after successful nonempty registration. For each `Execute`, it prepares one
-adapter session and reuses that session for parsing, help, and usage. If a
-callback registers commands during execution, metadata-dependent presentation
-refreshes without repeating input callbacks. The root still prepares typed
-input, invokes application/standard handlers, and coordinates outcomes and
-diagnostic delivery. Application callbacks and their supported error identity
-are handled in the root through its typed contracts.
+The root facade owns captured canonical command declarations, application-owned
+routing rules, binding conversion, invocation coordination, the per-App
+registries, standard help/version commands, invocation reporting, and outcome
+finalization.
+Its dependency graph has no ConfigKit or PromptKit integration dependency.
+Applications provide typed callbacks and install routing rules alongside the
+complete canonical command tree through the same batch API.
 
-Configuration registration owns and normalizes its declarations, then prepares
-ordered scopes, name lookup, installed operations, and a discovery DTO. Command
-handlers reuse that private metadata; each invocation still creates its context
-and invokes acquisition only for selected scopes.
+Canonical commands own handlers and parsing/help metadata; routing rules resolve
+entered command paths and flag spellings to those canonical records without
+adding command nodes or handlers. The shared command compiler prepares supplied
+values before constructing input. The batch installer validates retained
+issues, placement, and collisions across both registries before publishing
+either. Each invocation uses one routing snapshot and backend session; a
+successful registration invalidates the snapshot for a later invocation. The
+root package owns app input and callback execution, not provider configuration
+semantics.
+
+Each execution creates one reporter backed by the caller's result and diagnostic
+writers. The Cobra adapter returns parsed values, flag spellings, and reporting
+flag occurrences. Core reduces those occurrences in entered order after route
+resolution, applies the final mode and progress selection, and presents any
+collected parser events through that selection. The selected mode therefore
+applies to command execution, help, and version; routing and parsing failures
+remain visible in every mode.
+
+The reporter owns invocation-scoped visibility, message formatting, managed
+report rendering, delivery observations, and finalization. It presents queued
+messages after the handler returns, then a failed outcome's explanation, and
+closes its handles before `Execute` returns. It records rendering and write
+errors separately for result and diagnostic destinations; the returned
+`Outcome.Presentation` exposes those observations independently from the
+operation cause. The reporter does not retain a transcript and does not close
+or flush caller-owned writers.
+
+Internally, one reporting-state mutex guards visibility, queued messages,
+destination state, and delivery errors while serializing reporter operations
+and writes. Rendering callbacks execute within that coordination boundary, so
+they must not recursively submit or render through the same reporter. This is
+an implementation detail supporting the callback contract; the mutex does not
+coordinate writes made outside the reporter.
+
+## `internal/alias` and `internal/commandpath`
+
+`internal/commandpath` provides shared path parsing and token operations used by
+declaration capture, routing, and backend selection. `internal/alias` compiles
+application routing rules, resolves command prefixes while retaining token
+provenance, and validates command-route termination. Neither package owns
+handlers, application factories, or backend types.
+
+## `internal/commandmeta`
+
+This package owns the private neutral command, flag, argument, parsed-value, and
+failure records shared between the public facade and backend adapter. It does
+not import Cobra or optional integration modules. The facade and adapter
+exchange these records without exporting backend-specific types.
 
 ## `internal/cobra`
 
-This package owns the Cobra-specific command tree, argument/flag parsing,
-and help rendering. A session owns one mutable backend tree for an invocation;
-parsing and presentation reuse it. Backend commands map directly to neutral
-declarations, and Cobra parent links reconstruct only the selected command path.
-The adapter returns raw parsed values and neutral syntax-failure data consumed
-by the root package. It does not import `commandkit` and does not own registry
-policy, public command declarations, provider loading, or standard inspection
-report rendering.
+This package owns the Cobra command tree, argument/flag parsing, and help
+rendering. A session owns the mutable backend tree for one invocation; parsing
+and presentation reuse that session. The adapter returns raw values and neutral
+syntax failures to core. It does not own the registry, typed input preparation,
+integration declarations, provider acquisition, or native report rendering.
+Cobra and pflag imports remain inside this package.
 
-## External implementation boundaries
+## Optional modules
 
-ConfigKit owns typed configuration loading, source history, validation,
-resolution, and path explanations. PromptKit owns captured engine
-configuration, prompt definitions, profile inheritance, and named inspections.
-CommandKit depends on their public module APIs and does not maintain parallel
-schemas. Cobra and pflag are confined behind the internal adapter; YAML report
-encoding is performed by the root package.
+`integrations/ckconfig` owns ConfigKit adaptation, scope capture, the standard
+`config` command family, and native validate/show/sources/explain/diff behavior.
+It depends on the public core facade and ConfigKit; it does not depend on
+PromptKit. Each selected scope or comparison side receives an independently
+initialized input, while one suite-owned state value is shared by an invocation's
+acquisitions or comparison callback.
+
+`integrations/ckprompt` owns PromptKit engine loading, configuration-scope
+adaptation and native comparison, plus optional prompt/profile/backend/namespace/
+collection catalogs, named inspection, native requirements discovery,
+concrete request validation, and native smoke testing. Validation and smoke
+testing delegate to PromptKit and are independently opted into a suite. Smoke
+operations use the application's native engine and its configured client or
+probes. The integration uses public core and ckconfig contracts plus PromptKit's
+public APIs. It does not add a configuration family when its declaration is
+installed; callers compose `ckprompt.ConfigScope` with `ckconfig.Command`
+separately when they want configuration operations alongside PromptKit
+commands.
+
+The three maintained consumers live at `examples/core`,
+`integrations/ckconfig/examples/simple`, and
+`integrations/ckprompt/examples/composed`. The
+[consumer guide](../consumers/guide.md) links to those examples and explains the
+public wiring. Run tests from each module; root `./...` does not traverse the
+nested module directories. The [development guide](../development.md) gives the
+workspace test commands. Workspace builds do not establish independent module
+graph isolation.
+
+## Upstream implementation boundaries
+
+ConfigKit owns configuration decoding, validation, source history, and path
+explanations. PromptKit owns its captured engine configuration, prompt
+definitions, profile inheritance, named inspection, requirements discovery,
+and concrete request validation, and native smoke-test semantics. CommandKit
+adapts those public contracts without maintaining parallel schemas. Explicit
+native smoke operations may use the configured client or probes; other
+inspection, catalog, and request-validation paths do not make model calls.
+Native request validation may load resources and artifacts, render messages,
+and perform applicable configuration or credential checks through PromptKit.
+Application loaders and domain behavior remain application owned.

docs/oss/attribution.md

@@ -1,57 +1,5 @@
 # Open Source Attribution Notices
 
-## ConfigKit
-
-Selected module: `gitea.maximumdirect.net/eric/ConfigKit` at `v0.5.0`.
-
-Copyright (C) 2026 Eric Rakestraw
-
-SPDX-License-Identifier: LGPL-3.0-or-later
-
-License and notices: [LGPL v3.0](../../LICENSE) |
-[LICENSE](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/dc09959cca4e105f49ec316c6d4ba585bd2340bd/LICENSE).
-
-[Source](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/dc09959cca4e105f49ec316c6d4ba585bd2340bd).
-
-## PromptKit
-
-Selected module: `gitea.maximumdirect.net/eric/promptkit` at `v0.12.0`.
-
-Copyright (C) 2026 Eric Rakestraw
-
-SPDX-License-Identifier: LGPL-3.0-or-later
-
-License and notices: [LGPL v3.0](../../LICENSE) |
-[LICENSE](https://gitea.maximumdirect.net/eric/promptkit/src/commit/4b8169da286917fde7875425bb32b799b12c6af3/LICENSE).
-
-[Source](https://gitea.maximumdirect.net/eric/promptkit/src/commit/4b8169da286917fde7875425bb32b799b12c6af3).
-
-## PromptKit OpenRouter Catalog
-
-Selected module: `gitea.maximumdirect.net/eric/promptkit-backend-openrouter/v3` at `v3.20260930.0` (transitive dependency).
-
-Copyright (C) 2026 Eric Rakestraw
-
-SPDX-License-Identifier: MIT
-
-License and notices: [MIT](licenses/MIT.txt) |
-[LICENSE](https://gitea.maximumdirect.net/eric/promptkit-backend-openrouter/src/commit/f17d208cb7ad1fb043cda2266cd3011d11b40aa0/LICENSE).
-
-[Source](https://gitea.maximumdirect.net/eric/promptkit-backend-openrouter/src/commit/f17d208cb7ad1fb043cda2266cd3011d11b40aa0).
-
-## PromptKit Rakestrawhome Catalog
-
-Selected module: `gitea.maximumdirect.net/eric/promptkit-backend-rakestrawhome/v3` at `v3.20260930.0` (transitive dependency).
-
-Copyright (C) 2026 Eric Rakestraw
-
-SPDX-License-Identifier: MIT
-
-License and notices: [MIT](licenses/MIT.txt) |
-[LICENSE](https://gitea.maximumdirect.net/eric/promptkit-backend-rakestrawhome/src/commit/993443d88c451901f4c917fa00c204fd3b54d28d/LICENSE).
-
-[Source](https://gitea.maximumdirect.net/eric/promptkit-backend-rakestrawhome/src/commit/993443d88c451901f4c917fa00c204fd3b54d28d).
-
 ## Cobra
 
 Selected module: `github.com/spf13/cobra` at `v1.10.1`.
@@ -149,31 +97,6 @@ License and notices: [BSD 2-Clause](licenses/BSD-2-Clause.txt) |
 
 [Source](https://github.com/russross/blackfriday/tree/4c9bf9512682b995722660a4196c0013228e2049).
 
-## JSON Schema
-
-Selected module: `github.com/santhosh-tekuri/jsonschema/v6` at `v6.0.2` (transitive dependency).
-
-SPDX-License-Identifier: Apache-2.0
-
-License and notices: [Apache 2.0](licenses/Apache-2.0.txt) |
-[LICENSE](https://github.com/santhosh-tekuri/jsonschema/blob/29cbed948d24a04700eb94436416b18a07953b71/LICENSE).
-
-[Source](https://github.com/santhosh-tekuri/jsonschema/tree/29cbed948d24a04700eb94436416b18a07953b71).
-
-## Go text
-
-Selected module: `golang.org/x/text` at `v0.14.0` (transitive dependency).
-
-Copyright (c) 2009 The Go Authors. All rights reserved.
-
-SPDX-License-Identifier: BSD-3-Clause
-
-License and notices: [BSD 3-Clause](licenses/BSD-3-Clause.txt) |
-[LICENSE](https://go.googlesource.com/text/+/6c97a165dd661335ff7bce6104a008558123c353/LICENSE) |
-[PATENTS](https://go.googlesource.com/text/+/6c97a165dd661335ff7bce6104a008558123c353/PATENTS).
-
-[Source](https://go.googlesource.com/text/+/6c97a165dd661335ff7bce6104a008558123c353).
-
 ## gocheck
 
 Selected module: `gopkg.in/check.v1` at `v0.0.0-20161208181325-20d25e280405` (transitive test dependency).
@@ -213,3 +136,55 @@ License and notices: [CC BY-SA 4.0](licenses/CC-BY-SA-4.0.txt) |
 [Source](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843).
 
 [Source](https://gitea.maximumdirect.net/eric/policy/src/commit/e833faddf120c789a9b45348edaf75720de16348).
+
+## ReleaseKit
+
+Selected module: `go.maximumdirect.net/releasekit` at `v0.9.0` (selected Go tool; not a runtime import).
+
+Copyright (C) 2026 Eric Rakestraw
+
+SPDX-License-Identifier: LGPL-3.0-or-later
+
+License and notices: [LGPL v3.0](../../LICENSE) |
+[LICENSE](https://forge.maximumdirect.net/base-layer/releasekit/src/commit/2180aa868ec2caa95fc8279fd59d5f0ebac41bd4/LICENSE).
+
+[Source](https://forge.maximumdirect.net/base-layer/releasekit/src/commit/2180aa868ec2caa95fc8279fd59d5f0ebac41bd4).
+
+## Goldmark
+
+Selected module: `github.com/yuin/goldmark/v2` at `v2.1.6` (ReleaseKit tool dependency).
+
+Copyright (c) 2019 Yusuke Inuzuka
+
+SPDX-License-Identifier: MIT
+
+License and notices: [MIT](licenses/MIT.txt) |
+[LICENSE](https://github.com/yuin/goldmark/blob/a8d4ee5a0bd7d5493fdd1e339b4e75df92f8684c/LICENSE).
+
+[Source](https://github.com/yuin/goldmark/tree/a8d4ee5a0bd7d5493fdd1e339b4e75df92f8684c).
+
+## Go modules
+
+Selected module: `golang.org/x/mod` at `v0.40.0` (ReleaseKit tool dependency).
+
+Copyright 2009 The Go Authors.
+
+SPDX-License-Identifier: BSD-3-Clause
+
+License and notices: [BSD 3-Clause](licenses/BSD-3-Clause.txt) |
+[LICENSE](https://go.googlesource.com/mod/+/d3398d06de5fa5c71083d3d1c26f2cda73508e0f/LICENSE).
+
+[Source](https://go.googlesource.com/mod/+/d3398d06de5fa5c71083d3d1c26f2cda73508e0f).
+
+## Go tools
+
+Selected module: `golang.org/x/tools` at `v0.49.0` (ReleaseKit tool graph dependency).
+
+Copyright (c) 2009 The Go Authors. All rights reserved.
+
+SPDX-License-Identifier: BSD-3-Clause
+
+License and notices: [BSD 3-Clause](licenses/BSD-3-Clause.txt) |
+[LICENSE](https://go.googlesource.com/tools/+/18332fec72972efbb8ab9881984fec2d8cfc2b58/LICENSE).
+
+[Source](https://go.googlesource.com/tools/+/18332fec72972efbb8ab9881984fec2d8cfc2b58).

docs/policy/architecture.md

@@ -2,16 +2,18 @@
 
 **Base Policy Version:** 1.3
 
-**Last Updated**: 2026-10-08
+**Last Updated**: 2026-10-26
 
 **Upstream Source:** [architecture.md](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/architecture.md)
 
 ## Purpose And Ownership
 
 CommandKit is an opinionated Go library for standard inspection commands,
-consistent CLI syntax, and reduced application command infrastructure. This
-policy owns normative responsibility boundaries, dependency direction, and
-architectural constraints. ADRs own decision rationale; the
+consistent CLI syntax, and reduced application command infrastructure. It provides
+useful operator access to capabilities owned by its integrated libraries through
+shared command vocabulary, registration, selection, coordination, presentation,
+and invocation outcomes. This policy owns normative responsibility boundaries,
+dependency direction, and architectural constraints. ADRs own decision rationale; the
 [implementation roadmaps](../development.md#task-specific-reading-guide) own
 proposals, sequencing, and implementation status.
 
@@ -44,14 +46,23 @@ flexibility to express genuine application requirements within one command model
 
 [ADR 0001](../adr/0001-command-dispatch-and-inputs.md) records the selected
 CommandKit-owned dispatcher, per-instance registry, and typed-input model.
+[ADR 0011](../adr/0011-captured-declarations-and-installation.md) refines declaration
+capture, installation, optional-family ownership, and invocation input lifetimes.
 
 CommandKit owns dispatch, common parsing, presence tracking, help, shared syntax
-diagnostics, and the handlers and observable contracts of its standard families.
+diagnostics, and the handlers and CLI contracts of its standard families.
+The integrated libraries own the domain semantics exposed through those handlers.
 Applications register domain commands outside those families and own their
 meaning, effects, domain validation, artifacts, and operational outcomes.
-Namespaces provide the ownership boundary: standard `config` and an installed
-`promptkit` family remain CommandKit-owned. CommandKit reports registration errors
-for attempts to replace their handlers or add private operations beneath them.
+Namespaces provide the ownership boundary. Core construction reserves help and
+version. Optional standard families, including config and promptkit, own their
+root namespace when installed; importing an integration or declaring an absent
+family claims no namespace. An application may occupy an uninstalled family name.
+Installing the standard family then reports a collision, as does application
+registration after the standard family is installed. Neither order merges groups
+or replaces handlers. Installed standard families cannot acquire private
+application operations beneath them. Standard-family declarations are root-only;
+nesting a real family beneath another group reports an assembly error.
 
 Applications own their executable entry points, context creation, signals,
 stream selection, runtime construction, and final process exit. CommandKit
@@ -64,16 +75,31 @@ Its documentation recommends the same grammar and vocabulary for application-own
 commands, including those outside its dispatcher, under
 [ADR 0006](../adr/0006-command-grammar.md).
 
-CommandKit preserves application-supplied outcome classifications and supported
-error identity. It assigns responsibility for its diagnostics, avoids duplicate
-presentation through its own paths, and reports write failures. Caller callbacks
-retain control of their own output. [ADR 0005](../adr/0005-invocation-outcomes.md)
-describes the outcome and delivery model.
-
 Use explicit instance construction and composable command registration, not
-package-global or import-time registries. One definition supplies routing,
-parsing, and help metadata. Duplicate paths and attempts to replace reserved
-commands report errors rather than letting registration order select a winner.
+package-global or import-time registries. Applications and integrations supply
+captured canonical command declarations through the core installation API.
+Declaration factories capture metadata, bindings, and callback references eagerly;
+construction errors remain attached for installation to report. Capture the
+metadata collections needed to keep later edits to a source declaration from
+changing a returned command. Application callback objects retain their ownership.
+Canonical command declarations own handlers, parsing metadata, and help
+metadata. Applications may provide separate routing rules in the same
+installation batch; these rules resolve invocations to canonical commands and
+do not add command nodes, handlers, or flags.
+
+Validate each installation batch before mutating the instance registry. A failed
+construction yields no usable application; a failed later registration leaves the
+existing registry intact. Separate successful registration calls are not one
+transaction. Duplicate canonical paths and attempts to replace reserved commands
+report errors rather than letting registration order select a winner. Identical
+routing rules are idempotent; competing targets for the same source and scope
+report an error. Command-scoped flag routing refers to an exact canonical
+command path.
+
+Explicit absent-command declarations contribute no commands, help entries, or
+namespace claims; attached errors are reported before skipping absence. An invalid
+zero declaration is not absence. Integrations define their own empty-suite
+semantics and retain invalid wiring errors even when capabilities are narrowed.
 
 Standard families are assembled from declared provider capabilities. Each family
 specifies its own resources and supported operations; shared verbs retain
@@ -95,12 +121,69 @@ inspection/execution loading and focused acquisition callbacks are recommended
 integration practices. Independent consumer use of other CLI frameworks remains
 application-owned.
 
+## Invocation Reporting And Outcomes
+
+Use one reporting facility per invocation for command results, immediate messages,
+and deferred messages. Core owns shared visibility, formatting, delivery, and
+finalization. Applications and integrations choose their report content and
+messages; callers choose the destinations. [ADR 0014](../adr/0014-invocation-reporting.md)
+extends the outcome and delivery model in [ADR 0005](../adr/0005-invocation-outcomes.md).
+
+Applications decide how to respond to domain-specific errors. CommandKit may
+provide shared helpers for carrying, inspecting, and presenting errors while
+leaving those decisions with the application. Supplying an error cause alone
+does not select an outcome or generate an operator-facing message. CommandKit
+handles its own errors, including routing, parsing, and presentation failures.
+
+Preserve application-defined domain classifications and supplied error identity.
+Report rendering and delivery failures separately from the command's explanation
+and cause, applying the outcome rules in ADR 0005 and ADR 0014. Intentionally
+suppressed output is not a delivery failure. Present terminal failure explanations
+after normal reporting finishes, avoid duplicate presentation through core's own
+paths, and retain the explanation and any supplied cause in the returned outcome.
+
+Keep reporting state scoped to the invocation's presentation and returned outcome.
+Logging and message history remain application concerns.
+
 ## Handler Inputs And Invocation State
 
 Handlers receive typed input structs with explicit flag and operand bindings.
 Use presence-aware fields where omission matters; preserve explicitly supplied
 empty, false, and zero values independently of parser defaults. Context, streams,
-and execution dependencies are separate from CLI inputs.
+and execution dependencies are separate from CLI inputs. Integration suites keep
+their typed CLI input separate from shared acquisition state. For a configuration
+operation, initialize and populate each selected scope's input independently,
+applying only its applicable selector bindings; initialize shared state once for
+the selected inspection invocation. Configuration input validation receives the
+selected scope identity together with its applicable typed input. Named definition
+inspection uses one input and one shared state. Complete applicable preflight
+and input checks before shared state initialization and provider acquisition.
+Factories need not run after a failure and remain uninvoked during construction,
+installation, help, version, and scope discovery.
+
+For two-selection configuration comparison, prepare and check each side's input
+separately with its scope identity and selection, applying the same applicable
+converted selector values to both. Finish both checks before initializing shared
+state once and invoking the integration-owned pair provider under
+[ADR 0012](../adr/0012-typed-configuration-comparison-pairs.md). Required provider
+wiring follows declared capabilities; a comparison-only scope does not require
+an unrelated ordinary acquisition callback.
+
+Omitted input and state factories supply the respective type's zero value,
+including nil for pointers. Caller factories and callbacks retain responsibility
+for objects they return or reference; do not promise arbitrary deep copies,
+repair caller-created aliases, or silently allocate arbitrary pointer types.
+Core-owned parsed collections stay independent where values are applied to
+separate inputs.
+
+Provide typed binding composition through supported public core contracts when
+integrations need to apply captured converted values to selected inputs. Preserve
+binding identity and presence without exposing private setters or backend state.
+Required-value checks apply to the selected binding subset. Missing required
+operator input is a usage failure; invalid binding selection or destination is a
+wiring failure with operational classification when detected during invocation.
+Metadata defects detectable during assembly remain installation errors. Input
+composition does not create a second parser or a raw-argument handler model.
 
 CommandKit keeps parsed values, collections, and presence from one invocation out
 of subsequent runs. Storage allocation and safe reuse are implementation choices;
@@ -114,10 +197,20 @@ Keep input declarations available without application initialization.
 
 ## Public Facade And Dependency Direction
 
-[ADR 0003](../adr/0003-public-facade.md) records the root `commandkit` facade and
-internal adapter boundary. The root is the sole initial supported public package
-and defines CommandKit's public named types. Additional public packages require a
-deliberate decision based on a durable consumer responsibility.
+[ADR 0010](../adr/0010-optional-integration-modules.md) scopes the root
+`commandkit` facade to the core module and selects separate optional integration
+modules with their own public package contracts. It partially supersedes
+[ADR 0003](../adr/0003-public-facade.md), whose remaining facade and internal
+adapter principles apply to the core and integrations alike.
+
+The core owns command declarations, registration, bindings, dispatch, help/version,
+shared syntax, diagnostics, and outcomes. Each integration owns its standard
+handlers, provider contracts, reports, adapters, and integration-specific public
+types. Dependencies point from integrations toward the core; an integration may
+depend on another integration when its responsibility requires that relationship.
+Document those dependencies. Core public signatures, implementation imports, and
+module requirements remain independent of optional integration libraries,
+including dependencies introduced through tests, examples, or tools.
 
 Public handles retain private implementation state and expose explicitly selected
 methods. Any forwarding and conversions must preserve type identity, value
@@ -125,9 +218,9 @@ ownership, callback lifetime, presence, and supported public error semantics. Do
 not alias public types to internal or backend types, anonymously embed those types
 to promote methods, or expose implementation bridge methods.
 
-Straightforward implementation may live in the root package without expanding
-its exports. Introduce internal packages, interfaces, and conversions where they
-simplify implementation or protect the backend boundary. Package organization and
+Straightforward implementation may live in an owning public package without
+expanding its exports. Introduce internal packages, interfaces, and conversions
+where they simplify implementation or protect the backend boundary. Package organization and
 the amount of internal layering follow implementation needs.
 
 Public signatures, fields, callbacks, constraints, and method sets must not expose
@@ -138,9 +231,13 @@ retain their documented handling; this boundary does not require inspecting or
 transforming arbitrary application objects.
 
 Standard contracts such as `context.Context` and `io.Writer` remain appropriate.
-Public types from integration libraries, such as ConfigKit and PromptKit, may be
-selected as deliberate dependencies. Application-owned input types remain
-application-owned. Do not expand exports merely to simplify internal assembly.
+Upstream public types may be selected as deliberate dependencies in the
+integrations that own them; that permission does not justify optional library
+dependencies in the core. Core owns shared presentation categories,
+and integrations adapt upstream diagnostics while preserving selected outcome
+and error semantics. Application-owned input types remain application-owned.
+Expose narrow core composition contracts for demonstrated integration needs,
+without exporting private assembly or backend structures.
 
 ## Backend And Library Integration
 
@@ -158,9 +255,22 @@ them; a public backend selection or plugin framework is not part of the design.
 ConfigKit and PromptKit own configuration composition, provenance, inspection
 semantics, secret classification, and native rendering. Applications provide
 schemas, acquisition, domain resolution and validation, and construction of
-inspection providers. CommandKit exposes those capabilities without implementing
-a parallel configuration or prompt engine. Use independently released public
-contracts; do not import sibling internal packages or depend on adjacent checkouts.
+inspection providers. CommandKit exposes those capabilities through supported
+upstream APIs. The public contract of the adopted library version governs their
+meaning and disclosure rules. When CommandKit adopts an upstream revision,
+changes to those semantics flow through its integration. Adaptation and
+documentation follow the adopted contract; descriptions of upstream behavior
+do not establish a separate, fixed CommandKit specification of that behavior.
+
+CommandKit owns presentation and may summarize or transform returned safe data
+for different operator needs. Reports can evolve in format, organization, and
+detail while respecting upstream disclosure rules and the evidence supplied by
+the capability. Exact report contracts belong in the CLI reference when
+implemented; changes to CommandKit's published contracts follow the release
+policy.
+
+Use independently released public contracts; do not import sibling internal
+packages or depend on adjacent checkouts.
 
 Use narrow integration contracts, reusing upstream public types where useful and
 introducing CommandKit-owned abstractions where they simplify integration.
@@ -170,8 +280,10 @@ Concrete integration needs guide provider representations under
 Native report writers and safe inspection data preserve owning-library semantics.
 Loading all selected views before report output is a `config show` decision under
 [ADR 0007](../adr/0007-native-yaml-reports.md); other inspection operations define
-their own output timing. Semantic comparison uses supported safe snapshots and
-reports sensitivity gaps under [ADR 0008](../adr/0008-semantic-configuration-diff.md).
+their own output timing. Semantic comparison exposes the adopted upstream
+comparison API, carrying its results and relevant metadata through the provider
+boundary. CommandKit owns report presentation under
+[ADR 0008](../adr/0008-semantic-configuration-diff.md).
 
 ## Scope And Non-goals
 

docs/policy/documentation.md

@@ -2,7 +2,7 @@
 
 **Base Policy Version:** 1.11
 
-**Last Updated**: 2026-10-06
+**Last Updated**: 2026-10-10
 
 **Upstream Source:** [documentation.md](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/documentation.md)
 
@@ -147,6 +147,15 @@ mechanisms only.
 
 ## Architecture Decision Records
 
+ADRs record durable architectural decisions: responsibility boundaries,
+ownership, significant constraints, and the reasons for choosing them. A settled
+implementation or presentation choice does not automatically belong in an ADR.
+Ask whether changing the detail would alter the architecture or represent
+reasonable evolution within it. Details that can evolve within the chosen
+architecture belong in API or CLI contracts, implementation documentation, or
+roadmaps. Describe upstream behavior as context without turning it into an
+independent project guarantee.
+
 Use sequentially numbered ADR filenames such as
 `0001-record-architecture-decisions.md`. Follow the lightweight Nygard format:
 

docs/policy/release.md

@@ -2,7 +2,7 @@
 
 **Base Policy Version:** 1.6
 
-**Last Updated**: 2026-10-08
+**Last Updated**: 2026-10-11
 
 **Upstream Source:** [release.md](https://gitea.maximumdirect.net/eric/policy/src/commit/e833faddf120c789a9b45348edaf75720de16348/docs/policy/release.md)
 
@@ -16,17 +16,22 @@ Adopt stronger verification or reproducibility requirements through an explicit
 project-specific decision justified by the intended audience and support needs.
 
 The repository-specific commands belong in `docs/release.md`. Historical release
-summaries belong in `docs/releases/`. The procedure must agree with the adopted
-policy and link to it rather than introduce additional release requirements.
+summaries belong in each released module's `docs/releases/` directory. The
+procedure must agree with the adopted policy and link to it rather than introduce
+additional release requirements.
 
 ## CommandKit Release Scope
 
-CommandKit releases source-only Go modules. Standard CLI behavior is exposed by
-consuming applications; CommandKit does not declare binary deliverables or a
-cross-platform build matrix. ReleaseKit v0.3.0 is selected as the maintainer
-publication tool. The [release procedure](../release.md) owns its source-only
-workflow and repository-specific commands; the integration adds no application
-command family or runtime ReleaseKit import.
+CommandKit independently versions three source-only Go modules: the root core,
+`integrations/ckconfig`, and `integrations/ckprompt`. Standard CLI behavior is
+exposed by consuming applications; CommandKit does not declare binary
+deliverables or a cross-platform build matrix. ReleaseKit v0.9.0 is selected as
+the maintainer publication tool. Maintainers may separately deliver page-only
+Gitea releases from tagged source; delivery has its own outcome and URL. The
+[release procedure](../release.md) owns the selected-module workflow, release
+order, and repository-specific commands;
+the integration adds no application command family or runtime ReleaseKit
+import.
 
 ## Release Model And Completion
 
@@ -123,9 +128,18 @@ rules above.
 
 ## Release Documentation And Preparation
 
-Every new release must include `docs/releases/<version>.md` in the tagged
-source tree. Use the complete version tag as the filename and begin with a
-title containing the product name and that exact version.
+Every new module release must include `docs/releases/<version>.md` relative to
+the selected module directory in the tagged source tree. Here `<version>` is
+that module's stable semantic version, `vMAJOR.MINOR.PATCH`; use it as the
+filename and begin with a title containing the selected release profile's
+product name and that exact semantic version.
+
+The semantic version and full Git tag are distinct. The root module's tag is
+its semantic version; an integration's full tag includes its module prefix,
+as recorded in the [release procedure](../release.md#modules-versions-notes-and-shared-files).
+Use the full tag for Git refs and immutable source URLs, with repository-relative
+paths identifying the selected module's note, grant, license, and attribution.
+The module prefix is not part of the note filename or title's version.
 
 Include a short summary and any relevant compatibility impact or upgrade
 instructions. Choose sections suited to the release and keep the note

docs/policy/testing.md

@@ -2,7 +2,7 @@
 
 **Base Policy Version:** 1.3
 
-**Last Updated**: 2026-10-07
+**Last Updated**: 2026-10-17
 
 **Upstream Source:** [testing.md](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/testing.md)
 
@@ -70,7 +70,7 @@ implemented:
 
 Use external-package consumer tests for facade semantics and real backend
 integration where correctness depends on that interaction. Internal package
-tests own focused mechanisms. Do not retest the dependencies' complete suites.
+tests own focused mechanisms.
 Boundary checks protect selected architectural constraints; behavioral evidence
 protects invocation semantics and ownership through conversions.
 
@@ -79,7 +79,7 @@ concurrency guarantees only if deliberately selected. Coverage targets, race
 testing, static analysis, example gates, and platform matrices require their own
 risk justification; another library's workflow does not establish them here.
 
-To the extent the following features are present in the application, prioritize tests for:
+For behavior owned by CommandKit, prioritize tests for:
 
 1. Public and package-level contracts.
 2. Domain rules and important invariants.
@@ -106,6 +106,41 @@ application's guarantees. Account for protection already provided at other layer
 
 Do not add tests merely because a function, branch, or line exists. Do not add a test when the same meaningful risk is already adequately protected elsewhere.
 
+## Upstream integration testing ownership
+
+CommandKit tests the interfaces and adapters through which it exposes upstream
+APIs. ConfigKit, PromptKit, and other integrated libraries own tests establishing
+the correctness of their domain functionality. Trust their public contracts;
+CommandKit tests must not independently establish whether those libraries
+implement their claimed domain functionality. This applies to partial feature
+checks as well as complete suites.
+
+Integration assertions should establish CommandKit-owned behavior:
+
+- CLI choices, typed inputs, configuration selection, and context reach the
+  appropriate upstream API with the intended values.
+- CommandKit performs its selected coordination and preserves returned data,
+  diagnostics, and supported error identity across adaptation.
+- CommandKit's reports and invocation outcomes correctly represent the returned
+  evidence, including presence, null, empty, and redacted values where applicable.
+- Command availability, input/state lifetimes, cancellation handling, and output
+  delivery follow CommandKit's contracts.
+
+For example, test that a namespace choice becomes the intended native listing
+filter, rather than testing which resources PromptKit considers members of a
+namespace. Test faithful presentation of ConfigKit's returned source evidence,
+rather than its destination resolution, version checking, or sensitivity
+classification. Test request forwarding and returned-error handling, rather than
+whether PromptKit correctly detects missing artifacts or invalid templates.
+
+A real upstream engine or result can be a useful fixture for a focused
+integration test. Its use does not change assertion ownership: the test should
+detect incorrect CommandKit adaptation, not independently establish upstream
+domain correctness. Use the simplest suitable fixture or test double; this
+boundary does not require new mocking interfaces or prohibit real dependencies
+in tests. CommandKit's own parsing, registration, coordination, presentation,
+and outcome behavior remain within its testing scope.
+
 ## Choose the right test boundary
 
 Choose the narrowest stable boundary that expresses the behavior clearly and

docs/release.md

@@ -1,47 +1,49 @@
 # CommandKit release procedure
 
-## Scope and prerequisites
+## Scope and release order
 
-CommandKit publishes source-only Go module releases: an immutable annotated
-version tag for one committed candidate and its matching checked-in release
-note. This procedure does not publish a hosted release page, binaries,
-checksums, or other delivery assets, and it requires no delivery credentials.
+CommandKit publishes source-only Go module releases. Each module has an
+independent version and immutable annotated tag. A successful source-tag push
+completes the source release. A separate local delivery command can publish a
+Gitea release page; there are no binaries,
+checksums, or other delivery assets. CI, module proxy availability, and consumer
+installation are not completion gates.
 
-Use branch `main`, remote `origin`, and the expected effective push endpoint
-`https://gitea.maximumdirect.net/eric/CommandKit.git`. The profile enforces that
-endpoint during publication. The maintainer needs the selected
-[release toolchain](#release-toolchain), Git with push access to `origin`, and a
-POSIX shell.
+Publish in dependency order: core, then `ckconfig`, then `ckprompt`. The
+integration modules require the preceding CommandKit releases, so prepare and
+publish each module only after its CommandKit dependencies are available. A root
+release runs only the root module's default suite; it need not run suites for
+independently released integrations.
 
-This procedure follows the [release policy](policy/release.md); the release-note
-footer follows the [OSS discoverability policy](policy/oss.md#discoverability).
+Use branch `main`, remote `origin`, and expected effective push endpoint
+`ssh://git@forge.maximumdirect.net:22222/base-layer/commandkit.git`. The selected
+module profile enforces the endpoint. The maintainer needs the selected
+[release toolchain](#release-toolchain), Git push access, and a POSIX shell.
+This procedure follows the [release policy](policy/release.md); release-note
+footers follow the [OSS discoverability policy](policy/oss.md#discoverability).
 
-ReleaseKit v0.3.0 owns candidate validation, publication guards, annotated tag
-creation, tag publication, and outcome reporting. The repository profile selects
-only its default candidate suite. The launcher bootstraps the module-selected
-native executable into ignored `.releasekit/` storage and invokes its `publish`
-command. The upstream [CLI reference](https://gitea.maximumdirect.net/eric/ReleaseKit/src/commit/e43df4416e0ed987349b2ea04a2c68c25e552772/docs/cli.md),
-[profile reference](https://gitea.maximumdirect.net/eric/ReleaseKit/src/commit/e43df4416e0ed987349b2ea04a2c68c25e552772/docs/config.md),
-and [publication guide](https://gitea.maximumdirect.net/eric/ReleaseKit/src/commit/e43df4416e0ed987349b2ea04a2c68c25e552772/docs/consumers/publish.md)
-own detailed command, profile, and status contracts.
+ReleaseKit v0.9.0 (`go.maximumdirect.net/releasekit`) owns candidate validation,
+publication guards, tag creation, tag publication, and outcome reporting.
+Its pinned public contracts are the
+[CLI reference](https://forge.maximumdirect.net/base-layer/releasekit/src/commit/2180aa868ec2caa95fc8279fd59d5f0ebac41bd4/docs/cli.md),
+[profile reference](https://forge.maximumdirect.net/base-layer/releasekit/src/commit/2180aa868ec2caa95fc8279fd59d5f0ebac41bd4/docs/config.md),
+the [publication guide](https://forge.maximumdirect.net/base-layer/releasekit/src/commit/2180aa868ec2caa95fc8279fd59d5f0ebac41bd4/docs/consumers/publish.md),
+and the [delivery guide](https://forge.maximumdirect.net/base-layer/releasekit/src/commit/2180aa868ec2caa95fc8279fd59d5f0ebac41bd4/docs/consumers/delivery.md).
+The repository selects one default module suite per invocation. The launcher
+uses the root module’s registered tool with native host settings and read-only
+module metadata.
 
 ## Release toolchain
 
-The selected release toolchain is **Go 1.26.8**. The consumer minimum is
-**Go 1.26.0**; validation uses a later patch within that supported Go series.
-The [consumer guide](consumers/guide.md#go-compatibility) explains the minimum and
-its shared tool-module requirement; the
-[release policy](policy/release.md#consumer-minimum-and-release-toolchain) governs
-changes to either selection.
+The selected release toolchain is **Go 1.26.8**. Each module declares a consumer
+minimum of **Go 1.26.0**. Maintainers use Go 1.26.8 for dependency preparation,
+candidate validation, and ReleaseKit execution. The
+[consumer guide](consumers/guide.md#go-compatibility) and
+[release policy](policy/release.md#consumer-minimum-and-release-toolchain)
+describe these selections.
 
-Use this toolchain for candidate validation and the native ReleaseKit bootstrap,
-including CI jobs that perform those tasks. The launcher and ReleaseKit invoke
-`go` from `PATH` with `GOTOOLCHAIN=local`, so select that installation in the
-shell used for preparation and publication.
-
-If it is not installed, use the [standard Go installation method](https://go.dev/doc/manage-install).
-Ensure Go's executable installation directory (`GOBIN`, or `GOPATH/bin` by
-default) is on `PATH` so the downloaded-version wrapper can be invoked:
+Select Go 1.26.8 on `PATH`; the launcher uses `GOTOOLCHAIN=local`. If needed,
+install it with the standard Go tools:
 
 ```sh
 GOWORK=off GOTOOLCHAIN=local go install golang.org/dl/go1.26.8@latest
@@ -51,115 +53,145 @@ hash -r
 GOWORK=off GOTOOLCHAIN=local go version
 ```
 
-The final command should identify Go 1.26.8. An existing Go 1.26.8 installation
-may be selected directly on `PATH` instead. Toolchain installation and dependency
-preparation precede the offline publication checks; they add no validation pass.
+## Modules, versions, notes, and shared files
 
-## Prepare and publish a candidate
+Select exactly one module with the launcher:
 
-Choose a fresh, unused stable Semantic Version tag in the form
-`vMAJOR.MINOR.PATCH`, with no leading zeroes. Before `v1.0.0`, a minor release
-may change a documented contract if its note explains the impact and consumer
-action; a patch release must not intentionally break contracts within its
-minor line. Never reuse a version previously published through any release
-channel. The first version is selected during release preparation, not embedded
-in the tool or profile.
+| Selector | Physical module directory | Release note | Full tag |
+| --- | --- | --- | --- |
+| `core` | repository root | `docs/releases/<version>.md` | `<version>` |
+| `ckconfig` | `integrations/ckconfig` | `integrations/ckconfig/docs/releases/<version>.md` | `integrations/ckconfig/<version>` |
+| `ckprompt` | `integrations/ckprompt` | `integrations/ckprompt/docs/releases/<version>.md` | `integrations/ckprompt/<version>` |
 
-Start from `main` and prepare a note at `docs/releases/<version>.md`. Begin with
-a heading containing `CommandKit` and the exact version. Include a useful
-summary and any compatibility impact or upgrade instructions. End it with the
-license and attribution links at that version's immutable source tag, replacing
-`VERSION` with the selected tag:
+Use a fresh stable semantic version (`vMAJOR.MINOR.PATCH`) for the selected
+module. Before `v1.0.0`, a minor release may change a documented contract when
+its note explains the impact and consumer action. Never reuse a published
+version. Each release note starts with a product title and exact version, gives
+a proportionate summary and compatibility guidance, and ends with immutable
+links to that module's local grant, license, and attribution paths. The full tag
+in each URL includes the integration directory where applicable. For future
+notes, use `https://forge.maximumdirect.net/base-layer/commandkit/src/tag/FULL_TAG/`
+followed by the repository-relative path: `COPYRIGHT`, `LICENSE`, and
+`docs/oss/attribution.md` for core, or those paths prefixed with the selected
+integration directory. Future tag URLs need not resolve before publication.
 
-```markdown
-[COPYRIGHT](https://gitea.maximumdirect.net/eric/CommandKit/src/tag/VERSION/COPYRIGHT) |
-[LICENSE](https://gitea.maximumdirect.net/eric/CommandKit/src/tag/VERSION/LICENSE) |
-[ATTRIBUTION](https://gitea.maximumdirect.net/eric/CommandKit/src/tag/VERSION/docs/oss/attribution.md)
-```
+All three release profiles explicitly select the repository-root `COPYRIGHT`,
+`LICENSE`, and `docs/oss/attribution.md` through `validation.shared_files`.
+ReleaseKit requires these committed files to exist in the candidate. The list
+does not expand Go validation scope; see the pinned [profile reference](https://forge.maximumdirect.net/base-layer/releasekit/src/commit/2180aa868ec2caa95fc8279fd59d5f0ebac41bd4/docs/config.md).
 
-Review these paths in the candidate; the future tag URLs do not need to resolve
-before publication.
+Each integration also distributes its own `COPYRIGHT`, `LICENSE`, and
+`docs/oss/attribution.md`. These module-local materials are separate from the
+explicit root shared-file list and remain subject to the [OSS policy](policy/oss.md).
+Automatic module file inputs include applicable module-local files and stop at
+independent nested-module boundaries. Their inclusion does not itself enable
+license or content validation.
 
-Prepare dependencies separately from the offline candidate suite:
+Each profile selects Go formatting, Markdown links, workspace-file and local
+replacement checks, and forbids the committed `.releasekit/gitea-token` path.
+These upstream checks inspect committed inputs; module file selection stops at
+independent module boundaries, while the forbidden path covers the repository.
+They do not replace domain review. Publication also runs the selected module’s
+standard offline suite and ReleaseKit’s candidate/note and publication guards.
 
-Run these commands in the same shell session so the version variable remains
-set:
-
-```sh
-commandkit_version=vX.Y.Z
-GOWORK=off GOTOOLCHAIN=local go mod download
-```
-
-If dependency preparation changes `go.mod` or `go.sum`, review and commit those
-changes with the candidate. Commit the note and all candidate changes on `main`,
-then publish that commit to `origin`:
+## Prepare and publish one candidate
+
+Prepare dependencies in the selected module before the candidate is finalized.
+Do this after the preceding CommandKit module has been published and before the
+selected candidate suite is run. For `core`, run the command at the repository
+root; for integrations, run it from that module directory. Commit any resulting
+`go.mod` or `go.sum` changes with the release candidate. The sum files must
+reflect dependencies actually downloaded for that module; do not fabricate
+future sums.
+
+Then commit the selected module's release note and all intended candidate
+changes on `main`, and publish the candidate commit to `origin`. Set one
+module directory and version from the table above, then run the corresponding
+publication command:
 
 ```sh
+module_dir=.
+(cd "$module_dir" && GOWORK=off GOTOOLCHAIN=local go mod download)
+# Commit reviewed dependency changes and the selected module's note on main.
 git push origin HEAD:refs/heads/main
-./scripts/release "$commandkit_version"
+./scripts/release core vX.Y.Z
+# For integrations use: ./scripts/release ckconfig vX.Y.Z
+# or: ./scripts/release ckprompt vX.Y.Z
 ```
 
-The launcher builds the ReleaseKit version selected by the module in readonly
-mode. After preflight, `publish` runs the offline default Go suite once, checks
-the candidate and remote guards, creates an annotated tag from the committed
-note, and pushes only that tag object. The launcher does not push `main`; push
-the candidate first. `check` is available for optional diagnosis and is not a
-required step before `publish`. The automated publication workflow runs the
-final-candidate suite once; configured additional checks should avoid duplicating
-that suite. Maintainers may rerun diagnostics when useful. Successful source
-publication does not wait for CI, module availability, or consumer installation.
+Run only the command for the selected module. Its profile runs the complete
+offline deterministic default suite once for that module, checks candidate and
+remote guards, creates the annotated tag from the matching note, and pushes
+only that full tag. `./scripts/releasekit core check vX.Y.Z` is an optional
+diagnostic, not a required pre-publication step: publication repeats validation.
+Use the relevant integration selector and its version when diagnosing that
+module. Inspect the registered tool with `./scripts/releasekit version`. The
+launcher does not push `main`; publish the
+candidate commit first. Successful source publication does not wait for CI,
+proxy availability, or downstream installation.
 
-## Completion and statuses
+## Completion and ambiguous publication
 
-Publication is complete when the intended annotated tag is successfully pushed
-to the expected endpoint, or when an exact tag-object query confirms that push
-after an error. Status 0 reports confirmed publication. Status 1 reports a
-known failure or conflict; status 2 reports invalid input or profile; status 3
-means the push outcome remains unresolved. See the upstream [CLI status
-contract](https://gitea.maximumdirect.net/eric/ReleaseKit/src/commit/e43df4416e0ed987349b2ea04a2c68c25e552772/docs/cli.md).
+A successful push to the expected endpoint completes the source release.
+ReleaseKit also attempts to save private publication evidence under the
+repository's Git common directory, shared by linked worktrees. It reports the
+saved record path or a recording warning separately from publication status;
+a storage failure does not change publication status. Records can contain
+credential-bearing endpoints. Retain them privately while recovery is needed
+and remove them when their recovery value expires; retention is maintainer-owned.
 
-For a failed or ambiguous push, use the exact endpoint, version, and annotated
-tag object reported by the invocation. Confirm that Git still resolves the
-captured endpoint to itself before querying only that tag ref:
+On an ambiguous result, use the recovery command printed for that invocation's
+saved record. To discover records and explicitly select the matching attempt,
+the shared helper can also be used:
 
 ```sh
-releasekit_endpoint='COPY THE CAPTURED ENDPOINT EXACTLY'
-releasekit_version='vX.Y.Z'
-releasekit_tag_object='COPY THE REPORTED TAG OBJECT ID'
-releasekit_ref="refs/tags/$releasekit_version"
-
-releasekit_resolved_endpoint=$(git ls-remote --get-url -- "$releasekit_endpoint") || {
-    printf '%s\n' 'publication state is unresolved: endpoint resolution failed' >&2
-    exit 1
-}
-if [ "$releasekit_resolved_endpoint" != "$releasekit_endpoint" ]; then
-    printf '%s\n' 'publication state is unresolved: endpoint resolution changed' >&2
-    exit 1
-fi
-releasekit_remote_tag=$(git ls-remote --refs -- "$releasekit_endpoint" "$releasekit_ref") || {
-    printf '%s\n' 'publication state is unresolved: remote query failed' >&2
-    exit 1
-}
-printf '%s\n' "$releasekit_remote_tag"
+./scripts/releasekit publication-attempts
+./scripts/releasekit reconcile --record /absolute/path/to/attempt.json
 ```
 
-`--refs` returns the annotated tag object's ID, not its peeled commit. Compare
-that ID with `releasekit_tag_object`: an exact match confirms publication; a
-different object is a conflict; successful output with no matching ref proves
-absence at the captured endpoint. A failed query or changed URL resolution is
-unresolved, never evidence of absence. Do not query a different fetch URL or
-follow a rewritten endpoint to infer the captured destination's state.
+Replace the example record path with the saved path for the intended attempt.
+Relative record paths resolve from the repository root.
+Discovery lists local evidence without querying remotes or selecting an attempt.
+Reconciliation observes the recorded endpoint, full tag, and tag object without
+rerunning candidate validation or changing tags. It distinguishes confirmed
+publication, current absence, conflict, and an unresolved observation. Current
+absence does not prove that a version was never published. The pinned
+[CLI reference](https://forge.maximumdirect.net/base-layer/releasekit/src/commit/2180aa868ec2caa95fc8279fd59d5f0ebac41bd4/docs/cli.md#recover-a-saved-publication-attempt-or-discover-local-attempts)
+owns recovery statuses and structured output; the
+[publication guide](https://forge.maximumdirect.net/base-layer/releasekit/src/commit/2180aa868ec2caa95fc8279fd59d5f0ebac41bd4/docs/consumers/publish.md#retain-and-reconcile-publication-evidence)
+describes record storage and recovery entry points.
 
-ReleaseKit retains a local tag after a failed push, so the tag blocks an ordinary
-retry. After proving the tag absent at the captured endpoint,
-confirm that it was never published or used by another release channel before
-deliberately removing the unpublished local tag:
+If no usable record was saved, use the exact endpoint, full tag, and annotated
+tag object reported by that invocation. Query only that exact tag ref at the
+captured endpoint. An exact tag-object match confirms publication, a different
+object is a conflict, successful output without the ref shows current absence,
+and a failed query leaves the result unresolved. Do not infer the captured
+endpoint's state from another remote or a rewritten URL. Resolve unknown
+publication state before retrying.
+
+ReleaseKit may retain a local tag after a failed push. Remove an unpublished
+local tag only after proving absence at the captured endpoint and confirming
+that the tag was never published or used by another release channel. Never
+move, overwrite, recreate, or delete a published tag. Resolve conflicts with a
+fresh version; corrections to published source require a new version.
+
+## Hosted delivery
+
+After source publication, check out the original tagged source with a clean
+worktree and index, then deliver the selected module's page:
 
 ```sh
-git tag -d "$releasekit_version"
+./scripts/releasekit core deliver vX.Y.Z
+# Or use ckconfig or ckprompt with that module's semantic version.
 ```
 
-Do not move, overwrite, recreate, or delete a published tag. If the exact tag
-object is present remotely, keep it. Resolve conflicts with a fresh version;
-corrections to published source require a new version. A transport failure
-alone does not require a new version.
+The profile derives the full module-specific tag from the version. Delivery
+uses the checked-in release note as a page-only body and reports its own outcome
+and URL separately from source publication. Retry later from the same original
+tagged source. The pinned [delivery guide](https://forge.maximumdirect.net/base-layer/releasekit/src/commit/2180aa868ec2caa95fc8279fd59d5f0ebac41bd4/docs/consumers/delivery.md)
+owns delivery and retry behavior.
+
+A nonblank `RELEASEKIT_GITEA_TOKEN` takes precedence over the repository-relative
+`.releasekit/gitea-token` file. Keep the credential directory ignored and retain
+its local contents. Credentials and Gitea availability do not gate source
+publication.

docs/releases/v0.2.0.md

@@ -0,0 +1,52 @@
+# CommandKit v0.2.0
+
+## Summary
+
+CommandKit v0.2.0 replaces the core registration API with reusable captured
+command declarations and moves ConfigKit and PromptKit support into independently
+versioned optional modules. This is a source-only release with incompatible API
+changes from v0.1.0.
+
+## Changes
+
+- Capture typed command specifications with `NewCommand`, then install the
+  resulting `Command` declarations through `commandkit.New` or `App.Register`.
+  Installation validates a batch before changing the application's registry.
+- Reuse captured declarations across applications. Typed bindings preserve
+  supplied values separately from defaults, and input construction occurs only
+  when execution reaches the command.
+- Keep ConfigKit and PromptKit dependencies outside the core module. Applications
+  explicitly import integrations and install their returned declarations.
+- Adopt ReleaseKit v0.4.2 for independently versioned module publication. It
+  remains a maintainer tool dependency; production packages do not import it.
+
+## Compatibility and upgrade
+
+The consumer minimum remains **Go 1.26.0**. The selected maintainer release
+toolchain remains Go 1.26.8.
+
+Consumers upgrading from v0.1.0 must rewrite command declarations, typed
+bindings, and installation wiring for the captured declaration API. There is no
+compatibility layer for the earlier registration API. Move configuration
+integration code to
+`gitea.maximumdirect.net/eric/CommandKit/integrations/ckconfig`, and PromptKit
+integration code to
+`gitea.maximumdirect.net/eric/CommandKit/integrations/ckprompt`.
+
+The integrations' initial releases are each v0.1.0; their version numbers are
+independent of core and upstream dependency versions. They add native
+configuration comparison, richer source evidence, PromptKit requirements
+discovery and validation, five catalogs, and opt-in smoke testing. Their own
+release notes describe the features and operator changes:
+
+- [ckconfig v0.1.0](https://gitea.maximumdirect.net/eric/CommandKit/src/tag/integrations/ckconfig/v0.1.0/integrations/ckconfig/docs/releases/v0.1.0.md)
+- [ckprompt v0.1.0](https://gitea.maximumdirect.net/eric/CommandKit/src/tag/integrations/ckprompt/v0.1.0/integrations/ckprompt/docs/releases/v0.1.0.md)
+
+See the [consumer guide](https://gitea.maximumdirect.net/eric/CommandKit/src/tag/v0.2.0/docs/consumers/guide.md)
+for migration examples and the
+[CLI reference](https://gitea.maximumdirect.net/eric/CommandKit/src/tag/v0.2.0/docs/cli.md)
+for standard command and report contracts.
+
+[COPYRIGHT](https://gitea.maximumdirect.net/eric/CommandKit/src/tag/v0.2.0/COPYRIGHT) |
+[LICENSE](https://gitea.maximumdirect.net/eric/CommandKit/src/tag/v0.2.0/LICENSE) |
+[ATTRIBUTION](https://gitea.maximumdirect.net/eric/CommandKit/src/tag/v0.2.0/docs/oss/attribution.md)

docs/releases/v0.3.0.md

@@ -0,0 +1,88 @@
+# 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)

docs/roadmap/deferred.md

@@ -5,8 +5,8 @@ Status: retained future work and unselected proposals; no implementation schedul
 ## Purpose and authority
 
 Completed initial delivery, performance, ReleaseKit upgrade, and remediation
-records have been retired. This document preserves their unfinished capability
-targets and deferred ideas under the
+records have been retired. This document preserves remaining deferred
+capabilities and unselected ideas under the
 [release policy](../policy/release.md#release-documentation-and-preparation).
 The original records remain available in
 [Git history](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/6bc37e7ba64ca0920b4d0cc77039a18d4006b24e/docs/roadmap).
@@ -18,46 +18,39 @@ an idea here does not select its syntax, API, priority, or delivery date.
 
 ## Deferred capability targets
 
-### DIFF-01: semantic configuration comparison
+### Comparison extensions
 
-Expose comparison of two independently resolved selections of one scope using
-owning-library safe snapshots. [ADR 0008](../adr/0008-semantic-configuration-diff.md)
-owns the accepted comparison semantics, sensitivity union, and coverage-gap
-handling. The target includes text/YAML reports of differences and gaps;
-completed comparisons can succeed even when they find either.
+Independent per-side domain selectors and an optional assertion mode remain
+unselected extensions to the delivered ConfigKit comparison. Consider them only
+for a concrete consumer need and a deliberate API/behavior decision under the
+relevant ADRs.
 
-The initial review of ConfigKit v0.5.0 and PromptKit v0.12.0 did not find the
-complete public snapshot/sensitivity contract needed for that target. Reassess
-released upstream APIs when planning it; do not treat that historical review as
-a claim about newer versions. Hidden-path metadata and supported gap reasons
-must be available without fetching secrets. Rendered YAML and sibling internals
-are not substitutes for an agreed public comparison representation.
+### Alias completion and discovery
 
-Comparison selection syntax, context inheritance, and report layout remain
-future design work. Earlier possibilities included right-side root/overlay
-selection, shared versus independent domain context, and an optional assertion
-mode. Those choices are unselected. Add public types and handlers when the
-capability is supported, rather than exposing placeholders.
+The delivered [shell completion feature](../cli.md#shell-completion) provides
+canonical suggestions and alias-aware interpretation. Potential future work
+includes suggesting command and flag alias spellings and valid continuations of
+alias-only prefixes. For example, completion could suggest `inspect` after
+`app legacy ` when `legacy inspect` is an installed alias.
 
-### CAT-01: PromptKit catalogs
-
-List captured prompt/version entries and named profiles through owning public
-catalog APIs, with deterministic reports of loaded definitions. Resource names,
-enumeration details, and report shapes remain future design work.
-
-The initial PromptKit v0.12.0 review did not find public enumeration APIs.
-Reassess current released capabilities before planning delivery. Do not infer
-catalogs by reparsing configuration YAML or inspecting sibling internals.
+Alias discovery is outside the initial scope. This deferral does not establish a
+permanent canonical-only completion contract or prohibit future alias discovery.
+A later design should determine how alias suggestions are presented alongside
+canonical suggestions while ensuring inserted continuations form valid next
+steps. No delivery date or final API is selected here.
 
 ## Other deferred proposals
 
 These capabilities remain outside the delivered scope and require a concrete
 operator or consumer need and an appropriate ownership/behavior decision:
 
-- JSON reports, shell completion, and output-file management or reloadable export.
+- JSON reports and output-file management or reloadable export.
+- Shell completion extensions, including alias discovery described above and
+  dynamic discovery of configured or remote values.
 - Configuration mutation, generic value assignment, and exhaustive field-origin
   inventories.
-- Credential diagnostics and live provider probes.
+- Credential diagnostics beyond PromptKit's native smoke checks and additional
+  live provider probes.
 - Additional component identity registration and domain artifact catalogs.
 - Additional library families, including possible FeedKit integration; families
   can define suitable verbs without requiring comparison or configuration scopes.

docs/roadmap/implementation.md

@@ -0,0 +1,351 @@
+# CommandKit vanity migration and dependency alignment plan
+
+Status: Stages 1–3 complete; Stages 4–7 are not started.
+
+This plan is for the Luna coding agent implementing the
+[feature roadmap](integration-dependency-alignment.md). Follow the stages in
+integer order during one end-to-end sprint. Unpublished editing states may be
+temporarily inconsistent. Each published module must be a coherent, committed
+candidate validated by its ordinary release workflow.
+
+This planning pass changes documentation only. The target includes three real
+source releases because later modules need downloadable predecessors. The
+publication stages below describe that future work; this planning request does
+not perform or authorize Git pushes. Honor the user's implementation/publication
+scope when executing the plan, and report any unperformed release as pending.
+
+Read [development guidance](../development.md), the
+[agent policy](../policy/agents.md), [architecture policy](../policy/architecture.md),
+[testing policy](../policy/testing.md),
+[documentation policy](../policy/documentation.md),
+[release policy](../policy/release.md), and [OSS policy](../policy/oss.md) for
+the work they govern. Follow `AGENTS.md` codebase-memory discovery instructions.
+The [release procedure](../release.md) remains the owner of operational commands.
+
+The previous plan's [completed ReleaseKit v0.9.0 stages and evidence](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/c8d659dfe5ae3e834b3aeabdfd0fe29b736dc05a/docs/roadmap/implementation.md)
+remain in Git history. R1/R2 in [remediation.md](remediation.md) and the ReleaseKit
+adoption are complete; do not restart them or rewrite their historical evidence.
+
+## Baseline and fixed decisions
+
+Planning baseline: `c8d659dfe5ae3e834b3aeabdfd0fe29b736dc05a`.
+
+| Module directory | Current module path | Target module path | Target version and full tag |
+| --- | --- | --- | --- |
+| `.` | `gitea.maximumdirect.net/eric/CommandKit` | `go.maximumdirect.net/commandkit` | v0.3.0; `v0.3.0` |
+| `integrations/ckconfig` | `gitea.maximumdirect.net/eric/CommandKit/integrations/ckconfig` | `go.maximumdirect.net/ckconfig` | v0.2.0; `integrations/ckconfig/v0.2.0` |
+| `integrations/ckprompt` | `gitea.maximumdirect.net/eric/CommandKit/integrations/ckprompt` | `go.maximumdirect.net/ckprompt` | v0.2.0; `integrations/ckprompt/v0.2.0` |
+
+- Both integrations currently require core v0.2.0; ckprompt also requires
+  ckconfig v0.1.0. Their source uses newer core APIs. Independent baseline suites
+  fail; temporary local-source selections pass only when ckprompt also uses
+  current ckconfig. The feature roadmap records those diagnostics.
+- Target ckconfig requires `go.maximumdirect.net/commandkit v0.3.0`. Target
+  ckprompt requires that core and `go.maximumdirect.net/ckconfig v0.2.0`.
+- Vanity discovery is verified. The integration metadata's fourth field maps
+  the short paths to the existing physical directories. Existing tags still
+  declare old identities. Discovery alone does not complete module migration.
+- Preserve package names, exported declaration shapes, runtime behavior, Go
+  1.26.0 consumer minimums, and the Go 1.26.8 maintainer toolchain. Preserve root
+  ReleaseKit v0.9.0 selection, scripts, profiles, endpoints, and validators.
+- Retain ConfigKit v0.8.0 and PromptKit v0.16.0; no upstream library upgrade is
+  selected. Inspect tidy's actual graph changes and update affected attribution.
+- The three proposed tags were unused at planning time. Existing publication
+  guards recheck freshness; never move/reuse a published tag. A conflict needs
+  a deliberate new version selection and matching dependent metadata/notes.
+- Retain ignored `go.work` and `go.work.sum`, and the supplied ignored
+  `.releasekit/gitea-token` without reading its contents. No credential or live
+  provider is needed for local validation. Source publication uses the existing
+  Git endpoint; hosted delivery remains a separate operation/outcome.
+
+Do not rename physical module directories or flatten integration tag prefixes.
+Do not add an old-path forwarding module, type-interoperability layer, API
+rollback, permanent validation shim, or new recurring release gate. These are
+outside the selected migration, not new restrictions on application behavior.
+
+## Execution and validation conventions
+
+Use Go 1.26.8 on `PATH` following the existing
+[toolchain setup](../release.md#release-toolchain). The ignored workspace declares
+Go 1.26.10 at baseline; preserve it. Use `GOWORK=off GOTOOLCHAIN=local` for module
+preparation and independent validation. Use normal dependency retrieval during
+preparation; ReleaseKit runs the final selected-module suite offline/read-only.
+
+Migrate module-owned source, tests, and examples together. Apply integration
+path mappings before the broader core prefix when a replacement tool is used;
+`go.maximumdirect.net/commandkit/integrations/ckconfig` is not the selected
+ckconfig identity. Preserve import aliases such as `commandkit`. Core `internal`
+imports must use the new core prefix. Review identity-sensitive strings as well
+as Go import declarations.
+
+Update current prose and GoDoc for the module being migrated. Treat repository,
+license, and immutable historical source links separately from Go import paths.
+Keep published notes, accepted ADR history, and completed review evidence intact.
+Do not globally replace every old URL or migrate unrelated upstream identities.
+
+Publication steps use the existing protocol: prepare dependencies, review and
+commit the final selected candidate on `main`, publish that candidate commit to
+the authoritative branch, and invoke the module's release wrapper. The wrapper
+runs the owning complete suite once, selected file checks, and publication
+guards, then creates/pushes the intended tag. It does not push `main` for you.
+Run validation-only `check` for diagnosis when useful; do not make it a required
+duplicate suite before `publish`. Do not add CI/proxy polling or post-push
+read-back as a successful-publication gate. Reuse evidence for unchanged content.
+
+Each release has its own candidate commit, suite result, and publication outcome.
+The next module's dependency download is preparation for that next release;
+failure to download does not undo completion of the predecessor's source push.
+Use a command-scoped direct download to diagnose proxy lag if necessary rather
+than permanently changing proxy settings. Retain authentic downloaded sums.
+
+## Stage 1: Migrate core identity and prepare its release candidate
+
+**Completed.** The root module, owned imports, component build identity,
+consumer guidance, and v0.3.0 release note use the new core identity. The
+focused build-identity test passed offline with Go 1.26.8; affected links and
+whitespace were checked. The complete candidate suite belongs to publication.
+
+1. Change only the root module declaration to `go.maximumdirect.net/commandkit`.
+   Migrate root-owned imports in production files, root/external tests, internal
+   packages, and `examples/core`. Leave nested module migration to Stages 3/5.
+   Preserve the root tool declaration and other dependency versions; prepare
+   caches and tidy the root with workspace discovery off.
+2. Update `commandKitModulePath` in `builtins.go` to the new core identity.
+   `version --scope commandkit` uses it to find build information. Retain its
+   existing application/component scopes, tag/replacement handling, and `dev`
+   fallback; do not add a legacy-identity fallback.
+3. Adapt existing identity/import-path test expectations. In
+   `TestCommandKitBuildIdentityProjectsEffectiveModuleVersion`, make at least
+   one existing successful tagged case supply the literal new module path
+   independently of `commandKitModulePath`. Otherwise a stale constant and its
+   self-referencing fixtures could agree while real version lookup fails.
+   Preserve all existing replacement/development cases and boundary assertions.
+4. Update the root row in README's module table, current core imports and
+   installation guidance in `docs/consumers/guide.md`, affected developer and
+   internal guidance, example documentation, and GoDoc. Describe integrations
+   according to their implemented identity until their migration stages land;
+   keep the matched future set in migration guidance explicit.
+5. Refresh `docs/releases/v0.3.0.md` against the full v0.2.0-to-candidate change:
+   aliases, reporting migration, completion, ReleaseKit maintenance, and the new
+   core import path. Explain consumer updates and the forthcoming matched
+   integration versions. Use current procedure URLs with immutable `v0.3.0`
+   source/licensing links. Keep the declared toolchains unchanged.
+6. Format changed Go files. Review root-owned imports/identity literals and
+   module metadata; check affected prose links and whitespace. Run the existing
+   focused identity test with prepared caches:
+
+   ```sh
+   GOWORK=off GOTOOLCHAIN=local GOPROXY=off GONOPROXY=none GOSUMDB=off \
+     go test -mod=readonly -count=1 -run '^TestCommandKitBuildIdentityProjectsEffectiveModuleVersion$' .
+   ```
+
+**Stage result:** a reviewed core v0.3.0 candidate with the new identity, correct
+component version lookup, migrated root consumers, and current release notes.
+The full root suite belongs to Stage 2's normal publication workflow.
+
+## Stage 2: Validate and publish core v0.3.0
+
+**Completed.** Core `go.maximumdirect.net/commandkit v0.3.0` was published as
+tag `v0.3.0` at candidate `e256eb1cc02a0c72c4e23c4967ed1caeaef17008`.
+The ordinary Go 1.26.8 release workflow passed the complete root suite and
+selected file checks before the successful source-tag push.
+
+1. Review and commit the complete core candidate under the local commit policy.
+   Confirm that unrelated/private files and ignored workspaces are excluded.
+   The independently released integration sources may still declare old paths;
+   that does not make their suites a prerequisite for this root release.
+2. From the repository root, execute the existing publication sequence within
+   the authorized release scope:
+
+   ```sh
+   git push origin HEAD:refs/heads/main
+   ./scripts/release core v0.3.0
+   ```
+
+3. Require the real selected-module suite and file checks to pass. Fix actual
+   failures in scope and commit the corrected candidate before retrying. On a
+   failed/ambiguous push, use the existing publication evidence and recovery
+   procedure. Do not force refs, bypass guards, or treat a local tag as publication.
+4. Record the candidate commit, module path, full tag, validation outcome, and
+   confirmed source outcome here. A successful tag push completes this source
+   release; move to dependent preparation without waiting for hosted pages.
+
+**Stage result:** core v0.3.0 is source-published with
+`module go.maximumdirect.net/commandkit`. Actual download of this version and its
+sums is part of Stage 3, not a new completion gate for core publication.
+
+## Stage 3: Migrate ckconfig and prepare its independent candidate
+
+**Completed.** Ckconfig declares `go.maximumdirect.net/ckconfig`, imports the
+new core identity, and downloaded `go.maximumdirect.net/commandkit v0.3.0`
+with authentic sums. The resolved graph retains ConfigKit v0.8.0 and selects
+both the older ReleaseKit v0.4.1 and vanity ReleaseKit v0.9.0 tool modules;
+module-local attribution and current guidance reflect those selections. The
+v0.2.0 release note is prepared; independent suite validation follows.
+
+1. In `integrations/ckconfig`, migrate the module declaration to
+   `go.maximumdirect.net/ckconfig`. Update all owned imports, tests, and the
+   maintained simple example to that self-path and the new core path. Keep
+   package names and existing adapter behavior.
+2. Replace its old core dependency key with the published new-path version.
+   From the ckconfig module directory, use:
+
+   ```sh
+   GOWORK=off GOTOOLCHAIN=local go mod edit -module=go.maximumdirect.net/ckconfig -droprequire=gitea.maximumdirect.net/eric/CommandKit -require=go.maximumdirect.net/commandkit@v0.3.0
+   GOWORK=off GOTOOLCHAIN=local go mod download go.maximumdirect.net/commandkit@v0.3.0
+   GOWORK=off GOTOOLCHAIN=local go mod tidy
+   ```
+
+   Perform source import migration before tidy to avoid resolving old imports.
+   Keep real downloaded sums. If retrieval is unavailable, resolve dependency
+   preparation before proceeding; do not fabricate metadata or substitute a
+   local replacement as final release evidence.
+3. Inspect the actual direct and indirect graph, including tool requirements.
+   Preserve ConfigKit v0.8.0 and unrelated versions. Update affected notices in
+   `integrations/ckconfig/docs/oss/attribution.md` under the OSS policy using the
+   actual selected source revisions; add/retain applicable license texts. Do
+   not assume similarly named old/new upstream modules are interchangeable.
+4. Prepare `integrations/ckconfig/docs/releases/v0.2.0.md` with product
+   `CommandKit ckconfig`, the new module/core paths, compatible dependency set,
+   and relevant reporting/completion migration. Immutable footer/source URLs
+   use the full tag `integrations/ckconfig/v0.2.0` and correct physical files.
+5. Update README's ckconfig row, consumer module/import examples, the simple
+   example guidance, affected GoDoc, and relevant current release/development
+   references. Explain that applications moving to the new core identity also
+   use the matched new integration identity.
+6. Format changed Go files. Review for stale owned imports/direct requirement
+   keys, accidental replacements/workspace files, and unexplained graph churn.
+   Check current links and whitespace. The owning complete suite runs in
+   Stage 4; a local workspace pass is not a substitute.
+
+**Stage result:** a ckconfig v0.2.0 candidate whose actual dependency is
+downloaded `go.maximumdirect.net/commandkit v0.3.0`, with authentic metadata and
+aligned current documentation/attribution.
+
+## Stage 4: Validate and publish ckconfig v0.2.0
+
+**Status:** not started.
+
+Review and commit the complete ckconfig candidate. From the repository root,
+use the same authoritative-branch protocol as Stage 2:
+
+```sh
+git push origin HEAD:refs/heads/main
+./scripts/release ckconfig v0.2.0
+```
+
+The normal release command must pass the independent ckconfig suite, including
+its maintained example, with workspace discovery off and without dependency
+redirection. It must also pass selected committed-file checks and publication
+guards. Do not insert the earlier temporary Go shim or weaken a selected check.
+Apply the existing failed/ambiguous-publication procedure if needed.
+
+Record the candidate, path, version, full tag, validation, and source outcome.
+The intended tag is `integrations/ckconfig/v0.2.0`; the physical directory remains
+`integrations/ckconfig` despite the short vanity module path.
+
+**Stage result:** compatible ckconfig v0.2.0 is source-published under its vanity
+identity. Downloading it for ckprompt is the next module's preparation.
+
+## Stage 5: Migrate ckprompt and prepare its independent candidate
+
+**Status:** not started.
+
+1. Migrate `integrations/ckprompt` to `go.maximumdirect.net/ckprompt`. Update its
+   owned source/tests and composed example to import the new core, ckconfig,
+   and ckprompt paths. Preserve PromptKit adaptation and reporting behavior.
+2. From that module directory, replace both old CommandKit dependency keys:
+
+   ```sh
+   GOWORK=off GOTOOLCHAIN=local go mod edit -module=go.maximumdirect.net/ckprompt -droprequire=gitea.maximumdirect.net/eric/CommandKit -droprequire=gitea.maximumdirect.net/eric/CommandKit/integrations/ckconfig -require=go.maximumdirect.net/commandkit@v0.3.0 -require=go.maximumdirect.net/ckconfig@v0.2.0
+   GOWORK=off GOTOOLCHAIN=local go mod download go.maximumdirect.net/commandkit@v0.3.0 go.maximumdirect.net/ckconfig@v0.2.0
+   GOWORK=off GOTOOLCHAIN=local go mod tidy
+   ```
+
+   Migrate imports before tidy. Retain actual downloaded sums; resolve fetch
+   failures as preparation rather than masking them with local source. A new
+   core with old ckconfig v0.1.0 is the known incompatible combination.
+3. Review graph changes while retaining ConfigKit v0.8.0 and PromptKit v0.16.0.
+   Update affected module-local attribution and immutable notice links based on
+   the resolved graph, including transitive tools. Keep actual upstream module
+   identities distinct from the three CommandKit identities being migrated.
+4. Prepare `integrations/ckprompt/docs/releases/v0.2.0.md` with product
+   `CommandKit ckprompt`, new imports/dependencies, and consumer migration.
+   Footer/source links use full tag `integrations/ckprompt/v0.2.0` and physical
+   module-local files. Preserve the published v0.1.0 record.
+5. Update README's ckprompt row, consumer composition/import examples, composed
+   example guidance, affected GoDoc, and remaining current module descriptions.
+   Keep URLs to hosted repository files separate from Go package links.
+6. Format changed Go files and review remaining owned old-path imports or direct
+   requirement keys, metadata, links, and whitespace. Keep the ordinary source
+   checks intact; the independent suite runs in Stage 6.
+
+**Stage result:** ckprompt v0.2.0 composes the real new-path core and ckconfig
+versions in its declared graph, with current guidance and authentic metadata.
+
+## Stage 6: Validate and publish ckprompt v0.2.0
+
+**Status:** not started.
+
+Review and commit the complete ckprompt candidate. From the repository root:
+
+```sh
+git push origin HEAD:refs/heads/main
+./scripts/release ckprompt v0.2.0
+```
+
+The normal publication workflow must pass the independent ckprompt suite and
+composed consumer with actual downloaded predecessors, plus selected file and
+publication checks. Preserve the offline/read-only suite environment and
+ordinary recovery handling. No workspace or replacement shim supplies final
+release evidence.
+
+Record its candidate, module identity, full tag
+`integrations/ckprompt/v0.2.0`, suite outcome, and source-publication outcome.
+Report any separate hosted delivery under its own outcome; page publication
+is not required to establish dependency alignment.
+
+**Stage result:** all three matched source releases are published with vanity
+module declarations and verified independent dependency graphs.
+
+## Stage 7: Audit the completed migration and record evidence
+
+**Status:** not started.
+
+1. Review the cumulative diff against the feature roadmap. Confirm all three
+   module declarations, owned imports, examples, direct dependency keys, and
+   component build identity use the new paths. Preserve physical directories,
+   tag prefixes, root ReleaseKit selection, scripts/profiles, exported shapes,
+   Go minimums, and upstream versions apart from explained graph consequences.
+2. Check that tests and current guidance use the new identities while historical
+   notes, accepted ADRs, and immutable source URLs retain their historical
+   meaning. Resolve current dependency-readiness claims that are now stale.
+   Do not mechanically rewrite every old-path reference in completed records.
+3. Record each final candidate's exact commit, full tag, suite result, and
+   publication outcome. Identify diagnostic-only earlier evidence separately.
+   Reuse each successful publication suite for its unchanged candidate; do not
+   require another complete run just to finish this stage. Any later code or
+   metadata correction belongs in a new candidate/version under release policy.
+4. Mark stages complete only with their stated evidence and update the feature
+   roadmap's status/link here. Preserve this record and prior immutable plans;
+   apply normal roadmap retirement only during later preparation. If publication
+   was outside the authorized implementation scope or could not finish, record
+   the actual prepared state and pending release stages rather than claiming
+   alignment is complete.
+5. Review new evidence prose, links/fragments, intended staged files, and
+   `git diff --check` / `git diff --cached --check`. Commit any remaining
+   nonempty documentation unit with a short plain-English message, following
+   the local commit policy. Finish with a clean tracked worktree when only
+   planned work is present; preserve unrelated and ignored local files.
+
+**Stage result:** the implemented and published matched version set has accurate
+source/validation evidence, current migration guidance, and committed tracking.
+Source release and hosted-delivery outcomes remain separate.
+
+## Open Questions
+
+None required to choose the implementation. Vanity paths, target versions,
+physical layout, dependency order, validation ownership, and compatibility scope
+are selected in the roadmap. Publication authorization is an execution-scope
+constraint, not a reason to invent different versions, fabricated sums, or a
+local-only substitute for the target end state.

docs/roadmap/integration-dependency-alignment.md

@@ -0,0 +1,208 @@
+# Integration dependency alignment and vanity-path migration
+
+Status: proposed release-preparation roadmap. This pass adds documentation only;
+dependency changes and publication remain future work. The
+[implementation plan](implementation.md) owns execution stages, concrete tasks,
+and validation tracking; this roadmap owns the target and selected scope.
+
+## Purpose and authority
+
+Align the independently released integrations with the core APIs their current
+source already uses, and migrate all three CommandKit modules to the supplied
+vanity paths. Publish compatible module versions in dependency order so each
+integration builds and validates against its declared, downloaded dependencies
+with workspace discovery off.
+
+The [release procedure](../release.md) owns publication commands and release
+order. The [release policy](../policy/release.md),
+[agent policy](../policy/agents.md), [testing policy](../policy/testing.md),
+[documentation policy](../policy/documentation.md), and
+[OSS policy](../policy/oss.md) govern the work. This roadmap selects the target
+and release-preparation scope; it does not change those policies.
+
+## Baseline and investigation evidence
+
+Reviewed baseline: `289a171e97699ad9aa57ee2cc40bdad1c0b680a9`.
+Vanity-path review baseline: `d7cbaed3ed18bc2909c8144f308e2dfd58ade7ec`.
+Module declarations and library source were unchanged between these revisions.
+
+- Both integration module declarations require core v0.2.0. The
+  [ckprompt declaration](../../integrations/ckprompt/go.mod) also requires
+  ckconfig v0.1.0; the [ckconfig declaration](../../integrations/ckconfig/go.mod)
+  has no dependency on ckprompt.
+- Current integration source uses newer core APIs including `CompletionHint`,
+  `Explanation`, and `Reporter`. Both independent Go 1.26.8 suites fail to
+  compile with `GOWORK=off` and their existing read-only module graphs.
+- Updating core alone is insufficient for ckprompt: published ckconfig v0.1.0
+  still uses removed core APIs, including `Invocation.Streams`,
+  `Outcome.Diagnostics`, and `SeverityError`, plus the old `Failure(error)`
+  call shape.
+- The authoritative `origin` tag listing contains core v0.1.0 and v0.2.0, and
+  the two integration v0.1.0 tags. The proposed next versions below were unused
+  at review. Remote `main` was `230187296fae5253cb1773f16c2f1d1a39499ed0`;
+  the reviewed local changes still need normal publication to the authoritative
+  branch as part of candidate preparation.
+- A checked-in [core v0.3.0 draft](../releases/v0.3.0.md) already describes the
+  reporting and alias migration. It is an unpublished draft, not proof that
+  the module version can be downloaded.
+
+The investigation used disposable alternate module files, Go 1.26.8,
+`GOWORK=off`, and read-only offline tests. Only temporary dependency selections
+changed; the real module declarations, sums, and source remained unchanged.
+
+| Current source under test | Temporary dependency selection | Result |
+| --- | --- | --- |
+| ckconfig | Current core source | Module suite and maintained example passed. |
+| ckprompt | Current core source, published ckconfig v0.1.0 | Compilation failed in the old ckconfig implementation. |
+| ckprompt | Current core and current ckconfig source | Module suite and maintained example passed. |
+
+The successful cases retained ConfigKit v0.8.0 and PromptKit v0.16.0. These
+results isolate the CommandKit dependency alignment needed here; they do not
+prove that future published versions or their downloaded sums already exist.
+
+### Verified vanity discovery
+
+The core endpoint at `https://go.maximumdirect.net/commandkit?go-get=1` serves
+the mapping to `https://forge.maximumdirect.net/base-layer/commandkit`. Go direct
+discovery finds the existing core v0.1.0 and v0.2.0 tags. Fetching v0.2.0 through
+the vanity path reaches its source but reports a module-path mismatch because
+that release declares `gitea.maximumdirect.net/eric/CommandKit`.
+
+Both integration endpoints now return HTTP 200 with these `go-import` contents:
+
+| Vanity path | VCS | Repository URL | Subdirectory field |
+| --- | --- | --- | --- |
+| `go.maximumdirect.net/ckconfig` | `git` | `https://forge.maximumdirect.net/base-layer/commandkit` | `integrations/ckconfig` |
+| `go.maximumdirect.net/ckprompt` | `git` | `https://forge.maximumdirect.net/base-layer/commandkit` | `integrations/ckprompt` |
+
+Go 1.26.8 direct discovery finds each integration's v0.1.0 tag. Disposable
+consumer fetches reach the correct nested `go.mod` and report its old declared
+module path, confirming subdirectory routing. Discovery is working; the
+existing tags have not migrated. The optional fourth metadata field is
+supported from Go 1.25, within the existing Go 1.26.0 consumer minimum; see the
+[Go discovery reference](https://go.dev/ref/mod#vcs-find).
+
+## Targeted end state
+
+### Compatible independently released modules
+
+Use the following proposed next versions, subject to the existing fresh-version
+publication guards:
+
+| Module path | Physical module directory | Next release | Required CommandKit dependencies | Full tag |
+| --- | --- | --- | --- | --- |
+| `go.maximumdirect.net/commandkit` | `.` | v0.3.0 | None | `v0.3.0` |
+| `go.maximumdirect.net/ckconfig` | `integrations/ckconfig` | v0.2.0 | `go.maximumdirect.net/commandkit v0.3.0` | `integrations/ckconfig/v0.2.0` |
+| `go.maximumdirect.net/ckprompt` | `integrations/ckprompt` | v0.2.0 | `go.maximumdirect.net/commandkit v0.3.0` and `go.maximumdirect.net/ckconfig v0.2.0` | `integrations/ckprompt/v0.2.0` |
+
+Minor integration releases fit the existing pre-1.0 compatibility policy: the
+reporting migration changes consumer-facing behavior and adopts a core version
+with incompatible API changes. The vanity migration also deliberately changes
+Go module and import identities. Migration notes explain the new imports and
+dependency set, provider results, invocation reporting, and application changes.
+
+The three modules retain independent versions and source tags. Their candidates
+may identify successive commits: core publication need not wait for integration
+metadata that depends on that newly published core. Each selected module's
+final release suite runs against its actual declared dependencies.
+
+### Module and import identity
+
+Change each module declaration and all CommandKit-owned imports to the matching
+new path. Core self-imports, including its `internal` packages, use
+`go.maximumdirect.net/commandkit/...`; integration self-imports use
+`go.maximumdirect.net/ckconfig/...` or `go.maximumdirect.net/ckprompt/...`.
+Cross-module imports and requirements use the complete new paths in the table,
+including ckprompt's ckconfig dependency. Core component-version discovery uses
+`go.maximumdirect.net/commandkit` as its build-info identity, retaining the
+existing `version --scope commandkit` behavior with the new module path.
+
+Update production files, tests, maintained examples, and any import-path-based
+test expectations together. A declared vanity module that still imports the
+old core path would select a different Go package identity and can violate
+`internal` import rules. The matched new releases compose through one core
+identity rather than mixing old-path and new-path CommandKit types.
+
+Keep physical directories, repository URLs, and Git tag prefixes as shown. The
+Go subdirectory metadata makes the short integration vanity paths resolve to
+the existing layout. The existing release profiles select physical directories;
+the migration does not rename those directories or flatten integration tags.
+
+Published old-path versions remain immutable. This scope selects the new paths
+for new releases and updates consumer guidance; it makes no new promise of
+type interoperability between the two identities and adds no old-path forwarding
+module or compatibility layer.
+
+### Retained architecture and scope
+
+Preserve exported declaration shapes and runtime behavior while deliberately
+changing module/import identities. Retain the integration adapters, Go 1.26.0
+consumer minimum, Go 1.26.8 maintainer toolchain, and root-selected ReleaseKit
+v0.9.0. The earlier successful diagnostic suites establish the dependency fix
+before renaming; the migrated source still needs its own validation. This work
+selects no API rollback or shim for old reporting APIs.
+
+Retain ConfigKit v0.8.0, PromptKit v0.16.0, and other dependency selections
+unless ordinary tidy changes the resolved graph as a consequence of the
+CommandKit updates. Inspect and explain the resulting graph rather than
+bundling unrelated upgrades. In particular, transitive tools with different
+module paths may coexist; attribution must reflect the actual selection.
+
+Preserve the existing launchers, three release profiles, generic validators,
+credential handling, and separate source-publication and hosted-delivery
+outcomes. Development workspaces remain useful and ignored. Diagnostic local
+replacements and the earlier temporary Go shim remain development evidence;
+release validation uses normal downloaded dependencies without that redirection.
+
+## Release-preparation deliverables
+
+The core v0.3.0 draft describes the complete candidate, including completion,
+reporting, aliases, tool maintenance, and the vanity-path migration. New
+integration notes at `integrations/ckconfig/docs/releases/v0.2.0.md` and
+`integrations/ckprompt/docs/releases/v0.2.0.md` explain the matched dependency set
+and consumer migration. Their source and licensing links follow the current
+release procedure; published notes and tags remain immutable.
+
+Current installation examples, README module selections, consumer/developer
+guidance, affected GoDoc, and maintained examples use the implemented new
+identities. Import-path-aware tests retain their existing boundary assertions.
+Source-hosting and license URLs remain repository links, distinct from Go
+import paths. Module-local attribution describes each actual resolved graph.
+
+The final record identifies module paths, versions, candidate revisions,
+validation evidence, and independent source-publication outcomes. Current
+readiness guidance reflects the aligned state; historical failures remain in
+completed investigation records. The implementation plan owns the ordered
+migration, dependency preparation, release, and evidence-recording steps.
+
+## Validation and completion boundaries
+
+Review current CommandKit-owned source and dependency selections for stale
+self-imports or old direct dependency keys. Historical notes, source URLs, and
+unrelated upstream module identities are outside that mechanical rename.
+Confirm release identity still pairs each new module path with its existing
+physical directory and tag prefix. The verified redirects are preparation
+evidence; publishing the renamed modules is needed for real consumers to use
+them through those paths.
+
+Use the selected module's ordinary deterministic offline suite with
+`GOWORK=off` and read-only metadata after dependency preparation. Its maintained
+consumer compiles and runs with that suite. ReleaseKit's publication command
+owns the final candidate suite and selected file checks; validation-only checks
+remain optional diagnostics. Reuse successful evidence for unchanged candidates
+instead of adding a required check-then-publish repetition.
+
+Retrieving a newly published dependency is preparation for the next module's
+release. It does not turn proxy availability or consumer installation into a
+completion gate for the preceding source release. Continue to resolve failed
+or ambiguous publication using the existing policy and upstream recovery flow.
+Hosted Gitea delivery keeps its separate outcome; this roadmap adds no CI
+polling, live provider calls, or additional publication gate.
+
+Alignment is complete when the matched source versions are published under all
+three vanity module paths, owned imports and examples use the new identities,
+each integration declares the compatible vanity-path versions with authentic
+downloaded sums, each final selected-module suite passes without workspace or
+replacement redirection, and current documentation and attribution agree with
+that graph. Temporary local-source success alone does not establish that end
+state.

docs/roadmap/release-simplification.md

@@ -0,0 +1,198 @@
+# Release tooling simplification
+
+Status: the selected release-tooling design has been implemented. All four
+generic file checks, registered-tool execution, page-only hosted delivery, and
+protection of the supplied token path are selected.
+The [completed implementation record](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/87eb84ccb462bf54e6250c8b287ac217efe90883/docs/roadmap/implementation.md)
+contains stage order, tasks, validation, and completion evidence. Current release
+behavior stays with its canonical owners.
+
+## Purpose and authority
+
+Reduce CommandKit's release infrastructure to declarative module profiles,
+a small launcher, and focused tests of CommandKit-owned wiring. Delegate
+reusable candidate validation and publication mechanics to ReleaseKit while
+retaining CommandKit's domain-specific checks in their existing owners. Add
+hosted Gitea release pages as a separate local delivery operation after source
+publication.
+
+The [agent policy](../policy/agents.md),
+[release policy](../policy/release.md#candidate-validation), and
+[testing policy](../policy/testing.md#upstream-integration-testing-ownership)
+govern implementation. The [release procedure](../release.md) continues to own
+the current workflow.
+
+## Targeted end state
+
+### Ownership
+
+CommandKit retains module selectors, product identities, profile locations,
+the authoritative endpoint selection, release order, release-note meaning,
+compatibility decisions, and attribution accuracy. Its existing public API,
+CLI, integration-adaptation, and consumer-example tests remain local and run
+through the owning module's suite. No parallel release-only domain suite is
+needed unless a concrete CommandKit requirement is otherwise unprotected.
+
+ReleaseKit supplies the standard offline candidate suite, selected generic file
+checks, candidate/note and publication guards, tag creation and publication,
+hosted delivery, outcome reporting, and recovery. CommandKit's launcher delegates
+those operations. Existing source-release completion and immutability rules
+continue to apply. Hosted pages are the added delivery channel; binary
+deliverables and platform support commitments remain unchanged.
+
+### Profiles
+
+Select these existing ReleaseKit options in each profile:
+
+| Selection | Intended protection |
+| --- | --- |
+| `validation.go_format: true` | Detect unformatted committed Go source. |
+| `validation.markdown: {}` | Detect broken local Markdown destinations and supported heading fragments. |
+| `validation.module_distribution.workspace_files: true` | Detect committed development workspace files in selected inputs. |
+| `validation.module_distribution.local_replacements: true` | Detect filesystem replacements in selected committed module declarations. |
+
+Also select
+`validation.forbidden_files: [".releasekit/gitea-token"]` in all three profiles.
+This delegates protection of the supplied credential path to ReleaseKit's
+existing check. The path is repository-relative and the check applies across
+the captured repository even for an integration release. It does not read token
+contents, scan other paths, or inspect Git history.
+
+Retain the explicit shared-file lists and use ReleaseKit's existing input scope.
+The root profile does not run every nested module's suite. File checks inspect
+committed inputs and do not replace formatting worktree changes or reviewing
+documentation meaning, attribution, and external links. Markdown keeps its
+default treatment of outside-checkout destinations; no stricter boundary mode
+is proposed.
+
+The pinned [ReleaseKit configuration reference](https://forge.maximumdirect.net/base-layer/releasekit/src/commit/23203f235cc414c4ffe0fd3941030eb0c9f9943f/docs/config.md)
+owns exact scope and behavior, including nested-module boundaries and vendored
+inputs. Do not expand an option's scope into a general repository prohibition.
+Race testing, full vet, compilation matrices, size limits, and additional
+forbidden-file paths are not selected by this roadmap. They can be considered
+separately for demonstrated needs.
+
+### Launcher and recovery
+
+Use the root module's registered `go tool releasekit` through `exec`, keeping
+the current selector interface and publication argument mapping.
+Retain host normalization, workspace-off execution, the local toolchain, and
+read-only module metadata. Preserve other effective Go settings while arranging
+read-only selection.
+The implementation plan specifies the wrapper interface and invocation details.
+
+Go's cache supplies executable storage; the launcher creates no persistent
+binary directory. `/.releasekit/` remains ignored for the credential file, with
+an explanatory comment. Recovery instructions use the registered tool or the
+entry point printed for the saved attempt, preserving ReleaseKit's distinction
+between publication outcome and record-storage errors.
+
+Share module selection and host-safe tool invocation between publication,
+delivery, and recovery where applicable. Delivery selects the same module
+profile as publication; recovery uses its recorded attempt rather than inferring
+identity from a current profile. Keep the existing publication interface and
+provide an explicit delivery invocation without automatically chaining the two
+operations. Keep one selector mapping and shared invocation plumbing.
+
+ReleaseKit v0.9.0 shipped host-safe consumer launcher examples and regression
+coverage. The earlier simplification used v0.8.0, which already supported
+registered tools. Keep host normalization locally because the reviewed
+`go tool` invocation inherited foreign `GOOS`/`GOARCH` values and failed to run.
+Do not switch tool-version selection from the root module to each integration
+merely to match the upstream multi-module example.
+
+### Hosted Gitea release pages
+
+Configure this delivery selection in each module profile:
+
+| Field | Selected value |
+| --- | --- |
+| `delivery.forge` | `gitea` |
+| `delivery.base_url` | `https://forge.maximumdirect.net` |
+| `delivery.owner` | `base-layer` |
+| `delivery.repository` | `commandkit` |
+| `delivery.token_file` | `.releasekit/gitea-token` |
+
+Preserve the profiles' distinct product identities and physical module
+directories. All pages belong to the same Gitea repository and are keyed by
+the complete tag: `vX.Y.Z` for core, `integrations/ckconfig/vX.Y.Z` for ckconfig,
+and `integrations/ckprompt/vX.Y.Z` for ckprompt. Pass the selected profile and
+semantic version to `deliver`; ReleaseKit derives the complete module tag.
+
+With no build targets, delivery is page-only. ReleaseKit uses the complete
+checked-in module release note, including its licensing footer, as the hosted
+body. No binary assets, receipts, or checksum manifests are added. Use current
+forge URLs and the full module tag for future notes' immutable source and
+licensing links. Existing published tags and notes remain unchanged.
+
+After source publication succeeds, explicitly invoke delivery from a clean
+checkout whose `HEAD` identifies that published tag's commit. For later retries,
+use the original tagged source and its recorded module files. Report the source
+publication outcome and hosted-delivery outcome separately, including the hosted
+URL on success. A delivery failure leaves the source release complete; repair
+delivery without republishing or moving its tag.
+
+Delivery performs its own read-only credential preflight, without rerunning
+candidate validation or publishing a tag. Hosted-service availability and the
+Gitea token do not become source-publication gates. A nonblank
+`RELEASEKIT_GITEA_TOKEN` environment value takes precedence over the configured
+file. The file path resolves from the repository root for all three modules.
+
+ReleaseKit accepts matching hosted content and reports conflicting content
+without overwriting it. Resolve uncertain hosted writes before retrying the
+same immutable version. The pinned
+[delivery guide](https://forge.maximumdirect.net/base-layer/releasekit/src/commit/23203f235cc414c4ffe0fd3941030eb0c9f9943f/docs/consumers/delivery.md)
+owns exact delivery behavior and recovery. Start with tags containing the new
+delivery configuration; historical page backfilling remains a separate decision.
+This local workflow needs no CI delivery job or additional secret distribution.
+
+### Focused local tests
+
+Replace the release-test scaffolding with a small controlled Go-command boundary
+that invokes the actual launcher. Cover:
+
+- Selector-to-profile/module routing for core, ckconfig, and ckprompt, including
+  consistency with the checked-in profiles' intended module and product.
+- Invalid argument handling before tool invocation.
+- Invocation from another directory and paths containing spaces.
+- Host normalization and workspace/toolchain/read-only settings.
+- Publication and delivery argument, output-stream, and child exit-status
+  forwarding, with the selected module profile reaching the delivery operation.
+- Profile wiring for the shared Gitea destination, token path, and its selected
+  committed-path protection; assertions do not read the credential file.
+
+Exercise module routing separately from exit statuses rather than multiplying
+every combination. Assert behavior and meaningful selections, not helper
+implementation details or exact usage prose.
+
+The resulting local suite omits the disposable publication exercise, generic
+tag inspection, assertion-helper self-tests, and custom build-call log/parser.
+Upstream publication and delivery coverage owns those generic behaviors. No
+replacement publication engine or exported test-helper API is needed. There is
+no line-count target for the replacement tests.
+
+## Selected choices and rationale
+
+All four generic file checks are selected as release-time checks, in addition
+to the agreed forbidden token path. Formatting and local-link validation automate
+existing contributor review work. Workspace-file and filesystem-replacement
+checks address accidental inclusion of development metadata that a successful
+local test run can overlook. This adds specific release checks; it does not
+make every optional ReleaseKit validator mandatory or prohibit development
+workspaces and replacements outside the selected committed candidate inputs.
+Selecting only formatting and Markdown would change less release behavior, but
+would leave these distribution mistakes to manual review. The selected upstream
+checks avoid a second local implementation.
+
+Host-normalized registered-tool execution is selected because the root module
+already registers ReleaseKit and Go caches the executable. Retaining a persistent
+native executable would provide a recovery entry point independent of a later
+Go-driver invocation, but would retain executable-storage and bootstrap test
+maintenance. Recovery instead uses the registered tool or ReleaseKit's reported
+entry point. The credential directory remains ignored under either approach.
+
+The implementation plan records the existing integration dependency-version
+mismatch separately from validation of the current source. This infrastructure
+sprint does not publish releases or select new library dependency versions.
+Historical hosted-page backfilling and CI delivery remain separate future
+choices, not prerequisites for the selected local page-only workflow.

docs/roadmap/releasekit-v0.9.0.md

@@ -0,0 +1,184 @@
+# ReleaseKit v0.9.0 adoption
+
+Status: R1 and R2 remediation, ReleaseKit v0.9.0 adoption, and the completion
+assertion repair are complete. The [completed implementation record](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/c8d659dfe5ae3e834b3aeabdfd0fe29b736dc05a/docs/roadmap/implementation.md)
+records stage order, tasks, and validation evidence. This document owns the
+target and selected choices; it does not authorize source or hosted publication.
+
+## Purpose and authority
+
+Adopt ReleaseKit v0.9.0's improved recovery behavior while preserving
+CommandKit's existing release-tooling architecture. Update current dependency
+and maintainer documentation together, and make the validation evidence clear
+about existing local defects.
+
+The [agent policy](../policy/agents.md),
+[release policy](../policy/release.md#candidate-validation),
+[testing policy](../policy/testing.md#upstream-integration-testing-ownership),
+and [documentation policy](../policy/documentation.md) govern the work. Current
+behavior remains owned by the [release procedure](../release.md), Go declarations,
+and owning package tests until implementation updates them.
+
+## Current baseline and review evidence
+
+Reviewed CommandKit code baseline: `4d92ee4ee6a8403b22a4172e0f04face802b9499`.
+The original upgrade review used `98e7e9933353cf43f2be4a96cb0436a0bce068d2`;
+its findings and validation history are retained below.
+
+- The root [module](../../go.mod) selects
+  `go.maximumdirect.net/releasekit v0.8.0` as a Go tool. Its selected version
+  serves core, ckconfig, and ckprompt operations.
+- The [shared helper](../../scripts/releasekit) already normalizes the Go host,
+  disables workspace discovery, selects the local toolchain, retains read-only
+  metadata, and invokes the full executable package path. The
+  [legacy entry point](../../scripts/release) delegates publication to it.
+- All three profiles already select the agreed generic file checks, forbidden
+  token path, and page-only Gitea destination. Source publication and hosted
+  delivery are separate operations. The local token directory remains ignored.
+- [R1 and R2](remediation.md) are complete. Commit `7eac3fe` rejects invalid
+  legacy selectors before invoking Go; commit `4d92ee4` restores explicit,
+  optional POSIX-shell invocation in launcher tests. The remediation record owns
+  their acceptance evidence, including passing focused tests, shell syntax
+  checks, and profile assertions running when no shell is available.
+- Both integrations still require older published CommandKit dependencies than
+  their current source needs. The completed [release-tooling implementation record](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/87eb84ccb462bf54e6250c8b287ac217efe90883/docs/roadmap/implementation.md#stage-5-verify-the-final-source-and-record-validation-boundaries)
+  distinguishes workspace-backed tests from independent release readiness.
+
+The upstream v0.9.0 tag identifies commit
+`2180aa868ec2caa95fc8279fd59d5f0ebac41bd4`. The tag and direct Go-module
+resolution were verified. The default proxy initially returned v0.8.0 for
+`@latest`; select v0.9.0 explicitly rather than changing repository-wide proxy
+settings to work around that observation.
+
+Upstream [release notes](https://forge.maximumdirect.net/base-layer/releasekit/src/tag/v0.9.0/docs/releases/v0.9.0.md)
+describe host-safe launchers and generated recovery commands, full package-path
+tool selection, preservation of wildcard and version-specific replacements in
+API-only recovery, and safer manual hosted-page retries. Public Go APIs,
+profiles, record formats, and the Go 1.26.0 consumer minimum remain unchanged.
+The v0.8.0-to-v0.9.0 comparison also left upstream module requirements, checksums,
+copyright, and license texts unchanged.
+
+A disposable CommandKit upgrade changed only the selected ReleaseKit version in
+`go.mod`. With Go 1.26.8, the root suite passed on a subsequent run, both
+workspace-backed integration suites passed, and the real helper reported v0.9.0
+under foreign target settings. No production publication or delivery was run.
+
+A later disposable review at `7eac3fe` confirmed that downloading and tidying
+v0.9.0 changed only the ReleaseKit requirement and its checksum entries. The
+offline root suite and both workspace-backed integration suites passed with
+Go 1.26.8, and the helper reported v0.9.0 under Windows/ARM64 target settings.
+That snapshot excluded the then-uncommitted R2 change; it does not replace
+validation of the eventual adoption commit.
+
+The initial upgrade run failed in
+[`TestCompletionCommandContext`](../../completion_context_test.go). The same
+alias-order failure reproduced four times in 30 focused repetitions on the
+unchanged v0.8.0 baseline. A single passing rerun therefore does not establish
+stable validation. The test compares an internal alias slice in a fixed order;
+commit `0acbbf4` deliberately changed completion to use unsorted lookup records
+before this upgrade review.
+
+## Targeted end state
+
+### Tool adoption and retained architecture
+
+The root module selects ReleaseKit v0.9.0 with authentic downloaded checksums.
+Its existing tool declaration and root-owned selection remain. No integration
+dependency version, library import path, Go minimum, or selected Go 1.26.8
+maintainer toolchain changes as part of adoption.
+
+Keep host normalization and full-package invocation in the existing helper:
+upgrading a dependency does not update or replace local shell scripts. Keep one
+module/profile mapping and the established wrapper forms. Retain the selected
+profiles, token-file handling, credential-directory ignore rule, and separation
+of source and hosted outcomes. No new validator, binary target, CI workflow,
+publication channel, credential preflight gate, or runtime API is needed.
+
+The new generated Go recovery commands complement the helper's existing host
+handling. Recovery continues to use saved publication evidence and the upstream
+record formats; CommandKit does not acquire a parallel recovery implementation.
+
+### Release-code simplification review
+
+The v0.9.0 review identified no additional local release implementation to remove.
+The earlier simplification already delegated generic validation, publication,
+delivery, and recovery to ReleaseKit. This release improves launcher examples
+and generated recovery commands without adding validation options that replace
+the remaining CommandKit code.
+
+Retain the shared helper's module/profile selection and execution environment.
+Host normalization must happen before Go compiles and runs ReleaseKit. Retain
+the legacy publication wrapper to preserve the established maintainer interface.
+The upstream multi-module launcher example adds a module map and temporary
+metadata preparation for a different tool-selection model; replacing our
+root-owned registered-tool helper with it would add machinery.
+
+Retain the focused [wiring tests](../../scripts/release_test.go) for profile
+selections, argument forwarding, environment, streams, status, and optional-shell
+handling. ReleaseKit owns validation and recovery semantics; CommandKit's tests
+continue to cover its own adapter. The adoption work therefore preserves the
+release-code structure while updating the dependency and documentation, alongside
+the separately planned completion assertion repair.
+
+### Current documentation and history
+
+Current release procedure, project-specific release policy, consumer Go-tool
+selection summary, and root attribution describe v0.9.0. Upstream contract and
+notice links use the corresponding immutable source revision. Record that the
+host-safe launcher request has shipped upstream instead of describing it as
+pending in the earlier feature roadmap.
+
+Continue linking to upstream recovery and delivery contracts from the maintainer
+procedure. Use ReleaseKit's generated recovery commands and keep local guidance
+focused on CommandKit's entry points and selections.
+
+Preserve the baseline and validation history in completed implementation and
+review records. Do not mechanically replace every historical v0.8.0 reference.
+Integration attribution describes its own selected published dependency graph;
+update it only if that actual selection changes. No license-text replacement
+is needed for the unchanged upstream texts.
+
+### Completed remediation and remaining correctness work
+
+R1 and R2 were delivered before the dependency upgrade, with their completion
+markers and acceptance evidence in [remediation.md](remediation.md). Preserve
+their selector rejection, legitimate raw helper forms, and optional-shell test
+boundary during adoption; no further implementation of those findings remains.
+
+The completion assertion compares the expected alias source/target records
+without depending on their iteration order, while detecting missing, unexpected,
+or duplicate records. Its routing and visible-completion assertions remain.
+Production alias ordering and public contracts are unchanged. This correction
+was completed as part of the maintenance scope, separate from R1/R2 remediation;
+the implementation plan records the test changes and focused verification.
+
+Ordinary releases retain their single selected-module publication suite and
+separate hosted-delivery outcome. One-time upgrade diagnostics are maintenance
+evidence, with no new recurring release gate. Credentials and live publication
+are unnecessary for this adoption.
+
+## Completion evidence
+
+Adoption is demonstrated by authentic module metadata, the real helper reporting
+v0.9.0 for the host, aligned current documentation and attribution, and recorded
+validation of the final source. The reviewed upgrade introduced no other module
+version change; verify rather than assume that result during implementation.
+
+R1/R2 acceptance evidence is complete in the remediation record. Completion of
+the remaining maintenance work also includes a stable, order-independent
+completion assertion and validation that the adopted helper retains the
+corrected launcher behavior. Independent integration dependency alignment
+remains separate release-preparation work; this roadmap selects no future
+versions or sums.
+
+## Resolved choices
+
+R1 and R2 were corrected in separate commits before adoption, resolving the
+former OD-1 scheduling question. Their acceptance evidence remains in
+[remediation.md](remediation.md).
+
+The selected maintenance scope is the completion assertion repair, root tool
+upgrade, aligned current documentation and attribution, and validation of the
+resulting source. The older integration dependency-version mismatch remains
+separate release-preparation work. The implementation plan defines execution
+and commit sequencing.

docs/roadmap/remediation.md

@@ -0,0 +1,116 @@
+# Release tooling review findings
+
+Status: R1 and R2 complete; no open findings. Review baseline:
+`124a9fa57fb3f815bedbafe2d4819f6aa265ee7d`, covering the implementation commits
+after `cb40f1d`. The findings below preserve the review evidence; completion
+markers record the subsequent corrections. No implementation was changed during
+the original review.
+
+The selected architecture is substantially present: three declarative profiles,
+one host-normalized registered-tool helper, separate publication and page-only
+delivery, retained credential-directory ignoring, and focused wiring tests.
+Both issues identified by the review have been addressed.
+
+## R1 — P2: Reject raw helper command names as legacy module selectors
+
+**Completed.** The legacy entry point now checks its three module selectors
+before delegating to the helper, retaining the single profile/module mapping
+there. Regression cases cover all three raw-command collisions and require
+usage status 2 with no Go invocation. The new regression failed before the fix;
+the complete focused scripts suite and shell syntax checks passed afterward
+with Go 1.26.8, including valid legacy and direct raw-command forwarding.
+
+**Location:** [scripts/release](../../scripts/release), lines 9–10, delegating to
+the first-argument dispatch in [scripts/releasekit](../../scripts/releasekit),
+lines 10–15. The invalid-form cases in
+[scripts/release_test.go](../../scripts/release_test.go), lines 186–200, miss
+these collisions.
+
+The legacy interface is `scripts/release MODULE VERSION`, with three module
+selectors. It now delegates its first argument directly into a helper that also
+accepts `version`, `publication-attempts`, and `reconcile` as raw commands. These
+invalid module names consequently bypass selector rejection and invoke Go.
+
+For example, `./scripts/release version v1.2.3` reaches the tool as
+`version publish v1.2.3`. With the real pinned tool it returns upstream's
+"version takes no arguments" diagnostic after tool resolution. In a disposable
+copy with a controlled Go boundary returning status 73, each of the three raw
+command names returned 73 and invoked Go; an ordinary unknown selector returned
+2 without invoking Go. Thus invalid legacy input depends on tool availability
+and behavior instead of being rejected at the wrapper boundary.
+
+**Required correction:** Make legacy module selection unambiguous before raw
+command dispatch. Keep one profile/module mapping and the supported raw helper
+forms; a small selector check is preferable to another routing framework.
+Preserve upstream ownership of version and flag validation.
+
+**Verification:** Add all three raw command names as invalid legacy selectors.
+Each must return usage status 2 before any Go command runs. Valid legacy
+publication and the helper's direct raw forms must retain their forwarding and
+exit-status behavior. This restores the requested malformed-wrapper handling;
+it adds no new accepted-version restriction.
+
+## R2 — P2: Restore the tests' optional POSIX-shell execution boundary
+
+**Completed.** Launcher execution tests now discover `sh`, invoke it explicitly
+with the script path, and skip when it is unavailable. Profile assertions remain
+independent of shell availability. A regression case removes the fixture
+script's executable permission to verify interpreter invocation; it failed
+before the correction and passes afterward. The focused scripts suite and shell
+syntax checks passed with Go 1.26.8 on the available POSIX host. Running the
+compiled test binary with an empty `PATH` confirmed that every launcher
+execution case skips while all three profile assertions pass. Native Windows
+execution was not tested and no new platform guarantee is introduced.
+
+**Location:** [scripts/release_test.go](../../scripts/release_test.go), especially
+`fixture.run` at line 63 and the launcher test setup.
+
+The rewritten tests execute extensionless POSIX shell scripts directly through
+`exec.Command`. They neither discover a shell nor skip launcher execution when
+it is unavailable. The previous suite resolved `sh`, skipped shell-dependent
+tests when it was missing, and passed the script as an argument to that shell.
+
+Direct execution works on this review's Linux host, but relies on Unix script
+execution semantics. Native Windows process creation does not supply a POSIX
+interpreter for these files. Go's
+[os/exec documentation](https://pkg.go.dev/os/exec#hdr-Overview) explicitly notes
+that it does not invoke a system shell. Consequently the default repository
+suite now fails on hosts without compatible script execution rather than
+preserving the previous optional-shell behavior. This portability finding is
+based on the changed execution path and platform implementation; a native
+Windows test run was not available during review.
+
+**Required correction:** Discover a POSIX shell for launcher execution tests,
+invoke it explicitly with the script path, and skip those tests when the shell
+is unavailable. Keep profile-only JSON assertions runnable without requiring a
+shell. Preserve the reduced test architecture and existing argv/status checks.
+No native Windows release launcher or additional supported-platform guarantee
+is requested.
+
+**Verification:** Confirm that launcher tests use the discovered interpreter
+and handle its absence explicitly, while profile assertions still run. Rerun
+the focused suite on the available POSIX host. Broader platform matrices are
+not a new release gate; this correction removes an incidental environment
+restriction introduced by the test rewrite.
+
+## Review evidence and limits
+
+- Go 1.26.8 offline root tests and the temporary-workspace suites for both
+  integrations passed. Both production scripts passed shell syntax checks.
+- The real helper reported ReleaseKit v0.8.0 under foreign target settings.
+- ReleaseKit checks passed for a disposable committed source snapshot using
+  the actual profiles: ordinary root validation, then both integration checks
+  with the implementation plan's temporary workspace-backed test process.
+  Selected file checks continued to inspect the committed declarations.
+- Local documentation destinations and applicable Markdown fragments passed
+  inspection. The credential file remained ignored and its contents were not
+  read. No real publication or hosted-delivery operation was invoked.
+- Library code and dependency declarations were unchanged by the sprint. The
+  documented integration dependency-version mismatch remains a pre-existing
+  independent-release-readiness limitation; the workspace-backed results do
+  not establish that published dependencies are aligned.
+
+No additional architecture gaps or unrequested runtime/public-API guarantees
+were identified. The selected file checks and forbidden token path match the
+finalized scope. R2 concerns the default tests' execution environment rather
+than a new production validator or library contract.

docs/roadmap/reporting.md

@@ -0,0 +1,890 @@
+# Output policy and invocation reporting
+
+Status: behavioral decisions selected through OD-4. Message categories, all four
+output modes, uniform treatment of help and version, message prefixes, and
+OD-1's flag grammar and scope (including independent Progress control) are selected.
+OD-2's unified reporting direction, the terminal failure model, and application
+ownership of domain-specific error decisions are selected.
+OD-3's failure presentation and retention boundaries are selected.
+OD-4's delivery lifecycle, write-failure handling, and quiet-mode rendering are
+selected. The consumer API signatures, presentation-result model, provider
+diagnostic boundary, fallback explanations, and rendering callback boundary
+below are also selected. Architectural preparation is complete:
+[ADR 0014](../adr/0014-invocation-reporting.md) is accepted, and the
+[architecture policy](../policy/architecture.md) is aligned. Implementation and
+final validation are complete; Stages 1–20 are complete. The [implementation
+plan](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/230187296fae5253cb1773f16c2f1d1a39499ed0/docs/roadmap/implementation.md) records the stage order and validation evidence.
+
+## Purpose
+
+Provide consistent handling of `--quiet`, `--verbose`, `--debug`, and
+`--progress` across application commands and optional integrations. Reduce
+repeated output classification, diagnostic presentation, and delivery bookkeeping
+where CommandKit can provide a meaningful benefit.
+
+Ordinary Go writers and formatting functions already make application output
+straightforward. Design reporting conveniences around the shared output policy
+and invocation lifecycle. Applications continue to own their report content,
+domain behavior, and operation outcomes.
+
+## CLI presentation and error-handling ownership
+
+Applications decide how to respond to domain-specific errors: recover, retry,
+continue silently, report a Warning, or end the invocation with a failure.
+CommandKit may provide shared helpers for carrying, inspecting, and presenting
+errors while leaving those decisions with the application. A Go `error` alone
+does not determine a CLI message category. Warnings may describe issues with or
+without an underlying Go error, and handling an error does not require emitting
+a message.
+
+CommandKit handles the presentation the application requests: message category,
+visibility, formatting, timing, and delivery. For terminal application failures,
+the application supplies a non-zero outcome and an operator-facing explanation.
+It may also supply an optional Go error cause for the execution caller to inspect.
+CommandKit preserves that cause and its existing `errors.Is`/`errors.As` behavior.
+Supplying a cause alone does not select an outcome, generate an operator-facing
+message, or change visibility.
+
+Applications can explicitly present `err.Error()` as a Warning through the
+ordinary message API, illustrated by `report.Warn(err.Error())`. Defer a separate
+`WarnError` convenience helper pending demonstrated value; this conversion
+already requires little code.
+
+CommandKit retains responsibility for handling its own errors, including
+routing, parsing, and reporting failures. Integration-owned commands similarly
+adapt their upstream APIs into deliberate command outcomes and presentations.
+Ordinary Go error returns from CommandKit APIs and writers remain available where
+appropriate.
+
+## Current baseline
+
+[`Streams` and `Invocation`](../../identity.go) expose caller-selected output
+and diagnostic writers. [`Outcome` and `Diagnostic`](../../outcome.go) carry
+operation causes, diagnostic writers, and delivery state. Handlers can return
+`Failure(err)` or attach diagnostics to an outcome for presentation after the
+handler returns. `MessageDiagnostic` currently writes the supplied message with
+a newline; severity does not add a label automatically.
+
+CommandKit coordinates final diagnostic delivery and retains delivery failures
+separately from the operation cause. Custom handlers can also write directly to
+the supplied streams and retain responsibility for their output. The existing
+outcome and channel ownership decisions are recorded in
+[ADR 0005](../adr/0005-invocation-outcomes.md).
+
+Integration adapters already translate upstream diagnostic records into
+CommandKit diagnostics while preserving native rendering and source context.
+Some adapters wrap multiple records in one diagnostic writer and classify the
+batch by its highest severity. This matters when designing selective visibility.
+
+There is currently no shared verbosity policy or invocation reporter API.
+
+## Selected output policy
+
+Distinguish substantive application output from diagnostic message categories:
+
+- **Substantive output (Normal):** The requested report or command result.
+- **Error:** Terminal presentation of an unrecoverable invocation failure,
+  resulting in a non-zero status code.
+- **Warning:** Something went wrong or deserves attention, but the invocation
+  can still succeed. The application chooses whether to report such an issue.
+- **Info:** Informational context and useful explanation, such as which profile
+  was selected or a final operation summary.
+- **Progress:** Streaming updates about work underway, such as items processed.
+- **Debug:** Troubleshooting detail, including intermediate decisions and
+  execution-path information.
+
+Debug mode adds troubleshooting detail to verbose output:
+
+| Output category | `--quiet` | No flag | `--verbose` | `--debug` |
+| --- | --- | --- | --- | --- |
+| Substantive application output | Suppressed | Shown | Shown | Shown |
+| Error | Shown | Shown | Shown | Shown |
+| Warning | Suppressed | Suppressed | Shown | Shown |
+| Info | Suppressed | Suppressed | Shown | Shown |
+| Debug | Suppressed | Suppressed | Suppressed | Shown |
+| Progress, without an explicit setting | Suppressed | Suppressed | Suppressed | Shown |
+
+Info belongs in verbose mode; debug includes verbose messages. Normal output
+remains a substantive result category, separate from diagnostic severity.
+The category of a message determines its visibility; stream destination alone
+cannot distinguish a warning from an error.
+
+Progress is distinct from Info and is controlled separately as specified below.
+Applications and integrations are not required to generate messages in any
+category. Enabling a category adds no output when there are no messages in it;
+other output remains subject to its own visibility rules.
+
+Error presentation follows the terminal failure model below. An application
+may report a recovered problem as a Warning or continue without a message.
+
+Apply the same policy to help and version. There are no command-specific
+exceptions for successful output:
+
+```text
+app help --quiet       # succeeds silently
+app version --quiet    # succeeds silently
+```
+
+Usage and operational failures still report their errors in quiet mode.
+The feature must distinguish successful output suppression from failure
+diagnostic delivery.
+
+### Message prefixes and channels
+
+Substantive output uses the result destination, conventionally stdout. Warning,
+Info, Progress, Debug, and terminal explanations use the diagnostic destination,
+conventionally stderr. Callers supply both destinations.
+
+Use `WARN:`, `DEBUG:`, and `ERROR:` prefixes for simple warning, debug, and error
+messages respectively. Substantive output and Info messages have no prefix.
+For multiline diagnostics, prefix the opening line and preserve the structured
+detail. Integration adapters coordinate native diagnostic rendering to avoid
+duplicate severity labels or loss of upstream formatting.
+
+Usage guidance belongs to the terminal usage explanation and remains visible in
+quiet mode. Successful help output follows the substantive-output policy.
+
+Initially, Progress messages are unprefixed streamed lines. The diagnostic
+destination keeps them separate from substantive output such as JSON or YAML.
+Terminal redraw and progress-bar behavior are outside this implementation.
+
+### Terminal failure model
+
+During execution, applications can produce substantive output, Progress, Info,
+Debug, and Warnings. An unrecoverable failure ends the handler by returning a
+failed outcome. There is no standalone `report.Error(...)` method. Detailed
+error explanations accompany the returned failure and are presented as part of
+that terminal step.
+
+CommandKit finalizes reporting, presents the terminal failure explanation, and
+returns the non-zero outcome to the application entry point. It accepts no
+further normal output for that invocation after terminal error presentation.
+The same boundary applies to core routing and parsing failures that prevent
+handler execution. The application entry point retains ownership of process
+exit; CommandKit ends the invocation and returns its outcome.
+
+For example, if an export operation fails and the application decides it cannot
+continue, the handler returns a non-zero outcome with an explicit explanation
+such as "Unable to export the requested report." The application can choose to
+include detail from a Go error in that explanation. CommandKit presents the
+supplied explanation without automatically deriving text from an application
+error. The selected API below provides failure constructors for this purpose.
+When a failed outcome supplies no explanation, CommandKit supplies the generic
+fallback defined under terminal outcomes below.
+
+Output streamed before the failure remains visible according to its selected
+mode; terminal failure does not withdraw earlier bytes. Deferred messages,
+cleanup writes, and delivery failures must respect the end of normal reporting.
+Their finalization and late-write behavior follow OD-4 below. A terminal
+failure may have multiple explanatory records, all belonging to that failure.
+
+### Failure explanations and presentation ownership (OD-3)
+
+Make a non-zero outcome with an explicit message the convenient failure path.
+Support structured explanations, including multiple records, through the same
+presentation facility for richer application and integration reports. Neither
+form requires an underlying Go error.
+
+The application or integration explicitly identifies the context belonging to
+a terminal explanation. Present that context with the failure in every mode,
+including quiet. Independent warnings and other messages retain their own
+visibility rules. For mixed upstream batches, adapters preserve useful native
+rendering while distinguishing terminal explanatory context from independent
+messages. Core does not infer those relationships from error chains or text.
+
+Assign each submitted message one presentation path. Returning a terminal
+explanation schedules its presentation once; core does not append another
+message derived from an application error cause. Native renderers can supply
+already-labelled content without receiving duplicate prefixes. Avoid text-based
+deduplication: separate events may legitimately produce identical messages.
+
+Constructing a failure result attaches explanatory content without emitting or
+independently scheduling an Error. Returning that result hands the explanation
+to CommandKit for terminal delivery through the invocation's reporting facility.
+The selected API expresses this distinction for both simple and structured
+explanations. For example:
+
+| Handler action | Presentation |
+| --- | --- |
+| Construct a non-zero result with "Unable to export the requested report," then return it. | Construction emits nothing. CommandKit presents the message once during terminal delivery. |
+| Return a failure with native diagnostic records and their source context, submitting independent warnings separately. | CommandKit presents the structured terminal explanation in every mode. Independent warnings follow their own visibility policy. |
+
+### Retention boundary (OD-3)
+
+CommandKit provides invocation-scoped CLI presentation. Logging and message
+history collection remain application concerns. Keep terminal explanations and
+any supplied cause with the returned outcome, and keep the temporary state needed
+for deferred delivery, parser events awaiting mode selection, and delivery
+bookkeeping. The reporting facility does not collect a transcript or retain other
+emitted or suppressed messages for later inspection. No optional message-history
+facility is planned for this implementation.
+
+## Selected flag grammar and scope
+
+### Mode selection and resets
+
+Model quiet, ordinary, verbose, and debug as mutually exclusive presentation
+modes. Each invocation starts in ordinary mode. Process flag occurrences in
+invocation order; the last enabled mode wins. Repetition does not increment
+verbosity, and debug is selected explicitly.
+
+Accept presence and the existing explicit boolean syntax, including
+`--quiet=true` and `--quiet=false`. A false occurrence clears its mode only if
+that mode is currently selected, returning to ordinary mode. It does not restore
+an earlier selection or disable a different mode. Every occurrence is converted;
+invalid boolean values remain usage errors even when a later flag would replace
+the selection.
+
+| Flag sequence | Final mode |
+| --- | --- |
+| `--quiet --verbose` | Verbose |
+| `--debug --quiet` | Quiet |
+| `--verbose --verbose` | Verbose |
+| `--verbose --verbose=false` | Ordinary |
+| `--quiet --verbose=false` | Quiet |
+| `--verbose --quiet --quiet=false` | Ordinary |
+| `--quiet=false --debug` | Debug |
+
+Keep verbosity a presentation choice: quiet preserves the requested operation's
+semantics and rendering failures. Delivery failures depend on the output actually
+requested; suppressing a destination write can avoid a delivery failure. Apply
+the policy through CommandKit-managed reporting and streams. Output written
+directly to process streams or external destinations remains application-owned.
+
+### Progress selection
+
+`--progress` enables Progress without enabling Info, Warning, or Debug messages.
+`--progress=false` explicitly disables it. Accept the existing boolean syntax;
+repeated canonical or aliased progress settings use the last value. Retain
+whether a setting was explicitly supplied, separately from its boolean value.
+
+Determine effective Progress visibility from the final presentation mode and
+explicit progress setting:
+
+1. Quiet mode always suppresses Progress.
+2. Otherwise, an explicit progress setting controls visibility.
+3. Without an explicit setting, debug enables Progress; ordinary and verbose
+   modes leave it disabled.
+
+An explicit progress setting overrides the mode's default regardless of its
+position relative to mode flags. It does not select or reset the presentation
+mode. Debug includes verbose detail and defaults Progress on; verbose alone
+does not enable Progress.
+
+| Flags | Result |
+| --- | --- |
+| `--verbose` | Warning and Info, without Progress. |
+| `--verbose --progress` | Warning, Info, and Progress. |
+| `--debug` | Warning, Info, Debug, and Progress. |
+| `--debug --progress=false` or `--progress=false --debug` | Debug detail without Progress. |
+| `--quiet --progress` or `--progress --quiet` | Only failure diagnostics. |
+| `--debug --verbose` | Verbose detail without Progress, absent an explicit progress setting. |
+
+Passing `--progress` to an application that emits no Progress messages adds no
+visible output. It does not suppress that application's substantive results or
+require a progress implementation.
+
+### Placement, availability, and aliases
+
+Core supplies `--quiet`, `--verbose`, `--debug`, and `--progress` for application
+commands, integrations, the root, canonical groups, and alias-only discovery help.
+Consumers do not register them individually. Preserve the existing placement
+grammar: flags follow the complete command path and may be interspersed with
+operands after that path. For example:
+
+```text
+app config show --quiet
+app export destination --verbose
+app help config show --quiet
+app version --quiet
+```
+
+Options before or between command-path components are outside this grammar.
+Tokens consumed as values and tokens following `--` retain their ordinary
+meaning.
+
+Reserve the four long spellings. Applications may add `-q`, `-v`, or `-d`
+through the alias API; no built-in short spellings are selected. An application
+flag declaration that defines a reserved long name fails installation with a
+collision error. Aliases may target these flags but may not overload canonical
+spellings. Apply the existing collision and atomic installation rules, including
+later registration.
+
+Aliased and canonical occurrences participate in the same ordering. With
+`-q → --quiet`, `app export --verbose -q` selects quiet mode. Document the newly
+reserved canonical names as a compatibility change.
+
+### Routing and parsing failures
+
+Determine the mode through the normal parser before execution or successful
+help/report presentation. Do not add a separate verbosity scanner. This keeps
+token interpretation consistent and avoids reinterpreting values or operands.
+
+Routing and parsing failures report their errors regardless of verbosity. For
+example, `app export --quiet --unknown` still reports the unknown flag. Error
+visibility follows the selected output policy independently of how the mode is
+determined; avoiding a separate scanner is an implementation simplification.
+
+## CommandKit's own diagnostics
+
+Use the shared reporting system for CommandKit's invocation diagnostics so
+parser, integration, and application messages follow the same visibility and
+delivery policy. Installation errors occur before an invocation exists and
+continue to be returned to the application without automatic printing.
+
+Supported repetition and last-occurrence overrides are routine decisions.
+Repeated singleton flags, including `--verbose --verbose`, may produce debug
+detail; repetition alone does not warrant a warning. Repeatable flags retain
+their intended accumulation behavior. Add warnings for concrete concerns an
+operator can act on, such as a deprecated spelling if deprecation is introduced.
+Unknown flags, invalid values, and invalid command paths remain invocation
+failures with error diagnostics.
+
+Start debug instrumentation with routing, alias resolution, verbosity selection,
+and handler completion. Other useful candidates can be added where they
+explain a consequential decision:
+
+| Event | Useful detail |
+| --- | --- |
+| Command-alias resolution | Entered path, intermediate redirects, and final canonical path. |
+| Flag-alias resolution | Entered spelling and canonical flag name. |
+| Scoped alias selection | A command-scoped mapping took precedence over an application-wide mapping. |
+| Verbosity selection | A later occurrence selected a different mode; for `--verbose --debug`, debug wins because it appears last. |
+| Help-route selection | A canonical command or alias-only discovery context was selected. |
+| Repeated singleton flag | A later occurrence replaced an earlier occurrence, without printing their values. |
+| Input preparation | Canonical input validation completed and the handler is starting. |
+| Handler completion | Canonical command and the handler's returned classification and status, before final delivery. |
+
+The handler-completion event describes the handler's result. The final returned
+invocation outcome also includes delivery failures and remains authoritative.
+Present this event before terminal failure presentation; do not emit a completion
+message afterward.
+
+Use the final selected mode to present earlier parser decisions. Collect the
+relevant events during parsing and apply visibility after mode selection:
+`--verbose --debug` shows the selection explanation, while `--debug --quiet`
+suppresses it. This collection of parser events does not require whole-run
+output buffering.
+
+Debug messages should explain operator-relevant decisions independently of
+incidental implementation steps. Use command paths, flag names, and decision
+descriptions rather than raw argument or configuration-value dumps. Upstream
+libraries retain ownership of their diagnostic detail and disclosure rules.
+
+## Selected delivery lifecycle and quiet execution (OD-4)
+
+### Ordering and finalization
+
+Use synchronous delivery. Present immediate messages and substantive writes in
+submission order. After the handler returns:
+
+1. Deliver eligible deferred messages in queue order, without sorting by severity.
+2. Finish ordinary reporting, including any handler-completion debug message and
+   flushing any CommandKit-owned buffers for ordinary output. Account for failures
+   discovered during this delivery before preparing the terminal explanation.
+3. Present any terminal failure explanation and complete its delivery, including
+   any CommandKit-owned buffering of that explanation.
+4. Close the invocation's reporting facility and return the final outcome.
+
+Deferred messages remain eligible when the operation fails, subject to verbosity.
+Deferral controls timing; applications queue success summaries only after the
+relevant operation succeeds. Ordering governs CommandKit's writes; separate
+stdout and stderr destinations may be buffered or displayed differently by the
+caller.
+
+CommandKit finalizes automatically. Consumers do not need a separate flush or
+finish call. Handler cleanup, including Go `defer` functions, runs before the
+handler returns and participates in normal reporting. Applications complete any
+reporting goroutines before returning. After finalization, writes and message
+submissions return a closed-reporter error and emit nothing.
+
+Reporter operations within an invocation are safe to call concurrently.
+Serialize access to reporting state and delivery so individual messages do not
+interleave. Concurrent submissions have no predetermined order; deferred messages
+follow the order in which they enter the queue. Multiple writes composing one
+application report still require application coordination if they must remain
+together. This contract covers operations through one invocation's reporter;
+coordination with writes outside that reporter remains caller-owned.
+
+Finalize any buffers owned by CommandKit. Caller-supplied writers remain
+caller-owned; CommandKit does not automatically close them or invoke arbitrary
+flushing interfaces.
+
+Visibility applies when output is emitted. A verbose or debug run may show
+informational detail before subsequently failing. Progress and substantive
+output may likewise be partially delivered before a failure. Previously written
+bytes cannot be withdrawn. Whole-run buffering solely to make failed runs
+contain only error output is outside this implementation.
+
+Keep errors understandable in every mode, including source locations and
+related explanatory context. Unrelated warnings and informational messages
+remain subject to the selected mode. Apply the selected retention boundary
+without accumulating a message history.
+
+### Rendering failures, write failures, and execution flow
+
+Distinguish who invokes a renderer and whether its destination failed:
+
+| Failure source | Responsibility and handling |
+| --- | --- |
+| An encoder or renderer called directly by the application | The application handles its returned error and chooses the outcome and explanation. |
+| A rendering callback invoked by CommandKit | CommandKit handles its returned error as a presentation failure and reflects it in the invocation outcome. |
+| A destination rejects a write | CommandKit records the delivery failure and stops further writes to that destination. |
+
+A rendering failure may occur before any write or while the destination remains
+healthy. It does not by itself establish a failed destination. CommandKit can
+explain its rendering failure through a working diagnostic destination. These
+responsibilities also apply when rendering into a discard destination under
+quiet mode.
+
+Failure to deliver requested output makes an otherwise successful invocation
+unsuccessful. Apply this rule to substantive output, Warning, Info, Progress,
+Debug, and terminal explanations. Intentional suppression requests no delivery
+and is not a delivery failure.
+
+Standard writer operations return write errors normally. Immediate reporting
+methods also expose delivery errors. CommandKit records bounded delivery-failure
+information so an ignored write error cannot yield a successful invocation.
+Deferred delivery failures appear in the final outcome.
+
+Apply ADR 0005's outcome rules when presentation fails. For standard outcomes,
+return operational failure with status `1`, including when the original outcome
+was a usage failure. Preserve the original explanation and any supplied cause;
+record the presentation failure separately in `Presentation`.
+
+Application-defined domain outcomes retain their domain classification. Preserve
+an already non-zero domain status. If the domain status was `0`, change the
+suggested status to `1` so presentation failure cannot yield a successful
+invocation. The application entry point retains control of process exit.
+
+| Outcome before presentation fails | Final outcome |
+| --- | --- |
+| Success, status `0` | Operational failure, status `1`. |
+| Usage failure, status `2` | Operational failure, status `1`. |
+| Operational failure, status `1` | Operational failure, status `1`. |
+| Domain outcome, non-zero status | Same domain classification and status. |
+| Domain outcome, status `0` | Same domain classification, status `1`. |
+
+These rules apply to both destination-write failures and rendering failures from
+callbacks invoked by CommandKit. Reporting failures remain CommandKit's own
+error-handling responsibility.
+
+Stop writing to a destination after it fails. A substantive-output failure can
+receive a terminal explanation through the diagnostic destination if it still
+works. If diagnostic delivery fails, return that information to the caller.
+Do not redirect diagnostics into substantive output or recursively attempt to
+report the reporting failure.
+
+A failed write does not stop application code. The handler can inspect the error
+and return immediately; otherwise, CommandKit records the failure and finalizes
+when the handler returns. CommandKit does not use process exit or panic to
+interrupt execution. Terminal failure presentation ends normal output.
+
+### Quiet-mode rendering and suppression
+
+Initially, run substantive report generation normally with its managed writer
+discarding output in quiet mode. This preserves report generation, validation,
+and serialization failures while changing presentation. For example, a report
+encoder failure still fails the invocation under `--quiet`; the handler remains
+responsible for handling errors returned by an encoder it calls.
+
+Simple suppressed messages need no formatting or destination writes. For richer
+report renderers, initially render into a discard destination. Rendering may be
+skipped later where doing so preserves the command's operation and failure
+semantics.
+
+Treat suppression as intentional suppression, never as failed or incomplete
+delivery. Do not retain suppressed content. Delivery needs only the deferred
+queue, reporting lifecycle state, and bounded delivery-failure information,
+alongside the temporary parser state and returned explanations described above.
+
+## Selected consumer reporting API
+
+Provide one reporting facility per invocation for substantive output, immediate
+messages, and end-of-run diagnostics. The consumer API is chosen for its intended
+long-term design; with no current consumers, preserving existing API shapes
+carries no weight in this decision.
+
+The following declarations specify the target API and are not yet implemented.
+
+The reporter owns presentation: output visibility, progress settings, prefixes,
+ordering, and delivery bookkeeping. Its views share invocation state, allowing
+already-emitted messages, deferred messages, suppression, and write failures to
+be coordinated in one place. Helpers may receive the reporter or a narrow
+application-defined interface. Domain libraries can continue returning
+diagnostic data for the handler to submit, independently of CommandKit.
+
+Use the reporter as the common diagnostic submission path, replacing the earlier
+proposal to split submission between a reporter and `Outcome.Diagnostics`.
+Terminal explanations accompany returned outcomes and are delivered through the
+same facility. Caller-selected destinations remain at `App.Execute`; handlers
+use `Invocation.Reporter()` in place of raw invocation streams.
+
+### Invocation reporter and structured detail
+
+```go
+func (inv Invocation) Reporter() *Reporter
+
+type Reporter struct {
+    // Private invocation state.
+}
+
+func (r *Reporter) Output() io.Writer
+func (r *Reporter) RenderOutput(write func(io.Writer) error) error
+
+func (r *Reporter) Info(message string, details ...Detail) error
+func (r *Reporter) Warn(message string, details ...Detail) error
+func (r *Reporter) Debug(message string, details ...Detail) error
+func (r *Reporter) Progress(message string, details ...Detail) error
+
+func (r *Reporter) AtEnd() DeferredReporter
+
+type Detail func(io.Writer) error
+```
+
+`Output()` supports ordinary writers and encoders. `RenderOutput()` coordinates
+an entire rendering operation, captures its rendering error, and prevents other
+reporter operations from interleaving with it. Rendering callbacks write through
+their supplied writer. Each complete categorized message, including its details,
+is likewise coordinated as one reporter operation.
+
+Rendering callbacks use their supplied writer only during the callback. They may
+call rendering helpers that write through it. While a callback is running, it
+must not recursively submit messages, queue deferred messages, start another
+rendering operation, or write through a separate `Output()` handle belonging to
+the same invocation's reporter. Make additional reporter submissions before or
+after the callback. A callback must also avoid waiting for another goroutine to
+submit through that reporter, since the submission may be waiting for the
+callback to finish.
+
+This boundary applies to `RenderOutput`, immediate and deferred message details,
+and terminal explanation details. Ordinary concurrent reporter calls remain
+supported and serialized. Keeping each rendering operation together motivates
+the boundary; it does not prescribe a lock implementation or promise runtime
+detection of recursive calls.
+
+Message strings are literal; consumers use `fmt.Sprintf` when formatting is
+needed. Initially omit parallel `Infof`, `Warnf`, and similar methods. CommandKit
+formats the opening message with its category's prefix and a terminating newline.
+Optional details follow in order with their formatting preserved. An empty
+opening message produces no heading, prefix, or blank opening line, supporting
+native renderers that supply a complete, labelled diagnostic:
+
+```go
+_ = report.Warn("Using the default profile")
+_ = report.Warn("Some configuration settings need attention.", writeNativeWarnings)
+_ = report.Warn("", writeNativeWarnings)
+```
+
+These are alternative calls; `writeNativeWarnings` represents an
+application- or integration-supplied function with signature
+`func(io.Writer) error`. No generic logging method or severity enumeration is
+needed to submit messages. Applications need not check verbosity before reporting
+or implement categories they do not use.
+
+Immediate methods return rendering or delivery errors, and CommandKit records
+the corresponding presentation failure even if the caller ignores the error.
+A caller can inspect the returned error and end its handler immediately.
+
+### Deferred messages
+
+```go
+type DeferredReporter struct {
+    // Private reference to the same invocation state.
+}
+
+func (r DeferredReporter) Info(message string, details ...Detail) error
+func (r DeferredReporter) Warn(message string, details ...Detail) error
+func (r DeferredReporter) Debug(message string, details ...Detail) error
+```
+
+For example:
+
+```go
+_ = report.AtEnd().Warn("Three optional files were unavailable.")
+```
+
+Copies of the deferred view share invocation state. Its methods return submission
+errors, such as attempting to use a closed reporter. Errors encountered during
+deferred rendering appear in the final invocation outcome. Progress remains an
+immediate streaming operation; substantive output uses the main reporter.
+
+Copy callback lists when accepting a submission. Callers retain ownership of
+data captured by rendering callbacks and keep that data valid until presentation.
+
+### Terminal outcomes
+
+Outcome construction requires no invocation state and emits nothing:
+
+```go
+type Explanation struct {
+    Message string
+    Details []Detail
+}
+
+type Outcome struct {
+    Kind         OutcomeKind
+    Status       int
+    Domain       string
+    Cause        error
+    Explanation  Explanation
+    Presentation PresentationResult
+}
+
+func Success() Outcome
+func Failure(message string, details ...Detail) Outcome
+func Usage(message string, details ...Detail) Outcome
+func Domain(name string, status int) Outcome
+
+func (o Outcome) WithExplanation(message string, details ...Detail) Outcome
+func (o Outcome) WithCause(cause error) Outcome
+```
+
+`Success` returns a successful outcome with status `0`. `Failure` produces an
+operational failure with status `1`; `Usage` produces a usage failure with status
+`2`. `Domain` constructs an outcome with the supplied application-defined
+classification and status. Subsequent presentation failures follow OD-4's rules:
+domain classification is preserved, and a zero status becomes `1` if presentation
+fails.
+`OutcomeKind` retains the success, usage, operational, and domain classifications.
+
+`WithExplanation` returns a modified outcome value and replaces its terminal
+explanation. Explanations belong to failed outcomes; successful summaries use
+Info or substantive output. Ordinary application failure, native failure
+rendering, and a custom domain failure respectively can be expressed as:
+
+```go
+return commandkit.Failure("Unable to export the requested report.")
+```
+
+```go
+return commandkit.Failure("", writeNativeFailure)
+```
+
+```go
+return commandkit.Domain("validation", 3).
+    WithExplanation("The document failed validation.", writeFindings)
+```
+
+The named renderers above have signature `func(io.Writer) error` and preserve the
+owning library's safe diagnostic formatting. They run during terminal delivery,
+not when constructing the outcome.
+
+Before terminal delivery, supply the explanation `Command failed.` when a
+non-zero outcome has an empty `Explanation.Message` and no non-nil callback in
+`Explanation.Details`. This produces `ERROR: Command failed.` in every mode,
+including quiet, and becomes the explanation retained in the returned outcome.
+Adding the fallback leaves classification, status, and cause unchanged;
+presentation failures still follow OD-4's rules. The fallback is based on the
+failed outcome and absent explanation, without deriving text from `Cause.Error()`.
+
+An empty heading with a non-nil detail renderer is an explicitly supplied
+explanation. Trust that renderer to provide its content. Do not buffer or replay
+it to decide whether the explanation is sufficiently informative, and do not
+add the fallback merely because it writes no bytes.
+
+| Returned outcome | Terminal presentation |
+| --- | --- |
+| `Failure("")` | Generic fallback, operational classification and status `1`. |
+| `Domain("validation", 3)` | Generic fallback, domain classification and status `3`. |
+| `Failure("").WithCause(err)` | Generic fallback; the supplied cause remains available without automatic rendering. |
+| `Failure("", writeNativeFailure)` | Native explanation without an added generic heading. |
+
+`Cause` is optional. `WithCause` returns a modified outcome value, replacing the
+cause without changing the classification, status, or explanation. For example:
+
+```go
+return commandkit.Failure("Unable to open the configuration file.").
+    WithCause(err)
+```
+
+CommandKit presents the supplied explanation and carries the original error
+through to the execution caller, which can inspect it with expressions such as
+`errors.Is(outcome.Cause, fs.ErrNotExist)`. It does not automatically present
+`Cause.Error()` or use the cause to decide success, failure, or message category.
+Providing a cause is independent of choosing the terminal explanation; neither
+is inferred from the other. Warnings do not require supplying or retaining causes.
+
+Outcome processing preserves supplied causes, including their existing Go error
+identity, when a subsequent rendering or delivery failure occurs. Presentation
+failures are recorded separately in `Presentation`. The returned outcome retains
+its terminal explanation and optional cause, with other retention limited to the
+presentation needs described above.
+
+### Provider-returned diagnostic data
+
+Providers return values and diagnostic data without needing a reporter parameter.
+Retain `Acquired[T]` with separate fields for independent messages and failure
+explanations:
+
+```go
+type Acquired[T any] struct {
+    Value       T
+    Diagnostics []Diagnostic
+    Explanation Explanation
+}
+```
+
+`Diagnostics` carries independent, nonterminal messages. `Diagnostic` and
+`Severity` remain passive data types for those messages, with each diagnostic
+carrying its `Severity` and a `Write func(io.Writer) error` renderer. Adapt their
+contracts to the nonterminal reporting categories. Integrations submit the
+records through the corresponding reporter methods, including the deferred view
+where appropriate. Removing `Outcome.Diagnostics` removes a submission path;
+provider-returned records remain available for the integration to submit.
+
+`Explanation` carries context to attach when the integration returns a failed
+outcome. Terminal Error content uses this field rather than an independently
+submitted diagnostic. An upstream warning that helps explain the failure may
+belong in the explanation; unrelated warnings remain in `Diagnostics` and follow
+their ordinary visibility rules. Adapters preserve this distinction and useful
+native formatting when translating mixed upstream batches, instead of assigning
+the whole batch its highest severity.
+
+Providers may return acquired data alongside a Go error. The owning integration
+chooses the command outcome, attaches any terminal explanation, and decides which
+cause to preserve. Returning diagnostic data does not itself emit messages or
+select the invocation outcome. Diagnostic renderers follow the same callback
+boundary as other details when invoked through the reporter.
+
+### Presentation observations and closed reporters
+
+```go
+type PresentationResult struct {
+    Output      DeliveryResult
+    Diagnostics DeliveryResult
+}
+
+type DeliveryResult struct {
+    State       DeliveryState
+    RenderError error
+    WriteError  error
+}
+
+type DeliveryState uint8
+
+const (
+    DeliveryNone DeliveryState = iota
+    DeliverySuppressed
+    DeliveryComplete
+    DeliveryIncomplete
+)
+
+var ErrReporterClosed = errors.New("reporter is closed")
+```
+
+| State | Meaning |
+| --- | --- |
+| `DeliveryNone` | No content was submitted for this destination. |
+| `DeliverySuppressed` | All submitted content was intentionally suppressed, and rendering succeeded. |
+| `DeliveryComplete` | All requested delivery completed; other content may have been suppressed. |
+| `DeliveryIncomplete` | Rendering or destination writing failed. |
+
+Retain the first rendering failure and first destination-write failure for each
+destination. This provides bounded evidence without collecting an event history.
+`Outcome.Presentation` is populated by CommandKit during execution and
+finalization; it is observation data, not another submission API.
+
+The invocation supplies the reporter. Consumers neither construct nor finalize
+it. After closure, message submissions and writer operations return
+`ErrReporterClosed`, including in quiet mode. The initial API needs no explicit
+flush method, transcript accessor, or verbosity checks. Error-conversion helpers
+are deferred pending demonstrated value.
+
+### Application example
+
+This target-API handler uses an application-owned `exportData` operation that
+returns a JSON-encodable result with a `UsedDefaults` field:
+
+```go
+func runExport(inv commandkit.Invocation) commandkit.Outcome {
+    report := inv.Reporter()
+
+    result, err := exportData(inv.Context)
+    if err != nil {
+        return commandkit.Failure("Unable to export the requested data.")
+    }
+
+    if result.UsedDefaults {
+        _ = report.Warn("Some optional settings used defaults.")
+    }
+
+    if err := report.RenderOutput(func(w io.Writer) error {
+        return json.NewEncoder(w).Encode(result)
+    }); err != nil {
+        return commandkit.Failure("Unable to present the export result.")
+    }
+
+    _ = report.AtEnd().Info("Export completed.")
+    return commandkit.Success()
+}
+```
+
+Ignored immediate reporting errors are still recorded and can make the final
+invocation unsuccessful. The renderer runs in quiet mode against the discard
+destination, preserving serialization failures. The deferred summary follows
+the selected verbosity policy and describes the completed export operation;
+the final invocation outcome also accounts for presentation failures.
+
+## Upstream diagnostic ownership
+
+ConfigKit and PromptKit remain authoritative for their diagnostic semantics,
+severity, source context, and disclosure rules. Integration adapters expose
+those capabilities through the shared CommandKit presentation policy.
+
+Support consistent reporting of ConfigKit errors and warnings as its adopted
+public API evolves. This roadmap does not assume that a future warning API
+already exists or prescribe its upstream shape. Integration-owned commands
+select the outcome and submit useful native diagnostic detail for presentation.
+Core presents those records under the shared policy. Applications using upstream
+libraries directly choose how to respond to domain-specific errors and which
+outcomes and messages to supply, as for their other operations.
+
+An integration may receive both a useful substantive report and an operation
+failure, as PromptKit smoke testing supports. Preserve the report under the
+ordinary substantive-output policy, then present the terminal explanation.
+Quiet mode suppresses the report while retaining the explanation. Having a
+report does not imply a successful outcome, and returning a failure does not
+discard substantive output already prepared for delivery before the terminal step.
+
+Debug output follows the same upstream disclosure and safe-rendering contracts.
+Enabling debug does not authorize secret disclosure or bypass owning-library
+rules.
+
+## Delivery scope
+
+The completed feature includes the selected reporter and outcome API, ordered
+mode/progress selection through normal parsing, shared core presentation, and
+both optional integration migrations. Passive provider diagnostics distinguish
+independent messages from terminal explanations while preserving native evidence
+and rendering. Existing command behavior remains unchanged outside the selected
+reporting policy.
+
+Maintained consumers demonstrate ordinary output, immediate/deferred messages,
+silent recovery, explicit warnings, failure after partial output, optional cause
+transport, and structured terminal explanations. Integration consumers include
+native diagnostic context and useful reports returned alongside failures.
+
+Behavioral coverage establishes CommandKit-owned parsing, visibility, ordering,
+concurrent reporter coordination, closure, presentation observations, and failure
+handling. It preserves existing alias, input/state, discovery, native-report,
+and upstream-adapter protections without testing upstream domain correctness.
+GoDoc, CLI documentation, consumer guidance, internal documentation, and release
+notes describe the implemented boundary under their canonical ownership.
+
+The [implementation plan](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/230187296fae5253cb1773f16c2f1d1a39499ed0/docs/roadmap/implementation.md) defines the concrete migration
+steps, focused validation, and completion criteria. This roadmap defines the
+target behavior and selected policy choices.
+
+## Architectural preparation completed
+
+- [x] Review and accept [ADR 0014](../adr/0014-invocation-reporting.md) as an
+  extension for shared reporting, retaining ADR 0005's outcome and supplied-error
+  preservation decisions.
+- [x] Align the [architecture policy](../policy/architecture.md) with the reporting
+  ownership model, including application ownership of domain-specific error
+  decisions and scope for useful shared error helpers.
+
+OD-1 through OD-4 and the consumer API signatures are selected. The target end
+state includes maintained, executable consumers using those APIs; the
+[implementation plan](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/230187296fae5253cb1773f16c2f1d1a39499ed0/docs/roadmap/implementation.md) owns their delivery sequence.

examples/composed/README.md

@@ -1,18 +0,0 @@
-# Composed consumer
-
-This example composes application configuration, PromptKit configuration,
-definition inspection, and one application-owned command:
-
-```sh
-go run . config scopes
-go run . config validate --scope all --campaign spring
-go run . promptkit show prompt briefing --campaign spring --format yaml
-go run . promptkit show profile spring --campaign spring
-go run . session restore session-42 --campaign spring
-```
-
-The sources and session store are small in-memory fixtures. `--campaign` is a
-typed selector shared by the app and PromptKit configuration scopes. Their
-scope contexts share a per-invocation cache created by `ConfigSuite.NewContext`.
-Prompt/profile inspection has its own invocation context and composes the same
-application and engine loader functions.

examples/composed/main.go

@@ -1,223 +0,0 @@
-package main
-
-import (
-	"context"
-	"errors"
-	"fmt"
-	"os"
-
-	commandkit "gitea.maximumdirect.net/eric/CommandKit"
-	configkit "gitea.maximumdirect.net/eric/ConfigKit"
-	"gitea.maximumdirect.net/eric/promptkit"
-)
-
-type campaign struct {
-	PromptID      string `yaml:"prompt_id"`
-	PromptVersion string `yaml:"prompt_version"`
-	ProfileID     string `yaml:"profile_id"`
-	Model         string `yaml:"model"`
-}
-
-type appConfiguration struct {
-	DefaultCampaign string              `yaml:"default_campaign"`
-	Campaigns       map[string]campaign `yaml:"campaigns"`
-}
-
-type invocationCache struct {
-	application *configkit.Result[appConfiguration]
-}
-
-type configContext struct {
-	Cache    *invocationCache
-	Campaign commandkit.Supplied[string]
-}
-
-type definitionContext struct {
-	Cache    *invocationCache
-	Campaign commandkit.Supplied[string]
-}
-
-type restoreInput struct {
-	Campaign commandkit.Supplied[string]
-	Session  string
-}
-
-type session struct {
-	ID       string
-	Campaign string
-	Summary  string
-}
-
-type sessionStore struct {
-	active  string
-	records map[string]session
-}
-
-func loadApplicationConfig(_ context.Context, _ commandkit.Selection, cache *invocationCache) (*configkit.Result[appConfiguration], error) {
-	if cache != nil && cache.application != nil {
-		return cache.application, nil
-	}
-	result, err := configkit.Load[appConfiguration](configkit.Mapping("composed app config", map[string]any{
-		"default_campaign": "spring",
-		"campaigns": map[string]any{
-			"spring": map[string]any{"prompt_id": "briefing", "prompt_version": "1", "profile_id": "spring", "model": "spring-model"},
-			"autumn": map[string]any{"prompt_id": "briefing", "prompt_version": "1", "profile_id": "autumn", "model": "autumn-model"},
-		},
-	}))
-	if err == nil && cache != nil {
-		cache.application = result
-	}
-	return result, err
-}
-
-func selectedCampaign(configuration appConfiguration, supplied commandkit.Supplied[string]) (string, campaign, error) {
-	name := configuration.DefaultCampaign
-	if supplied.Set {
-		name = supplied.Value
-	}
-	value, ok := configuration.Campaigns[name]
-	if !ok {
-		return "", campaign{}, fmt.Errorf("unknown campaign %q", name)
-	}
-	return name, value, nil
-}
-
-func loadPromptEngine(ctx context.Context, selection commandkit.Selection, cache *invocationCache, selected commandkit.Supplied[string]) (*promptkit.Engine, error) {
-	application, err := loadApplicationConfig(ctx, selection, cache)
-	if err != nil {
-		return nil, err
-	}
-	name, chosen, err := selectedCampaign(application.Config, selected)
-	if err != nil {
-		return nil, err
-	}
-	engineConfig := configkit.Mapping("campaign "+name, map[string]any{
-		"profiles": map[string]any{chosen.ProfileID: map[string]any{
-			"endpoint": "https://example.invalid/v1",
-			"model":    chosen.Model,
-			"extra_params": map[string]any{
-				"campaign": name,
-			},
-		}},
-		"prompts": map[string]any{chosen.PromptID: map[string]any{
-			chosen.PromptVersion: map[string]any{
-				"default_profile": chosen.ProfileID,
-				"inputs":          []any{map[string]any{"name": "topic", "required": true, "content_type": "text/plain", "description": "Topic to brief"}},
-				"messages":        []any{map[string]any{"role": "user", "content": "Write a concise briefing about {{.topic}}."}},
-				"output":          map[string]any{"format": "text", "validation_mode": "none"},
-			},
-		}},
-	})
-	return promptkit.NewEngine(promptkit.Config{Sources: promptkit.ConfigurationSources{Main: &configkit.Input{Source: engineConfig}}})
-}
-
-func campaignSelector[C any](set func(*C, commandkit.Supplied[string])) commandkit.Selector[C] {
-	return commandkit.Selector[C]{
-		Binding: commandkit.ValueFlag[C](commandkit.FlagMeta{Name: "campaign", Usage: "Select a configured campaign."}, nil, func(value string) (string, error) { return value, nil }, set),
-		Scopes:  []string{"app", "promptkit"},
-	}
-}
-
-func newApp() (*commandkit.App, error) {
-	app, err := commandkit.New(commandkit.Identity{Name: "composed-example", Version: "1.0"})
-	if err != nil {
-		return nil, err
-	}
-	appScope, err := commandkit.NewConfigKitScope[configContext, appConfiguration]("app", "Application campaigns.", func(ctx context.Context, selection commandkit.Selection, input configContext) (*configkit.Result[appConfiguration], error) {
-		return loadApplicationConfig(ctx, selection, input.Cache)
-	})
-	if err != nil {
-		return nil, err
-	}
-	promptScope, err := commandkit.NewPromptKitScope(func(ctx context.Context, selection commandkit.Selection, input configContext) (*promptkit.Engine, error) {
-		return loadPromptEngine(ctx, selection, input.Cache, input.Campaign)
-	})
-	if err != nil {
-		return nil, err
-	}
-	configSuite := commandkit.ConfigSuite[configContext]{
-		NewContext: func() configContext { return configContext{Cache: &invocationCache{}} },
-		Selectors: []commandkit.Selector[configContext]{campaignSelector(func(input *configContext, value commandkit.Supplied[string]) {
-			input.Campaign = value
-		})},
-		Scopes: []commandkit.ConfigScope[configContext]{appScope, promptScope},
-	}
-	if err := commandkit.RegisterConfig(app, configSuite); err != nil {
-		return nil, err
-	}
-
-	definitionSuite, err := commandkit.NewPromptKitSuite(func(ctx context.Context, selection commandkit.Selection, input definitionContext) (*promptkit.Engine, error) {
-		return loadPromptEngine(ctx, selection, input.Cache, input.Campaign)
-	})
-	if err != nil {
-		return nil, err
-	}
-	definitionSuite.NewContext = func() definitionContext { return definitionContext{Cache: &invocationCache{}} }
-	definitionSuite.Selectors = []commandkit.Selector[definitionContext]{campaignSelector(func(input *definitionContext, value commandkit.Supplied[string]) {
-		input.Campaign = value
-	})}
-	if err := commandkit.RegisterPromptKit(app, definitionSuite); err != nil {
-		return nil, err
-	}
-
-	store := &sessionStore{records: map[string]session{"session-42": {ID: "session-42", Campaign: "spring", Summary: "A synthetic planning session."}}}
-	restore, err := commandkit.NewCommand(commandkit.CommandSpec[restoreInput]{
-		Name:    "restore",
-		Summary: "Restore one saved session.",
-		Flags: []commandkit.Flag[restoreInput]{commandkit.ValueFlag[restoreInput](commandkit.FlagMeta{Name: "campaign", Usage: "Campaign owning the session."}, nil, func(value string) (string, error) { return value, nil }, func(input *restoreInput, value commandkit.Supplied[string]) {
-			input.Campaign = value
-		})},
-		Arguments: []commandkit.Argument[restoreInput]{commandkit.ValueArgument[restoreInput](commandkit.ArgumentMeta{Name: "ID"}, true, func(value string) (string, error) { return value, nil }, func(input *restoreInput, value commandkit.Supplied[string]) {
-			input.Session = value.Value
-		})},
-		Run: func(invocation commandkit.Invocation, input restoreInput) commandkit.Outcome {
-			return restoreSession(invocation, store, input)
-		},
-	})
-	if err != nil {
-		return nil, err
-	}
-	sessionGroup, err := commandkit.Group("session", "Manage saved sessions.", restore)
-	if err != nil {
-		return nil, err
-	}
-	if err := app.Register(sessionGroup); err != nil {
-		return nil, err
-	}
-	return app, nil
-}
-
-func restoreSession(invocation commandkit.Invocation, store *sessionStore, input restoreInput) commandkit.Outcome {
-	application, err := loadApplicationConfig(invocation.Context, commandkit.Selection{}, nil)
-	if err != nil {
-		return commandkit.Failure(err)
-	}
-	name, _, err := selectedCampaign(application.Config, input.Campaign)
-	if err != nil {
-		return commandkit.Failure(err)
-	}
-	record, ok := store.records[input.Session]
-	if !ok {
-		return commandkit.Outcome{Kind: commandkit.OutcomeDomain, Status: 4, Domain: "session_not_found", Cause: errors.New("saved session was not found")}
-	}
-	if record.Campaign != name {
-		return commandkit.Outcome{Kind: commandkit.OutcomeDomain, Status: 3, Domain: "campaign_mismatch", Cause: fmt.Errorf("session belongs to campaign %q", record.Campaign)}
-	}
-	store.active = record.ID
-	if _, err := fmt.Fprintf(invocation.Streams.Out, "restored %s: %s\n", record.ID, record.Summary); err != nil {
-		return commandkit.Failure(err)
-	}
-	return commandkit.Success()
-}
-
-func main() {
-	app, err := newApp()
-	if err != nil {
-		fmt.Fprintln(os.Stderr, err)
-		os.Exit(1)
-	}
-	outcome := app.Execute(context.Background(), os.Args[1:], commandkit.Streams{Out: os.Stdout, Err: os.Stderr})
-	if outcome.Status != 0 {
-		os.Exit(outcome.Status)
-	}
-}

examples/core/README.md

@@ -0,0 +1,39 @@
+# Core example
+
+Run the example from the repository root:
+
+```sh
+go run ./examples/core hello --times=0 --tag=first
+go run ./examples/core ws greet --count=2
+go run ./examples/core ws --help
+go run ./examples/core hello --hlep
+go build -o core-example ./examples/core
+./core-example completion bash
+```
+
+The example installs a canonical `workspace greet` command together with a
+command shortcut, a group shortcut, a scoped flag alias, and a global help
+alias. Its declaration slice mixes the canonical group and routing rules as
+`[]commandkit.Declaration`. The handler prints `Invocation.EnteredPath()` and
+`Invocation.CanonicalPath()` so the alternate route and its canonical target
+are visible in the output.
+
+The example also installs `Completion("core-example")` and gives the `report`
+scenario argument static choices. Initialize `bash-completion` first if using
+Bash. Build it with the basename shown above, load
+the script for your shell using the [CLI reference](../../docs/cli.md#shell-completion),
+and try completing `core-example report d` or `core-example ws gr`.
+
+Compatible integration factories also return `commandkit.Command` and can be
+passed directly to `New` beside `commandkit.Alias` or flag-alias declarations.
+The ckconfig candidate uses the new core identity; ckprompt will use it in its
+planned matched release. For a
+command-only `[]commandkit.Command`, convert its elements into a
+`[]commandkit.Declaration` before appending routing rules; Go cannot expand the
+command slice as `...commandkit.Declaration`. The
+[consumer guide](../../docs/consumers/guide.md#application-owned-aliases)
+shows both forms, and the [composed consumer](../../integrations/ckprompt/examples/composed)
+is the maintained integration example.
+
+These aliases require core v0.3.0. Repository contributors can run its test with
+`go test ./examples/core` from the root.

examples/core/main.go

@@ -0,0 +1,155 @@
+package main
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"os"
+	"strconv"
+
+	commandkit "go.maximumdirect.net/commandkit"
+)
+
+type greetInput struct {
+	Count commandkit.Supplied[int]
+	Tags  commandkit.Supplied[[]string]
+}
+
+type reportInput struct {
+	Scenario string
+}
+
+var (
+	errRecoveredFixture = errors.New("a local read failed and was recovered")
+	errWarningFixture   = errors.New("a local warning has a cause")
+	errPartialFixture   = errors.New("the local report could not be completed")
+)
+
+func newApp() (*commandkit.App, error) {
+	countDefault := 1
+	tagDefaults := []string{"demo"}
+	greet := commandkit.NewCommand(commandkit.CommandSpec[greetInput]{
+		Name:    "greet",
+		Summary: "Show presence-aware values and repeated labels.",
+		Flags: []commandkit.Flag[greetInput]{
+			commandkit.ValueFlag(commandkit.FlagMeta{Name: "count", Usage: "Greeting count."}, &countDefault, strconv.Atoi, func(input *greetInput, value commandkit.Supplied[int]) {
+				input.Count = value
+			}),
+			commandkit.RepeatFlag(commandkit.FlagMeta{Name: "tag", Usage: "A repeatable label."}, tagDefaults, func(value string) (string, error) { return value, nil }, func(input *greetInput, value commandkit.Supplied[[]string]) {
+				input.Tags = value
+			}),
+		},
+		Run: func(invocation commandkit.Invocation, input greetInput) commandkit.Outcome {
+			reporter := invocation.Reporter()
+			count := fmt.Sprintf("default %d (not supplied)", input.Count.Value)
+			if input.Count.Set {
+				count = fmt.Sprintf("explicit %d", input.Count.Value)
+			}
+			tags := fmt.Sprintf("default %v (not supplied)", input.Tags.Value)
+			if input.Tags.Set {
+				tags = fmt.Sprintf("explicit %v", input.Tags.Value)
+			}
+			_ = reporter.RenderOutput(func(writer io.Writer) error {
+				_, err := fmt.Fprintf(writer, "Hello; count=%s; tags=%s; entered=%q; canonical=%q\n", count, tags, invocation.EnteredPath(), invocation.CanonicalPath())
+				return err
+			})
+			return commandkit.Success()
+		},
+	})
+	report := commandkit.NewCommand(commandkit.CommandSpec[reportInput]{
+		Name:    "report",
+		Summary: "Demonstrate invocation reporting with local scenarios.",
+		NewInput: func() reportInput {
+			return reportInput{Scenario: "demo"}
+		},
+		Arguments: []commandkit.Argument[reportInput]{
+			commandkit.ValueArgument(commandkit.ArgumentMeta{Name: "scenario", Usage: "demo, recover, warn, warn-error, fail, or partial.", Completion: commandkit.CompleteChoices(
+				commandkit.CompletionChoice{Value: "demo"}, commandkit.CompletionChoice{Value: "recover"}, commandkit.CompletionChoice{Value: "warn"},
+				commandkit.CompletionChoice{Value: "warn-error"}, commandkit.CompletionChoice{Value: "fail"}, commandkit.CompletionChoice{Value: "partial"})}, false, func(value string) (string, error) { return value, nil },
+				func(input *reportInput, value commandkit.Supplied[string]) { input.Scenario = value.Value }),
+		},
+		CheckInput: func(input reportInput) error {
+			switch input.Scenario {
+			case "demo", "recover", "warn", "warn-error", "fail", "partial":
+				return nil
+			default:
+				return fmt.Errorf("unknown reporting scenario %q", input.Scenario)
+			}
+		},
+		Run: func(invocation commandkit.Invocation, input reportInput) commandkit.Outcome {
+			return runReportingExample(invocation, input.Scenario)
+		},
+	})
+	workspace := commandkit.Group("workspace", "Workspace commands.", greet)
+	declarations := []commandkit.Declaration{
+		workspace,
+		report,
+		commandkit.Completion("core-example"),
+		commandkit.Alias("hello", "workspace greet"),
+		commandkit.Alias("ws", "workspace"),
+		commandkit.FlagAliasFor("workspace greet", "--times", "--count"),
+		commandkit.FlagAlias("--hlep", "--help"),
+	}
+	return commandkit.New(commandkit.Identity{Name: "core-example", Version: "1.0"}, declarations...)
+}
+
+func runReportingExample(invocation commandkit.Invocation, scenario string) commandkit.Outcome {
+	reporter := invocation.Reporter()
+	deferred := reporter.AtEnd()
+	switch scenario {
+	case "demo":
+		_ = reporter.Progress("Loaded one local fixture.")
+		_ = deferred.Warn("Optional fixture warning", func(writer io.Writer) error {
+			_, err := io.WriteString(writer, "The sample contains an optional note.\n")
+			return err
+		})
+		_ = deferred.Info("Using deterministic local data.")
+		_ = deferred.Debug("Selected the built-in reporting example.")
+		_ = deferred.Info("Summary", writeExampleSummary)
+		_ = reporter.RenderOutput(writeExampleReport)
+		return commandkit.Success()
+	case "recover":
+		return commandkit.Success().WithCause(errRecoveredFixture)
+	case "warn":
+		_ = deferred.Warn("The local operation completed with a warning.")
+		return commandkit.Success()
+	case "warn-error":
+		_ = deferred.Warn("The local operation completed with a warning.")
+		return commandkit.Success().WithCause(errWarningFixture)
+	case "fail":
+		return commandkit.Failure("The selected local operation could not be completed.")
+	case "partial":
+		_ = reporter.RenderOutput(writePartialExampleReport)
+		return commandkit.Failure("The local report stopped after partial output.").WithCause(errPartialFixture)
+	default:
+		return commandkit.Usage(fmt.Sprintf("unknown reporting scenario %q", scenario))
+	}
+}
+
+func writeExampleReport(writer io.Writer) error {
+	_, err := fmt.Fprintln(writer, "Prepared a local report from one fixture.")
+	return err
+}
+
+func writePartialExampleReport(writer io.Writer) error {
+	_, err := io.WriteString(writer, "Partial local report: first section complete.\n")
+	return err
+}
+
+func writeExampleSummary(writer io.Writer) error {
+	_, err := io.WriteString(writer, "Processed one local fixture.\n")
+	return err
+}
+
+func main() {
+	app, err := newApp()
+	if err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+	outcome := app.Execute(context.Background(), os.Args[1:], commandkit.Streams{Out: os.Stdout, Err: os.Stderr})
+	if outcome.Status != 0 {
+		os.Exit(outcome.Status)
+	}
+}

examples/core/main_test.go

@@ -0,0 +1,199 @@
+package main
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"io"
+	"strings"
+	"testing"
+
+	commandkit "go.maximumdirect.net/commandkit"
+)
+
+func TestAliasesReachCoreExampleCommand(t *testing.T) {
+	app, err := newApp()
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, test := range []struct {
+		name      string
+		args      []string
+		entered   string
+		canonical string
+		greeting  string
+	}{
+		{name: "command shortcut and scoped flag", args: []string{"hello", "--times=0", "--tag", "one"}, entered: "hello", canonical: "workspace greet", greeting: "count=explicit 0; tags=explicit [one]"},
+		{name: "group shortcut", args: []string{"ws", "greet", "--count=2"}, entered: "ws greet", canonical: "workspace greet", greeting: "count=explicit 2"},
+		{name: "canonical command", args: []string{"workspace", "greet"}, entered: "workspace greet", canonical: "workspace greet", greeting: "count=default 1 (not supplied)"},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			var output bytes.Buffer
+			outcome := app.Execute(context.Background(), test.args, commandkit.Streams{Out: &output, Err: io.Discard})
+			if outcome.Kind != commandkit.OutcomeSuccess {
+				t.Fatalf("Execute(%q) = %#v; output %q", test.args, outcome, output.String())
+			}
+			for _, fragment := range []string{
+				test.greeting,
+				"entered=\"" + test.entered + "\"",
+				"canonical=\"" + test.canonical + "\"",
+			} {
+				if !strings.Contains(output.String(), fragment) {
+					t.Errorf("output %q does not contain %q", output.String(), fragment)
+				}
+			}
+		})
+	}
+}
+
+func TestGlobalHelpAliasDoesNotRunCoreExampleCommand(t *testing.T) {
+	app, err := newApp()
+	if err != nil {
+		t.Fatal(err)
+	}
+	var output bytes.Buffer
+	outcome := app.Execute(context.Background(), []string{"hello", "--hlep"}, commandkit.Streams{Out: &output, Err: io.Discard})
+	if outcome.Kind != commandkit.OutcomeSuccess || !strings.Contains(output.String(), "--hlep → --help") || strings.Contains(output.String(), "Hello;") {
+		t.Fatalf("help alias outcome/output = (%#v, %q)", outcome, output.String())
+	}
+	output.Reset()
+	outcome = app.Execute(context.Background(), []string{"ws", "--help"}, commandkit.Streams{Out: &output, Err: io.Discard})
+	if outcome.Kind != commandkit.OutcomeSuccess || !strings.Contains(output.String(), "greet") || strings.Contains(output.String(), "Hello;") {
+		t.Fatalf("group shortcut help outcome/output = (%#v, %q)", outcome, output.String())
+	}
+}
+
+func TestReportingExampleModes(t *testing.T) {
+	for _, test := range []struct {
+		name       string
+		args       []string
+		wantOutput []string
+		wantDiag   []string
+		omitDiag   []string
+	}{
+		{
+			name:       "ordinary result",
+			args:       []string{"report", "demo"},
+			wantOutput: []string{"Prepared a local report from one fixture."},
+			omitDiag:   []string{"Optional fixture warning", "Using deterministic local data.", "Loaded one local fixture.", "DEBUG:"},
+		},
+		{
+			name:       "progress selected",
+			args:       []string{"report", "demo", "--progress"},
+			wantOutput: []string{"Prepared a local report from one fixture."},
+			wantDiag:   []string{"Loaded one local fixture."},
+			omitDiag:   []string{"WARN:", "Using deterministic local data.", "DEBUG:"},
+		},
+		{
+			name:       "verbose messages",
+			args:       []string{"report", "demo", "--verbose"},
+			wantOutput: []string{"Prepared a local report from one fixture."},
+			wantDiag:   []string{"WARN: Optional fixture warning", "The sample contains an optional note.", "Using deterministic local data.", "Summary", "Processed one local fixture."},
+			omitDiag:   []string{"Loaded one local fixture.", "DEBUG:"},
+		},
+		{
+			name:       "debug messages",
+			args:       []string{"report", "demo", "--debug"},
+			wantOutput: []string{"Prepared a local report from one fixture."},
+			wantDiag:   []string{"WARN: Optional fixture warning", "Using deterministic local data.", "Loaded one local fixture.", "DEBUG: Selected the built-in reporting example.", "Processed one local fixture."},
+		},
+		{
+			name: "quiet suppresses result and messages",
+			args: []string{"report", "demo", "--quiet"},
+		},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			outcome, output, diagnostics := executeExample(t, test.args...)
+			if outcome.Kind != commandkit.OutcomeSuccess {
+				t.Fatalf("Execute(%q) = %#v", test.args, outcome)
+			}
+			for _, fragment := range test.wantOutput {
+				if !strings.Contains(output, fragment) {
+					t.Errorf("output %q does not contain %q", output, fragment)
+				}
+			}
+			for _, fragment := range test.wantDiag {
+				if !strings.Contains(diagnostics, fragment) {
+					t.Errorf("diagnostics %q does not contain %q", diagnostics, fragment)
+				}
+			}
+			for _, fragment := range test.omitDiag {
+				if strings.Contains(diagnostics, fragment) {
+					t.Errorf("diagnostics %q unexpectedly contain %q", diagnostics, fragment)
+				}
+			}
+			if test.name == "quiet suppresses result and messages" && (output != "" || diagnostics != "") {
+				t.Errorf("quiet output/diagnostics = (%q, %q), want both empty", output, diagnostics)
+			}
+		})
+	}
+}
+
+func TestReportingExampleScenarios(t *testing.T) {
+	t.Run("silent recovery retains cause", func(t *testing.T) {
+		outcome, output, diagnostics := executeExample(t, "report", "recover")
+		if outcome.Kind != commandkit.OutcomeSuccess || !errors.Is(outcome.Cause, errRecoveredFixture) {
+			t.Fatalf("outcome = %#v, want successful recovery with original cause", outcome)
+		}
+		if output != "" || diagnostics != "" {
+			t.Fatalf("recovery output/diagnostics = (%q, %q), want silent recovery", output, diagnostics)
+		}
+	})
+
+	t.Run("warning without cause", func(t *testing.T) {
+		outcome, _, diagnostics := executeExample(t, "report", "warn", "--verbose")
+		if outcome.Kind != commandkit.OutcomeSuccess || outcome.Cause != nil {
+			t.Fatalf("outcome = %#v, want success without cause", outcome)
+		}
+		if !strings.Contains(diagnostics, "WARN: The local operation completed with a warning.") {
+			t.Fatalf("diagnostics = %q, want explicit warning", diagnostics)
+		}
+	})
+
+	t.Run("warning with independent cause", func(t *testing.T) {
+		outcome, _, diagnostics := executeExample(t, "report", "warn-error", "--verbose")
+		if outcome.Kind != commandkit.OutcomeSuccess || !errors.Is(outcome.Cause, errWarningFixture) {
+			t.Fatalf("outcome = %#v, want successful warning with original cause", outcome)
+		}
+		if !strings.Contains(diagnostics, "WARN: The local operation completed with a warning.") || strings.Contains(diagnostics, errWarningFixture.Error()) {
+			t.Fatalf("diagnostics = %q, want warning text without cause text", diagnostics)
+		}
+	})
+
+	t.Run("terminal explanation without cause", func(t *testing.T) {
+		outcome, _, diagnostics := executeExample(t, "report", "fail", "--quiet")
+		if outcome.Kind != commandkit.OutcomeOperational || outcome.Status == 0 || outcome.Cause != nil {
+			t.Fatalf("outcome = %#v, want terminal failure without cause", outcome)
+		}
+		if outcome.Explanation.Message != "The selected local operation could not be completed." || !strings.Contains(diagnostics, outcome.Explanation.Message) {
+			t.Fatalf("explanation/diagnostics = (%q, %q)", outcome.Explanation.Message, diagnostics)
+		}
+	})
+
+	t.Run("partial output keeps cause independent", func(t *testing.T) {
+		outcome, output, diagnostics := executeExample(t, "report", "partial")
+		if outcome.Kind != commandkit.OutcomeOperational || !errors.Is(outcome.Cause, errPartialFixture) {
+			t.Fatalf("outcome = %#v, want terminal failure with original cause", outcome)
+		}
+		if !strings.Contains(output, "Partial local report: first section complete.") {
+			t.Fatalf("output = %q, want completed first section", output)
+		}
+		if outcome.Explanation.Message != "The local report stopped after partial output." || !strings.Contains(diagnostics, outcome.Explanation.Message) {
+			t.Fatalf("explanation/diagnostics = (%q, %q)", outcome.Explanation.Message, diagnostics)
+		}
+		if strings.Contains(diagnostics, errPartialFixture.Error()) {
+			t.Errorf("diagnostics %q unexpectedly contain cause text", diagnostics)
+		}
+	})
+}
+
+func executeExample(t *testing.T, args ...string) (commandkit.Outcome, string, string) {
+	t.Helper()
+	app, err := newApp()
+	if err != nil {
+		t.Fatal(err)
+	}
+	var output, diagnostics bytes.Buffer
+	outcome := app.Execute(context.Background(), args, commandkit.Streams{Out: &output, Err: &diagnostics})
+	return outcome, output.String(), diagnostics.String()
+}

examples/simple/README.md

@@ -1,14 +0,0 @@
-# Simple consumer
-
-Run the maintained example with:
-
-```sh
-go run . config show
-go run . greet
-go run . greet --count=0 --tag=first --tag second
-```
-
-The `config` family comes from one typed ConfigKit scope. The custom `greet`
-command uses CommandKit's typed bindings and shows the difference between an
-omitted `--count` and an explicitly supplied zero, plus ordered repeated tags.
-The configuration is synthetic and stays in memory.

examples/simple/main.go

@@ -1,90 +0,0 @@
-package main
-
-import (
-	"context"
-	"fmt"
-	"os"
-	"strconv"
-
-	commandkit "gitea.maximumdirect.net/eric/CommandKit"
-	configkit "gitea.maximumdirect.net/eric/ConfigKit"
-)
-
-type appConfiguration struct {
-	Greeting string `yaml:"greeting"`
-}
-
-type greetInput struct {
-	Count commandkit.Supplied[int]
-	Tags  commandkit.Supplied[[]string]
-}
-
-func loadAppConfiguration(context.Context, commandkit.Selection, struct{}) (*configkit.Result[appConfiguration], error) {
-	return configkit.Load[appConfiguration](configkit.Bytes("simple example", []byte("greeting: hello\n")))
-}
-
-func newApp() (*commandkit.App, error) {
-	app, err := commandkit.New(commandkit.Identity{Name: "simple-example", Version: "1.0"})
-	if err != nil {
-		return nil, err
-	}
-	scope, err := commandkit.NewConfigKitScope[struct{}, appConfiguration]("app", "Application settings.", loadAppConfiguration)
-	if err != nil {
-		return nil, err
-	}
-	if err := commandkit.RegisterConfig(app, commandkit.ConfigSuite[struct{}]{Scopes: []commandkit.ConfigScope[struct{}]{scope}}); err != nil {
-		return nil, err
-	}
-
-	countDefault := 1
-	tagDefaults := []string{"example"}
-	greet, err := commandkit.NewCommand(commandkit.CommandSpec[greetInput]{
-		Name:    "greet",
-		Summary: "Show flag presence and repeated values.",
-		Flags: []commandkit.Flag[greetInput]{
-			commandkit.ValueFlag[greetInput](commandkit.FlagMeta{Name: "count", Usage: "Greeting count."}, &countDefault, strconv.Atoi, func(input *greetInput, value commandkit.Supplied[int]) {
-				input.Count = value
-			}),
-			commandkit.RepeatFlag[greetInput](commandkit.FlagMeta{Name: "tag", Usage: "A repeatable label."}, tagDefaults, func(value string) (string, error) { return value, nil }, func(input *greetInput, value commandkit.Supplied[[]string]) {
-				input.Tags = value
-			}),
-		},
-		Run: func(invocation commandkit.Invocation, input greetInput) commandkit.Outcome {
-			configuration, err := loadAppConfiguration(invocation.Context, commandkit.Selection{}, struct{}{})
-			if err != nil {
-				return commandkit.Failure(err)
-			}
-			count := fmt.Sprintf("default %d (not supplied)", input.Count.Value)
-			if input.Count.Set {
-				count = fmt.Sprintf("explicit %d", input.Count.Value)
-			}
-			tags := fmt.Sprintf("default %v (not supplied)", input.Tags.Value)
-			if input.Tags.Set {
-				tags = fmt.Sprintf("explicit %v", input.Tags.Value)
-			}
-			if _, err := fmt.Fprintf(invocation.Streams.Out, "%s; count=%s; tags=%s\n", configuration.Config.Greeting, count, tags); err != nil {
-				return commandkit.Failure(err)
-			}
-			return commandkit.Success()
-		},
-	})
-	if err != nil {
-		return nil, err
-	}
-	if err := app.Register(greet); err != nil {
-		return nil, err
-	}
-	return app, nil
-}
-
-func main() {
-	app, err := newApp()
-	if err != nil {
-		fmt.Fprintln(os.Stderr, err)
-		os.Exit(1)
-	}
-	outcome := app.Execute(context.Background(), os.Args[1:], commandkit.Streams{Out: os.Stdout, Err: os.Stderr})
-	if outcome.Status != 0 {
-		os.Exit(outcome.Status)
-	}
-}

execute.go

@@ -5,108 +5,215 @@ import (
 	"errors"
 	"fmt"
 	"io"
+	"strconv"
+	"strings"
 
-	internalcobra "gitea.maximumdirect.net/eric/CommandKit/internal/cobra"
-	configkit "gitea.maximumdirect.net/eric/ConfigKit"
+	internalcobra "go.maximumdirect.net/commandkit/internal/cobra"
+	commandmeta "go.maximumdirect.net/commandkit/internal/commandmeta"
+	"go.maximumdirect.net/commandkit/internal/commandpath"
 )
 
 // Execute parses and dispatches one invocation. args excludes the executable
-// name. CommandKit writes diagnostics to streams.Err and leaves process exit to
-// the caller. A nil context returns an operational failure, and nil streams are
-// replaced with io.Discard.
+// name. Supplied values are converted before command input construction; help
+// does not construct caller inputs or run acquisition callbacks. It applies the
+// parsed reporting selection, finalizes invocation presentation, and returns
+// the resulting Outcome without exiting the process. Supplied streams remain
+// caller-owned; nil destinations are replaced with io.Discard. A nil context
+// returns an operational failure.
 func (a *App) Execute(ctx context.Context, args []string, streams Streams) Outcome {
-	if ctx == nil {
-		return a.present(Failure(errors.New("invocation context must not be nil")), nil, streams)
-	}
-	streams = normalizeStreams(streams)
 	current := newExecution(a, ctx, streams)
-	parsed := current.parse(args)
+	if a == nil {
+		err := errors.New("cannot execute commands on a nil app")
+		return current.finalize(Failure(err.Error()).WithCause(err), nil, false)
+	}
+	if ctx == nil {
+		err := errors.New("invocation context must not be nil")
+		return current.finalize(Failure(err.Error()).WithCause(err), nil, false)
+	}
+	if current.snapshot != nil && current.snapshot.completion && len(args) > 0 && args[0] == internalcobra.CompletionQueryToken {
+		return current.complete(args[1:])
+	}
+	routedSnapshot := current.snapshot
+	current.route = resolveEnteredRoute(args, routedSnapshot)
+	current.recordRouteEvents()
+	parsed := current.parse(current.route.args)
+	current.reporter.applySelection(parsed.Reporting)
+	current.recordSelectionEvents(parsed)
+	current.submitDebugEvents()
+	var outcome Outcome
+	path := parsed.Path
+	handlerRan := false
 	if parsed.Failure != nil {
-		return current.present(Usage(errors.New(parsed.Failure.Message)), parsed.Path)
-	}
-	command, ok := a.commandAt(parsed.Path)
-	if !ok || command.payload == nil {
-		return current.present(current.renderHelp(parsed.Path), parsed.Path)
-	}
-	if parsed.HelpRequested || !command.payload.hasRun() {
-		if _, err := command.payload.prepare(parsed.FlagValues, parsed.Operands, false); err != nil {
-			return current.present(Usage(err), parsed.Path)
+		outcome = Usage(parsed.Failure.Message)
+	} else if current.route.kind == routeDiscovery {
+		if parsed.HelpRequested {
+			outcome = current.renderHelp(parsed.Path)
+			path = clonePath(current.route.enteredPath)
+		} else {
+			entered := current.route.enteredPath.String()
+			outcome = Usage(fmt.Sprintf("incomplete command path %q; use %q --help", entered, entered))
+			path = clonePath(current.route.enteredPath)
 		}
-		return current.present(current.renderHelp(parsed.Path), parsed.Path)
-	}
-	buildInput, err := command.payload.prepare(parsed.FlagValues, parsed.Operands, true)
-	if err != nil {
-		return current.present(Usage(err), parsed.Path)
-	}
-	input := buildInput()
-	if err := command.payload.checkInput(input); err != nil {
-		return current.present(Usage(err), parsed.Path)
-	}
-	if len(parsed.Path) == 1 && parsed.Path[0] == "help" {
-		help, ok := input.(*helpInput)
-		if !ok {
-			return current.present(Failure(errors.New("built-in help input has an unexpected type")), parsed.Path)
+	} else {
+		payload, ok := routedSnapshot.runners[parsed.Key]
+		if !ok || payload == nil {
+			outcome = current.renderHelp(parsed.Path)
+		} else if parsed.HelpRequested || !payload.hasRun() {
+			if _, err := payload.prepare(parsed.FlagValues, parsed.FlagSpellings, parsed.Operands, false); err != nil {
+				outcome = classifyInputError(err)
+			} else {
+				outcome = current.renderHelp(parsed.Path)
+			}
+		} else {
+			run, err := payload.prepare(parsed.FlagValues, parsed.FlagSpellings, parsed.Operands, true)
+			if err != nil {
+				outcome = classifyInputError(err)
+			} else {
+				handlerRan = true
+				outcome = run(current)
+			}
 		}
-		return current.present(current.renderHelpTargets(help.Targets.Value), parsed.Path)
 	}
-	outcome := command.payload.run(Invocation{Context: ctx, Streams: streams}, input)
-	return current.present(outcome, parsed.Path)
+	return current.finalize(outcome, path, handlerRan)
 }
 
 type execution struct {
-	app      *App
-	ctx      context.Context
-	streams  Streams
-	options  internalcobra.ParseOptions
-	metadata *internalcobra.Command
-	session  *internalcobra.Session
+	app         *App
+	ctx         context.Context
+	streams     Streams
+	reporter    *Reporter
+	debugEvents []string
+	options     commandmeta.ParseOptions
+	snapshot    *routingSnapshot
+	session     *internalcobra.Session
+	route       routeResult
+}
+
+type commandExecution struct {
+	invocation            Invocation
+	renderHelpTargetsFunc func([]string) Outcome
+}
+
+func (current *execution) commandContext() commandExecution {
+	return commandExecution{
+		invocation:            current.invocation(),
+		renderHelpTargetsFunc: current.renderHelpTargets,
+	}
+}
+
+func (current *execution) invocation() Invocation {
+	return Invocation{
+		Context:       current.ctx,
+		reporter:      current.reporter,
+		enteredPath:   current.route.enteredPath.String(),
+		canonicalPath: current.route.canonicalPath.String(),
+	}
+}
+
+func (current commandExecution) renderHelpTargets(targets []string) Outcome {
+	return current.renderHelpTargetsFunc(targets)
 }
 
 func newExecution(app *App, ctx context.Context, streams Streams) *execution {
+	streams = normalizeStreams(streams)
 	current := &execution{
-		app:     app,
-		ctx:     ctx,
-		streams: streams,
-		options: internalcobra.ParseOptions{Context: ctx, Out: streams.Out, Err: streams.Err},
+		app:      app,
+		ctx:      ctx,
+		streams:  streams,
+		reporter: newReporter(streams),
+		options:  commandmeta.ParseOptions{Context: ctx, Out: streams.Out, Err: streams.Err},
 	}
 	if app != nil {
-		current.metadata = app.bridgeTree()
-		current.session = internalcobra.Prepare(current.metadata, current.options)
+		current.snapshot = app.routeSnapshot()
 	}
 	return current
 }
 
-func (current *execution) parse(args []string) internalcobra.Result {
+func (current *execution) parse(args []string) commandmeta.Result {
 	if current.app == nil {
-		return internalcobra.Result{Failure: &internalcobra.Failure{Message: "cannot parse commands on a nil app"}}
+		return commandmeta.Result{Failure: &commandmeta.Failure{Message: "cannot parse commands on a nil app"}}
+	}
+	if current.session == nil {
+		current.prepareSession()
+	}
+	return reduceReportingOccurrences(current.session.Parse(args))
+}
+
+func (current *execution) prepareSession() {
+	if current.app == nil {
+		return
+	}
+	if current.snapshot == nil {
+		current.snapshot = current.app.routeSnapshot()
+	}
+	options := current.options
+	if current.snapshot != nil {
+		switch current.route.kind {
+		case routeCanonical:
+			options.FlagAliases = current.snapshot.flagAliases[current.route.canonicalPath.Key()].neutralRecords()
+		case routeDiscovery:
+			options.FlagAliases = current.snapshot.discoveryFlags[current.route.discoveryPath.Key()].neutralRecords()
+		default:
+			snapshot := current.snapshot
+			options.FlagAliasesForPath = func(path []string) []commandmeta.FlagAlias {
+				return snapshot.flagAliases[commandpath.FromTokens(path).Key()].neutralRecords()
+			}
+		}
+		current.session = internalcobra.Prepare(current.snapshot.metadata, options)
 	}
-	return current.session.Parse(args)
 }
 
 func (current *execution) presentationSession() *internalcobra.Session {
 	if current.app == nil {
 		return nil
 	}
-	metadata := current.app.bridgeTree()
-	if current.session == nil || current.session.Metadata() != metadata {
-		current.metadata = metadata
-		current.session = internalcobra.Prepare(metadata, current.options)
+	snapshot := current.app.routeSnapshot()
+	if current.session == nil || current.snapshot != snapshot {
+		current.snapshot = snapshot
+		current.session = nil
+		current.prepareSession()
 	}
 	return current.session
 }
 
 func (current *execution) renderHelp(path []string) Outcome {
 	if current.app == nil {
-		return Failure(errors.New("cannot render help on a nil app"))
+		err := errors.New("cannot render help on a nil app")
+		return Failure(err.Error()).WithCause(err)
 	}
-	return current.app.renderHelpOutcomeWithSession(path, current.streams, current.presentationSession())
+	session := current.presentationSession()
+	view := current.app.helpView(current.route, current.snapshot)
+	return current.app.renderHelpViewOutcomeWithSession(view, current.reporter, session)
 }
 
 func (current *execution) renderHelpTargets(targets []string) Outcome {
 	if current.app == nil {
-		return Failure(errors.New("cannot render help on a nil app"))
+		err := errors.New("cannot render help on a nil app")
+		return Failure(err.Error()).WithCause(err)
 	}
-	return current.app.renderHelpTargetsWithSession(targets, current.streams, current.presentationSession())
+	snapshot := current.app.routeSnapshot()
+	if snapshot == nil {
+		err := errors.New("cannot render help without command metadata")
+		return Failure(err.Error()).WithCause(err)
+	}
+	route := resolveEnteredRoute(targets, snapshot)
+	// Explicit help targets are paths, not command invocations with operands.
+	// Discovery routes have no canonical path and retain only trailing options.
+	if route.kind == routeUnknown || len(route.args) != len(route.canonicalPath) {
+		session := internalcobra.Prepare(snapshot.metadata, current.options)
+		view := commandmeta.HelpView{EnteredPath: targets, CanonicalPath: targets}
+		return current.app.renderHelpViewOutcomeWithSession(view, current.reporter, session)
+	}
+	options := current.options
+	switch route.kind {
+	case routeCanonical:
+		options.FlagAliases = snapshot.flagAliases[route.canonicalPath.Key()].neutralRecords()
+	case routeDiscovery:
+		options.FlagAliases = snapshot.discoveryFlags[route.discoveryPath.Key()].neutralRecords()
+	}
+	session := internalcobra.Prepare(snapshot.metadata, options)
+	view := current.app.helpView(route, snapshot)
+	return current.app.renderHelpViewOutcomeWithSession(view, current.reporter, session)
 }
 
 func (current *execution) usageLine(path []string) string {
@@ -122,104 +229,138 @@ func (current *execution) usageLine(path []string) string {
 	return current.app.usageFallback()
 }
 
-func (current *execution) present(outcome Outcome, path []string) Outcome {
-	return current.app.presentWithUsageLine(outcome, path, current.streams, current.usageLine)
+func (current *execution) routeUsageLine() string {
+	line := current.usageLine(clonePath(current.route.canonicalPath))
+	canonical := strings.TrimSpace(current.app.identity.Name + " " + current.route.canonicalPath.String())
+	entered := strings.TrimSpace(current.app.identity.Name + " " + current.route.enteredPath.String())
+	line = strings.Replace(line, "Usage: "+canonical, "Usage: "+entered, 1)
+	return line + "\nAlias for: " + canonical
 }
 
-func normalizeStreams(streams Streams) Streams {
-	if streams.Out == nil {
-		streams.Out = io.Discard
+func (current *execution) recordRouteEvents() {
+	entered := current.route.enteredPath.String()
+	canonical := current.route.canonicalPath.String()
+	switch current.route.kind {
+	case routeCanonical:
+		if entered == canonical {
+			if canonical == "" {
+				current.debugEvents = append(current.debugEvents, "selected the application root command")
+			} else {
+				current.debugEvents = append(current.debugEvents, fmt.Sprintf("selected command path %q", canonical))
+			}
+		} else {
+			current.debugEvents = append(current.debugEvents, fmt.Sprintf("resolved command alias %q to %q", entered, canonical))
+		}
+	case routeDiscovery:
+		current.debugEvents = append(current.debugEvents, fmt.Sprintf("selected discovery route for prefix %q", entered))
+	default:
+		if entered != "" {
+			current.debugEvents = append(current.debugEvents, fmt.Sprintf("no canonical route matched command path %q", entered))
+		}
 	}
-	if streams.Err == nil {
-		streams.Err = io.Discard
-	}
-	return streams
 }
 
-func (a *App) commandAt(path []string) (Command, bool) {
-	if a == nil {
-		return Command{}, false
+func (current *execution) recordSelectionEvents(result commandmeta.Result) {
+	mode := "ordinary"
+	flagName := ""
+	switch result.Reporting.Mode {
+	case commandmeta.ReportingModeQuiet:
+		mode, flagName = "quiet", "quiet"
+	case commandmeta.ReportingModeVerbose:
+		mode, flagName = "verbose", "verbose"
+	case commandmeta.ReportingModeDebug:
+		mode, flagName = "debug", "debug"
 	}
-	if len(path) == 0 {
-		return Command{}, true
+	event := "selected ordinary reporting mode"
+	if flagName != "" {
+		event = fmt.Sprintf("selected %s reporting mode", mode)
+		for index := len(result.FlagOccurrences) - 1; index >= 0; index-- {
+			occurrence := result.FlagOccurrences[index]
+			if occurrence.Name != flagName {
+				continue
+			}
+			enabled, err := strconv.ParseBool(occurrence.RawValue)
+			if err != nil || !enabled {
+				continue
+			}
+			canonical := "--" + flagName
+			if occurrence.Spelling != canonical {
+				event += fmt.Sprintf(" using %s (alias for %s)", occurrence.Spelling, canonical)
+			} else {
+				event += fmt.Sprintf(" using %s", canonical)
+			}
+			break
+		}
 	}
-	command, ok := a.commands[path[0]]
-	if !ok || (command.reserved && command.command.payload == nil) {
-		return Command{}, false
-	}
-	current := command.command
-	for _, name := range path[1:] {
-		found := false
-		for _, child := range current.children {
-			if child.name == name {
-				current = child
-				found = true
+	current.debugEvents = append(current.debugEvents, event)
+	if result.Reporting.ProgressSet {
+		state := "disabled"
+		if result.Reporting.Progress {
+			state = "enabled"
+		}
+		event := "explicitly " + state + " progress output"
+		for index := len(result.FlagOccurrences) - 1; index >= 0; index-- {
+			occurrence := result.FlagOccurrences[index]
+			if occurrence.Name == "progress" {
+				if occurrence.Spelling != "--progress" {
+					event += fmt.Sprintf(" using %s (alias for --progress)", occurrence.Spelling)
+				}
 				break
 			}
 		}
-		if !found {
-			return Command{}, false
-		}
+		current.debugEvents = append(current.debugEvents, event)
 	}
-	return current, true
 }
 
-func (a *App) present(outcome Outcome, path []string, streams Streams) Outcome {
-	return a.presentWithUsageLine(outcome, path, streams, a.usageLine)
+func (current *execution) submitDebugEvents() {
+	events := current.debugEvents
+	current.debugEvents = nil
+	for _, event := range events {
+		_ = current.reporter.Debug(event)
+	}
 }
 
-func (a *App) presentWithUsageLine(outcome Outcome, path []string, streams Streams, usageLine func([]string) string) Outcome {
-	if outcome.Kind == "" && outcome.Status == 0 && outcome.Domain == "" &&
-		outcome.Cause == nil && outcome.DeliveryError == nil &&
-		!outcome.ReportIncomplete && len(outcome.Diagnostics) == 0 {
-		outcome.Kind = OutcomeSuccess
-	}
-	if outcome.DiagnosticDelivery == "" {
-		outcome.DiagnosticDelivery = DeliveryNone
-	}
-	streams = normalizeStreams(streams)
-	if outcome.DiagnosticDelivery == DeliveryComplete {
-		return outcome
-	}
-	diagnostics := append([]Diagnostic(nil), outcome.Diagnostics...)
-	if outcome.Cause != nil && !hasErrorDiagnostic(diagnostics) {
-		diagnostics = append(diagnostics, MessageDiagnostic(configkit.SeverityError, outcome.Cause.Error()))
-	}
+func (current *execution) finalize(outcome Outcome, path []string, handlerRan bool) Outcome {
 	if outcome.Kind == OutcomeUsage {
-		diagnostics = append(diagnostics, MessageDiagnostic(configkit.SeverityError, usageLine(path)))
-	}
-	outcome.Diagnostics = diagnostics
-	if len(diagnostics) == 0 {
-		return outcome
-	}
-	delivered := false
-	for _, diagnostic := range diagnostics {
-		if diagnostic.Write == nil {
-			continue
-		}
-		delivered = true
-		writer := &checkedWriter{writer: streams.Err}
-		writeErr := diagnostic.Write(writer)
-		if writer.failure != nil {
-			if writeErr == nil {
-				writeErr = writer.failure
-			} else if !errors.Is(writeErr, writer.failure) {
-				writeErr = errors.Join(writeErr, writer.failure)
+		details := append([]Detail(nil), outcome.Explanation.Details...)
+		details = append(details, func(w io.Writer) error {
+			line := current.usageText(path)
+			if !strings.HasSuffix(line, "\n") {
+				line += "\n"
 			}
-		}
-		if writeErr != nil {
-			return deliveryFailure(outcome, writeErr)
+			_, err := io.WriteString(w, line)
+			return err
+		})
+		outcome.Explanation.Details = details
+	}
+	var completion func(*Reporter)
+	if handlerRan {
+		completion = func(reporter *Reporter) {
+			kind := outcome.Kind
+			if kind == "" && outcome.Status == 0 && outcome.Domain == "" {
+				kind = OutcomeSuccess
+			}
+			path := current.route.canonicalPath.String()
+			_ = reporter.Debug(fmt.Sprintf("handler completed for %q with %s outcome and status %d", path, kind, outcome.Status))
 		}
 	}
-	if delivered {
-		outcome.DiagnosticDelivery = DeliveryComplete
+	return current.reporter.finalize(outcome, completion)
+}
+
+func (current *execution) usageText(path []string) string {
+	switch {
+	case current.route.kind == routeDiscovery && current.app != nil:
+		return fmt.Sprintf("Usage: %s %s [command]", current.app.identity.Name, current.route.enteredPath.String())
+	case current.route.kind == routeCanonical && !current.route.enteredPath.Equal(current.route.canonicalPath):
+		return current.routeUsageLine()
+	default:
+		return current.usageLine(path)
 	}
-	return outcome
 }
 
 func (a *App) usageLine(path []string) string {
 	if a != nil {
-		if usage, failure := internalcobra.UsageLine(a.bridgeTree(), path); failure == nil {
+		if usage, failure := internalcobra.UsageLine(a.routeSnapshot().metadata, path); failure == nil {
 			return "Usage: " + usage
 		}
 	}
@@ -233,42 +374,3 @@ func (a *App) usageFallback() string {
 	}
 	return fmt.Sprintf("Usage: %s [command]", name)
 }
-
-func hasErrorDiagnostic(diagnostics []Diagnostic) bool {
-	for _, diagnostic := range diagnostics {
-		if diagnostic.Write != nil && diagnostic.Severity == configkit.SeverityError {
-			return true
-		}
-	}
-	return false
-}
-
-func deliveryFailure(outcome Outcome, err error) Outcome {
-	if outcome.DeliveryError == nil {
-		outcome.DeliveryError = err
-	} else {
-		outcome.DeliveryError = errors.Join(outcome.DeliveryError, err)
-	}
-	outcome.DiagnosticDelivery = DeliveryIncomplete
-	if outcome.Kind != OutcomeDomain {
-		outcome.Kind = OutcomeOperational
-		outcome.Status = 1
-	}
-	return outcome
-}
-
-type checkedWriter struct {
-	writer  io.Writer
-	failure error
-}
-
-func (w *checkedWriter) Write(data []byte) (int, error) {
-	n, err := w.writer.Write(data)
-	if err == nil && n < len(data) {
-		err = io.ErrShortWrite
-	}
-	if err != nil && w.failure == nil {
-		w.failure = err
-	}
-	return n, err
-}

execute_external_test.go

@@ -9,8 +9,7 @@ import (
 	"strings"
 	"testing"
 
-	commandkit "gitea.maximumdirect.net/eric/CommandKit"
-	configkit "gitea.maximumdirect.net/eric/ConfigKit"
+	commandkit "go.maximumdirect.net/commandkit"
 )
 
 func TestExecuteRunsTypedCommandsWithFreshInvocationState(t *testing.T) {
@@ -20,11 +19,11 @@ func TestExecuteRunsTypedCommandsWithFreshInvocationState(t *testing.T) {
 	}
 	var inputs []input
 	var contexts []context.Context
-	var streams []commandkit.Streams
+	var reporters []*commandkit.Reporter
 	firstContext := context.WithValue(context.Background(), struct{}{}, "first")
 	secondContext := context.WithValue(context.Background(), struct{}{}, "second")
 	var firstOut, secondOut, firstDiagnostic, secondDiagnostic bytes.Buffer
-	command, err := commandkit.NewCommand(commandkit.CommandSpec[input]{
+	command := commandkit.NewCommand(commandkit.CommandSpec[input]{
 		Name: "run",
 		Flags: []commandkit.Flag[input]{
 			commandkit.ValueFlag(commandkit.FlagMeta{Name: "name"}, (*string)(nil), func(value string) (string, error) { return value, nil }, func(target *input, value commandkit.Supplied[string]) { target.name = value }),
@@ -33,13 +32,15 @@ func TestExecuteRunsTypedCommandsWithFreshInvocationState(t *testing.T) {
 		Run: func(invocation commandkit.Invocation, value input) commandkit.Outcome {
 			inputs = append(inputs, value)
 			contexts = append(contexts, invocation.Context)
-			streams = append(streams, invocation.Streams)
+			reporter := invocation.Reporter()
+			reporters = append(reporters, reporter)
+			_ = reporter.RenderOutput(func(writer io.Writer) error {
+				_, err := io.WriteString(writer, value.name.Value+"\n")
+				return err
+			})
 			return commandkit.Success()
 		},
 	})
-	if err != nil {
-		t.Fatal(err)
-	}
 	app, err := commandkit.New(commandkit.Identity{Name: "example"}, command)
 	if err != nil {
 		t.Fatal(err)
@@ -56,11 +57,30 @@ func TestExecuteRunsTypedCommandsWithFreshInvocationState(t *testing.T) {
 	if inputs[1].name.Set || inputs[1].name.Value != "" || inputs[1].ids.Set {
 		t.Fatalf("second invocation inherited state: %#v", inputs[1])
 	}
-	if streams[2].Out != io.Discard || streams[2].Err != io.Discard {
-		t.Fatalf("nil streams were not replaced with io.Discard: %#v", streams[2])
+	if reporters[0] == nil || reporters[1] == nil || reporters[2] == nil || reporters[0] == reporters[1] || reporters[0] == reporters[2] || reporters[1] == reporters[2] {
+		t.Fatalf("invocations did not receive fresh reporters: %#v", reporters)
 	}
-	if contexts[0] != firstContext || contexts[1] != secondContext || streams[0].Out != &firstOut || streams[0].Err != &firstDiagnostic || streams[1].Out != &secondOut || streams[1].Err != &secondDiagnostic {
-		t.Fatalf("handler invocation contexts or streams were not forwarded independently")
+	if firstOut.String() != "first\n" || secondOut.String() != "\n" || contexts[0] != firstContext || contexts[1] != secondContext {
+		t.Fatalf("handler invocation contexts or reporter destinations were not independent: out=%q/%q contexts=%v/%v", firstOut.String(), secondOut.String(), contexts[0], contexts[1])
+	}
+}
+
+func TestOmittedInputFactoryUsesExactPointerZeroValue(t *testing.T) {
+	command := commandkit.NewCommand(commandkit.CommandSpec[*int]{
+		Name: "run",
+		Run: func(_ commandkit.Invocation, value *int) commandkit.Outcome {
+			if value != nil {
+				return commandkit.Failure("omitted input factory allocated a pointer")
+			}
+			return commandkit.Success()
+		},
+	})
+	app, err := commandkit.New(commandkit.Identity{Name: "example"}, command)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if outcome := app.Execute(context.Background(), []string{"run"}, commandkit.Streams{}); outcome.Kind != commandkit.OutcomeSuccess {
+		t.Fatalf("pointer zero value outcome = %#v", outcome)
 	}
 }
 
@@ -70,7 +90,7 @@ func TestExecuteUsesFreshSessionForHelpAfterFlagBearingInvocation(t *testing.T)
 		enabled commandkit.Supplied[bool]
 	}
 	var received []input
-	command, err := commandkit.NewCommand(commandkit.CommandSpec[input]{
+	command := commandkit.NewCommand(commandkit.CommandSpec[input]{
 		Name: "run",
 		Flags: []commandkit.Flag[input]{
 			commandkit.ValueFlag(commandkit.FlagMeta{Name: "name"}, (*string)(nil), func(value string) (string, error) {
@@ -83,9 +103,6 @@ func TestExecuteUsesFreshSessionForHelpAfterFlagBearingInvocation(t *testing.T)
 			return commandkit.Success()
 		},
 	})
-	if err != nil {
-		t.Fatal(err)
-	}
 	app, err := commandkit.New(commandkit.Identity{Name: "example"}, command)
 	if err != nil {
 		t.Fatal(err)
@@ -115,27 +132,21 @@ func TestExecutePresentsHandlerUsageAfterRegisteringCommand(t *testing.T) {
 	usageCause := errors.New("handler requests usage")
 	var app *commandkit.App
 	var calls int
-	late, err := commandkit.NewCommand(commandkit.CommandSpec[struct{}]{
+	late := commandkit.NewCommand(commandkit.CommandSpec[struct{}]{
 		Name: "late",
 		Run:  func(commandkit.Invocation, struct{}) commandkit.Outcome { return commandkit.Success() },
 	})
-	if err != nil {
-		t.Fatal(err)
-	}
-	command, err := commandkit.NewCommand(commandkit.CommandSpec[struct{}]{
+	command := commandkit.NewCommand(commandkit.CommandSpec[struct{}]{
 		Name: "run",
 		Run: func(commandkit.Invocation, struct{}) commandkit.Outcome {
 			calls++
 			if err := app.Register(late); err != nil {
-				return commandkit.Failure(err)
+				return commandkit.Failure(err.Error()).WithCause(err)
 			}
-			return commandkit.Usage(usageCause)
+			return commandkit.Usage("The handler requests usage.").WithCause(usageCause)
 		},
 	})
-	if err != nil {
-		t.Fatal(err)
-	}
-	app, err = commandkit.New(commandkit.Identity{Name: "example"}, command)
+	app, err := commandkit.New(commandkit.Identity{Name: "example"}, command)
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -156,7 +167,7 @@ func TestExecuteReturnsUsageForParsingRequirementsAndInputChecks(t *testing.T) {
 	type input struct{ count commandkit.Supplied[int] }
 	parseFailure := errors.New("bad count")
 	checkFailure := errors.New("incompatible inputs")
-	command, err := commandkit.NewCommand(commandkit.CommandSpec[input]{
+	command := commandkit.NewCommand(commandkit.CommandSpec[input]{
 		Name: "run",
 		Flags: []commandkit.Flag[input]{commandkit.ValueFlag(commandkit.FlagMeta{Name: "count", Required: true}, nil, func(value string) (int, error) {
 			if value == "bad" {
@@ -168,9 +179,6 @@ func TestExecuteReturnsUsageForParsingRequirementsAndInputChecks(t *testing.T) {
 		CheckInput: func(input) error { return checkFailure },
 		Run:        func(commandkit.Invocation, input) commandkit.Outcome { return commandkit.Success() },
 	})
-	if err != nil {
-		t.Fatal(err)
-	}
 	app, err := commandkit.New(commandkit.Identity{Name: "example"}, command)
 	if err != nil {
 		t.Fatal(err)
@@ -192,120 +200,86 @@ func TestExecuteReturnsUsageForParsingRequirementsAndInputChecks(t *testing.T) {
 
 func TestExecutePreservesDomainOutcomesAndWarningDiagnostics(t *testing.T) {
 	domainCause := errors.New("domain rejected the request")
-	warning := commandkit.MessageDiagnostic(configkit.SeverityWarning, "review needed")
-	command, err := commandkit.NewCommand(commandkit.CommandSpec[struct{}]{
+	command := commandkit.NewCommand(commandkit.CommandSpec[struct{}]{
 		Name: "run",
-		Run: func(commandkit.Invocation, struct{}) commandkit.Outcome {
-			outcome := commandkit.Domain("sample", 2, domainCause)
-			outcome.Diagnostics = []commandkit.Diagnostic{warning}
+		Run: func(invocation commandkit.Invocation, _ struct{}) commandkit.Outcome {
+			_ = invocation.Reporter().Warn("review needed")
+			outcome := commandkit.Domain("sample", 2).WithExplanation("The request was rejected.").WithCause(domainCause)
 			return outcome
 		},
 	})
-	if err != nil {
-		t.Fatal(err)
-	}
 	app, err := commandkit.New(commandkit.Identity{Name: "example"}, command)
 	if err != nil {
 		t.Fatal(err)
 	}
 	var diagnostic bytes.Buffer
-	outcome := app.Execute(context.Background(), []string{"run"}, commandkit.Streams{Err: &diagnostic})
+	outcome := app.Execute(context.Background(), []string{"run", "--verbose"}, commandkit.Streams{Err: &diagnostic})
 	if outcome.Kind != commandkit.OutcomeDomain || outcome.Domain != "sample" || outcome.Status != 2 || !errors.Is(outcome.Cause, domainCause) {
 		t.Fatalf("domain outcome changed: %#v", outcome)
 	}
-	if diagnostic.String() != "review needed\ndomain rejected the request\n" || outcome.DiagnosticDelivery != commandkit.DeliveryComplete {
+	if diagnostic.String() != "WARN: review needed\nERROR: The request was rejected.\n" || outcome.Presentation.Diagnostics.State != commandkit.DeliveryComplete {
 		t.Fatalf("warning delivery = %q, %#v", diagnostic.String(), outcome)
 	}
-	warningOnly, err := commandkit.NewCommand(commandkit.CommandSpec[struct{}]{
+	warningOnly := commandkit.NewCommand(commandkit.CommandSpec[struct{}]{
 		Name: "warn",
-		Run: func(commandkit.Invocation, struct{}) commandkit.Outcome {
-			result := commandkit.Success()
-			result.Diagnostics = []commandkit.Diagnostic{warning}
-			return result
+		Run: func(invocation commandkit.Invocation, _ struct{}) commandkit.Outcome {
+			_ = invocation.Reporter().Warn("review needed")
+			return commandkit.Success()
 		},
 	})
-	if err != nil {
-		t.Fatal(err)
-	}
 	app, err = commandkit.New(commandkit.Identity{Name: "example"}, warningOnly)
 	if err != nil {
 		t.Fatal(err)
 	}
 	diagnostic.Reset()
-	outcome = app.Execute(context.Background(), []string{"warn"}, commandkit.Streams{Err: &diagnostic})
-	if outcome.Kind != commandkit.OutcomeSuccess || diagnostic.String() != "review needed\n" {
+	outcome = app.Execute(context.Background(), []string{"warn", "--verbose"}, commandkit.Streams{Err: &diagnostic})
+	if outcome.Kind != commandkit.OutcomeSuccess || diagnostic.String() != "WARN: review needed\n" {
 		t.Fatalf("warning-only outcome = %#v, diagnostics %q", outcome, diagnostic.String())
 	}
 }
 
-func TestExecuteDoesNotRepeatCompletedDiagnosticsOrPresentedCauses(t *testing.T) {
-	cause := errors.New("already shown")
-	command, err := commandkit.NewCommand(commandkit.CommandSpec[struct{}]{
+func TestExecuteDoesNotPresentOperationCauseWithoutExplanation(t *testing.T) {
+	cause := errors.New("private operation detail")
+	command := commandkit.NewCommand(commandkit.CommandSpec[struct{}]{
 		Name: "run",
 		Run: func(commandkit.Invocation, struct{}) commandkit.Outcome {
-			outcome := commandkit.Domain("sample", 2, cause)
-			outcome.Diagnostics = []commandkit.Diagnostic{{Severity: configkit.SeverityError, Write: func(writer io.Writer) error {
-				_, err := io.WriteString(writer, "presented\n")
-				return err
-			}}}
-			return outcome
+			return commandkit.Domain("sample", 2).WithCause(cause)
 		},
 	})
-	if err != nil {
-		t.Fatal(err)
-	}
 	app, err := commandkit.New(commandkit.Identity{Name: "example"}, command)
 	if err != nil {
 		t.Fatal(err)
 	}
 	var diagnostic bytes.Buffer
 	outcome := app.Execute(context.Background(), []string{"run"}, commandkit.Streams{Err: &diagnostic})
-	if outcome.Kind != commandkit.OutcomeDomain || diagnostic.String() != "presented\n" {
-		t.Fatalf("presented cause was duplicated: %#v, %q", outcome, diagnostic.String())
+	if outcome.Kind != commandkit.OutcomeDomain || !errors.Is(outcome.Cause, cause) {
+		t.Fatalf("domain outcome changed: %#v", outcome)
 	}
-
-	diagnostic.Reset()
-	completed := commandkit.Domain("sample", 2, cause)
-	completed.DiagnosticDelivery = commandkit.DeliveryComplete
-	command, err = commandkit.NewCommand(commandkit.CommandSpec[struct{}]{Name: "done", Run: func(commandkit.Invocation, struct{}) commandkit.Outcome { return completed }})
-	if err != nil {
-		t.Fatal(err)
-	}
-	app, err = commandkit.New(commandkit.Identity{Name: "example"}, command)
-	if err != nil {
-		t.Fatal(err)
-	}
-	outcome = app.Execute(context.Background(), []string{"done"}, commandkit.Streams{Err: &diagnostic})
-	if diagnostic.Len() != 0 || outcome.DiagnosticDelivery != commandkit.DeliveryComplete {
-		t.Fatalf("completed diagnostics were repeated: %#v, %q", outcome, diagnostic.String())
+	if strings.Contains(diagnostic.String(), cause.Error()) || !strings.Contains(diagnostic.String(), "ERROR: Command failed.") {
+		t.Fatalf("cause was presented instead of the fallback explanation: %#v, %q", outcome, diagnostic.String())
 	}
 }
 
 func TestExecuteRetainsOperationAndDiagnosticDeliveryFailures(t *testing.T) {
 	operationFailure := context.Canceled
 	writeFailure := errors.New("writer failed")
-	command, err := commandkit.NewCommand(commandkit.CommandSpec[struct{}]{
+	command := commandkit.NewCommand(commandkit.CommandSpec[struct{}]{
 		Name: "run",
 		Run: func(commandkit.Invocation, struct{}) commandkit.Outcome {
-			outcome := commandkit.Failure(operationFailure)
-			outcome.ReportIncomplete = true
-			return outcome
+			return commandkit.Failure("The operation was canceled.").WithCause(operationFailure)
 		},
 	})
-	if err != nil {
-		t.Fatal(err)
-	}
 	app, err := commandkit.New(commandkit.Identity{Name: "example"}, command)
 	if err != nil {
 		t.Fatal(err)
 	}
 	outcome := app.Execute(context.Background(), []string{"run"}, commandkit.Streams{Err: failingWriter{err: writeFailure}})
-	if outcome.Kind != commandkit.OutcomeOperational || outcome.Status != 1 || outcome.DiagnosticDelivery != commandkit.DeliveryIncomplete || !outcome.ReportIncomplete || !errors.Is(outcome.Cause, operationFailure) || !errors.Is(outcome.DeliveryError, writeFailure) {
+	if outcome.Kind != commandkit.OutcomeOperational || outcome.Status != 1 || outcome.Presentation.Diagnostics.State != commandkit.DeliveryIncomplete || !errors.Is(outcome.Cause, operationFailure) || !errors.Is(outcome.Presentation.Diagnostics.WriteError, writeFailure) {
 		t.Fatalf("combined operation and delivery failure = %#v", outcome)
 	}
 
 	short := app.Execute(context.Background(), []string{"run"}, commandkit.Streams{Err: shortWriter{}})
-	if !errors.Is(short.DeliveryError, io.ErrShortWrite) || short.DiagnosticDelivery != commandkit.DeliveryIncomplete {
+	if !errors.Is(short.Presentation.Diagnostics.WriteError, io.ErrShortWrite) || short.Presentation.Diagnostics.State != commandkit.DeliveryIncomplete {
 		t.Fatalf("short write was not detected: %#v", short)
 	}
 }
@@ -313,7 +287,7 @@ func TestExecuteRetainsOperationAndDiagnosticDeliveryFailures(t *testing.T) {
 func TestExecuteHelpSkipsRequiredInputsAndRejectsNilContext(t *testing.T) {
 	type input struct{ id commandkit.Supplied[string] }
 	factoryCalls, checkCalls, runCalls := 0, 0, 0
-	command, err := commandkit.NewCommand(commandkit.CommandSpec[input]{
+	command := commandkit.NewCommand(commandkit.CommandSpec[input]{
 		Name: "run",
 		NewInput: func() input {
 			factoryCalls++
@@ -323,9 +297,6 @@ func TestExecuteHelpSkipsRequiredInputsAndRejectsNilContext(t *testing.T) {
 		CheckInput: func(input) error { checkCalls++; return nil },
 		Run:        func(commandkit.Invocation, input) commandkit.Outcome { runCalls++; return commandkit.Success() },
 	})
-	if err != nil {
-		t.Fatal(err)
-	}
 	app, err := commandkit.New(commandkit.Identity{Name: "example"}, command)
 	if err != nil {
 		t.Fatal(err)
@@ -344,7 +315,7 @@ func TestExecuteRunsApplicationOwnedNestedHelp(t *testing.T) {
 	type input struct{ topic commandkit.Supplied[string] }
 	var received []input
 	domainCause := errors.New("application help result")
-	help, err := commandkit.NewCommand(commandkit.CommandSpec[input]{
+	help := commandkit.NewCommand(commandkit.CommandSpec[input]{
 		Name:        "help",
 		Description: "Explain a session topic.",
 		Arguments: []commandkit.Argument[input]{commandkit.ValueArgument(
@@ -354,16 +325,10 @@ func TestExecuteRunsApplicationOwnedNestedHelp(t *testing.T) {
 		)},
 		Run: func(_ commandkit.Invocation, value input) commandkit.Outcome {
 			received = append(received, value)
-			return commandkit.Domain("session-help", 7, domainCause)
+			return commandkit.Domain("session-help", 7).WithExplanation("Session help is unavailable.").WithCause(domainCause)
 		},
 	})
-	if err != nil {
-		t.Fatal(err)
-	}
-	session, err := commandkit.Group("session", "Session commands.", help)
-	if err != nil {
-		t.Fatal(err)
-	}
+	session := commandkit.Group("session", "Session commands.", help)
 	app, err := commandkit.New(commandkit.Identity{Name: "example"}, session)
 	if err != nil {
 		t.Fatal(err)
@@ -401,7 +366,7 @@ func TestHelpRendersRegisteredMetadataAndResolvesExactPaths(t *testing.T) {
 		tags  commandkit.Supplied[[]string]
 	}
 	factoryCalls, runCalls := 0, 0
-	show, err := commandkit.NewCommand(commandkit.CommandSpec[input]{
+	show := commandkit.NewCommand(commandkit.CommandSpec[input]{
 		Name:        "show",
 		Summary:     "Show one item.",
 		Description: "Display the selected item in detail.",
@@ -418,25 +383,9 @@ func TestHelpRendersRegisteredMetadataAndResolvesExactPaths(t *testing.T) {
 		Arguments: []commandkit.Argument[input]{commandkit.RepeatArgument(commandkit.ArgumentMeta{Name: "ID", Usage: "item identifier"}, 1, 3, func(value string) (string, error) { return value, nil }, func(*input, commandkit.Supplied[[]string]) {})},
 		Run:       func(commandkit.Invocation, input) commandkit.Outcome { runCalls++; return commandkit.Success() },
 	})
-	if err != nil {
-		t.Fatal(err)
-	}
-	config, err := commandkit.Group("config", "Inspect configuration.", show)
-	if err != nil {
-		t.Fatal(err)
-	}
-	now, err := commandkit.NewCommand(commandkit.CommandSpec[struct{}]{Name: "now", Summary: "Deploy immediately.", Run: func(commandkit.Invocation, struct{}) commandkit.Outcome { return commandkit.Success() }})
-	if err != nil {
-		t.Fatal(err)
-	}
-	deployParent, err := commandkit.NewCommand(commandkit.CommandSpec[struct{}]{Name: "deploy", Summary: "Deploy artifacts.", Run: func(commandkit.Invocation, struct{}) commandkit.Outcome { runCalls++; return commandkit.Success() }})
-	if err != nil {
-		t.Fatal(err)
-	}
-	deploy, err := commandkit.WithChildren(deployParent, now)
-	if err != nil {
-		t.Fatal(err)
-	}
+	config := commandkit.Group("config", "Inspect configuration.", show)
+	now := commandkit.NewCommand(commandkit.CommandSpec[struct{}]{Name: "now", Summary: "Deploy immediately.", Run: func(commandkit.Invocation, struct{}) commandkit.Outcome { return commandkit.Success() }})
+	deploy := commandkit.NewCommand(commandkit.CommandSpec[struct{}]{Name: "deploy", Summary: "Deploy artifacts.", Children: []commandkit.Command{now}, Run: func(commandkit.Invocation, struct{}) commandkit.Outcome { runCalls++; return commandkit.Success() }})
 	app, err := commandkit.New(commandkit.Identity{Name: "example"}, config, deploy)
 	if err != nil {
 		t.Fatal(err)
@@ -500,7 +449,7 @@ func TestHelpRendersRegisteredMetadataAndResolvesExactPaths(t *testing.T) {
 		t.Fatalf("version invoked an application command: %#v calls=%d/%d", versionOutcome, factoryCalls, runCalls)
 	}
 	failed := app.Execute(context.Background(), []string{"config", "show", "--help"}, commandkit.Streams{Out: shortWriter{}, Err: &diagnostic})
-	if failed.Kind != commandkit.OutcomeOperational || !failed.ReportIncomplete || !errors.Is(failed.DeliveryError, io.ErrShortWrite) {
+	if failed.Kind != commandkit.OutcomeOperational || failed.Presentation.Output.State != commandkit.DeliveryIncomplete || !errors.Is(failed.Presentation.Output.WriteError, io.ErrShortWrite) {
 		t.Fatalf("failed help delivery = %#v", failed)
 	}
 	out.Reset()
@@ -540,7 +489,7 @@ func TestVersionCommandFormatsApplicationAndCommandKitIdentity(t *testing.T) {
 		t.Fatalf("invalid version scope = %#v, output %q", invalid, out.String())
 	}
 	failed := app.Execute(context.Background(), []string{"version"}, commandkit.Streams{Out: shortWriter{}, Err: &diagnostic})
-	if failed.Kind != commandkit.OutcomeOperational || !failed.ReportIncomplete || !errors.Is(failed.DeliveryError, io.ErrShortWrite) {
+	if failed.Kind != commandkit.OutcomeOperational || failed.Presentation.Output.State != commandkit.DeliveryIncomplete || !errors.Is(failed.Presentation.Output.WriteError, io.ErrShortWrite) {
 		t.Fatalf("failed version delivery = %#v", failed)
 	}
 }
@@ -559,10 +508,7 @@ func (shortWriter) Write(data []byte) (int, error) {
 }
 
 func TestHelpEntryFormsPresentReportAndDiagnosticFailures(t *testing.T) {
-	group, err := commandkit.Group("notes", "Notes metadata.")
-	if err != nil {
-		t.Fatal(err)
-	}
+	group := commandkit.Group("notes", "Notes metadata.")
 	app, err := commandkit.New(commandkit.Identity{Name: "example"}, group)
 	if err != nil {
 		t.Fatal(err)
@@ -572,11 +518,11 @@ func TestHelpEntryFormsPresentReportAndDiagnosticFailures(t *testing.T) {
 	for _, args := range [][]string{nil, {"notes"}, {"--help"}, {"-h"}, {"notes", "--help"}, {"help"}, {"help", "notes"}} {
 		var diagnostics bytes.Buffer
 		result := app.Execute(context.Background(), args, commandkit.Streams{Out: failingWriter{reportErr}, Err: &diagnostics})
-		if result.Kind != commandkit.OutcomeOperational || !result.ReportIncomplete || !errors.Is(result.Cause, reportErr) || !errors.Is(result.DeliveryError, reportErr) || result.DiagnosticDelivery != commandkit.DeliveryComplete || strings.Count(diagnostics.String(), reportErr.Error()) != 1 {
+		if result.Kind != commandkit.OutcomeOperational || result.Presentation.Output.State != commandkit.DeliveryIncomplete || !errors.Is(result.Presentation.Output.WriteError, reportErr) || result.Presentation.Diagnostics.State != commandkit.DeliveryComplete || (!strings.Contains(diagnostics.String(), "deliver") || !strings.Contains(diagnostics.String(), "output")) {
 			t.Fatalf("%v: result=%#v diagnostics=%q", args, result, diagnostics.String())
 		}
 		result = app.Execute(context.Background(), args, commandkit.Streams{Out: failingWriter{reportErr}, Err: failingWriter{diagnosticErr}})
-		if result.DiagnosticDelivery != commandkit.DeliveryIncomplete || !errors.Is(result.Cause, reportErr) || !errors.Is(result.DeliveryError, reportErr) || !errors.Is(result.DeliveryError, diagnosticErr) {
+		if result.Presentation.Output.State != commandkit.DeliveryIncomplete || !errors.Is(result.Presentation.Output.WriteError, reportErr) || result.Presentation.Diagnostics.State != commandkit.DeliveryIncomplete || !errors.Is(result.Presentation.Diagnostics.WriteError, diagnosticErr) {
 			t.Fatalf("%v: result=%#v", args, result)
 		}
 	}
@@ -595,104 +541,39 @@ func TestExecuteNormalizesOutcomeDefaultsAndPreservesDomainValues(t *testing.T)
 		{commandkit.Outcome{Kind: commandkit.OutcomeDomain, Status: 2, Domain: "needs action", Cause: cause}, commandkit.OutcomeDomain, 2, "needs action", cause},
 		{commandkit.Outcome{Kind: commandkit.OutcomeDomain, Status: 0, Domain: "complete"}, commandkit.OutcomeDomain, 0, "complete", nil},
 	} {
-		command, err := commandkit.NewCommand(commandkit.CommandSpec[struct{}]{Name: "run", Run: func(commandkit.Invocation, struct{}) commandkit.Outcome { return tc.outcome }})
-		if err != nil {
-			t.Fatal(err)
-		}
+		command := commandkit.NewCommand(commandkit.CommandSpec[struct{}]{Name: "run", Run: func(commandkit.Invocation, struct{}) commandkit.Outcome { return tc.outcome }})
 		app, err := commandkit.New(commandkit.Identity{Name: "example"}, command)
 		if err != nil {
 			t.Fatal(err)
 		}
-		result := app.Execute(context.Background(), []string{"run"}, commandkit.Streams{})
-		wantDelivery := commandkit.DeliveryNone
-		if tc.cause != nil {
-			wantDelivery = commandkit.DeliveryComplete
-		}
-		if result.Kind != tc.kind || result.Status != tc.status || result.Domain != tc.domain || result.Cause != tc.cause || result.DiagnosticDelivery != wantDelivery {
+		var diagnostic bytes.Buffer
+		result := app.Execute(context.Background(), []string{"run"}, commandkit.Streams{Err: &diagnostic})
+		if result.Kind != tc.kind || result.Status != tc.status || result.Domain != tc.domain || result.Cause != tc.cause {
 			t.Fatalf("result=%#v expected=%#v", result, tc)
 		}
+		if tc.status != 0 && !strings.Contains(diagnostic.String(), "ERROR: Command failed.") {
+			t.Fatalf("failed outcome omitted its fallback explanation: %q", diagnostic.String())
+		}
+		if tc.cause != nil && strings.Contains(diagnostic.String(), tc.cause.Error()) {
+			t.Fatalf("operation cause was presented automatically: %q", diagnostic.String())
+		}
 	}
 }
 
-func TestNilDiagnosticWritersHaveNoOutputAndDoNotHideCauses(t *testing.T) {
+func TestNilDiagnosticWriterDoesNotHideOperationCause(t *testing.T) {
 	cause := errors.New("operation failed")
-	for _, base := range []commandkit.Outcome{commandkit.Success(), commandkit.Domain("needs action", 2, nil), commandkit.Failure(cause)} {
-		base.Diagnostics = []commandkit.Diagnostic{{}, {Severity: configkit.SeverityWarning}, {Severity: configkit.SeverityError}}
-		command, err := commandkit.NewCommand(commandkit.CommandSpec[struct{}]{Name: "run", Run: func(commandkit.Invocation, struct{}) commandkit.Outcome { return base }})
-		if err != nil {
-			t.Fatal(err)
-		}
-		app, err := commandkit.New(commandkit.Identity{Name: "example"}, command)
-		if err != nil {
-			t.Fatal(err)
-		}
-		var diagnostics bytes.Buffer
-		result := app.Execute(context.Background(), []string{"run"}, commandkit.Streams{Err: &diagnostics})
-		want := commandkit.DeliveryNone
-		if base.Cause != nil {
-			want = commandkit.DeliveryComplete
-		}
-		if result.Kind != base.Kind || result.Status != base.Status || result.Domain != base.Domain || result.Cause != base.Cause || result.DeliveryError != nil || result.DiagnosticDelivery != want {
-			t.Fatalf("result=%#v base=%#v", result, base)
-		}
-		if base.Cause == nil && diagnostics.Len() != 0 {
-			t.Fatalf("unexpected output=%q", diagnostics.String())
-		}
-		if base.Cause != nil && strings.Count(diagnostics.String(), cause.Error()) != 1 {
-			t.Fatalf("cause output=%q", diagnostics.String())
-		}
-		if base.Cause != nil {
-			result = app.Execute(context.Background(), []string{"run"}, commandkit.Streams{Err: failingWriter{io.ErrClosedPipe}})
-			if !errors.Is(result.Cause, cause) || !errors.Is(result.DeliveryError, io.ErrClosedPipe) || result.DiagnosticDelivery != commandkit.DeliveryIncomplete {
-				t.Fatalf("failed delivery=%#v", result)
-			}
-		}
-	}
-}
-
-func TestParentHelpDiscoversMetadataOnlyGroups(t *testing.T) {
-	leaf, err := commandkit.Group("notes", "Read notes metadata.")
-	if err != nil {
-		t.Fatal(err)
-	}
-	parent, err := commandkit.Group("topics", "Browse topic metadata.", leaf)
-	if err != nil {
-		t.Fatal(err)
-	}
-	app, err := commandkit.New(commandkit.Identity{Name: "example"}, parent)
-	if err != nil {
-		t.Fatal(err)
-	}
-	loads := 0
-	if err := commandkit.RegisterConfig(app, commandkit.ConfigSuite[struct{}]{Scopes: []commandkit.ConfigScope[struct{}]{{Name: "app", Operations: []commandkit.ConfigOperation{commandkit.ConfigValidate}, Acquire: func(context.Context, commandkit.ConfigRequest, struct{}) (commandkit.Acquired[commandkit.ConfigView], error) {
-		loads++
-		return commandkit.Acquired[commandkit.ConfigView]{}, nil
-	}}}}); err != nil {
-		t.Fatal(err)
-	}
-	for _, tc := range []struct {
-		args    []string
-		content string
-	}{
-		{nil, "Browse topic metadata."},
-		{[]string{"topics"}, "Read notes metadata."},
-		{[]string{"topics", "--help"}, "Read notes metadata."},
-		{[]string{"help", "topics"}, "Read notes metadata."},
-		{[]string{"topics", "notes"}, "Read notes metadata."},
-		{[]string{"help", "topics", "notes"}, "Read notes metadata."},
-	} {
-		var out bytes.Buffer
-		result := app.Execute(context.Background(), tc.args, commandkit.Streams{Out: &out})
-		if result.Kind != commandkit.OutcomeSuccess || !strings.Contains(out.String(), tc.content) || loads != 0 {
-			t.Fatalf("%v: result=%#v output=%q loads=%d", tc.args, result, out.String(), loads)
-		}
-		if len(tc.args) == 1 && (!strings.Contains(out.String(), "Available Commands:") || !strings.Contains(out.String(), "[command]")) {
-			t.Fatalf("missing child inventory/usage: %q", out.String())
-		}
-	}
-	var diagnostic bytes.Buffer
-	result := app.Execute(context.Background(), []string{"topics", "unknown"}, commandkit.Streams{Err: &diagnostic})
-	if result.Kind != commandkit.OutcomeUsage || !strings.Contains(diagnostic.String(), "[command]") {
-		t.Fatalf("result=%#v diagnostic=%q", result, diagnostic.String())
+	command := commandkit.NewCommand(commandkit.CommandSpec[struct{}]{
+		Name: "run",
+		Run: func(commandkit.Invocation, struct{}) commandkit.Outcome {
+			return commandkit.Failure("The operation failed.").WithCause(cause)
+		},
+	})
+	app, err := commandkit.New(commandkit.Identity{Name: "example"}, command)
+	if err != nil {
+		t.Fatal(err)
+	}
+	result := app.Execute(context.Background(), []string{"run"}, commandkit.Streams{})
+	if result.Kind != commandkit.OutcomeOperational || !errors.Is(result.Cause, cause) || result.Presentation.Diagnostics.State != commandkit.DeliveryComplete {
+		t.Fatalf("nil diagnostic destination changed the outcome: %#v", result)
 	}
 }

execute_reporting_test.go

@@ -0,0 +1,189 @@
+package commandkit
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"strings"
+	"testing"
+)
+
+func TestExecuteGivesEachInvocationItsReporterAndAppliesSelection(t *testing.T) {
+	var reporters []*Reporter
+	command := NewCommand(CommandSpec[struct{}]{
+		Name: "run",
+		Run: func(inv Invocation, _ struct{}) Outcome {
+			reporter := inv.Reporter()
+			reporters = append(reporters, reporter)
+			if _, err := fmt.Fprint(reporter.Output(), "result\n"); err != nil {
+				t.Errorf("write result: %v", err)
+			}
+			if err := reporter.Warn("attention"); err != nil {
+				t.Errorf("submit warning: %v", err)
+			}
+			return Outcome{
+				Kind: OutcomeDomain, Domain: "accepted", Status: 0,
+				Presentation: PresentationResult{
+					Output: DeliveryResult{State: DeliveryIncomplete, WriteError: io.ErrClosedPipe},
+				},
+			}
+		},
+	})
+	app, err := New(Identity{Name: "Example"}, command)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	var quietOut, quietErr bytes.Buffer
+	quiet := app.Execute(context.Background(), []string{"run", "--quiet"}, Streams{Out: &quietOut, Err: &quietErr})
+	if quiet.Kind != OutcomeDomain || quiet.Status != 0 || quiet.Domain != "accepted" {
+		t.Fatalf("quiet outcome = %#v", quiet)
+	}
+	if quietOut.Len() != 0 || quietErr.Len() != 0 {
+		t.Fatalf("quiet output = %q, diagnostics = %q", quietOut.String(), quietErr.String())
+	}
+	if quiet.Presentation.Output.State != DeliverySuppressed || quiet.Presentation.Diagnostics.State != DeliverySuppressed {
+		t.Fatalf("quiet presentation = %#v", quiet.Presentation)
+	}
+
+	var verboseOut, verboseErr bytes.Buffer
+	verbose := app.Execute(context.Background(), []string{"run", "--verbose"}, Streams{Out: &verboseOut, Err: &verboseErr})
+	if verbose.Kind != OutcomeDomain || verbose.Status != 0 {
+		t.Fatalf("verbose outcome = %#v", verbose)
+	}
+	if verboseOut.String() != "result\n" || verboseErr.String() != "WARN: attention\n" {
+		t.Fatalf("verbose output = %q, diagnostics = %q", verboseOut.String(), verboseErr.String())
+	}
+	if verbose.Presentation.Output.State != DeliveryComplete || verbose.Presentation.Diagnostics.State != DeliveryComplete {
+		t.Fatalf("verbose presentation = %#v", verbose.Presentation)
+	}
+	if len(reporters) != 2 || reporters[0] == nil || reporters[1] == nil || reporters[0] == reporters[1] {
+		t.Fatalf("invocation reporters = %#v", reporters)
+	}
+	if _, err := reporters[0].Output().Write([]byte("late")); !errors.Is(err, ErrReporterClosed) {
+		t.Fatalf("write through finalized reporter error = %v", err)
+	}
+}
+
+func TestExecuteQuietUsageKeepsAliasGuidanceVisible(t *testing.T) {
+	command := NewCommand(CommandSpec[struct{}]{
+		Name: "run",
+		Run:  func(Invocation, struct{}) Outcome { return Success() },
+	})
+	app, err := New(Identity{Name: "Example"}, command, Alias("r", "run"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	var output, diagnostics bytes.Buffer
+	outcome := app.Execute(context.Background(), []string{"r", "--quiet", "--unknown"}, Streams{Out: &output, Err: &diagnostics})
+	if outcome.Kind != OutcomeUsage || outcome.Status != 2 {
+		t.Fatalf("outcome = %#v", outcome)
+	}
+	if output.Len() != 0 {
+		t.Fatalf("usage output = %q", output.String())
+	}
+	if got := diagnostics.String(); !strings.Contains(got, "ERROR: unknown flag") || !strings.Contains(got, "Usage: Example r") || !strings.Contains(got, "Alias for: Example run") {
+		t.Fatalf("usage diagnostics = %q", got)
+	}
+	if outcome.Presentation.Diagnostics.State != DeliveryComplete {
+		t.Fatalf("diagnostic presentation = %#v", outcome.Presentation.Diagnostics)
+	}
+}
+
+func TestUnresolvedRoutesUseReportingAliasesForTheirParseContext(t *testing.T) {
+	calls := 0
+	command := NewCommand(CommandSpec[struct{}]{
+		Name:     "run",
+		NewInput: func() struct{} { calls++; return struct{}{} },
+		Run:      func(Invocation, struct{}) Outcome { calls++; return Success() },
+	})
+	app, err := New(Identity{Name: "Example"}, Group("group", "", Group("nested", "", command)),
+		FlagAlias("-d", "--debug"), FlagAlias("-q", "--quiet"),
+		FlagAlias("-x", "--quiet"), FlagAliasFor("group nested", "-x", "--debug"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, path := range [][]string{{"missing"}, {"group", "missing"}, {"group", "nested", "missing"}} {
+		t.Run(strings.Join(path, "/"), func(t *testing.T) {
+			var canonicalDiagnostics, aliasDiagnostics bytes.Buffer
+			canonical := app.Execute(context.Background(), append(append([]string(nil), path...), "--debug"), Streams{Err: &canonicalDiagnostics})
+			alias := app.Execute(context.Background(), append(append([]string(nil), path...), "-d"), Streams{Err: &aliasDiagnostics})
+			if canonical.Kind != OutcomeUsage || alias.Kind != OutcomeUsage || canonical.Status != alias.Status || canonical.Explanation.Message != alias.Explanation.Message {
+				t.Fatalf("canonical=%#v alias=%#v", canonical, alias)
+			}
+			for _, text := range []string{canonicalDiagnostics.String(), aliasDiagnostics.String()} {
+				if !strings.Contains(text, "DEBUG:") || !strings.Contains(text, "ERROR:") || strings.Contains(text, "unknown shorthand") || strings.Contains(text, "Alias for:") {
+					t.Fatalf("diagnostics=%q", text)
+				}
+			}
+			route := resolveEnteredRoute(path, app.routeSnapshot())
+			if route.kind != routeUnknown || len(route.canonicalPath) != 0 {
+				t.Fatalf("invalid route acquired canonical identity: %#v", route)
+			}
+			var quiet bytes.Buffer
+			got := app.Execute(context.Background(), append(append([]string(nil), path...), "-q", "--unknown"), Streams{Err: &quiet})
+			if got.Kind != OutcomeUsage || !strings.Contains(quiet.String(), "ERROR: unknown flag") || strings.Contains(quiet.String(), "DEBUG:") {
+				t.Fatalf("quiet alias outcome=%#v diagnostics=%q", got, quiet.String())
+			}
+		})
+	}
+	var scoped bytes.Buffer
+	got := app.Execute(context.Background(), []string{"group", "nested", "missing", "-x"}, Streams{Err: &scoped})
+	if got.Kind != OutcomeUsage || !strings.Contains(scoped.String(), "DEBUG:") {
+		t.Fatalf("scoped precedence outcome=%#v diagnostics=%q", got, scoped.String())
+	}
+	if calls != 0 {
+		t.Fatalf("invalid routes ran factories or handlers %d times", calls)
+	}
+}
+
+type executeReportingFailureWriter struct{ err error }
+
+func (w executeReportingFailureWriter) Write([]byte) (int, error) { return 0, w.err }
+
+func TestExecuteFinalizesEarlyAndIgnoredWriterFailures(t *testing.T) {
+	command := NewCommand(CommandSpec[struct{}]{
+		Name: "run",
+		Run: func(inv Invocation, _ struct{}) Outcome {
+			_, _ = inv.Reporter().Output().Write([]byte("report"))
+			return Success()
+		},
+	})
+	app, err := New(Identity{Name: "Example"}, command)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	writeErr := errors.New("result destination failed")
+	var diagnostics bytes.Buffer
+	outcome := app.Execute(context.Background(), []string{"run"}, Streams{
+		Out: executeReportingFailureWriter{err: writeErr}, Err: &diagnostics,
+	})
+	if outcome.Kind != OutcomeOperational || outcome.Status != 1 || !errors.Is(outcome.Presentation.Output.WriteError, writeErr) {
+		t.Fatalf("ignored output failure outcome = %#v", outcome)
+	}
+	if !strings.Contains(diagnostics.String(), "deliver") || !strings.Contains(diagnostics.String(), "output") {
+		t.Fatalf("fallback diagnostic = %q", diagnostics.String())
+	}
+
+	diagnostics.Reset()
+	outcome = app.Execute(nil, []string{"run"}, Streams{Err: &diagnostics})
+	if outcome.Kind != OutcomeOperational || outcome.Status != 1 || outcome.Cause == nil {
+		t.Fatalf("nil context outcome = %#v", outcome)
+	}
+	if !strings.Contains(diagnostics.String(), "ERROR: invocation context must not be nil\n") {
+		t.Fatalf("nil context diagnostic = %q", diagnostics.String())
+	}
+
+	diagnostics.Reset()
+	var nilApp *App
+	outcome = nilApp.Execute(context.Background(), []string{"run"}, Streams{Err: &diagnostics})
+	if outcome.Kind != OutcomeOperational || outcome.Status != 1 || outcome.Cause == nil {
+		t.Fatalf("nil app outcome = %#v", outcome)
+	}
+	if !strings.Contains(diagnostics.String(), "ERROR: cannot execute commands on a nil app\n") {
+		t.Fatalf("nil app diagnostic = %q", diagnostics.String())
+	}
+}

explain.go

@@ -1,230 +0,0 @@
-package commandkit
-
-import (
-	"bytes"
-	"errors"
-	"fmt"
-	"io"
-
-	configkit "gitea.maximumdirect.net/eric/ConfigKit"
-)
-
-func newConfigExplainCommand[C any](prepared *preparedConfigSuite[C]) (Command, error) {
-	flags := configInputFlags(prepared.suite, "text")
-	flags = append(flags, ValueFlag[configInput[C]](FlagMeta{
-		Name:     "path",
-		Usage:    "Configuration path as a JSON Pointer; an empty value selects the root.",
-		Required: true,
-	}, nil, parseString, func(input *configInput[C], value Supplied[string]) {
-		input.Path = value
-	}))
-	spec := CommandSpec[configInput[C]]{
-		Name:    string(ConfigExplain),
-		Summary: "Explain the effective and historical value at a configuration path.",
-		Flags:   flags,
-		CheckInput: func(input configInput[C]) error {
-			if _, err := preflightConfig(prepared, input, ConfigExplain); err != nil {
-				return err
-			}
-			if !input.Path.Set {
-				return fmt.Errorf("--path is required")
-			}
-			if _, err := configkit.ParsePath(input.Path.Value); err != nil {
-				return fmt.Errorf("invalid configuration path %q: %w", input.Path.Value, err)
-			}
-			return nil
-		},
-		Run: func(invocation Invocation, input configInput[C]) Outcome {
-			return runConfigExplanation(invocation, prepared, input)
-		},
-	}
-	return NewCommand(spec)
-}
-
-type explanationReport struct {
-	Scope           string                 `yaml:"scope"`
-	Path            string                 `yaml:"path"`
-	Effective       snapshotDTO            `yaml:"effective"`
-	Origin          explanationOriginDTO   `yaml:"origin"`
-	History         []explanationChangeDTO `yaml:"history"`
-	SecretReference *secretReferenceDTO    `yaml:"secret_reference"`
-}
-
-type snapshotDTO struct {
-	Present  bool   `yaml:"present"`
-	Redacted bool   `yaml:"redacted"`
-	YAML     string `yaml:"yaml"`
-}
-
-type explanationOriginDTO struct {
-	Layer       string               `yaml:"layer"`
-	Locations   []locationDTO        `yaml:"locations"`
-	Operation   string               `yaml:"operation"`
-	Inheritance []inheritanceStepDTO `yaml:"inheritance"`
-}
-
-type inheritanceStepDTO struct {
-	From      string        `yaml:"from"`
-	To        string        `yaml:"to"`
-	Reference string        `yaml:"reference"`
-	Locations []locationDTO `yaml:"locations"`
-}
-
-type explanationChangeDTO struct {
-	Before       snapshotDTO          `yaml:"before"`
-	After        snapshotDTO          `yaml:"after"`
-	Origin       explanationOriginDTO `yaml:"origin"`
-	Reasons      []string             `yaml:"reasons"`
-	Dependencies []string             `yaml:"dependencies"`
-}
-
-type secretReferenceDTO struct {
-	Name string `yaml:"name"`
-}
-
-func runConfigExplanation[C any](invocation Invocation, prepared *preparedConfigSuite[C], input configInput[C]) Outcome {
-	if err := invocation.Context.Err(); err != nil {
-		return Failure(err)
-	}
-	scopeNames, err := selectConfigScopes(prepared, input, ConfigExplain)
-	if err != nil {
-		return Failure(err)
-	}
-	if !input.Path.Set {
-		return Failure(fmt.Errorf("--path is required"))
-	}
-	path, err := configkit.ParsePath(input.Path.Value)
-	if err != nil {
-		return Usage(fmt.Errorf("invalid configuration path %q: %w", input.Path.Value, err))
-	}
-	name := scopeNames[0]
-	contexts := contextsForScopes(prepared, input, scopeNames)
-	scope, ok := findConfigScope(prepared, name)
-	if !ok || scope.Acquire == nil {
-		return Failure(fmt.Errorf("configuration scope %q has no acquisition callback", name))
-	}
-	if err := invocation.Context.Err(); err != nil {
-		return explanationFailure(err, nil, false)
-	}
-	acquired, acquireErr := scope.Acquire(invocation.Context, ConfigRequest{Operation: ConfigExplain, Selection: input.Selection}, contexts[name])
-	diagnostics := append([]Diagnostic(nil), acquired.Diagnostics...)
-	if acquireErr != nil {
-		return explanationFailure(acquireErr, diagnostics, false)
-	}
-	if err := invocation.Context.Err(); err != nil {
-		return explanationFailure(err, diagnostics, false)
-	}
-
-	if acquired.Value.Explanation == nil {
-		return explanationFailure(fmt.Errorf("configuration scope %q did not provide an explanation reader", name), diagnostics, false)
-	}
-	explanation, found := acquired.Value.Explanation.Explain(path)
-	if !found {
-		return explanationFailure(fmt.Errorf("configuration path %q is not known in scope %q", path.String(), name), diagnostics, false)
-	}
-	if err := invocation.Context.Err(); err != nil {
-		return explanationFailure(err, diagnostics, false)
-	}
-	if input.Format != "yaml" {
-		return writeNativeExplanation(invocation.Streams.Out, acquired.Value.Explanation, path, diagnostics)
-	}
-	var report bytes.Buffer
-	if err := encodeYAML(&report, makeExplanationReport(name, explanation)); err != nil {
-		return explanationFailure(err, diagnostics, false)
-	}
-	if err := invocation.Context.Err(); err != nil {
-		return explanationFailure(err, diagnostics, false)
-	}
-	if err := writeReport(invocation.Streams.Out, report.Bytes()); err != nil {
-		outcome := explanationFailure(err, diagnostics, true)
-		outcome.DeliveryError = err
-		return outcome
-	}
-	outcome := Success()
-	outcome.Diagnostics = diagnostics
-	return outcome
-}
-
-func writeNativeExplanation(writer io.Writer, reader ExplanationReader, path configkit.Path, diagnostics []Diagnostic) Outcome {
-	checked := &checkedWriter{writer: writer}
-	renderErr := reader.WriteExplanation(checked, path)
-	if checked.failure != nil {
-		if renderErr == nil {
-			renderErr = checked.failure
-		} else {
-			renderErr = errors.Join(renderErr, checked.failure)
-		}
-	}
-	if renderErr != nil {
-		outcome := explanationFailure(renderErr, diagnostics, true)
-		outcome.DeliveryError = checked.failure
-		return outcome
-	}
-	outcome := Success()
-	outcome.Diagnostics = diagnostics
-	return outcome
-}
-
-func makeExplanationReport(scope string, explanation configkit.Explanation) explanationReport {
-	report := explanationReport{
-		Scope:     scope,
-		Path:      explanation.Path.String(),
-		Effective: snapshotReport(explanation.Effective),
-		Origin:    originReport(explanation.Origin),
-		History:   make([]explanationChangeDTO, 0, len(explanation.History)),
-	}
-	for _, change := range explanation.History {
-		entry := explanationChangeDTO{
-			Before:       snapshotReport(change.Before),
-			After:        snapshotReport(change.After),
-			Origin:       originReport(change.Origin),
-			Reasons:      append([]string{}, change.Reasons...),
-			Dependencies: make([]string, 0, len(change.Dependencies)),
-		}
-		for _, dependency := range change.Dependencies {
-			entry.Dependencies = append(entry.Dependencies, dependency.String())
-		}
-		report.History = append(report.History, entry)
-	}
-	if explanation.SecretReference != nil {
-		report.SecretReference = &secretReferenceDTO{Name: explanation.SecretReference.Name}
-	}
-	return report
-}
-
-func snapshotReport(snapshot configkit.ValueSnapshot) snapshotDTO {
-	return snapshotDTO{Present: snapshot.Present, Redacted: snapshot.Redacted, YAML: snapshot.YAML}
-}
-
-func originReport(origin configkit.Origin) explanationOriginDTO {
-	report := explanationOriginDTO{
-		Layer:       string(origin.Layer),
-		Locations:   locationReports(origin.Locations),
-		Operation:   string(origin.Operation),
-		Inheritance: make([]inheritanceStepDTO, 0, len(origin.Inheritance)),
-	}
-	for _, step := range origin.Inheritance {
-		report.Inheritance = append(report.Inheritance, inheritanceStepDTO{
-			From:      step.From.String(),
-			To:        step.To.String(),
-			Reference: step.Reference.String(),
-			Locations: locationReports(step.Locations),
-		})
-	}
-	return report
-}
-
-func locationReports(locations []configkit.Location) []locationDTO {
-	report := make([]locationDTO, 0, len(locations))
-	for _, location := range locations {
-		report = append(report, locationDTO{SourceID: location.SourceID, Line: location.Line, Column: location.Column})
-	}
-	return report
-}
-
-func explanationFailure(cause error, diagnostics []Diagnostic, reportStarted bool) Outcome {
-	outcome := Failure(cause)
-	outcome.Diagnostics = diagnostics
-	outcome.ReportIncomplete = reportStarted
-	return outcome
-}

flag_aliases.go

@@ -0,0 +1,296 @@
+package commandkit
+
+import (
+	"fmt"
+	"sort"
+	"strings"
+
+	commandmeta "go.maximumdirect.net/commandkit/internal/commandmeta"
+	"go.maximumdirect.net/commandkit/internal/commandpath"
+)
+
+type resolvedFlagAlias struct {
+	source capturedFlagSpelling
+	target capturedFlagSpelling
+}
+
+type resolvedFlagAliases struct {
+	bySpelling map[string]resolvedFlagAlias
+}
+
+type flagAliasMapping struct {
+	target capturedFlagSpelling
+	scoped bool
+}
+
+type flagAliasContext struct {
+	path      commandpath.Path
+	canonical map[string]capturedFlagSpelling
+	discovery bool
+}
+
+func (aliases resolvedFlagAliases) neutralRecords() []commandmeta.FlagAlias {
+	keys := make([]string, 0, len(aliases.bySpelling))
+	for key := range aliases.bySpelling {
+		keys = append(keys, key)
+	}
+	sort.Strings(keys)
+	records := make([]commandmeta.FlagAlias, 0, len(keys))
+	for _, key := range keys {
+		alias := aliases.bySpelling[key]
+		records = append(records, alias.neutralRecord())
+	}
+	return records
+}
+
+// lookupRecords skips sorting: resolved source spellings are unique and the
+// parser's lookup does not depend on record order.
+func (aliases resolvedFlagAliases) lookupRecords() []commandmeta.FlagAlias {
+	records := make([]commandmeta.FlagAlias, 0, len(aliases.bySpelling))
+	for _, alias := range aliases.bySpelling {
+		records = append(records, alias.neutralRecord())
+	}
+	return records
+}
+
+func (alias resolvedFlagAlias) neutralRecord() commandmeta.FlagAlias {
+	return commandmeta.FlagAlias{Source: alias.source.token(), Target: alias.target.token()}
+}
+
+func (spelling capturedFlagSpelling) token() string {
+	if spelling.short {
+		return "-" + spelling.name
+	}
+	return "--" + spelling.name
+}
+
+func compileFlagAliases(rules []RoutingRule, roots map[string]*canonicalNode, aliases interface {
+	Resolve(commandpath.Path) commandpath.Path
+}) (map[string]resolvedFlagAliases, map[string]resolvedFlagAliases, error) {
+	canonicalNodes := indexCanonicalNodes(roots)
+	global := make(map[string]flagAliasMapping)
+	scoped := make(map[string]map[string]flagAliasMapping)
+	for _, rule := range rules {
+		record := rule.record
+		switch record.kind {
+		case globalFlagAliasRule:
+			source := flagSpellingKey(record.sourceFlag)
+			global[source] = flagAliasMapping{target: record.targetFlag}
+		case scopedFlagAliasRule:
+			scope := record.scopePath.Key()
+			if canonicalNodes[scope] == nil {
+				return nil, nil, fmt.Errorf("flag alias scope %q is not a canonical command path", record.scopePath.String())
+			}
+			if scoped[scope] == nil {
+				scoped[scope] = make(map[string]flagAliasMapping)
+			}
+			source := flagSpellingKey(record.sourceFlag)
+			scoped[scope][source] = flagAliasMapping{target: record.targetFlag, scoped: true}
+		}
+	}
+
+	canonicalContexts := make(map[string]flagAliasContext, len(canonicalNodes)+1)
+	rootPath := commandpath.Path(nil)
+	canonicalContexts[rootPath.Key()] = flagAliasContext{path: rootPath, canonical: helpFlagSpellings()}
+	for key, node := range canonicalNodes {
+		canonicalContexts[key] = flagAliasContext{path: node.path.Clone(), canonical: canonicalFlagSpellings(node.command)}
+	}
+	discoveryContexts := discoverFlagContexts(rules, roots, aliases, canonicalNodes)
+
+	canonicalKeys := sortedContextKeys(canonicalContexts)
+	resolvedCanonical := make(map[string]resolvedFlagAliases, len(canonicalContexts))
+	for _, key := range canonicalKeys {
+		context := canonicalContexts[key]
+		mappings := cloneFlagMappings(global)
+		for source, mapping := range scoped[key] {
+			mappings[source] = mapping
+		}
+		resolved, err := resolveFlagAliases(context, mappings)
+		if err != nil {
+			return nil, nil, err
+		}
+		resolvedCanonical[key] = resolved
+	}
+
+	discoveryKeys := sortedContextKeys(discoveryContexts)
+	resolvedDiscovery := make(map[string]resolvedFlagAliases, len(discoveryContexts))
+	for _, key := range discoveryKeys {
+		context := discoveryContexts[key]
+		resolved, err := resolveFlagAliases(context, cloneFlagMappings(global))
+		if err != nil {
+			return nil, nil, err
+		}
+		resolvedDiscovery[key] = resolved
+	}
+	return resolvedCanonical, resolvedDiscovery, nil
+}
+
+func indexCanonicalNodes(roots map[string]*canonicalNode) map[string]*canonicalNode {
+	indexed := make(map[string]*canonicalNode)
+	var add func(*canonicalNode)
+	add = func(node *canonicalNode) {
+		indexed[node.path.Key()] = node
+		for _, child := range node.children {
+			add(child)
+		}
+	}
+	for _, root := range roots {
+		add(root)
+	}
+	return indexed
+}
+
+func helpFlagSpellings() map[string]capturedFlagSpelling {
+	flags := make(map[string]capturedFlagSpelling, 2+len(commandmeta.ReportingFlags()))
+	for _, spelling := range []capturedFlagSpelling{{name: "help"}, {name: "h", short: true}} {
+		flags[flagSpellingKey(spelling)] = spelling
+	}
+	for _, metadata := range commandmeta.ReportingFlags() {
+		spelling := capturedFlagSpelling{name: metadata.Name}
+		flags[flagSpellingKey(spelling)] = spelling
+	}
+	return flags
+}
+
+func canonicalFlagSpellings(command Command) map[string]capturedFlagSpelling {
+	flags := helpFlagSpellings()
+	if command.record.payload == nil {
+		return flags
+	}
+	for _, metadata := range command.record.payload.bridgeFlags() {
+		long := capturedFlagSpelling{name: metadata.Name}
+		flags[flagSpellingKey(long)] = long
+		if metadata.Short != "" {
+			short := capturedFlagSpelling{name: metadata.Short, short: true}
+			flags[flagSpellingKey(short)] = short
+		}
+	}
+	return flags
+}
+
+func discoverFlagContexts(rules []RoutingRule, roots map[string]*canonicalNode, aliases interface {
+	Resolve(commandpath.Path) commandpath.Path
+}, canonicalNodes map[string]*canonicalNode) map[string]flagAliasContext {
+	commandSources := make(map[string]struct{})
+	prefixes := make(map[string]commandpath.Path)
+	for _, rule := range rules {
+		if rule.record.kind == commandAliasRule {
+			commandSources[rule.record.sourcePath.Key()] = struct{}{}
+		}
+	}
+	for _, rule := range rules {
+		if rule.record.kind != commandAliasRule {
+			continue
+		}
+		for length := 1; length < len(rule.record.sourcePath); length++ {
+			prefix := rule.record.sourcePath[:length].Clone()
+			key := prefix.Key()
+			if canonicalNodes[key] != nil {
+				continue
+			}
+			if _, exactAlias := commandSources[key]; exactAlias {
+				continue
+			}
+			resolved := aliases.Resolve(prefix)
+			trace := traceCanonicalPath(roots, resolved)
+			if trace.exact != nil || (trace.operandOwner != nil && acceptsOperandPrefix(trace.operandOwner.command, len(resolved)-len(trace.operandOwner.path))) {
+				continue
+			}
+			prefixes[key] = prefix
+		}
+	}
+	contexts := make(map[string]flagAliasContext, len(prefixes))
+	for key, path := range prefixes {
+		contexts[key] = flagAliasContext{path: path, canonical: helpFlagSpellings(), discovery: true}
+	}
+	return contexts
+}
+
+func cloneFlagMappings(mappings map[string]flagAliasMapping) map[string]flagAliasMapping {
+	cloned := make(map[string]flagAliasMapping, len(mappings))
+	for source, mapping := range mappings {
+		cloned[source] = mapping
+	}
+	return cloned
+}
+
+func sortedContextKeys(contexts map[string]flagAliasContext) []string {
+	keys := make([]string, 0, len(contexts))
+	for key := range contexts {
+		keys = append(keys, key)
+	}
+	sort.Strings(keys)
+	return keys
+}
+
+func resolveFlagAliases(context flagAliasContext, mappings map[string]flagAliasMapping) (resolvedFlagAliases, error) {
+	result := resolvedFlagAliases{bySpelling: make(map[string]resolvedFlagAlias)}
+	sources := make([]string, 0, len(mappings))
+	for source := range mappings {
+		sources = append(sources, source)
+	}
+	sort.Strings(sources)
+	for _, sourceKey := range sources {
+		mapping := mappings[sourceKey]
+		source := spellingFromKey(sourceKey)
+		target, active, err := resolveFlagTarget(source, mapping.target, mappings, context.canonical)
+		if err != nil {
+			return resolvedFlagAliases{}, fmt.Errorf("%s: %w", flagContextDescription(context), err)
+		}
+		if !active {
+			if mapping.scoped {
+				return resolvedFlagAliases{}, fmt.Errorf("scoped flag alias %s has no canonical destination in %s", source.token(), flagContextDescription(context))
+			}
+			continue
+		}
+		if _, collision := context.canonical[sourceKey]; collision {
+			return resolvedFlagAliases{}, fmt.Errorf("flag alias %s conflicts with a canonical spelling in %s", source.token(), flagContextDescription(context))
+		}
+		result.bySpelling[sourceKey] = resolvedFlagAlias{source: source, target: target}
+	}
+	return result, nil
+}
+
+func resolveFlagTarget(source, target capturedFlagSpelling, mappings map[string]flagAliasMapping, canonical map[string]capturedFlagSpelling) (capturedFlagSpelling, bool, error) {
+	visited := map[string]int{flagSpellingKey(source): 0}
+	chain := []capturedFlagSpelling{source}
+	current := target
+	for {
+		key := flagSpellingKey(current)
+		if endpoint, exists := canonical[key]; exists {
+			return endpoint, true, nil
+		}
+		if start, exists := visited[key]; exists {
+			cycle := append(append([]capturedFlagSpelling(nil), chain[start:]...), current)
+			spellings := make([]string, 0, len(cycle))
+			for _, spelling := range cycle {
+				spellings = append(spellings, spelling.token())
+			}
+			return capturedFlagSpelling{}, false, fmt.Errorf("flag alias cycle: %s", strings.Join(spellings, " → "))
+		}
+		visited[key] = len(chain)
+		chain = append(chain, current)
+		next, exists := mappings[key]
+		if !exists {
+			return capturedFlagSpelling{}, false, nil
+		}
+		current = next.target
+	}
+}
+
+func spellingFromKey(key string) capturedFlagSpelling {
+	if strings.HasPrefix(key, "short:") {
+		return capturedFlagSpelling{name: strings.TrimPrefix(key, "short:"), short: true}
+	}
+	return capturedFlagSpelling{name: strings.TrimPrefix(key, "long:")}
+}
+
+func flagContextDescription(context flagAliasContext) string {
+	if context.discovery {
+		return fmt.Sprintf("alias prefix %q", context.path.String())
+	}
+	if len(context.path) == 0 {
+		return "application root"
+	}
+	return fmt.Sprintf("command %q", context.path.String())
+}

flag_aliases_test.go

@@ -0,0 +1,297 @@
+package commandkit
+
+import (
+	"strings"
+	"testing"
+
+	commandmeta "go.maximumdirect.net/commandkit/internal/commandmeta"
+	"go.maximumdirect.net/commandkit/internal/commandpath"
+)
+
+func flagAliasCommand(name string, flags ...Flag[struct{}]) Command {
+	return NewCommand(CommandSpec[struct{}]{
+		Name: name, Summary: name, Flags: flags,
+		Run: func(Invocation, struct{}) Outcome { return Success() },
+	})
+}
+
+func stringFlag(name, short string) Flag[struct{}] {
+	return ValueFlag(FlagMeta{Name: name, Short: short}, (*string)(nil),
+		func(value string) (string, error) { return value, nil },
+		func(*struct{}, Supplied[string]) {},
+	)
+}
+
+func TestFlagAliasChainsUseScopedOverridesAndCanonicalEndpoints(t *testing.T) {
+	inspect := flagAliasCommand("inspect", stringFlag("color", "c"), stringFlag("format", "f"))
+	show := flagAliasCommand("show", stringFlag("color", "c"), stringFlag("format", "f"))
+	group := Group("Tools", "tools", show)
+	app, err := New(Identity{Name: "Example"},
+		inspect,
+		group,
+		Alias("look", "inspect"),
+		FlagAlias("--colour", "--hue"),
+		FlagAlias("--hue", "--color"),
+		FlagAlias("-x", "--color"),
+		FlagAlias("--tint", "-c"),
+		FlagAliasFor("Tools", "--group-help", "--help"),
+		FlagAliasFor("inspect", "--hue", "--format"),
+		FlagAliasFor("inspect", "--local", "--format"),
+	)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	inspectAliases := app.flagAliases[commandpath.Path{"inspect"}.Key()].bySpelling
+	for source, target := range map[string]string{
+		"--colour": "--format",
+		"--hue":    "--format",
+		"-x":       "--color",
+		"--tint":   "-c",
+		"--local":  "--format",
+	} {
+		alias, ok := inspectAliases[flagSpellingKey(capturedSpelling(source))]
+		if !ok || alias.target.token() != target {
+			t.Errorf("inspect alias %s = (%s, %v), want %s", source, alias.target.token(), ok, target)
+		}
+	}
+
+	groupAliases := app.flagAliases[commandpath.Path{"Tools"}.Key()].bySpelling
+	if _, active := groupAliases[flagSpellingKey(capturedFlagSpelling{name: "colour"})]; active {
+		t.Error("global alias was active on a group without its destination flag")
+	}
+	if _, inherited := groupAliases[flagSpellingKey(capturedFlagSpelling{name: "local"})]; inherited {
+		t.Fatal("command-scoped alias was inherited by its parent group")
+	}
+	if _, inherited := app.flagAliases[commandpath.Path{"Tools", "show"}.Key()].bySpelling[flagSpellingKey(capturedFlagSpelling{name: "local"})]; inherited {
+		t.Fatal("command-scoped alias was inherited by a different command")
+	}
+	groupHelp := flagSpellingKey(capturedFlagSpelling{name: "group-help"})
+	if got := groupAliases[groupHelp].target.token(); got != "--help" {
+		t.Fatalf("group-scoped help alias target = %s, want --help", got)
+	}
+	if _, inherited := app.flagAliases[commandpath.Path{"Tools", "show"}.Key()].bySpelling[groupHelp]; inherited {
+		t.Fatal("group-scoped alias was inherited by its child command")
+	}
+}
+
+func TestFlagAliasDiscoveryContextsUseGlobalReportingAliases(t *testing.T) {
+	show := flagAliasCommand("show")
+	app, err := New(Identity{Name: "Example"},
+		Group("Tools", "tools", show),
+		Alias("shortcut show", "Tools show"),
+		FlagAlias("--hlep", "--help"),
+		FlagAlias("--silent", "--quiet"),
+		FlagAlias("--chatty", "--verbose"),
+		FlagAlias("--trace", "--debug"),
+		FlagAlias("--show-progress", "--progress"),
+		FlagAliasFor("Tools show", "--local-help", "--help"),
+	)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	globalHelp := flagSpellingKey(capturedFlagSpelling{name: "hlep"})
+	if got := app.flagAliases[commandpath.Path(nil).Key()].bySpelling[globalHelp].target.token(); got != "--help" {
+		t.Fatalf("root --hlep target = %s, want --help", got)
+	}
+	if got := app.flagAliases[commandpath.Path{"Tools"}.Key()].bySpelling[globalHelp].target.token(); got != "--help" {
+		t.Fatalf("group --hlep target = %s, want --help", got)
+	}
+	discovery := app.discoveryFlags[commandpath.Path{"shortcut"}.Key()].bySpelling
+	if got := discovery[globalHelp].target.token(); got != "--help" {
+		t.Fatalf("discovery --hlep target = %s, want --help", got)
+	}
+	for label, aliases := range map[string]resolvedFlagAliases{
+		"root":      app.flagAliases[commandpath.Path(nil).Key()],
+		"group":     app.flagAliases[commandpath.Path{"Tools"}.Key()],
+		"command":   app.flagAliases[commandpath.Path{"Tools", "show"}.Key()],
+		"discovery": app.discoveryFlags[commandpath.Path{"shortcut"}.Key()],
+	} {
+		for source, target := range map[string]string{
+			"silent":        "quiet",
+			"chatty":        "verbose",
+			"trace":         "debug",
+			"show-progress": "progress",
+		} {
+			key := flagSpellingKey(capturedFlagSpelling{name: source})
+			if got := aliases.bySpelling[key].target.token(); got != "--"+target {
+				t.Errorf("%s --%s target = %s, want --%s", label, source, got, target)
+			}
+		}
+	}
+	if _, inherited := discovery[flagSpellingKey(capturedFlagSpelling{name: "local-help"})]; inherited {
+		t.Fatal("discovery context inherited a command-scoped alias")
+	}
+}
+
+func TestReportingFlagsAreReservedAndAcceptApplicationShortAliases(t *testing.T) {
+	for _, name := range []string{"quiet", "verbose", "debug", "progress"} {
+		command := flagAliasCommand("reserved", stringFlag(name, ""))
+		if len(command.record.issues) == 0 {
+			t.Errorf("capturing --%s did not retain a declaration error", name)
+		}
+		app, err := New(Identity{Name: "Example"}, flagAliasCommand("safe"))
+		if err != nil {
+			t.Fatal(err)
+		}
+		snapshot := app.routeSnapshot()
+		if err := app.Register(command, Alias("reserved-shortcut", "reserved")); err == nil || !strings.Contains(err.Error(), "reserved for reporting") {
+			t.Errorf("registering --%s returned %v, want a retained reporting reservation error", name, err)
+		}
+		if app.routeSnapshot() != snapshot || app.commands["reserved"] != nil || app.commands["safe"] == nil || len(app.routingRules) != 0 {
+			t.Fatalf("failed registration of --%s changed the installed commands", name)
+		}
+	}
+
+	declarations := []Declaration{flagAliasCommand("run")}
+	for short, target := range map[string]string{"q": "quiet", "v": "verbose", "d": "debug"} {
+		declarations = append(declarations, FlagAlias("-"+short, "--"+target))
+	}
+	if _, err := New(Identity{Name: "Example"}, declarations...); err != nil {
+		t.Fatalf("application short aliases for reporting flags were rejected: %v", err)
+	}
+}
+
+func TestReportingFlagSpellingsConflictWithAliasSources(t *testing.T) {
+	for _, name := range []string{"quiet", "verbose", "debug", "progress"} {
+		if _, err := New(Identity{Name: "Example"}, FlagAlias("--"+name, "--help")); err == nil || !strings.Contains(err.Error(), "conflicts with a canonical spelling") {
+			t.Errorf("alias source --%s returned %v, want a canonical spelling collision", name, err)
+		}
+	}
+	if _, err := New(Identity{Name: "Example"}, Group("tools", "", flagAliasCommand("show")), FlagAliasFor("tools", "--quiet", "--help")); err == nil || !strings.Contains(err.Error(), "conflicts with a canonical spelling") {
+		t.Errorf("group-scoped canonical reporting spelling returned %v, want a collision", err)
+	}
+}
+
+func TestRoutingSnapshotCarriesReportingMetadataOutsideConsumerBindings(t *testing.T) {
+	app, err := New(Identity{Name: "Example"},
+		flagAliasCommand("run", stringFlag("format", "f")),
+		Group("tools", "", flagAliasCommand("show")),
+	)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var check func(*commandmeta.Command)
+	check = func(node *commandmeta.Command) {
+		if len(node.CoreFlags) != 4 {
+			t.Errorf("%s core reporting flags = %#v", node.Name, node.CoreFlags)
+		}
+		for _, flag := range node.Flags {
+			if commandmeta.IsReportingFlag(flag.Name) {
+				t.Errorf("%s reporting flag %q was added to consumer bindings", node.Name, flag.Name)
+			}
+		}
+		for _, child := range node.Children {
+			check(child)
+		}
+	}
+	check(app.routeSnapshot().metadata)
+}
+
+func TestFlagAliasDuplicatesAndScopesAreDeterministic(t *testing.T) {
+	command := flagAliasCommand("inspect", stringFlag("color", "c"), stringFlag("format", "f"))
+	duplicate := FlagAlias("--colour", "--color")
+	app, err := New(Identity{Name: "Example"}, command, flagAliasCommand("plain", stringFlag("color", "c")), duplicate, FlagAlias("--colour", "--color"),
+		FlagAliasFor("inspect", "--colour", "--format"))
+	if err != nil {
+		t.Fatalf("identical duplicates and scoped override were rejected: %v", err)
+	}
+	if got := app.flagAliases[commandpath.Path{"inspect"}.Key()].bySpelling[flagSpellingKey(capturedFlagSpelling{name: "colour"})].target.token(); got != "--format" {
+		t.Fatalf("scoped alias target = %s, want --format", got)
+	}
+	if got := app.flagAliases[commandpath.Path{"plain"}.Key()].bySpelling[flagSpellingKey(capturedFlagSpelling{name: "colour"})].target.token(); got != "--color" {
+		t.Fatalf("effective global alias target = %s, want --color", got)
+	}
+
+	for name, rules := range map[string][]RoutingRule{
+		"competing global targets": {
+			FlagAlias("--colour", "--color"),
+			FlagAlias("--colour", "--format"),
+		},
+		"competing scoped targets": {
+			FlagAliasFor("inspect", "--colour", "--color"),
+			FlagAliasFor("inspect", "--colour", "--format"),
+		},
+		"unknown scope":              {FlagAliasFor("missing", "--colour", "--color")},
+		"missing scoped destination": {FlagAliasFor("inspect", "--colour", "--missing")},
+	} {
+		t.Run(name, func(t *testing.T) {
+			declarations := []Declaration{command}
+			for _, rule := range rules {
+				declarations = append(declarations, rule)
+			}
+			if _, err := New(Identity{Name: "Example"}, declarations...); err == nil {
+				t.Fatal("New() accepted invalid flag alias rules")
+			}
+		})
+	}
+}
+
+func TestFlagAliasCyclesIdentifyParticipatingSpellings(t *testing.T) {
+	for name, declarations := range map[string][]Declaration{
+		"global": {
+			FlagAlias("--first", "--second"),
+			FlagAlias("--second", "--first"),
+		},
+		"scoped": {
+			flagAliasCommand("inspect"),
+			FlagAliasFor("inspect", "-a", "--second"),
+			FlagAliasFor("inspect", "--second", "-a"),
+		},
+	} {
+		t.Run(name, func(t *testing.T) {
+			_, err := New(Identity{Name: "Example"}, declarations...)
+			if err == nil {
+				t.Fatal("New() accepted a flag alias cycle")
+			}
+			message := err.Error()
+			for _, spelling := range []string{"--first", "--second"} {
+				if name == "scoped" {
+					continue
+				}
+				if !strings.Contains(message, spelling) {
+					t.Errorf("cycle error %q does not identify %s", message, spelling)
+				}
+			}
+			if name == "scoped" && (!strings.Contains(message, "-a") || !strings.Contains(message, "--second")) {
+				t.Errorf("scoped cycle error %q does not identify both spellings", message)
+			}
+		})
+	}
+}
+
+func TestInactiveGlobalAliasesActivateAtomicallyWhenDestinationAppears(t *testing.T) {
+	command := flagAliasCommand("inspect", stringFlag("color", "c"))
+	app, err := New(Identity{Name: "Example"}, command,
+		FlagAlias("--color", "--missing"),
+		FlagAlias("--colour", "--color"),
+	)
+	if err != nil {
+		t.Fatal(err)
+	}
+	aliases := app.flagAliases[commandpath.Path{"inspect"}.Key()].bySpelling
+	if _, active := aliases[flagSpellingKey(capturedFlagSpelling{name: "color"})]; active {
+		t.Fatal("global alias with an unavailable destination became active")
+	}
+	if got := aliases[flagSpellingKey(capturedFlagSpelling{name: "colour"})].target.token(); got != "--color" {
+		t.Fatalf("--colour endpoint = %s, want canonical --color", got)
+	}
+
+	snapshot := app.routeSnapshot()
+	commands := len(app.commands)
+	rules := len(app.routingRules)
+	originalAlias := aliases[flagSpellingKey(capturedFlagSpelling{name: "colour"})]
+	if err := app.Register(flagAliasCommand("later", stringFlag("color", "c"), stringFlag("missing", ""))); err == nil {
+		t.Fatal("Register() accepted a newly active global source collision")
+	}
+	currentAlias := app.flagAliases[commandpath.Path{"inspect"}.Key()].bySpelling[flagSpellingKey(capturedFlagSpelling{name: "colour"})]
+	if app.routeSnapshot() != snapshot || len(app.commands) != commands || len(app.routingRules) != rules || currentAlias != originalAlias {
+		t.Fatal("failed registration changed the existing command or routing state")
+	}
+}
+
+func capturedSpelling(token string) capturedFlagSpelling {
+	issues := []error(nil)
+	return captureFlagSpelling("test", token, &issues)
+}

flag_values.go

@@ -0,0 +1,96 @@
+package commandkit
+
+import (
+	"errors"
+	"fmt"
+)
+
+// ErrFlagInput identifies a missing required captured flag selected for an input.
+var ErrFlagInput = errors.New("required flag input is missing")
+
+// ErrFlagWiring identifies an invalid captured binding or destination.
+var ErrFlagWiring = errors.New("flag wiring is invalid")
+
+// FlagValues stores invocation-local converted values and presence for captured
+// flags. It does not retain an input instance; values can be applied to
+// independently initialized destinations.
+type FlagValues[I any] struct {
+	values map[*bindingIdentity]preparedValue[I]
+}
+
+// CaptureFlags adapts flags declared for I into flags on Outer. During parsing,
+// each adapted flag stores its prepared value in target, associated with the
+// original inner binding identity. Copies of an original handle remain
+// selectable; an independently constructed lookalike does not.
+func CaptureFlags[Outer, I any](flags []Flag[I], target func(*Outer) *FlagValues[I]) []Flag[Outer] {
+	captured := make([]Flag[Outer], len(flags))
+	for index, original := range flags {
+		inner := original
+		identity := newBindingIdentity()
+		binding := flagBinding[Outer]{
+			identity:         identity,
+			meta:             inner.binding.meta,
+			deferredRequired: inner.binding.meta.Required,
+			defaultText:      inner.binding.defaultText,
+			repeated:         inner.binding.repeated,
+			boolean:          inner.binding.boolean,
+		}
+		if target != nil && inner.binding.identity != nil && inner.binding.valid && inner.binding.prepare != nil {
+			binding.valid = true
+			binding.prepare = func(raw []string) (preparedValue[Outer], error) {
+				prepared, err := inner.binding.prepare(raw)
+				if err != nil {
+					return preparedValue[Outer]{}, err
+				}
+				return preparedValue[Outer]{
+					identity: identity,
+					supplied: prepared.supplied,
+					apply: func(outer *Outer) {
+						store := target(outer)
+						if store == nil {
+							return
+						}
+						if store.values == nil {
+							store.values = make(map[*bindingIdentity]preparedValue[I])
+						}
+						store.values[inner.binding.identity] = prepared
+					},
+				}, nil
+			}
+		}
+		captured[index] = Flag[Outer]{binding: binding}
+	}
+	return captured
+}
+
+// ApplyTo applies selected original captured flags to an initialized
+// destination. A missing captured binding or nil destination matches
+// ErrFlagWiring. A required selected value that was not supplied matches
+// ErrFlagInput. Repeated core-owned values are copied for each application.
+func (values FlagValues[I]) ApplyTo(target *I, selected ...Flag[I]) error {
+	if target == nil {
+		return fmt.Errorf("%w: destination is nil", ErrFlagWiring)
+	}
+	for _, flag := range selected {
+		binding := flag.binding
+		if binding.identity == nil {
+			return fmt.Errorf("%w: selected flag has no identity", ErrFlagWiring)
+		}
+		prepared, exists := values.values[binding.identity]
+		if !exists {
+			return fmt.Errorf("%w: flag --%s was not captured", ErrFlagWiring, binding.meta.Name)
+		}
+		if binding.meta.Required && !prepared.supplied {
+			return fmt.Errorf("flag --%s: %w", binding.meta.Name, ErrFlagInput)
+		}
+		prepared.apply(target)
+	}
+	return nil
+}
+
+func classifyInputError(err error) Outcome {
+	if errors.Is(err, ErrFlagWiring) {
+		return Failure(err.Error()).WithCause(err)
+	}
+	return Usage(err.Error()).WithCause(err)
+}

flag_values_test.go

@@ -0,0 +1,144 @@
+package commandkit
+
+import (
+	"errors"
+	"fmt"
+	"testing"
+)
+
+type capturedInput struct {
+	name Supplied[string]
+	tags Supplied[[]string]
+}
+
+type capturedOuter struct {
+	flags FlagValues[capturedInput]
+}
+
+func TestCaptureFlagsAppliesOnlyOriginalBindingWithoutReconversion(t *testing.T) {
+	parseCalls := 0
+	original := ValueFlag(FlagMeta{Name: "name"}, nil, func(value string) (string, error) {
+		parseCalls++
+		return value, nil
+	}, func(input *capturedInput, value Supplied[string]) { input.name = value })
+	copied := original
+	captured := CaptureFlags([]Flag[capturedInput]{original}, func(input *capturedOuter) *FlagValues[capturedInput] { return &input.flags })
+	prepared, err := captured[0].binding.prepare([]string{"chosen"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	outer := capturedOuter{}
+	prepared.apply(&outer)
+	var target capturedInput
+	if err := outer.flags.ApplyTo(&target, copied); err != nil {
+		t.Fatal(err)
+	}
+	if target.name.Value != "chosen" || !target.name.Set || parseCalls != 1 {
+		t.Fatalf("target=%#v parse calls=%d", target, parseCalls)
+	}
+	lookalike := ValueFlag(FlagMeta{Name: "name"}, nil, func(value string) (string, error) { return value, nil }, func(*capturedInput, Supplied[string]) {})
+	if err := outer.flags.ApplyTo(&target, lookalike); !errors.Is(err, ErrFlagWiring) {
+		t.Fatalf("lookalike binding error = %v", err)
+	}
+	if err := outer.flags.ApplyTo(nil, copied); !errors.Is(err, ErrFlagWiring) {
+		t.Fatalf("nil target error = %v", err)
+	}
+	if err := (FlagValues[capturedInput]{}).ApplyTo(&target); err != nil {
+		t.Fatalf("empty selection from zero store: %v", err)
+	}
+}
+
+func TestCaptureFlagsDefersRequiredCheckToSelectedBindings(t *testing.T) {
+	required := ValueFlag(FlagMeta{Name: "name", Required: true}, strptr("default"), func(value string) (string, error) { return value, nil }, func(input *capturedInput, value Supplied[string]) { input.name = value })
+	captured := CaptureFlags([]Flag[capturedInput]{required}, func(input *capturedOuter) *FlagValues[capturedInput] { return &input.flags })
+	prepared, err := captured[0].binding.prepare(nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	outer := capturedOuter{}
+	prepared.apply(&outer)
+	var target capturedInput
+	if err := outer.flags.ApplyTo(&target); err != nil {
+		t.Fatalf("unselected required flag failed: %v", err)
+	}
+	if err := outer.flags.ApplyTo(&target, required); !errors.Is(err, ErrFlagInput) {
+		t.Fatalf("selected missing required flag error = %v", err)
+	}
+	optional := ValueFlag(FlagMeta{Name: "name"}, strptr("default"), func(value string) (string, error) { return value, nil }, func(input *capturedInput, value Supplied[string]) { input.name = value })
+	optionalCapture := CaptureFlags([]Flag[capturedInput]{optional}, func(input *capturedOuter) *FlagValues[capturedInput] { return &input.flags })
+	optionalPrepared, err := optionalCapture[0].binding.prepare(nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	outer = capturedOuter{}
+	optionalPrepared.apply(&outer)
+	target = capturedInput{}
+	if err := outer.flags.ApplyTo(&target, optional); err != nil {
+		t.Fatal(err)
+	}
+	if target.name.Value != "default" || target.name.Set {
+		t.Fatalf("captured default value = %#v", target.name)
+	}
+
+	badCapture := CaptureFlags[capturedOuter]([]Flag[capturedInput]{required}, nil)
+	command := NewCommand(CommandSpec[capturedOuter]{Name: "broken", Flags: badCapture})
+	if _, err := New(Identity{Name: "example"}, command); err == nil {
+		t.Fatal("installation accepted a nil captured-flag accessor")
+	}
+}
+
+func TestCaptureFlagsCopiesRepeatedValuesOnEachApplication(t *testing.T) {
+	original := RepeatFlag(FlagMeta{Name: "tag"}, nil, func(value string) (string, error) { return value, nil }, func(input *capturedInput, value Supplied[[]string]) { input.tags = value })
+	captured := CaptureFlags([]Flag[capturedInput]{original}, func(input *capturedOuter) *FlagValues[capturedInput] { return &input.flags })
+	prepared, err := captured[0].binding.prepare([]string{"a,b", "c"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	outer := capturedOuter{}
+	prepared.apply(&outer)
+	var first, second capturedInput
+	if err := outer.flags.ApplyTo(&first, original); err != nil {
+		t.Fatal(err)
+	}
+	if err := outer.flags.ApplyTo(&second, original); err != nil {
+		t.Fatal(err)
+	}
+	first.tags.Value[0] = "changed"
+	if second.tags.Value[0] != "a,b" || second.tags.Value[1] != "c" || !second.tags.Set {
+		t.Fatalf("second application shares repeat storage: %#v", second.tags)
+	}
+}
+
+func TestCapturedFlagErrorClassificationPreservesWrappedCategories(t *testing.T) {
+	if got := classifyInputError(fmt.Errorf("scope input: %w", ErrFlagWiring)); got.Kind != OutcomeOperational {
+		t.Fatalf("wiring outcome = %#v", got)
+	}
+	if got := classifyInputError(fmt.Errorf("scope input: %w", ErrFlagInput)); got.Kind != OutcomeUsage {
+		t.Fatalf("input outcome = %#v", got)
+	}
+}
+
+func TestCheckInputClassifiesWrappedFlagWiringAsOperational(t *testing.T) {
+	command := NewCommand(CommandSpec[struct{}]{
+		Name:       "run",
+		CheckInput: func(struct{}) error { return fmt.Errorf("scope selector: %w", ErrFlagWiring) },
+		Run:        func(Invocation, struct{}) Outcome { t.Fatal("run called after wiring error"); return Success() },
+	})
+	app, err := New(Identity{Name: "example"}, command)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if outcome := app.Execute(t.Context(), []string{"run"}, Streams{}); outcome.Kind != OutcomeOperational || !errors.Is(outcome.Cause, ErrFlagWiring) {
+		t.Fatalf("wrapped wiring outcome = %#v", outcome)
+	}
+	usage := NewCommand(CommandSpec[struct{}]{Name: "usage", CheckInput: func(struct{}) error { return fmt.Errorf("selected value: %w", ErrFlagInput) }, Run: func(Invocation, struct{}) Outcome { return Success() }})
+	app, err = New(Identity{Name: "example"}, usage)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if outcome := app.Execute(t.Context(), []string{"usage"}, Streams{}); outcome.Kind != OutcomeUsage || !errors.Is(outcome.Cause, ErrFlagInput) {
+		t.Fatalf("wrapped input outcome = %#v", outcome)
+	}
+}
+
+func strptr(value string) *string { return &value }

go.mod

@@ -1,24 +1,18 @@
-module gitea.maximumdirect.net/eric/CommandKit
+module go.maximumdirect.net/commandkit
 
 go 1.26.0
 
 require (
-	gitea.maximumdirect.net/eric/ConfigKit v0.5.0
-	gitea.maximumdirect.net/eric/promptkit v0.12.0
 	github.com/spf13/cobra v1.10.1
 	github.com/spf13/pflag v1.0.9
 	go.yaml.in/yaml/v4 v4.0.0-rc.6
 )
 
 require (
-	gitea.maximumdirect.net/eric/ReleaseKit v0.3.0 // indirect
-	gitea.maximumdirect.net/eric/promptkit-backend-openrouter/v3 v3.20260930.0 // indirect
-	gitea.maximumdirect.net/eric/promptkit-backend-rakestrawhome/v3 v3.20260930.0 // indirect
 	github.com/inconshreveable/mousetrap v1.1.0 // indirect
-	github.com/santhosh-tekuri/jsonschema/v6 v6.0.2 // indirect
 	github.com/yuin/goldmark/v2 v2.1.6 // indirect
+	go.maximumdirect.net/releasekit v0.9.0 // indirect
 	golang.org/x/mod v0.40.0 // indirect
-	golang.org/x/text v0.14.0 // indirect
 )
 
-tool gitea.maximumdirect.net/eric/ReleaseKit/cmd/releasekit
+tool go.maximumdirect.net/releasekit/cmd/releasekit

go.sum

@@ -1,33 +1,18 @@
-gitea.maximumdirect.net/eric/ConfigKit v0.5.0 h1:2KwG10+kApWM3avOoYA+p768xcbHUp7tQ2rqizBNpyg=
-gitea.maximumdirect.net/eric/ConfigKit v0.5.0/go.mod h1:tYWpsrbLyu05r8+1MapWp5fN6ZrX9I8hU2xEPedYmYk=
-gitea.maximumdirect.net/eric/ReleaseKit v0.3.0 h1:aTMn+50MEpHpHI2RoCCmJYsy7Ohrpa+RSva63Kq0/tU=
-gitea.maximumdirect.net/eric/ReleaseKit v0.3.0/go.mod h1:LVodqNQ3OIKv9NBq+fFeyMByd1lHY25YOmmpah/NaNI=
-gitea.maximumdirect.net/eric/promptkit v0.12.0 h1:oIFWEg6GPxtmX3Plqv0euP+FnK1LCk/t4xDy6oKCpP4=
-gitea.maximumdirect.net/eric/promptkit v0.12.0/go.mod h1:pFOOy5v1zH17stEi9rmHYmfbuLjnfVMcUhfmk+4VtJY=
-gitea.maximumdirect.net/eric/promptkit-backend-openrouter/v3 v3.20260930.0 h1:lzfCDbzJQRGzIlRPRprnAV9hVVL5zUQy80VMQ0kbYa0=
-gitea.maximumdirect.net/eric/promptkit-backend-openrouter/v3 v3.20260930.0/go.mod h1:HjS0f+3q0IdHCTEz+VVAEgIwIWJFAZUjuKdAtvtqKdg=
-gitea.maximumdirect.net/eric/promptkit-backend-rakestrawhome/v3 v3.20260930.0 h1:h12ZTRldAmpLAomj0oQRGteFxHLN1LPE6XDl9zJNbm8=
-gitea.maximumdirect.net/eric/promptkit-backend-rakestrawhome/v3 v3.20260930.0/go.mod h1:OEFBeKdjTsLzqJwLmXI2O5gG3r64FktcVJVb3mBrRfg=
 github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g=
-github.com/dlclark/regexp2 v1.11.0 h1:G/nrcoOa7ZXlpoa/91N3X7mM3r8eIlMBBJZvsz/mxKI=
-github.com/dlclark/regexp2 v1.11.0/go.mod h1:DHkYz0B9wPfa6wondMfaivmHpzrQ3v9q8cnmRbL6yW8=
 github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8=
 github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw=
 github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
-github.com/santhosh-tekuri/jsonschema/v6 v6.0.2 h1:KRzFb2m7YtdldCEkzs6KqmJw4nqEVZGK7IN2kJkjTuQ=
-github.com/santhosh-tekuri/jsonschema/v6 v6.0.2/go.mod h1:JXeL+ps8p7/KNMjDQk3TCwPpBy0wYklyWTfbkIzdIFU=
 github.com/spf13/cobra v1.10.1 h1:lJeBwCfmrnXthfAupyUTzJ/J4Nc1RsHC/mSRU2dll/s=
 github.com/spf13/cobra v1.10.1/go.mod h1:7SmJGaTHFVBY0jW4NXGluQoLvhqFQM+6XSKD+P4XaB0=
 github.com/spf13/pflag v1.0.9 h1:9exaQaMOCwffKiiiYk6/BndUBv+iRViNW+4lEMi0PvY=
 github.com/spf13/pflag v1.0.9/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
 github.com/yuin/goldmark/v2 v2.1.6 h1:igy0q9JcqovoFXFx/XjtU8sHVhcUHavPj2sA3EoKJUE=
 github.com/yuin/goldmark/v2 v2.1.6/go.mod h1:G6M4/qOFtfn01/o14BU1UR2Lo5N3S9Qo7xCuz/sHjGQ=
+go.maximumdirect.net/releasekit v0.9.0 h1:sK+Aoj6gS6ATU/1reocjwBekp4YETYENwkcX5ti6mrE=
+go.maximumdirect.net/releasekit v0.9.0/go.mod h1:QE4BLrAhVJTzi+/YTcVl21K/qZp9ojRLg5kuoy3Zb44=
 go.yaml.in/yaml/v4 v4.0.0-rc.6 h1:1h7H1ohdUh93/FyE4YaDa1Zh64K6VVbjF4K6WUxMtH4=
 go.yaml.in/yaml/v4 v4.0.0-rc.6/go.mod h1:aZqd9kCMsGL7AuUv/m/PvWLdg5sjJsZ4oHDEnfPPfY0=
 golang.org/x/mod v0.40.0 h1:hUv+3cXcdRHz08UmSiOob7sadHig73uo5bkXxQ/tvUs=
 golang.org/x/mod v0.40.0/go.mod h1:0/weTWkPWGBikyTWAX3dkjVztMmBA5hM0DH6BElSupE=
-golang.org/x/text v0.14.0 h1:ScX5w1eTa3QqT8oi6+ziP7dTV1S2+ALU0bI+0zXKWiQ=
-golang.org/x/text v0.14.0/go.mod h1:18ZOQIKpY8NJVqYksKHtTdi31H5itFRjB5/qKTNYzSU=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
-gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

help_view.go

@@ -0,0 +1,63 @@
+package commandkit
+
+import (
+	"sort"
+
+	commandmeta "go.maximumdirect.net/commandkit/internal/commandmeta"
+	"go.maximumdirect.net/commandkit/internal/commandpath"
+)
+
+func (a *App) helpView(route routeResult, snapshot *routingSnapshot) commandmeta.HelpView {
+	view := commandmeta.HelpView{
+		EnteredPath:   clonePath(route.enteredPath),
+		CanonicalPath: clonePath(route.canonicalPath),
+		Discovery:     route.kind == routeDiscovery,
+		CoreFlags:     commandmeta.ReportingFlags(),
+	}
+	if snapshot == nil {
+		return view
+	}
+	view.CommandAliases = routeHelpAliases(snapshot, route)
+	if view.Discovery {
+		view.FlagAliases = snapshot.discoveryFlags[route.discoveryPath.Key()].neutralRecords()
+		return view
+	}
+	view.FlagAliases = snapshot.flagAliases[route.canonicalPath.Key()].neutralRecords()
+	return view
+}
+
+func clonePath(path commandpath.Path) []string {
+	return append([]string(nil), path...)
+}
+
+func routeHelpAliases(snapshot *routingSnapshot, route routeResult) []commandmeta.CommandAlias {
+	if route.kind != routeDiscovery && len(route.canonicalPath) == 0 {
+		return append([]commandmeta.CommandAlias(nil), snapshot.commandAliases...)
+	}
+	bySource := make(map[string]commandmeta.CommandAlias)
+	for _, prefix := range snapshot.aliases.ResolutionPaths(route.enteredPath) {
+		for _, alias := range snapshot.commandAliases {
+			source := commandpath.FromTokens(alias.Source)
+			if len(source) <= len(prefix) || !source.HasPrefix(prefix) {
+				continue
+			}
+			suffix := source[len(prefix):]
+			entered := append(route.enteredPath.Clone(), suffix...)
+			target := snapshot.aliases.Resolve(entered)
+			if traceCanonicalPath(snapshot.canonical, target).exact == nil {
+				continue
+			}
+			bySource[suffix.Key()] = commandmeta.CommandAlias{Source: clonePath(suffix), Target: clonePath(target)}
+		}
+	}
+	keys := make([]string, 0, len(bySource))
+	for key := range bySource {
+		keys = append(keys, key)
+	}
+	sort.Strings(keys)
+	result := make([]commandmeta.CommandAlias, 0, len(keys))
+	for _, key := range keys {
+		result = append(result, bySource[key])
+	}
+	return result
+}

identity.go

@@ -18,8 +18,11 @@ type Identity struct {
 	Revision string
 }
 
-// Streams contains the output destinations associated with a command
-// invocation.
+// Streams contains the caller-owned output destinations associated with an
+// invocation. Out receives substantive results; Err receives messages,
+// terminal explanations, usage guidance, and CommandKit diagnostics. Nil
+// destinations are replaced with io.Discard. CommandKit does not close or flush
+// supplied writers.
 type Streams struct {
 	// Out receives help and command reports.
 	Out io.Writer
@@ -27,11 +30,41 @@ type Streams struct {
 	Err io.Writer
 }
 
-// Invocation provides execution context and output streams to a command
-// handler.
+func normalizeStreams(streams Streams) Streams {
+	if streams.Out == nil {
+		streams.Out = io.Discard
+	}
+	if streams.Err == nil {
+		streams.Err = io.Discard
+	}
+	return streams
+}
+
+// Invocation provides execution context and invocation-scoped reporting to a
+// command handler. Execute finalizes its reporter before returning. For command
+// aliases, EnteredPath and CanonicalPath expose the route the caller used and
+// the selected canonical command path. Both omit the executable name, flags,
+// and operands.
 type Invocation struct {
 	// Context carries caller cancellation and request-scoped values.
 	Context context.Context
-	// Streams are the caller-selected output destinations.
-	Streams Streams
+
+	reporter      *Reporter
+	enteredPath   string
+	canonicalPath string
 }
+
+// Reporter returns the reporting facility supplied for this invocation. A
+// manually constructed Invocation has no reporter.
+func (inv Invocation) Reporter() *Reporter { return inv.reporter }
+
+// EnteredPath returns the command path used to invoke the selected command,
+// excluding the executable name, flags, and operands. It is empty for an
+// Invocation that was not created by command execution.
+func (inv Invocation) EnteredPath() string { return inv.enteredPath }
+
+// CanonicalPath returns the selected command's canonical path after resolving
+// aliases, excluding the executable name, flags, and operands. It equals
+// EnteredPath for a direct canonical invocation and is empty for an Invocation
+// that was not created by command execution.
+func (inv Invocation) CanonicalPath() string { return inv.canonicalPath }

integrations/ckconfig/COPYRIGHT

@@ -0,0 +1,20 @@
+CommandKit ckconfig
+
+Copyright (C) 2026 Eric Rakestraw
+
+SPDX-License-Identifier: LGPL-3.0-or-later
+
+This library is free software: you can redistribute it and/or modify it
+under the terms of the GNU Lesser General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+The GNU Lesser General Public License version 3 and its incorporated
+GNU General Public License version 3 text are provided in LICENSE.
+
+This library is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU Lesser General Public License for more details.
+
+Third-party code and assets are subject to their respective license terms.

integrations/ckconfig/LICENSE

@@ -0,0 +1,304 @@
+GNU LESSER GENERAL PUBLIC LICENSE
+Version 3, 29 June 2007
+
+Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
+
+Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.
+
+This version of the GNU Lesser General Public License incorporates the terms and conditions of version 3 of the GNU General Public License, supplemented by the additional permissions listed below.
+
+0. Additional Definitions.
+
+As used herein, "this License" refers to version 3 of the GNU Lesser General Public License, and the "GNU GPL" refers to version 3 of the GNU General Public License.
+
+"The Library" refers to a covered work governed by this License, other than an Application or a Combined Work as defined below.
+
+An "Application" is any work that makes use of an interface provided by the Library, but which is not otherwise based on the Library. Defining a subclass of a class defined by the Library is deemed a mode of using an interface provided by the Library.
+
+A "Combined Work" is a work produced by combining or linking an Application with the Library.  The particular version of the Library with which the Combined Work was made is also called the "Linked Version".
+
+The "Minimal Corresponding Source" for a Combined Work means the Corresponding Source for the Combined Work, excluding any source code for portions of the Combined Work that, considered in isolation, are based on the Application, and not on the Linked Version.
+
+The "Corresponding Application Code" for a Combined Work means the object code and/or source code for the Application, including any data and utility programs needed for reproducing the Combined Work from the Application, but excluding the System Libraries of the Combined Work.
+
+1. Exception to Section 3 of the GNU GPL.
+You may convey a covered work under sections 3 and 4 of this License without being bound by section 3 of the GNU GPL.
+
+2. Conveying Modified Versions.
+If you modify a copy of the Library, and, in your modifications, a facility refers to a function or data to be supplied by an Application that uses the facility (other than as an argument passed when the facility is invoked), then you may convey a copy of the modified version:
+
+     a) under this License, provided that you make a good faith effort to ensure that, in the event an Application does not supply the function or data, the facility still operates, and performs whatever part of its purpose remains meaningful, or
+
+     b) under the GNU GPL, with none of the additional permissions of this License applicable to that copy.
+
+3. Object Code Incorporating Material from Library Header Files.
+The object code form of an Application may incorporate material from a header file that is part of the Library.  You may convey such object code under terms of your choice, provided that, if the incorporated material is not limited to numerical parameters, data structure layouts and accessors, or small macros, inline functions and templates (ten or fewer lines in length), you do both of the following:
+
+     a) Give prominent notice with each copy of the object code that the Library is used in it and that the Library and its use are covered by this License.
+
+     b) Accompany the object code with a copy of the GNU GPL and this license document.
+
+4. Combined Works.
+You may convey a Combined Work under terms of your choice that, taken together, effectively do not restrict modification of the portions of the Library contained in the Combined Work and reverse engineering for debugging such modifications, if you also do each of the following:
+
+     a) Give prominent notice with each copy of the Combined Work that the Library is used in it and that the Library and its use are covered by this License.
+
+     b) Accompany the Combined Work with a copy of the GNU GPL and this license document.
+
+     c) For a Combined Work that displays copyright notices during execution, include the copyright notice for the Library among these notices, as well as a reference directing the user to the copies of the GNU GPL and this license document.
+
+     d) Do one of the following:
+
+           0) Convey the Minimal Corresponding Source under the terms of this License, and the Corresponding Application Code in a form suitable for, and under terms that permit, the user to recombine or relink the Application with a modified version of the Linked Version to produce a modified Combined Work, in the manner specified by section 6 of the GNU GPL for conveying Corresponding Source.
+
+          1) Use a suitable shared library mechanism for linking with the Library.  A suitable mechanism is one that (a) uses at run time a copy of the Library already present on the user's computer system, and (b) will operate properly with a modified version of the Library that is interface-compatible with the Linked Version.
+
+     e) Provide Installation Information, but only if you would otherwise be required to provide such information under section 6 of the GNU GPL, and only to the extent that such information is necessary to install and execute a modified version of the Combined Work produced by recombining or relinking the Application with a modified version of the Linked Version. (If you use option 4d0, the Installation Information must accompany the Minimal Corresponding Source and Corresponding Application Code. If you use option 4d1, you must provide the Installation Information in the manner specified by section 6 of the GNU GPL for conveying Corresponding Source.)
+
+5. Combined Libraries.
+You may place library facilities that are a work based on the Library side by side in a single library together with other library facilities that are not Applications and are not covered by this License, and convey such a combined library under terms of your choice, if you do both of the following:
+
+     a) Accompany the combined library with a copy of the same work based on the Library, uncombined with any other library facilities, conveyed under the terms of this License.
+
+     b) Give prominent notice with the combined library that part of it is a work based on the Library, and explaining where to find the accompanying uncombined form of the same work.
+
+6. Revised Versions of the GNU Lesser General Public License.
+The Free Software Foundation may publish revised and/or new versions of the GNU Lesser General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns.
+
+Each version is given a distinguishing version number. If the Library as you received it specifies that a certain numbered version of the GNU Lesser General Public License "or any later version" applies to it, you have the option of following the terms and conditions either of that published version or of any later version published by the Free Software Foundation. If the Library as you received it does not specify a version number of the GNU Lesser General Public License, you may choose any version of the GNU Lesser General Public License ever published by the Free Software Foundation.
+
+If the Library as you received it specifies that a proxy can decide whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is permanent authorization for you to choose that version for the Library.
+
+GNU GENERAL PUBLIC LICENSE
+Version 3, 29 June 2007
+
+Copyright © 2007 Free Software Foundation, Inc. <http://fsf.org/>
+
+Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.
+
+Preamble
+
+The GNU General Public License is a free, copyleft license for software and other kinds of works.
+
+The licenses for most software and other practical works are designed to take away your freedom to share and change the works. By contrast, the GNU General Public License is intended to guarantee your freedom to share and change all versions of a program--to make sure it remains free software for all its users. We, the Free Software Foundation, use the GNU General Public License for most of our software; it applies also to any other work released this way by its authors. You can apply it to your programs, too.
+
+When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for them if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs, and that you know you can do these things.
+
+To protect your rights, we need to prevent others from denying you these rights or asking you to surrender the rights. Therefore, you have certain responsibilities if you distribute copies of the software, or if you modify it: responsibilities to respect the freedom of others.
+
+For example, if you distribute copies of such a program, whether gratis or for a fee, you must pass on to the recipients the same freedoms that you received. You must make sure that they, too, receive or can get the source code. And you must show them these terms so they know their rights.
+
+Developers that use the GNU GPL protect your rights with two steps: (1) assert copyright on the software, and (2) offer you this License giving you legal permission to copy, distribute and/or modify it.
+
+For the developers' and authors' protection, the GPL clearly explains that there is no warranty for this free software. For both users' and authors' sake, the GPL requires that modified versions be marked as changed, so that their problems will not be attributed erroneously to authors of previous versions.
+
+Some devices are designed to deny users access to install or run modified versions of the software inside them, although the manufacturer can do so. This is fundamentally incompatible with the aim of protecting users' freedom to change the software. The systematic pattern of such abuse occurs in the area of products for individuals to use, which is precisely where it is most unacceptable. Therefore, we have designed this version of the GPL to prohibit the practice for those products. If such problems arise substantially in other domains, we stand ready to extend this provision to those domains in future versions of the GPL, as needed to protect the freedom of users.
+
+Finally, every program is threatened constantly by software patents. States should not allow patents to restrict development and use of software on general-purpose computers, but in those that do, we wish to avoid the special danger that patents applied to a free program could make it effectively proprietary. To prevent this, the GPL assures that patents cannot be used to render the program non-free.
+
+The precise terms and conditions for copying, distribution and modification follow.
+
+TERMS AND CONDITIONS
+
+0. Definitions.
+
+“This License” refers to version 3 of the GNU General Public License.
+
+“Copyright” also means copyright-like laws that apply to other kinds of works, such as semiconductor masks.
+
+“The Program” refers to any copyrightable work licensed under this License. Each licensee is addressed as “you”. “Licensees” and “recipients” may be individuals or organizations.
+
+To “modify” a work means to copy from or adapt all or part of the work in a fashion requiring copyright permission, other than the making of an exact copy. The resulting work is called a “modified version” of the earlier work or a work “based on” the earlier work.
+
+A “covered work” means either the unmodified Program or a work based on the Program.
+
+To “propagate” a work means to do anything with it that, without permission, would make you directly or secondarily liable for infringement under applicable copyright law, except executing it on a computer or modifying a private copy. Propagation includes copying, distribution (with or without modification), making available to the public, and in some countries other activities as well.
+
+To “convey” a work means any kind of propagation that enables other parties to make or receive copies. Mere interaction with a user through a computer network, with no transfer of a copy, is not conveying.
+
+An interactive user interface displays “Appropriate Legal Notices” to the extent that it includes a convenient and prominently visible feature that (1) displays an appropriate copyright notice, and (2) tells the user that there is no warranty for the work (except to the extent that warranties are provided), that licensees may convey the work under this License, and how to view a copy of this License. If the interface presents a list of user commands or options, such as a menu, a prominent item in the list meets this criterion.
+
+1. Source Code.
+The “source code” for a work means the preferred form of the work for making modifications to it. “Object code” means any non-source form of a work.
+
+A “Standard Interface” means an interface that either is an official standard defined by a recognized standards body, or, in the case of interfaces specified for a particular programming language, one that is widely used among developers working in that language.
+
+The “System Libraries” of an executable work include anything, other than the work as a whole, that (a) is included in the normal form of packaging a Major Component, but which is not part of that Major Component, and (b) serves only to enable use of the work with that Major Component, or to implement a Standard Interface for which an implementation is available to the public in source code form. A “Major Component”, in this context, means a major essential component (kernel, window system, and so on) of the specific operating system (if any) on which the executable work runs, or a compiler used to produce the work, or an object code interpreter used to run it.
+
+The “Corresponding Source” for a work in object code form means all the source code needed to generate, install, and (for an executable work) run the object code and to modify the work, including scripts to control those activities. However, it does not include the work's System Libraries, or general-purpose tools or generally available free programs which are used unmodified in performing those activities but which are not part of the work. For example, Corresponding Source includes interface definition files associated with source files for the work, and the source code for shared libraries and dynamically linked subprograms that the work is specifically designed to require, such as by intimate data communication or control flow between those subprograms and other parts of the work.
+
+The Corresponding Source need not include anything that users can regenerate automatically from other parts of the Corresponding Source.
+
+The Corresponding Source for a work in source code form is that same work.
+
+2. Basic Permissions.
+All rights granted under this License are granted for the term of copyright on the Program, and are irrevocable provided the stated conditions are met. This License explicitly affirms your unlimited permission to run the unmodified Program. The output from running a covered work is covered by this License only if the output, given its content, constitutes a covered work. This License acknowledges your rights of fair use or other equivalent, as provided by copyright law.
+
+You may make, run and propagate covered works that you do not convey, without conditions so long as your license otherwise remains in force. You may convey covered works to others for the sole purpose of having them make modifications exclusively for you, or provide you with facilities for running those works, provided that you comply with the terms of this License in conveying all material for which you do not control copyright. Those thus making or running the covered works for you must do so exclusively on your behalf, under your direction and control, on terms that prohibit them from making any copies of your copyrighted material outside their relationship with you.
+
+Conveying under any other circumstances is permitted solely under the conditions stated below. Sublicensing is not allowed; section 10 makes it unnecessary.
+
+3. Protecting Users' Legal Rights From Anti-Circumvention Law.
+No covered work shall be deemed part of an effective technological measure under any applicable law fulfilling obligations under article 11 of the WIPO copyright treaty adopted on 20 December 1996, or similar laws prohibiting or restricting circumvention of such measures.
+
+When you convey a covered work, you waive any legal power to forbid circumvention of technological measures to the extent such circumvention is effected by exercising rights under this License with respect to the covered work, and you disclaim any intention to limit operation or modification of the work as a means of enforcing, against the work's users, your or third parties' legal rights to forbid circumvention of technological measures.
+
+4. Conveying Verbatim Copies.
+You may convey verbatim copies of the Program's source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice; keep intact all notices stating that this License and any non-permissive terms added in accord with section 7 apply to the code; keep intact all notices of the absence of any warranty; and give all recipients a copy of this License along with the Program.
+
+You may charge any price or no price for each copy that you convey, and you may offer support or warranty protection for a fee.
+
+5. Conveying Modified Source Versions.
+You may convey a work based on the Program, or the modifications to produce it from the Program, in the form of source code under the terms of section 4, provided that you also meet all of these conditions:
+
+     a) The work must carry prominent notices stating that you modified it, and giving a relevant date.
+
+     b) The work must carry prominent notices stating that it is released under this License and any conditions added under section 7. This requirement modifies the requirement in section 4 to “keep intact all notices”.
+
+     c) You must license the entire work, as a whole, under this License to anyone who comes into possession of a copy. This License will therefore apply, along with any applicable section 7 additional terms, to the whole of the work, and all its parts, regardless of how they are packaged. This License gives no permission to license the work in any other way, but it does not invalidate such permission if you have separately received it.
+
+     d) If the work has interactive user interfaces, each must display Appropriate Legal Notices; however, if the Program has interactive interfaces that do not display Appropriate Legal Notices, your work need not make them do so.
+
+A compilation of a covered work with other separate and independent works, which are not by their nature extensions of the covered work, and which are not combined with it such as to form a larger program, in or on a volume of a storage or distribution medium, is called an “aggregate” if the compilation and its resulting copyright are not used to limit the access or legal rights of the compilation's users beyond what the individual works permit. Inclusion of a covered work in an aggregate does not cause this License to apply to the other parts of the aggregate.
+
+6. Conveying Non-Source Forms.
+You may convey a covered work in object code form under the terms of sections 4 and 5, provided that you also convey the machine-readable Corresponding Source under the terms of this License, in one of these ways:
+
+     a) Convey the object code in, or embodied in, a physical product (including a physical distribution medium), accompanied by the Corresponding Source fixed on a durable physical medium customarily used for software interchange.
+
+     b) Convey the object code in, or embodied in, a physical product (including a physical distribution medium), accompanied by a written offer, valid for at least three years and valid for as long as you offer spare parts or customer support for that product model, to give anyone who possesses the object code either (1) a copy of the Corresponding Source for all the software in the product that is covered by this License, on a durable physical medium customarily used for software interchange, for a price no more than your reasonable cost of physically performing this conveying of source, or (2) access to copy the Corresponding Source from a network server at no charge.
+
+     c) Convey individual copies of the object code with a copy of the written offer to provide the Corresponding Source. This alternative is allowed only occasionally and noncommercially, and only if you received the object code with such an offer, in accord with subsection 6b.
+
+     d) Convey the object code by offering access from a designated place (gratis or for a charge), and offer equivalent access to the Corresponding Source in the same way through the same place at no further charge. You need not require recipients to copy the Corresponding Source along with the object code. If the place to copy the object code is a network server, the Corresponding Source may be on a different server (operated by you or a third party) that supports equivalent copying facilities, provided you maintain clear directions next to the object code saying where to find the Corresponding Source. Regardless of what server hosts the Corresponding Source, you remain obligated to ensure that it is available for as long as needed to satisfy these requirements.
+
+     e) Convey the object code using peer-to-peer transmission, provided you inform other peers where the object code and Corresponding Source of the work are being offered to the general public at no charge under subsection 6d.
+
+A separable portion of the object code, whose source code is excluded from the Corresponding Source as a System Library, need not be included in conveying the object code work.
+
+A “User Product” is either (1) a “consumer product”, which means any tangible personal property which is normally used for personal, family, or household purposes, or (2) anything designed or sold for incorporation into a dwelling. In determining whether a product is a consumer product, doubtful cases shall be resolved in favor of coverage. For a particular product received by a particular user, “normally used” refers to a typical or common use of that class of product, regardless of the status of the particular user or of the way in which the particular user actually uses, or expects or is expected to use, the product. A product is a consumer product regardless of whether the product has substantial commercial, industrial or non-consumer uses, unless such uses represent the only significant mode of use of the product.
+
+“Installation Information” for a User Product means any methods, procedures, authorization keys, or other information required to install and execute modified versions of a covered work in that User Product from a modified version of its Corresponding Source. The information must suffice to ensure that the continued functioning of the modified object code is in no case prevented or interfered with solely because modification has been made.
+
+If you convey an object code work under this section in, or with, or specifically for use in, a User Product, and the conveying occurs as part of a transaction in which the right of possession and use of the User Product is transferred to the recipient in perpetuity or for a fixed term (regardless of how the transaction is characterized), the Corresponding Source conveyed under this section must be accompanied by the Installation Information. But this requirement does not apply if neither you nor any third party retains the ability to install modified object code on the User Product (for example, the work has been installed in ROM).
+
+The requirement to provide Installation Information does not include a requirement to continue to provide support service, warranty, or updates for a work that has been modified or installed by the recipient, or for the User Product in which it has been modified or installed. Access to a network may be denied when the modification itself materially and adversely affects the operation of the network or violates the rules and protocols for communication across the network.
+
+Corresponding Source conveyed, and Installation Information provided, in accord with this section must be in a format that is publicly documented (and with an implementation available to the public in source code form), and must require no special password or key for unpacking, reading or copying.
+
+7. Additional Terms.
+“Additional permissions” are terms that supplement the terms of this License by making exceptions from one or more of its conditions. Additional permissions that are applicable to the entire Program shall be treated as though they were included in this License, to the extent that they are valid under applicable law. If additional permissions apply only to part of the Program, that part may be used separately under those permissions, but the entire Program remains governed by this License without regard to the additional permissions.
+
+When you convey a copy of a covered work, you may at your option remove any additional permissions from that copy, or from any part of it. (Additional permissions may be written to require their own removal in certain cases when you modify the work.) You may place additional permissions on material, added by you to a covered work, for which you have or can give appropriate copyright permission.
+
+Notwithstanding any other provision of this License, for material you add to a covered work, you may (if authorized by the copyright holders of that material) supplement the terms of this License with terms:
+
+     a) Disclaiming warranty or limiting liability differently from the terms of sections 15 and 16 of this License; or
+
+     b) Requiring preservation of specified reasonable legal notices or author attributions in that material or in the Appropriate Legal Notices displayed by works containing it; or
+
+     c) Prohibiting misrepresentation of the origin of that material, or requiring that modified versions of such material be marked in reasonable ways as different from the original version; or
+
+     d) Limiting the use for publicity purposes of names of licensors or authors of the material; or
+
+     e) Declining to grant rights under trademark law for use of some trade names, trademarks, or service marks; or
+
+     f) Requiring indemnification of licensors and authors of that material by anyone who conveys the material (or modified versions of it) with contractual assumptions of liability to the recipient, for any liability that these contractual assumptions directly impose on those licensors and authors.
+
+All other non-permissive additional terms are considered “further restrictions” within the meaning of section 10. If the Program as you received it, or any part of it, contains a notice stating that it is governed by this License along with a term that is a further restriction, you may remove that term. If a license document contains a further restriction but permits relicensing or conveying under this License, you may add to a covered work material governed by the terms of that license document, provided that the further restriction does not survive such relicensing or conveying.
+
+If you add terms to a covered work in accord with this section, you must place, in the relevant source files, a statement of the additional terms that apply to those files, or a notice indicating where to find the applicable terms.
+
+Additional terms, permissive or non-permissive, may be stated in the form of a separately written license, or stated as exceptions; the above requirements apply either way.
+
+8. Termination.
+You may not propagate or modify a covered work except as expressly provided under this License. Any attempt otherwise to propagate or modify it is void, and will automatically terminate your rights under this License (including any patent licenses granted under the third paragraph of section 11).
+
+However, if you cease all violation of this License, then your license from a particular copyright holder is reinstated (a) provisionally, unless and until the copyright holder explicitly and finally terminates your license, and (b) permanently, if the copyright holder fails to notify you of the violation by some reasonable means prior to 60 days after the cessation.
+
+Moreover, your license from a particular copyright holder is reinstated permanently if the copyright holder notifies you of the violation by some reasonable means, this is the first time you have received notice of violation of this License (for any work) from that copyright holder, and you cure the violation prior to 30 days after your receipt of the notice.
+
+Termination of your rights under this section does not terminate the licenses of parties who have received copies or rights from you under this License. If your rights have been terminated and not permanently reinstated, you do not qualify to receive new licenses for the same material under section 10.
+
+9. Acceptance Not Required for Having Copies.
+You are not required to accept this License in order to receive or run a copy of the Program. Ancillary propagation of a covered work occurring solely as a consequence of using peer-to-peer transmission to receive a copy likewise does not require acceptance. However, nothing other than this License grants you permission to propagate or modify any covered work. These actions infringe copyright if you do not accept this License. Therefore, by modifying or propagating a covered work, you indicate your acceptance of this License to do so.
+
+10. Automatic Licensing of Downstream Recipients.
+Each time you convey a covered work, the recipient automatically receives a license from the original licensors, to run, modify and propagate that work, subject to this License. You are not responsible for enforcing compliance by third parties with this License.
+
+An “entity transaction” is a transaction transferring control of an organization, or substantially all assets of one, or subdividing an organization, or merging organizations. If propagation of a covered work results from an entity transaction, each party to that transaction who receives a copy of the work also receives whatever licenses to the work the party's predecessor in interest had or could give under the previous paragraph, plus a right to possession of the Corresponding Source of the work from the predecessor in interest, if the predecessor has it or can get it with reasonable efforts.
+
+You may not impose any further restrictions on the exercise of the rights granted or affirmed under this License. For example, you may not impose a license fee, royalty, or other charge for exercise of rights granted under this License, and you may not initiate litigation (including a cross-claim or counterclaim in a lawsuit) alleging that any patent claim is infringed by making, using, selling, offering for sale, or importing the Program or any portion of it.
+
+11. Patents.
+A “contributor” is a copyright holder who authorizes use under this License of the Program or a work on which the Program is based. The work thus licensed is called the contributor's “contributor version”.
+
+A contributor's “essential patent claims” are all patent claims owned or controlled by the contributor, whether already acquired or hereafter acquired, that would be infringed by some manner, permitted by this License, of making, using, or selling its contributor version, but do not include claims that would be infringed only as a consequence of further modification of the contributor version. For purposes of this definition, “control” includes the right to grant patent sublicenses in a manner consistent with the requirements of this License.
+
+Each contributor grants you a non-exclusive, worldwide, royalty-free patent license under the contributor's essential patent claims, to make, use, sell, offer for sale, import and otherwise run, modify and propagate the contents of its contributor version.
+
+In the following three paragraphs, a “patent license” is any express agreement or commitment, however denominated, not to enforce a patent (such as an express permission to practice a patent or covenant not to sue for patent infringement). To “grant” such a patent license to a party means to make such an agreement or commitment not to enforce a patent against the party.
+
+If you convey a covered work, knowingly relying on a patent license, and the Corresponding Source of the work is not available for anyone to copy, free of charge and under the terms of this License, through a publicly available network server or other readily accessible means, then you must either (1) cause the Corresponding Source to be so available, or (2) arrange to deprive yourself of the benefit of the patent license for this particular work, or (3) arrange, in a manner consistent with the requirements of this License, to extend the patent license to downstream recipients. “Knowingly relying” means you have actual knowledge that, but for the patent license, your conveying the covered work in a country, or your recipient's use of the covered work in a country, would infringe one or more identifiable patents in that country that you have reason to believe are valid.
+
+If, pursuant to or in connection with a single transaction or arrangement, you convey, or propagate by procuring conveyance of, a covered work, and grant a patent license to some of the parties receiving the covered work authorizing them to use, propagate, modify or convey a specific copy of the covered work, then the patent license you grant is automatically extended to all recipients of the covered work and works based on it.
+
+A patent license is “discriminatory” if it does not include within the scope of its coverage, prohibits the exercise of, or is conditioned on the non-exercise of one or more of the rights that are specifically granted under this License. You may not convey a covered work if you are a party to an arrangement with a third party that is in the business of distributing software, under which you make payment to the third party based on the extent of your activity of conveying the work, and under which the third party grants, to any of the parties who would receive the covered work from you, a discriminatory patent license (a) in connection with copies of the covered work conveyed by you (or copies made from those copies), or (b) primarily for and in connection with specific products or compilations that contain the covered work, unless you entered into that arrangement, or that patent license was granted, prior to 28 March 2007.
+
+Nothing in this License shall be construed as excluding or limiting any implied license or other defenses to infringement that may otherwise be available to you under applicable patent law.
+
+12. No Surrender of Others' Freedom.
+If conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot convey a covered work so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not convey it at all. For example, if you agree to terms that obligate you to collect a royalty for further conveying from those to whom you convey the Program, the only way you could satisfy both those terms and this License would be to refrain entirely from conveying the Program.
+
+13. Use with the GNU Affero General Public License.
+Notwithstanding any other provision of this License, you have permission to link or combine any covered work with a work licensed under version 3 of the GNU Affero General Public License into a single combined work, and to convey the resulting work. The terms of this License will continue to apply to the part which is the covered work, but the special requirements of the GNU Affero General Public License, section 13, concerning interaction through a network will apply to the combination as such.
+
+14. Revised Versions of this License.
+The Free Software Foundation may publish revised and/or new versions of the GNU General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns.
+
+Each version is given a distinguishing version number. If the Program specifies that a certain numbered version of the GNU General Public License “or any later version” applies to it, you have the option of following the terms and conditions either of that numbered version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of the GNU General Public License, you may choose any version ever published by the Free Software Foundation.
+
+If the Program specifies that a proxy can decide which future versions of the GNU General Public License can be used, that proxy's public statement of acceptance of a version permanently authorizes you to choose that version for the Program.
+
+Later license versions may give you additional or different permissions. However, no additional obligations are imposed on any author or copyright holder as a result of your choosing to follow a later version.
+
+15. Disclaimer of Warranty.
+THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+16. Limitation of Liability.
+IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+
+17. Interpretation of Sections 15 and 16.
+If the disclaimer of warranty and limitation of liability provided above cannot be given local legal effect according to their terms, reviewing courts shall apply local law that most closely approximates an absolute waiver of all civil liability in connection with the Program, unless a warranty or assumption of liability accompanies a copy of the Program in return for a fee.
+
+END OF TERMS AND CONDITIONS
+
+How to Apply These Terms to Your New Programs
+
+If you develop a new program, and you want it to be of the greatest possible use to the public, the best way to achieve this is to make it free software which everyone can redistribute and change under these terms.
+
+To do so, attach the following notices to the program. It is safest to attach them to the start of each source file to most effectively state the exclusion of warranty; and each file should have at least the “copyright” line and a pointer to where the full notice is found.
+
+     CommandKit
+     Copyright (C) 2026  eric
+
+     This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
+
+     This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
+
+     You should have received a copy of the GNU General Public License along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+Also add information on how to contact you by electronic and paper mail.
+
+If the program does terminal interaction, make it output a short notice like this when it starts in an interactive mode:
+
+     CommandKit  Copyright (C) 2026  eric
+     This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
+     This is free software, and you are welcome to redistribute it under certain conditions; type `show c' for details.
+
+The hypothetical commands `show w' and `show c' should show the appropriate parts of the General Public License. Of course, your program's commands might be different; for a GUI interface, you would use an “about box”.
+
+You should also get your employer (if you work as a programmer) or school, if any, to sign a “copyright disclaimer” for the program, if necessary. For more information on this, and how to apply and follow the GNU GPL, see <http://www.gnu.org/licenses/>.
+
+The GNU General Public License does not permit incorporating your program into proprietary programs. If your program is a subroutine library, you may consider it more useful to permit linking proprietary applications with the library. If this is what you want to do, use the GNU Lesser General Public License instead of this License. But first, please read <http://www.gnu.org/philosophy/why-not-lgpl.html>.

integrations/ckconfig/README.md

@@ -0,0 +1,44 @@
+# CommandKit ckconfig
+
+`ckconfig` is the optional ConfigKit integration for CommandKit. It adapts
+ConfigKit loaders and scopes into reusable `commandkit.Command` declarations;
+installing the integration is explicit and does not modify an application by
+itself.
+
+## Module
+
+The module path is `go.maximumdirect.net/ckconfig`. Version v0.2.0 uses
+`go.maximumdirect.net/commandkit v0.3.0` and
+ConfigKit; it does not import PromptKit. See the
+[consumer guide](https://gitea.maximumdirect.net/eric/CommandKit/src/branch/main/docs/consumers/guide.md#configkit-scopes)
+for exact callback and lifetime contracts.
+
+## Example
+
+For one application configuration scope, install the convenience declaration:
+
+```go
+app, err := commandkit.New(identity, ckconfig.AppCommand(loadAppConfig))
+```
+
+Use `ckconfig.Command(ckconfig.Suite[Input, State]{...})` to define named
+scopes, selectors, input checks, and state shared by the selected acquisitions
+or comparison in a config invocation. `ckconfig.FromConfigKit` adapts a typed
+ConfigKit loader. The `config` command family exposes scope discovery and the
+validate, show, sources, explain, and diff operations supported by the declared
+scopes. Source reports include native destination, placement, unresolved
+destination, and source version-check evidence. Comparison returns ConfigKit's
+native records to the YAML report path; the
+[CLI reference](https://gitea.maximumdirect.net/eric/CommandKit/src/branch/main/docs/cli.md#compare-configuration-selections)
+owns its operator details.
+
+The maintained [simple example](examples/simple) shows a complete consumer.
+The [CommandKit CLI reference](https://gitea.maximumdirect.net/eric/CommandKit/src/branch/main/docs/cli.md#configuration-scopes)
+describes its operator-facing behavior.
+
+## License and attribution
+
+This module is licensed under the [GNU Lesser General Public License v3.0 or
+later](COPYRIGHT). The accompanying [LICENSE](LICENSE) contains the full LGPL
+v3 and GPL v3 texts. See [third-party attribution](docs/oss/attribution.md)
+for incorporated and dependency notices.

integrations/ckconfig/comparison_adapter_test.go

@@ -0,0 +1,334 @@
+package ckconfig
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	configkit "gitea.maximumdirect.net/eric/ConfigKit"
+	commandkit "go.maximumdirect.net/commandkit"
+)
+
+type adapterSettings struct {
+	Greeting string `yaml:"greeting"`
+	Secret   string `yaml:"secret"`
+}
+
+func adapterDefinition() configkit.Definition[adapterSettings] {
+	return configkit.Definition[adapterSettings]{
+		Defaults: func() adapterSettings { return adapterSettings{Greeting: "Hello"} },
+		Validate: func(value *adapterSettings, validation *configkit.Validation) {
+			if value.Greeting == "Hello" {
+				validation.Warning(configkit.Keys("greeting"), "using the default greeting")
+			}
+		},
+		Secret: func(path configkit.Path) bool { return path.String() == "/secret" },
+	}
+}
+
+func adapterSettingsLoad(source configkit.Source) (*configkit.Result[adapterSettings], error) {
+	return configkit.Load(source, configkit.Options[adapterSettings]{Definition: adapterDefinition()})
+}
+
+func comparisonSide(selection Selection, greeting string) ComparisonSide[struct{ Label string }] {
+	return ComparisonSide[struct{ Label string }]{
+		Selection: selection,
+		Input:     struct{ Label string }{Label: greeting},
+	}
+}
+
+func TestFromConfigKitCompareReturnsNativeChangesAndLoadsEqualSelections(t *testing.T) {
+	selection := Selection{Config: commandkit.Supplied[string]{Value: "same.yml", Set: true}}
+	var calls []struct {
+		selection Selection
+		input     struct{ Label string }
+		state     *int
+	}
+	scope := FromConfigKit[struct{ Label string }, *int, adapterSettings]("app", "Application configuration", func(_ context.Context, selected Selection, input struct{ Label string }, state *int) (*configkit.Result[adapterSettings], error) {
+		calls = append(calls, struct {
+			selection Selection
+			input     struct{ Label string }
+			state     *int
+		}{selected, input, state})
+		*state++
+		return adapterSettingsLoad(configkit.Mapping(input.Label, map[string]any{"greeting": input.Label}))
+	})
+	state := new(int)
+	acquired, err := scope.Compare(context.Background(), ComparisonRequest[struct{ Label string }]{
+		Left:  comparisonSide(selection, "before"),
+		Right: comparisonSide(selection, "after"),
+	}, state)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(calls) != 2 || calls[0].selection != selection || calls[1].selection != selection {
+		t.Fatalf("loader calls = %#v", calls)
+	}
+	if calls[0].input.Label != "before" || calls[1].input.Label != "after" || calls[0].state != state || calls[1].state != state || *state != 2 {
+		t.Fatalf("loader inputs/state = %#v, %#v, state=%d", calls[0], calls[1], *state)
+	}
+	if len(acquired.Value) != 1 || acquired.Value[0].Path.String() != "/greeting" || acquired.Value[0].Left.YAML != "before\n" || acquired.Value[0].Right.YAML != "after\n" {
+		t.Fatalf("native differences = %#v", acquired.Value)
+	}
+
+	equal, err := scope.Compare(context.Background(), ComparisonRequest[struct{ Label string }]{
+		Left:  comparisonSide(selection, "same"),
+		Right: comparisonSide(selection, "same"),
+	}, state)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(equal.Value) != 0 || len(calls) != 4 {
+		t.Fatalf("equal comparison records/calls = %#v / %d", equal.Value, len(calls))
+	}
+}
+
+func TestFromConfigKitCompareIgnoresDefaultAndResolutionHistoryForEqualValues(t *testing.T) {
+	type resolvedSettings struct {
+		Greeting string `yaml:"greeting"`
+	}
+	definition := configkit.Definition[resolvedSettings]{
+		Defaults: func() resolvedSettings { return resolvedSettings{Greeting: "resolved"} },
+		Resolve: func(value *resolvedSettings, resolution *configkit.Resolution) error {
+			if value.Greeting != "resolved" {
+				value.Greeting = "resolved"
+				resolution.Record(configkit.Keys("greeting"), configkit.ChangeNormalization, "canonical greeting")
+			}
+			return nil
+		},
+	}
+	left, err := configkit.Load(configkit.NoSource(), configkit.Options[resolvedSettings]{Definition: definition})
+	if err != nil {
+		t.Fatal(err)
+	}
+	right, err := configkit.Load(configkit.Mapping("right-source", map[string]any{"greeting": "source value"}), configkit.Options[resolvedSettings]{Definition: definition})
+	if err != nil {
+		t.Fatal(err)
+	}
+	scope := FromConfigKit[struct{}, struct{}, resolvedSettings]("app", "Application configuration", func(_ context.Context, selected Selection, _ struct{}, _ struct{}) (*configkit.Result[resolvedSettings], error) {
+		if selected.Config.Value == "left" {
+			return left, nil
+		}
+		return right, nil
+	})
+	acquired, err := scope.Compare(context.Background(), ComparisonRequest[struct{}]{
+		Left:  ComparisonSide[struct{}]{Selection: Selection{Config: commandkit.Supplied[string]{Value: "left", Set: true}}},
+		Right: ComparisonSide[struct{}]{Selection: Selection{Config: commandkit.Supplied[string]{Value: "right", Set: true}}},
+	}, struct{}{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if left.Config != right.Config || left.Config.Greeting != "resolved" || len(acquired.Value) != 0 {
+		t.Fatalf("equal resolved values yielded differences: left=%#v right=%#v records=%#v", left.Config, right.Config, acquired.Value)
+	}
+}
+
+func TestFromConfigKitCompareUsesBaseAndOverlaySelections(t *testing.T) {
+	dir := t.TempDir()
+	basePath := filepath.Join(dir, "base.yml")
+	overlayPath := filepath.Join(dir, "overlays", "testing.yml")
+	if err := os.WriteFile(basePath, []byte("greeting: Hello\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.Mkdir(filepath.Dir(overlayPath), 0o700); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(overlayPath, []byte("greeting: Goodbye\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	loader := func(_ context.Context, selection Selection, _ struct{}, _ struct{}) (*configkit.Result[adapterSettings], error) {
+		options := configkit.LayeredOptions[adapterSettings]{Definition: adapterDefinition()}
+		if selection.Overlay.Set {
+			options.Overlay = selection.Overlay.Value
+			options.OverlayFilesystem = &configkit.FilesystemContext{Root: dir, BaseDir: dir}
+		}
+		return configkit.LoadLayered(configkit.Input{Source: configkit.File(selection.Config.Value)}, options)
+	}
+	scope := FromConfigKit[struct{}, struct{}, adapterSettings]("app", "Application configuration", loader)
+	acquired, err := scope.Compare(context.Background(), ComparisonRequest[struct{}]{
+		Left: ComparisonSide[struct{}]{Selection: Selection{Config: commandkit.Supplied[string]{Value: basePath, Set: true}}},
+		Right: ComparisonSide[struct{}]{Selection: Selection{
+			Config:  commandkit.Supplied[string]{Value: basePath, Set: true},
+			Overlay: commandkit.Supplied[string]{Value: "testing", Set: true},
+		}},
+	}, struct{}{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(acquired.Value) != 1 || acquired.Value[0].Path.String() != "/greeting" || acquired.Value[0].Left.YAML != "Hello\n" || acquired.Value[0].Right.YAML != "Goodbye\n" {
+		t.Fatalf("base/overlay differences = %#v", acquired.Value)
+	}
+}
+
+func TestFromConfigKitCompareRetainsSideDiagnosticsAndLoadError(t *testing.T) {
+	left, err := adapterSettingsLoad(configkit.Mapping("left-source", map[string]any{"greeting": "Hello"}))
+	if err != nil {
+		t.Fatal(err)
+	}
+	_, loadErr := configkit.Load(configkit.Mapping("right-source", map[string]any{"unknown": true}), configkit.Options[adapterSettings]{Definition: adapterDefinition()})
+	if loadErr == nil {
+		t.Fatal("invalid right source unexpectedly loaded")
+	}
+	wrapper := fmt.Errorf("application loader context: %w", loadErr)
+	scope := FromConfigKit[struct{}, struct{}, adapterSettings]("app", "Application configuration", func(_ context.Context, selected Selection, _ struct{}, _ struct{}) (*configkit.Result[adapterSettings], error) {
+		if selected.Config.Value == "left" {
+			return left, nil
+		}
+		return nil, wrapper
+	})
+	acquired, gotErr := scope.Compare(context.Background(), ComparisonRequest[struct{}]{
+		Left:  ComparisonSide[struct{}]{Selection: Selection{Config: commandkit.Supplied[string]{Value: "left", Set: true}}},
+		Right: ComparisonSide[struct{}]{Selection: Selection{Config: commandkit.Supplied[string]{Value: "right", Set: true}}},
+	}, struct{}{})
+	if !errors.Is(gotErr, loadErr) {
+		t.Fatalf("load error identity not preserved: %v", gotErr)
+	}
+	var typed *configkit.LoadError
+	if !errors.As(gotErr, &typed) || typed != loadErr {
+		t.Fatalf("load error type not preserved: %#v", typed)
+	}
+	if len(acquired.Diagnostics) != 1 || acquired.Diagnostics[0].Severity != commandkit.SeverityWarning || len(acquired.Explanation.Details) != 1 {
+		t.Fatalf("retained diagnostics/explanation = %#v / %#v", acquired.Diagnostics, acquired.Explanation)
+	}
+	var leftText, rightText bytes.Buffer
+	if err := acquired.Diagnostics[0].Write(&leftText); err != nil {
+		t.Fatal(err)
+	}
+	if err := acquired.Explanation.Details[0](&rightText); err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(leftText.String(), `Configuration scope "app" left:`) || !strings.Contains(leftText.String(), `"left-source"`) {
+		t.Fatalf("left diagnostic lost side/source identity: %q", leftText.String())
+	}
+	if !strings.Contains(rightText.String(), `Configuration scope "app" right:`) || !strings.Contains(rightText.String(), `"right-source"`) {
+		t.Fatalf("right diagnostic lost side/source identity: %q", rightText.String())
+	}
+}
+
+func TestFromConfigKitCompareStopsAfterLeftLoadFailure(t *testing.T) {
+	_, loadErr := configkit.Load(configkit.Mapping("left-source", map[string]any{"unknown": true}), configkit.Options[adapterSettings]{Definition: adapterDefinition()})
+	if loadErr == nil {
+		t.Fatal("invalid left source unexpectedly loaded")
+	}
+	rightCalled := false
+	scope := FromConfigKit[struct{}, struct{}, adapterSettings]("app", "Application configuration", func(_ context.Context, selected Selection, _ struct{}, _ struct{}) (*configkit.Result[adapterSettings], error) {
+		if selected.Config.Value == "left" {
+			return nil, loadErr
+		}
+		rightCalled = true
+		return adapterSettingsLoad(configkit.Mapping("right-source", map[string]any{"greeting": "Goodbye"}))
+	})
+	acquired, err := scope.Compare(context.Background(), ComparisonRequest[struct{}]{
+		Left:  ComparisonSide[struct{}]{Selection: Selection{Config: commandkit.Supplied[string]{Value: "left", Set: true}}},
+		Right: ComparisonSide[struct{}]{Selection: Selection{Config: commandkit.Supplied[string]{Value: "right", Set: true}}},
+	}, struct{}{})
+	if !errors.Is(err, loadErr) || rightCalled {
+		t.Fatalf("left failure/right load = %v / %v", err, rightCalled)
+	}
+	var typed *configkit.LoadError
+	if !errors.As(err, &typed) || typed != loadErr || len(acquired.Explanation.Details) != 1 {
+		t.Fatalf("left failure identity/explanation = %v / %#v", err, acquired.Explanation)
+	}
+	var terminal bytes.Buffer
+	if err := acquired.Explanation.Details[0](&terminal); err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(terminal.String(), `Configuration scope "app" left:`) || !strings.Contains(terminal.String(), `"left-source"`) {
+		t.Fatalf("left terminal context lost side/source identity: %q", terminal.String())
+	}
+}
+
+func TestFromConfigKitCompareCancellationStopsBeforeRightLoad(t *testing.T) {
+	left, err := adapterSettingsLoad(configkit.Mapping("left-source", map[string]any{"greeting": "Hello"}))
+	if err != nil {
+		t.Fatal(err)
+	}
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+	rightCalled := false
+	scope := FromConfigKit[struct{}, struct{}, adapterSettings]("app", "Application configuration", func(_ context.Context, selection Selection, _ struct{}, _ struct{}) (*configkit.Result[adapterSettings], error) {
+		if selection.Config.Value == "left" {
+			cancel()
+			return left, nil
+		}
+		rightCalled = true
+		return adapterSettingsLoad(configkit.Mapping("right-source", map[string]any{"greeting": "Goodbye"}))
+	})
+	acquired, err := scope.Compare(ctx, ComparisonRequest[struct{}]{
+		Left:  ComparisonSide[struct{}]{Selection: Selection{Config: commandkit.Supplied[string]{Value: "left", Set: true}}},
+		Right: ComparisonSide[struct{}]{Selection: Selection{Config: commandkit.Supplied[string]{Value: "right", Set: true}}},
+	}, struct{}{})
+	if !errors.Is(err, context.Canceled) || rightCalled {
+		t.Fatalf("cancellation/right load = %v / %v", err, rightCalled)
+	}
+	if len(acquired.Diagnostics) != 1 || acquired.Diagnostics[0].Severity != commandkit.SeverityWarning {
+		t.Fatalf("left diagnostics lost on cancellation: %#v", acquired.Diagnostics)
+	}
+}
+
+func TestFromConfigKitCompareRejectsNilResultAndRetainsNativeDiffFailureDiagnostics(t *testing.T) {
+	t.Run("nil result", func(t *testing.T) {
+		scope := FromConfigKit[struct{}, struct{}, adapterSettings]("app", "Application configuration", func(context.Context, Selection, struct{}, struct{}) (*configkit.Result[adapterSettings], error) {
+			return nil, nil
+		})
+		_, err := scope.Compare(context.Background(), ComparisonRequest[struct{}]{}, struct{}{})
+		if err == nil || !strings.Contains(err.Error(), `"app" left`) || !strings.Contains(err.Error(), "nil result") {
+			t.Fatalf("nil left result error = %v", err)
+		}
+	})
+
+	t.Run("native diff error", func(t *testing.T) {
+		left, err := adapterSettingsLoad(configkit.Mapping("left-source", map[string]any{"greeting": "Hello"}))
+		if err != nil {
+			t.Fatal(err)
+		}
+		scope := FromConfigKit[struct{}, struct{}, adapterSettings]("app", "Application configuration", func(_ context.Context, selection Selection, _ struct{}, _ struct{}) (*configkit.Result[adapterSettings], error) {
+			if selection.Config.Value == "left" {
+				return left, nil
+			}
+			return &configkit.Result[adapterSettings]{}, nil
+		})
+		acquired, err := scope.Compare(context.Background(), ComparisonRequest[struct{}]{
+			Left:  ComparisonSide[struct{}]{Selection: Selection{Config: commandkit.Supplied[string]{Value: "left", Set: true}}},
+			Right: ComparisonSide[struct{}]{Selection: Selection{Config: commandkit.Supplied[string]{Value: "right", Set: true}}},
+		}, struct{}{})
+		if err == nil || !strings.Contains(err.Error(), "native diff") {
+			t.Fatalf("native diff error = %v", err)
+		}
+		if len(acquired.Diagnostics) != 1 || acquired.Diagnostics[0].Severity != commandkit.SeverityWarning {
+			t.Fatalf("native diff failure lost diagnostics: %#v", acquired.Diagnostics)
+		}
+	})
+}
+
+func TestFromConfigKitComparePreservesConcealedNativeDifference(t *testing.T) {
+	left, err := adapterSettingsLoad(configkit.Mapping("left-source", map[string]any{"secret": "old"}))
+	if err != nil {
+		t.Fatal(err)
+	}
+	right, err := adapterSettingsLoad(configkit.Mapping("right-source", map[string]any{"secret": "new"}))
+	if err != nil {
+		t.Fatal(err)
+	}
+	scope := FromConfigKit[struct{}, struct{}, adapterSettings]("app", "Application configuration", func(_ context.Context, selected Selection, _ struct{}, _ struct{}) (*configkit.Result[adapterSettings], error) {
+		if selected.Config.Value == "left" {
+			return left, nil
+		}
+		return right, nil
+	})
+	acquired, err := scope.Compare(context.Background(), ComparisonRequest[struct{}]{
+		Left:  ComparisonSide[struct{}]{Selection: Selection{Config: commandkit.Supplied[string]{Value: "left", Set: true}}},
+		Right: ComparisonSide[struct{}]{Selection: Selection{Config: commandkit.Supplied[string]{Value: "right", Set: true}}},
+	}, struct{}{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(acquired.Value) != 1 || !acquired.Value[0].HiddenChanged || !acquired.Value[0].Left.Redacted || !acquired.Value[0].Right.Redacted || acquired.Value[0].Left.YAML != acquired.Value[0].Right.YAML {
+		t.Fatalf("concealed native difference was altered: %#v", acquired.Value)
+	}
+}

integrations/ckconfig/comparison_contract_test.go

@@ -0,0 +1,105 @@
+package ckconfig
+
+import (
+	"context"
+	"errors"
+	"io"
+	"strings"
+	"testing"
+
+	configkit "gitea.maximumdirect.net/eric/ConfigKit"
+	commandkit "go.maximumdirect.net/commandkit"
+)
+
+func TestComparisonCapabilitiesAreIndependentAndCaptured(t *testing.T) {
+	type input struct{ Value string }
+	var inputCalls, stateCalls, acquireCalls, compareCalls int
+	compare := func(context.Context, ComparisonRequest[input], struct{}) (commandkit.Acquired[[]configkit.Difference], error) {
+		compareCalls++
+		return commandkit.Acquired[[]configkit.Difference]{}, nil
+	}
+	operations := []Operation{Diff}
+	suite := Suite[input, struct{}]{
+		NewInput: func() input { inputCalls++; return input{} },
+		NewState: func() struct{} { stateCalls++; return struct{}{} },
+		Scopes: []Scope[input, struct{}]{
+			{Name: "app", Operations: operations, Compare: compare},
+			{Name: "promptkit", Operations: []Operation{Diff, Show, Validate}, Acquire: func(context.Context, Request, input, struct{}) (commandkit.Acquired[View], error) {
+				acquireCalls++
+				return commandkit.Acquired[View]{}, nil
+			}, Compare: compare},
+			{Name: "alpha"},
+			{Name: "plain", Operations: []Operation{Validate}, Acquire: func(context.Context, Request, input, struct{}) (commandkit.Acquired[View], error) {
+				acquireCalls++
+				return commandkit.Acquired[View]{}, nil
+			}},
+		},
+	}
+	captured := captureSuite(suite)
+	declaration := Command(suite)
+
+	// Capability metadata and callback references are copied during capture.
+	suite.Scopes[0].Operations[0] = Show
+	suite.Scopes[0].Compare = nil
+
+	app := newConfigTestApp(t, declaration)
+	var output strings.Builder
+	outcome := app.Execute(context.Background(), []string{"config", "scopes"}, commandkit.Streams{Out: &output, Err: io.Discard})
+	if outcome.Kind != commandkit.OutcomeSuccess {
+		t.Fatalf("scope discovery outcome = %#v", outcome)
+	}
+	if got, want := output.String(), "app: diff\npromptkit: validate, show, diff\nalpha: \nplain: validate\n"; got != want {
+		t.Fatalf("scope discovery = %q, want %q", got, want)
+	}
+
+	// A family-wide diff command is available, but unsupported scopes fail before
+	// suite factories or either provider runs.
+	outcome = app.Execute(context.Background(), []string{"config", "diff", "--scope", "plain"}, commandkit.Streams{Out: io.Discard, Err: io.Discard})
+	if outcome.Kind != commandkit.OutcomeUsage {
+		t.Fatalf("unsupported scope outcome = %#v", outcome)
+	}
+	if inputCalls != 0 || stateCalls != 0 || acquireCalls != 0 || compareCalls != 0 {
+		t.Fatalf("discovery or preflight invoked suite work: input=%d state=%d acquire=%d compare=%d", inputCalls, stateCalls, acquireCalls, compareCalls)
+	}
+	if captured.byName["app"].scope.Compare == nil {
+		t.Fatal("captured comparison callback was cleared by a source edit")
+	}
+	if _, err := captured.byName["app"].scope.Compare(context.Background(), ComparisonRequest[input]{}, struct{}{}); err != nil || compareCalls != 1 {
+		t.Fatalf("captured comparison callback result=%v calls=%d", err, compareCalls)
+	}
+
+	withoutComparison := newConfigTestApp(t, Command(Suite[input, struct{}]{Scopes: []Scope[input, struct{}]{{
+		Name: "plain", Operations: []Operation{Validate},
+		Acquire: func(context.Context, Request, input, struct{}) (commandkit.Acquired[View], error) {
+			return commandkit.Acquired[View]{}, nil
+		},
+	}}}))
+	outcome = withoutComparison.Execute(context.Background(), []string{"config", "diff"}, commandkit.Streams{Out: io.Discard, Err: io.Discard})
+	if outcome.Kind != commandkit.OutcomeUsage {
+		t.Fatalf("family without comparison exposed diff: %#v", outcome)
+	}
+}
+
+func TestComparisonCallbackWiringAndRetainedAdapterIssues(t *testing.T) {
+	newApp := func(scope Scope[struct{}, struct{}]) error {
+		_, err := commandkit.New(commandkit.Identity{Name: "example"}, Command(Suite[struct{}, struct{}]{Scopes: []Scope[struct{}, struct{}]{scope}}))
+		return err
+	}
+
+	if err := newApp(Scope[struct{}, struct{}]{Name: "app", Operations: []Operation{Diff}}); err == nil {
+		t.Fatalf("missing comparison callback error = %v", err)
+	}
+	if err := newApp(Scope[struct{}, struct{}]{Name: "app", Operations: []Operation{Validate}}); err == nil {
+		t.Fatalf("missing ordinary acquisition callback error = %v", err)
+	}
+
+	scope := FromConfigKit[struct{}, struct{}, struct{}]("app", "Application configuration", nil)
+	scope.Operations = []Operation{Diff}
+	scope.Compare = func(context.Context, ComparisonRequest[struct{}], struct{}) (commandkit.Acquired[[]configkit.Difference], error) {
+		return commandkit.Acquired[[]configkit.Difference]{}, nil
+	}
+	retained := scope.issues[0]
+	if err := newApp(scope); err == nil || !errors.Is(err, retained) {
+		t.Fatalf("narrowed adapter lost its retained loader issue: %v", err)
+	}
+}

integrations/ckconfig/comparison_input_test.go

@@ -0,0 +1,183 @@
+package ckconfig
+
+import (
+	"context"
+	"io"
+	"strings"
+	"testing"
+
+	configkit "gitea.maximumdirect.net/eric/ConfigKit"
+	commandkit "go.maximumdirect.net/commandkit"
+)
+
+func TestComparisonSelectionInheritsFieldsIndependently(t *testing.T) {
+	leftConfig := commandkit.Supplied[string]{Value: "before.yml", Set: true}
+	leftOverlay := commandkit.Supplied[string]{Value: "base", Set: true}
+	tests := []struct {
+		name  string
+		left  Selection
+		right Selection
+		want  Selection
+	}{
+		{
+			name: "omitted fields stay omitted",
+		},
+		{
+			name: "both fields inherit supplied state",
+			left: Selection{Config: leftConfig, Overlay: leftOverlay},
+			want: Selection{Config: leftConfig, Overlay: leftOverlay},
+		},
+		{
+			name:  "explicit empty config overrides while overlay inherits",
+			left:  Selection{Config: leftConfig, Overlay: leftOverlay},
+			right: Selection{Config: commandkit.Supplied[string]{Set: true}},
+			want:  Selection{Config: commandkit.Supplied[string]{Set: true}, Overlay: leftOverlay},
+		},
+		{
+			name:  "explicit overlay overrides while config inherits",
+			left:  Selection{Config: leftConfig, Overlay: leftOverlay},
+			right: Selection{Overlay: commandkit.Supplied[string]{Value: "candidate", Set: true}},
+			want:  Selection{Config: leftConfig, Overlay: commandkit.Supplied[string]{Value: "candidate", Set: true}},
+		},
+		{
+			name:  "explicit empty overlay remains supplied",
+			left:  Selection{Config: leftConfig, Overlay: leftOverlay},
+			right: Selection{Overlay: commandkit.Supplied[string]{Set: true}},
+			want:  Selection{Config: leftConfig, Overlay: commandkit.Supplied[string]{Set: true}},
+		},
+		{
+			name:  "both explicit right fields replace left",
+			left:  Selection{Config: leftConfig, Overlay: leftOverlay},
+			right: Selection{Config: commandkit.Supplied[string]{Value: "after.yml", Set: true}, Overlay: commandkit.Supplied[string]{Value: "new", Set: true}},
+			want:  Selection{Config: commandkit.Supplied[string]{Value: "after.yml", Set: true}, Overlay: commandkit.Supplied[string]{Value: "new", Set: true}},
+		},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			if got := inheritComparisonSelection(test.left, test.right); got != test.want {
+				t.Fatalf("inherited selection = %#v, want %#v", got, test.want)
+			}
+		})
+	}
+}
+
+func TestComparisonHelpLimitsFlagsAndDefaultsFormatToYAML(t *testing.T) {
+	scope := Scope[struct{}, struct{}]{
+		Name: "app", Operations: []Operation{Diff, Show, Explain, Validate, Sources},
+		Acquire: func(context.Context, Request, struct{}, struct{}) (commandkit.Acquired[View], error) {
+			return commandkit.Acquired[View]{}, nil
+		},
+		Compare: func(context.Context, ComparisonRequest[struct{}], struct{}) (commandkit.Acquired[[]configkit.Difference], error) {
+			return commandkit.Acquired[[]configkit.Difference]{}, nil
+		},
+	}
+	app := newConfigTestApp(t, Command(Suite[struct{}, struct{}]{Scopes: []Scope[struct{}, struct{}]{scope}}))
+	help := func(args ...string) string {
+		t.Helper()
+		var output strings.Builder
+		app.Execute(context.Background(), args, commandkit.Streams{Out: &output, Err: io.Discard})
+		return output.String()
+	}
+
+	diffHelp := help("config", "diff", "--help")
+	if !strings.Contains(diffHelp, "--against-config") || !strings.Contains(diffHelp, "--against-overlay") {
+		t.Fatalf("diff help omits right-side selection flags:\n%s", diffHelp)
+	}
+	if !strings.Contains(diffHelp, "default: yaml") {
+		t.Fatalf("diff help does not show the YAML default:\n%s", diffHelp)
+	}
+	for _, operation := range []string{"validate", "show", "sources", "explain"} {
+		operationHelp := help("config", operation, "--help")
+		if strings.Contains(operationHelp, "--against-config") || strings.Contains(operationHelp, "--against-overlay") {
+			t.Errorf("%s exposes comparison-only flags:\n%s", operation, operationHelp)
+		}
+		if operation == "show" && !strings.Contains(operationHelp, "default: yaml") {
+			t.Errorf("show format default changed:\n%s", operationHelp)
+		}
+		if operation != "show" && !strings.Contains(operationHelp, "default: text") {
+			t.Errorf("%s format default changed:\n%s", operation, operationHelp)
+		}
+		if operation != "explain" && strings.Contains(operationHelp, "--path") {
+			t.Errorf("%s exposes the explain-only path flag:\n%s", operation, operationHelp)
+		}
+	}
+	explainHelp := help("config", "explain", "--help")
+	if !strings.Contains(explainHelp, "--path") {
+		t.Fatalf("explain flags changed:\n%s", explainHelp)
+	}
+}
+
+func TestComparisonPreparationAcceptsOnlyYAML(t *testing.T) {
+	inputCalls, stateCalls := 0, 0
+	prepared := captureSuite(Suite[struct{}, struct{}]{
+		NewInput: func() struct{} { inputCalls++; return struct{}{} },
+		NewState: func() struct{} { stateCalls++; return struct{}{} },
+		Scopes: []Scope[struct{}, struct{}]{{
+			Name: "app", Operations: []Operation{Diff},
+			Compare: func(context.Context, ComparisonRequest[struct{}], struct{}) (commandkit.Acquired[[]configkit.Difference], error) {
+				return commandkit.Acquired[[]configkit.Difference]{}, nil
+			},
+		}},
+	})
+
+	input := &configCommandInput[struct{}, struct{}]{
+		selection: Selection{Config: commandkit.Supplied[string]{Value: "before.yml", Set: true}},
+		against:   Selection{Overlay: commandkit.Supplied[string]{Value: "candidate", Set: true}},
+		format:    commandkit.Supplied[string]{Value: "yaml", Set: true},
+	}
+	if err := prepareConfigOperation(prepared, Diff, input); err != nil {
+		t.Fatalf("explicit YAML format rejected: %v", err)
+	}
+	if input.plan == nil || input.plan.format != "yaml" {
+		t.Fatalf("comparison plan = %#v", input.plan)
+	}
+	if input.plan.scopeName != "app" {
+		t.Fatalf("comparison default scope = %q, want app", input.plan.scopeName)
+	}
+	if want := (Selection{
+		Config:  commandkit.Supplied[string]{Value: "before.yml", Set: true},
+		Overlay: commandkit.Supplied[string]{Value: "candidate", Set: true},
+	}); input.against != want {
+		t.Fatalf("resolved right selection = %#v, want %#v", input.against, want)
+	}
+
+	for _, format := range []string{"text", "json"} {
+		input := &configCommandInput[struct{}, struct{}]{format: commandkit.Supplied[string]{Value: format}}
+		if err := prepareConfigOperation(prepared, Diff, input); err == nil {
+			t.Errorf("comparison format %q was accepted", format)
+		}
+	}
+	if inputCalls != 2 || stateCalls != 0 {
+		t.Fatalf("comparison preparation calls input/state: %d/%d", inputCalls, stateCalls)
+	}
+}
+
+func TestComparisonAvailabilityPreflightPrecedesFactories(t *testing.T) {
+	inputCalls, stateCalls, acquireCalls, compareCalls := 0, 0, 0, 0
+	prepared := captureSuite(Suite[struct{}, struct{}]{
+		NewInput: func() struct{} { inputCalls++; return struct{}{} },
+		NewState: func() struct{} { stateCalls++; return struct{}{} },
+		Scopes: []Scope[struct{}, struct{}]{
+			{Name: "app", Operations: []Operation{Diff}, Compare: func(context.Context, ComparisonRequest[struct{}], struct{}) (commandkit.Acquired[[]configkit.Difference], error) {
+				compareCalls++
+				return commandkit.Acquired[[]configkit.Difference]{}, nil
+			}},
+			{Name: "plain", Operations: []Operation{Validate}, Acquire: func(context.Context, Request, struct{}, struct{}) (commandkit.Acquired[View], error) {
+				acquireCalls++
+				return commandkit.Acquired[View]{}, nil
+			}},
+		},
+	})
+	for _, scope := range []string{"missing", "all", "plain"} {
+		input := &configCommandInput[struct{}, struct{}]{
+			scope:  commandkit.Supplied[string]{Value: scope, Set: true},
+			format: commandkit.Supplied[string]{Value: "yaml"},
+		}
+		if err := prepareConfigOperation(prepared, Diff, input); err == nil {
+			t.Errorf("comparison scope %q was accepted", scope)
+		}
+	}
+	if inputCalls != 0 || stateCalls != 0 || acquireCalls != 0 || compareCalls != 0 {
+		t.Fatalf("failed preflight invoked suite work: input=%d state=%d acquire=%d compare=%d", inputCalls, stateCalls, acquireCalls, compareCalls)
+	}
+}

integrations/ckconfig/comparison_preparation_test.go

@@ -0,0 +1,357 @@
+package ckconfig
+
+import (
+	"context"
+	"errors"
+	"io"
+	"strconv"
+	"strings"
+	"testing"
+
+	configkit "gitea.maximumdirect.net/eric/ConfigKit"
+	commandkit "go.maximumdirect.net/commandkit"
+)
+
+func TestComparisonPreparesEqualSelectionsWithSeparateTypedInputs(t *testing.T) {
+	type input struct {
+		Enabled commandkit.Supplied[bool]
+		Limit   commandkit.Supplied[int]
+		Tags    commandkit.Supplied[[]string]
+	}
+	var inputCalls, checkCalls, stateCalls int
+	var parseCalls int
+	var preparedInputs []*input
+	var selections []Selection
+	enabled := commandkit.BoolFlag[*input](commandkit.FlagMeta{Name: "enabled"}, true, func(value **input, supplied commandkit.Supplied[bool]) {
+		(*value).Enabled = supplied
+	})
+	limit := commandkit.ValueFlag[*input](commandkit.FlagMeta{Name: "limit", Required: true}, (*int)(nil), func(raw string) (int, error) {
+		parseCalls++
+		return strconv.Atoi(raw)
+	}, func(value **input, supplied commandkit.Supplied[int]) {
+		(*value).Limit = supplied
+	})
+	tags := commandkit.RepeatFlag[*input](commandkit.FlagMeta{Name: "tag"}, nil, func(raw string) (string, error) {
+		parseCalls++
+		return raw, nil
+	}, func(value **input, supplied commandkit.Supplied[[]string]) {
+		(*value).Tags = supplied
+	})
+	suite := Suite[*input, struct{}]{
+		NewInput: func() *input {
+			inputCalls++
+			return &input{}
+		},
+		NewState: func() struct{} {
+			stateCalls++
+			if checkCalls != 2 {
+				t.Errorf("shared state created after %d input checks", checkCalls)
+			}
+			if len(preparedInputs) != 2 || preparedInputs[0] == preparedInputs[1] {
+				t.Errorf("inputs were not initialized separately: %#v", preparedInputs)
+			} else {
+				left, right := preparedInputs[0].Tags.Value, preparedInputs[1].Tags.Value
+				if len(left) != 2 || len(right) != 2 || &left[0] == &right[0] {
+					t.Errorf("repeated values share storage: left=%#v right=%#v", left, right)
+				} else {
+					left[0] = "changed"
+					if right[0] != "alpha" {
+						t.Errorf("mutating one side changed the other: %#v", right)
+					}
+				}
+			}
+			return struct{}{}
+		},
+		Selectors: []Selector[*input]{{Binding: enabled}, {Binding: limit}, {Binding: tags}},
+		CheckInput: func(scope string, selection Selection, value *input) error {
+			checkCalls++
+			preparedInputs = append(preparedInputs, value)
+			selections = append(selections, selection)
+			if scope != "app" || value == nil {
+				return errors.New("unexpected scope input")
+			}
+			if !value.Enabled.Set || value.Enabled.Value {
+				return errors.New("explicit false was not preserved")
+			}
+			if !value.Limit.Set || value.Limit.Value != 0 {
+				return errors.New("explicit zero was not preserved")
+			}
+			if !value.Tags.Set || len(value.Tags.Value) != 2 || value.Tags.Value[0] != "alpha" || value.Tags.Value[1] != "beta" {
+				return errors.New("repeated input was not preserved")
+			}
+			return nil
+		},
+		Scopes: []Scope[*input, struct{}]{{
+			Name: "app", Operations: []Operation{Diff},
+			Compare: func(context.Context, ComparisonRequest[*input], struct{}) (commandkit.Acquired[[]configkit.Difference], error) {
+				return commandkit.Acquired[[]configkit.Difference]{}, nil
+			},
+		}},
+	}
+	app := newConfigTestApp(t, Command(suite))
+	outcome := app.Execute(context.Background(), []string{
+		"config", "diff", "--config", "same.yml", "--against-config", "same.yml", "--overlay=",
+		"--enabled=false", "--limit=0", "--tag", "alpha", "--tag", "beta",
+	}, commandkit.Streams{Out: io.Discard, Err: io.Discard})
+	if outcome.Kind != commandkit.OutcomeSuccess {
+		t.Fatalf("valid comparison outcome = %#v", outcome)
+	}
+	if inputCalls != 2 || checkCalls != 2 || stateCalls != 1 {
+		t.Fatalf("preparation calls input=%d check=%d state=%d", inputCalls, checkCalls, stateCalls)
+	}
+	if parseCalls != 3 {
+		t.Fatalf("typed values were converted %d times, want once per supplied occurrence", parseCalls)
+	}
+	wantSelection := Selection{
+		Config:  commandkit.Supplied[string]{Value: "same.yml", Set: true},
+		Overlay: commandkit.Supplied[string]{Set: true},
+	}
+	if len(selections) != 2 || selections[0] != wantSelection || selections[1] != wantSelection {
+		t.Fatalf("side selections = %#v, want equal %#v values", selections, wantSelection)
+	}
+}
+
+func TestComparisonProviderReceivesCheckedPairAndSharedState(t *testing.T) {
+	type input struct{ ID int }
+	type state struct{ Label string }
+	inputCalls, checkCalls, stateCalls, compareCalls, acquireCalls := 0, 0, 0, 0, 0
+	checked := make(map[Selection]input)
+	shared := &state{Label: "shared"}
+	var request ComparisonRequest[input]
+	app := newConfigTestApp(t, Command(Suite[input, *state]{
+		NewInput: func() input {
+			inputCalls++
+			return input{ID: inputCalls}
+		},
+		NewState: func() *state {
+			stateCalls++
+			if checkCalls != 2 {
+				t.Errorf("shared state created after %d input checks", checkCalls)
+			}
+			return shared
+		},
+		CheckInput: func(scope string, selection Selection, value input) error {
+			checkCalls++
+			if scope != "app" {
+				return errors.New("unexpected scope")
+			}
+			checked[selection] = value
+			return nil
+		},
+		Scopes: []Scope[input, *state]{{
+			Name: "app", Operations: []Operation{Show, Diff},
+			Acquire: func(context.Context, Request, input, *state) (commandkit.Acquired[View], error) {
+				acquireCalls++
+				return commandkit.Acquired[View]{}, errors.New("ordinary acquisition reached during comparison")
+			},
+			Compare: func(_ context.Context, pair ComparisonRequest[input], value *state) (commandkit.Acquired[[]configkit.Difference], error) {
+				compareCalls++
+				if checkCalls != 2 || stateCalls != 1 || value != shared {
+					t.Errorf("provider reached with checks=%d states=%d shared=%t", checkCalls, stateCalls, value == shared)
+				}
+				request = pair
+				return commandkit.Acquired[[]configkit.Difference]{}, nil
+			},
+		}},
+	}))
+	outcome := app.Execute(context.Background(), []string{
+		"config", "diff", "--config", "before.yml", "--against-overlay=",
+	}, commandkit.Streams{Out: io.Discard, Err: io.Discard})
+	if outcome.Kind != commandkit.OutcomeSuccess {
+		t.Fatalf("comparison outcome = %#v", outcome)
+	}
+	left := Selection{Config: commandkit.Supplied[string]{Value: "before.yml", Set: true}}
+	right := Selection{Config: left.Config, Overlay: commandkit.Supplied[string]{Set: true}}
+	if request.Left.Selection != left || request.Right.Selection != right {
+		t.Fatalf("provider selections = %#v", request)
+	}
+	if len(checked) != 2 || request.Left.Input != checked[left] || request.Right.Input != checked[right] {
+		t.Fatalf("provider inputs = %#v, checked = %#v", request, checked)
+	}
+	if inputCalls != 2 || checkCalls != 2 || stateCalls != 1 || compareCalls != 1 || acquireCalls != 0 {
+		t.Fatalf("invocation calls input=%d check=%d state=%d compare=%d acquire=%d", inputCalls, checkCalls, stateCalls, compareCalls, acquireCalls)
+	}
+}
+
+func TestComparisonDoesNotRetainPartialPlanAfterSideFailure(t *testing.T) {
+	checkCalls := 0
+	failure := errors.New("right input rejected")
+	prepared := captureSuite(Suite[struct{}, struct{}]{
+		CheckInput: func(string, Selection, struct{}) error {
+			checkCalls++
+			if checkCalls == 2 {
+				return failure
+			}
+			return nil
+		},
+		Scopes: []Scope[struct{}, struct{}]{{
+			Name: "app", Operations: []Operation{Diff},
+			Compare: func(context.Context, ComparisonRequest[struct{}], struct{}) (commandkit.Acquired[[]configkit.Difference], error) {
+				return commandkit.Acquired[[]configkit.Difference]{}, nil
+			},
+		}},
+	})
+	commandInput := &configCommandInput[struct{}, struct{}]{format: commandkit.Supplied[string]{Value: "yaml"}}
+	if err := prepareConfigOperation(prepared, Diff, commandInput); !errors.Is(err, failure) {
+		t.Fatalf("right-side input failure = %v", err)
+	}
+	if commandInput.plan != nil || checkCalls != 2 {
+		t.Fatalf("failed pair retained partial state: plan=%#v checks=%d", commandInput.plan, checkCalls)
+	}
+}
+
+func TestComparisonNilInputFactoryUsesZeroValue(t *testing.T) {
+	checkCalls := 0
+	prepared := captureSuite(Suite[*int, struct{}]{
+		CheckInput: func(_ string, _ Selection, value *int) error {
+			checkCalls++
+			if value != nil {
+				return errors.New("nil factory did not supply the zero value")
+			}
+			return nil
+		},
+		Scopes: []Scope[*int, struct{}]{{
+			Name: "app", Operations: []Operation{Diff},
+			Compare: func(context.Context, ComparisonRequest[*int], struct{}) (commandkit.Acquired[[]configkit.Difference], error) {
+				return commandkit.Acquired[[]configkit.Difference]{}, nil
+			},
+		}},
+	})
+	commandInput := &configCommandInput[*int, struct{}]{format: commandkit.Supplied[string]{Value: "yaml"}}
+	if err := prepareConfigOperation(prepared, Diff, commandInput); err != nil {
+		t.Fatal(err)
+	}
+	request := commandInput.plan.comparison.request
+	if checkCalls != 2 || request.Left.Input != nil || request.Right.Input != nil {
+		t.Fatalf("nil input value changed: checks=%d request=%#v", checkCalls, request)
+	}
+}
+
+func TestComparisonPreservesCallerOwnedInputAliases(t *testing.T) {
+	shared := new(int)
+	inputCalls, checkCalls := 0, 0
+	prepared := captureSuite(Suite[*int, struct{}]{
+		NewInput: func() *int { inputCalls++; return shared },
+		CheckInput: func(_ string, _ Selection, value *int) error {
+			checkCalls++
+			if value != shared {
+				return errors.New("caller-owned alias was replaced")
+			}
+			return nil
+		},
+		Scopes: []Scope[*int, struct{}]{{
+			Name: "app", Operations: []Operation{Diff},
+			Compare: func(context.Context, ComparisonRequest[*int], struct{}) (commandkit.Acquired[[]configkit.Difference], error) {
+				return commandkit.Acquired[[]configkit.Difference]{}, nil
+			},
+		}},
+	})
+	commandInput := &configCommandInput[*int, struct{}]{format: commandkit.Supplied[string]{Value: "yaml"}}
+	if err := prepareConfigOperation(prepared, Diff, commandInput); err != nil {
+		t.Fatal(err)
+	}
+	request := commandInput.plan.comparison.request
+	if inputCalls != 2 || checkCalls != 2 || request.Left.Input != shared || request.Right.Input != shared {
+		t.Fatalf("caller-owned alias changed: calls=%d/%d request=%#v", inputCalls, checkCalls, request)
+	}
+}
+
+func TestComparisonInputFailureStopsBeforeStateAndPreservesWiringClassification(t *testing.T) {
+	var inputCalls, checkCalls, stateCalls int
+	suite := Suite[struct{}, struct{}]{
+		NewInput: func() struct{} { inputCalls++; return struct{}{} },
+		NewState: func() struct{} { stateCalls++; return struct{}{} },
+		CheckInput: func(string, Selection, struct{}) error {
+			checkCalls++
+			if checkCalls == 2 {
+				return commandkit.ErrFlagWiring
+			}
+			return nil
+		},
+		Scopes: []Scope[struct{}, struct{}]{{
+			Name: "app", Operations: []Operation{Diff},
+			Compare: func(context.Context, ComparisonRequest[struct{}], struct{}) (commandkit.Acquired[[]configkit.Difference], error) {
+				return commandkit.Acquired[[]configkit.Difference]{}, nil
+			},
+		}},
+	}
+	app := newConfigTestApp(t, Command(suite))
+	outcome := app.Execute(context.Background(), []string{"config", "diff"}, commandkit.Streams{Out: io.Discard, Err: io.Discard})
+	if outcome.Kind != commandkit.OutcomeOperational || !errors.Is(outcome.Cause, commandkit.ErrFlagWiring) {
+		t.Fatalf("right-side wiring failure = %#v", outcome)
+	}
+	if !strings.Contains(outcome.Cause.Error(), `scope "app" right input`) {
+		t.Fatalf("right-side error lacks scope context: %v", outcome.Cause)
+	}
+	if inputCalls != 2 || checkCalls != 2 || stateCalls != 0 {
+		t.Fatalf("failed preparation calls input=%d check=%d state=%d", inputCalls, checkCalls, stateCalls)
+	}
+}
+
+func TestComparisonMissingRequiredSelectorIsUsageBeforeState(t *testing.T) {
+	type input struct{ Token commandkit.Supplied[string] }
+	var inputCalls, checkCalls, stateCalls int
+	token := commandkit.ValueFlag(commandkit.FlagMeta{Name: "token", Required: true}, (*string)(nil), parseConfigString, func(value *input, supplied commandkit.Supplied[string]) {
+		value.Token = supplied
+	})
+	suite := Suite[input, struct{}]{
+		NewInput:   func() input { inputCalls++; return input{} },
+		NewState:   func() struct{} { stateCalls++; return struct{}{} },
+		Selectors:  []Selector[input]{{Binding: token, Scopes: []string{"app"}}},
+		CheckInput: func(string, Selection, input) error { checkCalls++; return nil },
+		Scopes: []Scope[input, struct{}]{{
+			Name: "app", Operations: []Operation{Diff},
+			Compare: func(context.Context, ComparisonRequest[input], struct{}) (commandkit.Acquired[[]configkit.Difference], error) {
+				return commandkit.Acquired[[]configkit.Difference]{}, nil
+			},
+		}},
+	}
+	app := newConfigTestApp(t, Command(suite))
+	outcome := app.Execute(context.Background(), []string{"config", "diff"}, commandkit.Streams{Out: io.Discard, Err: io.Discard})
+	if outcome.Kind != commandkit.OutcomeUsage || !errors.Is(outcome.Cause, commandkit.ErrFlagInput) {
+		t.Fatalf("missing required selector = %#v", outcome)
+	}
+	if inputCalls != 1 || checkCalls != 0 || stateCalls != 0 {
+		t.Fatalf("missing selector calls input=%d check=%d state=%d", inputCalls, checkCalls, stateCalls)
+	}
+}
+
+func TestComparisonHelpConvertsInapplicableSelectorsWithoutBuildingInputs(t *testing.T) {
+	type input struct{ Tenant int }
+	parseErr := errors.New("invalid tenant")
+	var parseCalls, inputCalls, checkCalls, stateCalls int
+	tenant := commandkit.ValueFlag(commandkit.FlagMeta{Name: "tenant", Required: true}, (*int)(nil), func(raw string) (int, error) {
+		parseCalls++
+		if raw == "bad" {
+			return 0, parseErr
+		}
+		return strconv.Atoi(raw)
+	}, func(value *input, supplied commandkit.Supplied[int]) {
+		value.Tenant = supplied.Value
+	})
+	makeScope := func(name string) Scope[input, struct{}] {
+		return Scope[input, struct{}]{Name: name, Operations: []Operation{Diff}, Compare: func(context.Context, ComparisonRequest[input], struct{}) (commandkit.Acquired[[]configkit.Difference], error) {
+			return commandkit.Acquired[[]configkit.Difference]{}, nil
+		}}
+	}
+	suite := Suite[input, struct{}]{
+		NewInput:   func() input { inputCalls++; return input{} },
+		NewState:   func() struct{} { stateCalls++; return struct{}{} },
+		Selectors:  []Selector[input]{{Binding: tenant, Scopes: []string{"promptkit"}}},
+		CheckInput: func(string, Selection, input) error { checkCalls++; return nil },
+		Scopes:     []Scope[input, struct{}]{makeScope("app"), makeScope("promptkit")},
+	}
+	app := newConfigTestApp(t, Command(suite))
+	var output strings.Builder
+	app.Execute(context.Background(), []string{"config", "diff", "--scope", "app", "--tenant=7", "--help"}, commandkit.Streams{Out: &output, Err: io.Discard})
+	if !strings.Contains(output.String(), "--tenant") || parseCalls != 1 {
+		t.Fatalf("help did not convert the inapplicable supplied selector: calls=%d help=%q", parseCalls, output.String())
+	}
+	outcome := app.Execute(context.Background(), []string{"config", "diff", "--scope", "app", "--tenant=bad", "--help"}, commandkit.Streams{Out: io.Discard, Err: io.Discard})
+	if outcome.Kind != commandkit.OutcomeUsage || !errors.Is(outcome.Cause, parseErr) || parseCalls != 2 {
+		t.Fatalf("malformed help selector outcome=%#v conversions=%d", outcome, parseCalls)
+	}
+	if inputCalls != 0 || checkCalls != 0 || stateCalls != 0 {
+		t.Fatalf("help built suite work: input=%d check=%d state=%d", inputCalls, checkCalls, stateCalls)
+	}
+}

integrations/ckconfig/completion.go

@@ -0,0 +1,11 @@
+package ckconfig
+
+import commandkit "go.maximumdirect.net/commandkit"
+
+func completionChoices(values ...string) commandkit.CompletionHint {
+	choices := make([]commandkit.CompletionChoice, len(values))
+	for i, value := range values {
+		choices[i].Value = value
+	}
+	return commandkit.CompleteChoices(choices...)
+}

integrations/ckconfig/completion_test.go

@@ -0,0 +1,66 @@
+package ckconfig
+
+import (
+	"bytes"
+	"context"
+	"io"
+	"strings"
+	"testing"
+
+	configkit "gitea.maximumdirect.net/eric/ConfigKit"
+	commandkit "go.maximumdirect.net/commandkit"
+)
+
+func TestCompletionUsesInstalledScopeCapabilitiesWithoutAcquisition(t *testing.T) {
+	var inputs, states, acquisitions, comparisons int
+	suite := Suite[struct{}, struct{}]{
+		NewInput: func() struct{} { inputs++; return struct{}{} },
+		NewState: func() struct{} { states++; return struct{}{} },
+		Scopes: []Scope[struct{}, struct{}]{
+			{Name: "app", Operations: []Operation{Diff}, Compare: func(context.Context, ComparisonRequest[struct{}], struct{}) (commandkit.Acquired[[]configkit.Difference], error) {
+				comparisons++
+				return commandkit.Acquired[[]configkit.Difference]{}, nil
+			}},
+			{Name: "other", Operations: []Operation{Validate}, Acquire: func(context.Context, Request, struct{}, struct{}) (commandkit.Acquired[View], error) {
+				acquisitions++
+				return commandkit.Acquired[View]{}, nil
+			}},
+		},
+	}
+	app, err := commandkit.New(commandkit.Identity{Name: "example"}, Command(suite), commandkit.Completion("example"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, tc := range []struct {
+		args           []string
+		contains, omit string
+	}{
+		{[]string{"__complete", "config", "diff", "--scope="}, "app\n", "other\n"},
+		{[]string{"__complete", "config", "validate", "--scope="}, "other\n", "all\n"},
+		{[]string{"__complete", "config", "diff", "--format="}, "yaml\n", "text\n"},
+		{[]string{"__complete", "config", "validate", "--format="}, "text\n", "invalid\n"},
+		{[]string{"__complete", "config", "diff", "--against-config=fixtures/"}, ":0\n", ":4\n"},
+	} {
+		var output bytes.Buffer
+		outcome := app.Execute(context.Background(), tc.args, commandkit.Streams{Out: &output, Err: io.Discard})
+		if outcome.Status != 0 || !strings.Contains(output.String(), tc.contains) || strings.Contains(output.String(), tc.omit) {
+			t.Fatalf("query %q outcome=%#v output=%q", tc.args, outcome, output.String())
+		}
+	}
+	allSuite := Suite[struct{}, struct{}]{Scopes: []Scope[struct{}, struct{}]{
+		{Name: "app", Operations: []Operation{Validate}, Acquire: suite.Scopes[1].Acquire},
+		{Name: "other", Operations: []Operation{Validate}, Acquire: suite.Scopes[1].Acquire},
+	}}
+	allApp, err := commandkit.New(commandkit.Identity{Name: "example"}, Command(allSuite), commandkit.Completion("example"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	var allOutput bytes.Buffer
+	allOutcome := allApp.Execute(context.Background(), []string{"__complete", "config", "validate", "--scope="}, commandkit.Streams{Out: &allOutput})
+	if allOutcome.Status != 0 || !strings.Contains(allOutput.String(), "all\n") {
+		t.Fatalf("all-scope query outcome=%#v output=%q", allOutcome, allOutput.String())
+	}
+	if inputs != 0 || states != 0 || acquisitions != 0 || comparisons != 0 {
+		t.Fatalf("completion ran suite work: %d %d %d %d", inputs, states, acquisitions, comparisons)
+	}
+}

integrations/ckconfig/configkit_adapter.go

@@ -0,0 +1,213 @@
+package ckconfig
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"strconv"
+
+	configkit "gitea.maximumdirect.net/eric/ConfigKit"
+	commandkit "go.maximumdirect.net/commandkit"
+)
+
+// FromConfigKit adapts a typed ConfigKit loader to all five native
+// configuration operations. The loader receives the operation's explicit
+// Selection, initialized input, and shared invocation state, and runs only when
+// an installed operation selects this scope. Comparison invokes it separately
+// for each reached side. Construction and help do not call it. A nil original
+// loader is retained as a construction issue, even if callers later narrow the
+// scope's operation list.
+func FromConfigKit[I, S, T any](
+	name, summary string,
+	load func(context.Context, Selection, I, S) (*configkit.Result[T], error),
+) Scope[I, S] {
+	scope := Scope[I, S]{
+		Name:       name,
+		Summary:    summary,
+		Operations: []Operation{Validate, Show, Sources, Explain, Diff},
+	}
+	if load == nil {
+		return WithScopeError(scope, fmt.Errorf("ConfigKit scope %q loader must not be nil", name))
+	}
+
+	scope.Acquire = func(ctx context.Context, request Request, input I, state S) (commandkit.Acquired[View], error) {
+		result, err := load(ctx, request.Selection, input, state)
+		acquired := commandkit.Acquired[View]{}
+		if result != nil {
+			acquired.Value = View{Effective: result, Sources: result, Explanation: result}
+			acquired.Diagnostics, acquired.Explanation = configKitDiagnostics(name, result.Sources(), result.Diagnostics())
+		}
+		if err != nil {
+			var loadError *configkit.LoadError
+			if errors.As(err, &loadError) && loadError != nil {
+				warnings, explanation := configKitDiagnostics(name, loadError.Sources(), loadError.Diagnostics())
+				acquired.Diagnostics = append(acquired.Diagnostics, warnings...)
+				acquired.Explanation = appendConfigKitExplanation(acquired.Explanation, explanation)
+			}
+			return acquired, err
+		}
+		if result == nil {
+			return commandkit.Acquired[View]{}, fmt.Errorf("ConfigKit scope %q returned a nil result", name)
+		}
+		return acquired, nil
+	}
+	scope.Compare = func(ctx context.Context, request ComparisonRequest[I], state S) (commandkit.Acquired[[]configkit.Difference], error) {
+		if err := ctx.Err(); err != nil {
+			return commandkit.Acquired[[]configkit.Difference]{}, fmt.Errorf("ConfigKit scope %q comparison before left load: %w", name, err)
+		}
+
+		acquired := commandkit.Acquired[[]configkit.Difference]{}
+		left, leftDiagnostics, leftExplanation, err := loadComparisonSide(ctx, name, "left", load, request.Left, state)
+		acquired.Diagnostics = append(acquired.Diagnostics, leftDiagnostics...)
+		acquired.Explanation = appendConfigKitExplanation(acquired.Explanation, leftExplanation)
+		if err != nil {
+			return acquired, err
+		}
+
+		if err := ctx.Err(); err != nil {
+			return acquired, fmt.Errorf("ConfigKit scope %q comparison after left load: %w", name, err)
+		}
+
+		right, rightDiagnostics, rightExplanation, err := loadComparisonSide(ctx, name, "right", load, request.Right, state)
+		acquired.Diagnostics = append(acquired.Diagnostics, rightDiagnostics...)
+		acquired.Explanation = appendConfigKitExplanation(acquired.Explanation, rightExplanation)
+		if err != nil {
+			return acquired, err
+		}
+
+		if err := ctx.Err(); err != nil {
+			return acquired, fmt.Errorf("ConfigKit scope %q comparison before native diff: %w", name, err)
+		}
+
+		acquired.Value, err = configkit.Diff(left, right)
+		if err != nil {
+			return acquired, fmt.Errorf("ConfigKit scope %q native diff: %w", name, err)
+		}
+		return acquired, nil
+	}
+	return scope
+}
+
+func loadComparisonSide[I, S, T any](
+	ctx context.Context,
+	scope, side string,
+	load func(context.Context, Selection, I, S) (*configkit.Result[T], error),
+	request ComparisonSide[I],
+	state S,
+) (*configkit.Result[T], []commandkit.Diagnostic, commandkit.Explanation, error) {
+	result, err := load(ctx, request.Selection, request.Input, state)
+	var diagnostics []commandkit.Diagnostic
+	var explanation commandkit.Explanation
+	if result != nil {
+		warnings, terminal := configKitComparisonDiagnostics(scope, side, result.Sources(), result.Diagnostics())
+		diagnostics = append(diagnostics, warnings...)
+		explanation = appendConfigKitExplanation(explanation, terminal)
+	}
+	if err != nil {
+		var loadError *configkit.LoadError
+		if errors.As(err, &loadError) && loadError != nil {
+			warnings, terminal := configKitComparisonDiagnostics(scope, side, loadError.Sources(), loadError.Diagnostics())
+			diagnostics = append(diagnostics, warnings...)
+			explanation = appendConfigKitExplanation(explanation, terminal)
+		}
+		return result, diagnostics, explanation, fmt.Errorf("ConfigKit scope %q %s load: %w", scope, side, err)
+	}
+	if result == nil {
+		return nil, diagnostics, explanation, fmt.Errorf("ConfigKit scope %q %s loader returned a nil result", scope, side)
+	}
+	return result, diagnostics, explanation, nil
+}
+
+func configKitDiagnostics(scope string, sources []configkit.SourceInfo, records []configkit.Diagnostic) ([]commandkit.Diagnostic, commandkit.Explanation) {
+	return configKitDiagnosticsWithHeading("Configuration scope "+strconv.Quote(scope)+":\n", sources, records)
+}
+
+func configKitComparisonDiagnostics(scope, side string, sources []configkit.SourceInfo, records []configkit.Diagnostic) ([]commandkit.Diagnostic, commandkit.Explanation) {
+	return configKitDiagnosticsWithHeading("Configuration scope "+strconv.Quote(scope)+" "+side+":\n", sources, records)
+}
+
+func configKitDiagnosticsWithHeading(heading string, sources []configkit.SourceInfo, records []configkit.Diagnostic) ([]commandkit.Diagnostic, commandkit.Explanation) {
+	if len(records) == 0 {
+		return nil, commandkit.Explanation{}
+	}
+
+	sources = append([]configkit.SourceInfo(nil), sources...)
+	records = cloneConfigKitDiagnostics(records)
+	warnings := make([]configkit.Diagnostic, 0, len(records))
+	terminal := make([]configkit.Diagnostic, 0, len(records))
+	for _, record := range records {
+		if record.Severity == configkit.SeverityError {
+			terminal = append(terminal, record)
+		} else {
+			warnings = append(warnings, record)
+		}
+	}
+
+	if len(warnings) == 0 {
+		return nil, explanationWithConfigKitRecords(heading, sources, terminal)
+	}
+	warning := commandkit.Diagnostic{
+		Severity: commandkit.SeverityWarning,
+		Write:    configKitDiagnosticWriter(heading, sources, warnings),
+	}
+	return []commandkit.Diagnostic{warning}, explanationWithConfigKitRecords(heading, sources, terminal)
+}
+
+func explanationWithConfigKitRecords(heading string, sources []configkit.SourceInfo, records []configkit.Diagnostic) commandkit.Explanation {
+	if len(records) == 0 {
+		return commandkit.Explanation{}
+	}
+	return commandkit.Explanation{Details: []commandkit.Detail{configKitDiagnosticWriter(heading, sources, records)}}
+}
+
+func configKitDiagnosticWriter(heading string, sources []configkit.SourceInfo, records []configkit.Diagnostic) commandkit.Detail {
+	return func(writer io.Writer) error {
+		if err := writeDiagnosticText(writer, heading); err != nil {
+			return err
+		}
+		if len(sources) > 0 {
+			if err := writeDiagnosticText(writer, "Source IDs:\n"); err != nil {
+				return err
+			}
+			for _, source := range sources {
+				line := "  " + strconv.Quote(source.ID) + ": label=" + strconv.Quote(source.Label) + ", path=" + strconv.Quote(source.Path) + "\n"
+				if err := writeDiagnosticText(writer, line); err != nil {
+					return err
+				}
+			}
+		}
+		return configkit.WriteDiagnostics(writer, records)
+	}
+}
+
+func cloneConfigKitDiagnostics(records []configkit.Diagnostic) []configkit.Diagnostic {
+	cloned := append([]configkit.Diagnostic(nil), records...)
+	for index := range cloned {
+		if records[index].Primary != nil {
+			primary := *records[index].Primary
+			cloned[index].Primary = &primary
+		}
+		cloned[index].Related = append([]configkit.Location(nil), records[index].Related...)
+	}
+	return cloned
+}
+
+func appendConfigKitExplanation(left, right commandkit.Explanation) commandkit.Explanation {
+	if left.Message == "" {
+		left.Message = right.Message
+	}
+	left.Details = append(left.Details, right.Details...)
+	return left
+}
+
+func writeDiagnosticText(writer io.Writer, value string) error {
+	written, err := io.WriteString(writer, value)
+	if err != nil {
+		return err
+	}
+	if written != len(value) {
+		return io.ErrShortWrite
+	}
+	return nil
+}

integrations/ckconfig/contracts.go

@@ -0,0 +1,163 @@
+package ckconfig
+
+import (
+	"context"
+	"io"
+
+	configkit "gitea.maximumdirect.net/eric/ConfigKit"
+	commandkit "go.maximumdirect.net/commandkit"
+)
+
+// Selection carries the configuration and overlay choices supplied for a
+// configuration scope.
+type Selection struct {
+	// Config is the caller-supplied configuration path, if present.
+	Config commandkit.Supplied[string]
+	// Overlay is the caller-supplied overlay path, if present.
+	Overlay commandkit.Supplied[string]
+}
+
+// Operation identifies a supported standard configuration operation.
+type Operation string
+
+const (
+	// Validate checks the selected configuration and reports diagnostics.
+	Validate Operation = "validate"
+	// Show writes the selected configuration's effective form.
+	Show Operation = "show"
+	// Sources reports the selected configuration's input sources.
+	Sources Operation = "sources"
+	// Explain reports the history and provenance of a selected path.
+	Explain Operation = "explain"
+	// Diff compares two selections of the same configuration scope.
+	Diff Operation = "diff"
+)
+
+// Request describes one configuration operation and its selected inputs.
+type Request struct {
+	// Operation identifies the requested inspection operation.
+	Operation Operation
+	// Selection carries the explicit config and overlay inputs.
+	Selection Selection
+}
+
+// ComparisonSide groups one configuration selection with its independently
+// initialized and checked typed input. The supplied-state fields of Selection
+// are preserved for the scope's loader.
+type ComparisonSide[I any] struct {
+	// Selection carries the explicit config and overlay inputs for this side.
+	Selection Selection
+	// Input is initialized and checked for this side before comparison.
+	Input I
+}
+
+// ComparisonRequest carries the earlier and later selections supplied to a
+// scope's comparison callback. Each side has a separately prepared input; the
+// callback receives shared invocation state separately.
+type ComparisonRequest[I any] struct {
+	// Left is the earlier configuration selection.
+	Left ComparisonSide[I]
+	// Right is the later configuration selection.
+	Right ComparisonSide[I]
+}
+
+// EffectiveWriter writes a configuration's native effective representation.
+type EffectiveWriter interface {
+	WriteEffective(io.Writer) error
+}
+
+// SourceReader reports the native source inventory for a configuration.
+type SourceReader interface {
+	Sources() []configkit.SourceInfo
+}
+
+// ExplanationReader reads and writes a configuration's native path explanation.
+type ExplanationReader interface {
+	Explain(configkit.Path) (configkit.Explanation, bool)
+	WriteExplanation(io.Writer, configkit.Path) error
+}
+
+// View exposes native configuration facets without reconstructing their
+// reports.
+type View struct {
+	Effective   EffectiveWriter
+	Sources     SourceReader
+	Explanation ExplanationReader
+}
+
+// Scope declares the operations and providers for one named configuration.
+// Ordinary inspection operations use Acquire; Diff uses Compare and does not
+// require Acquire unless an ordinary operation is also declared. Construction
+// issues are retained privately until family assembly attaches them to its
+// command declaration.
+type Scope[I, S any] struct {
+	// Name identifies the scope in CLI selection and reports.
+	Name string
+	// Summary describes the scope. Scope discovery reports name and operations only.
+	Summary string
+	// Operations selects the standard handlers exposed for this scope.
+	Operations []Operation
+	// Acquire loads the selected configuration for one ordinary inspection
+	// invocation. It returns independent diagnostics and terminal context
+	// separately from the native value and optional operation error.
+	Acquire func(context.Context, Request, I, S) (commandkit.Acquired[View], error)
+	// Compare compares two selections for this scope using one shared state.
+	// Its Acquired result carries native difference records, independent
+	// diagnostics, and terminal context; returned errors retain their supported
+	// cause identity. It is required when Diff is declared in Operations.
+	Compare func(context.Context, ComparisonRequest[I], S) (commandkit.Acquired[[]configkit.Difference], error)
+
+	issues []error
+}
+
+// Selector binds a typed flag to the configuration scopes that use it.
+type Selector[I any] struct {
+	// Binding is the original typed flag handle captured by the suite.
+	Binding commandkit.Flag[I]
+	// Scopes lists the scope names that receive this flag's value.
+	Scopes []string
+}
+
+// Suite declares the typed input, shared state, selectors, and configuration
+// scopes used to assemble configuration commands.
+//
+// Input initialization is separate for each selected ordinary scope and each
+// reached comparison side; state is shared by the invocation's acquisitions or
+// comparison callback. Factory results and callback effects remain
+// caller-owned: Command does not deep-copy arbitrary objects or repair aliases
+// returned by factories. Core-owned repeated flag collections are copied when
+// applied to separate inputs. Factories are not invoked during construction,
+// installation, help, version, or scope discovery, and need not run after failure.
+type Suite[I, S any] struct {
+	// NewInput is called once for each selected ordinary scope, or once for each
+	// reached side of a comparison, after operation preflight and before applying
+	// selectors and calling CheckInput.
+	// If nil, input is the zero value of I, including nil for pointer types.
+	NewInput func() I
+	// NewState is called once when provider execution is reached, after all
+	// selected inputs pass their checks. The result is shared by selected
+	// acquisitions or the comparison callback.
+	// If nil, state is the zero value of S, including nil for pointer types.
+	NewState func() S
+	// Selectors declares typed flags and their applicable scopes.
+	Selectors []Selector[I]
+	// CheckInput validates one initialized scope input after applicable values
+	// are applied. Comparison sides are checked separately with their selection.
+	CheckInput func(scope string, selection Selection, input I) error
+	// Scopes declares the configuration scopes assembled by Command.
+	Scopes []Scope[I, S]
+}
+
+// WithScopeError returns a copy of scope that retains err as a construction
+// issue for ckconfig.Command to report during installation. Existing issues
+// remain available to family assembly, and scope is not mutated. A nil error
+// returns scope unchanged.
+func WithScopeError[I, S any](scope Scope[I, S], err error) Scope[I, S] {
+	if err == nil {
+		return scope
+	}
+	issues := make([]error, len(scope.issues), len(scope.issues)+1)
+	copy(issues, scope.issues)
+	scope.issues = append(issues, err)
+	return scope
+}

integrations/ckconfig/contracts_adapter_test.go

@@ -0,0 +1,276 @@
+package ckconfig
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"strings"
+	"testing"
+
+	configkit "gitea.maximumdirect.net/eric/ConfigKit"
+	commandkit "go.maximumdirect.net/commandkit"
+)
+
+func TestWithScopeErrorCopiesAndRetainsCauses(t *testing.T) {
+	first := &scopeCause{message: "first construction problem"}
+	second := errors.New("second construction problem")
+	original := Scope[struct{}, struct{}]{issues: []error{fmt.Errorf("wrapped: %w", first)}}
+
+	copyWithError := WithScopeError(original, second)
+	if len(original.issues) != 1 || !errors.Is(original.issues[0], first) {
+		t.Fatalf("original issues changed: %#v", original.issues)
+	}
+	if len(copyWithError.issues) != 2 || !errors.Is(copyWithError.issues[0], first) || !errors.Is(copyWithError.issues[1], second) {
+		t.Fatalf("attached issues = %#v", copyWithError.issues)
+	}
+	if copyWithError.issues[0] != original.issues[0] {
+		t.Fatal("existing cause identity was not preserved")
+	}
+	var retained *scopeCause
+	if !errors.As(copyWithError.issues[0], &retained) || retained != first {
+		t.Fatalf("retained concrete cause = %#v, want %#v", retained, first)
+	}
+
+	narrowed := copyWithError
+	narrowed.Operations = nil
+	third := errors.New("third construction problem")
+	withThird := WithScopeError(narrowed, third)
+	unchanged := WithScopeError(withThird, nil)
+	if len(unchanged.issues) != len(copyWithError.issues)+1 || !errors.Is(unchanged.issues[2], third) {
+		t.Fatalf("repeated attachment lost issues: %#v", unchanged.issues)
+	}
+}
+
+type scopeCause struct{ message string }
+
+func (e *scopeCause) Error() string { return e.message }
+
+func TestFromConfigKitRetainsNilLoaderIssue(t *testing.T) {
+	scope := FromConfigKit[struct{}, struct{}, struct{}]("app", "Application configuration", nil)
+	scope.Operations = nil
+	if scope.Acquire != nil {
+		t.Fatal("nil loader produced an acquisition callback")
+	}
+	if len(scope.issues) != 1 || !strings.Contains(scope.issues[0].Error(), "loader") {
+		t.Fatalf("retained nil-loader issues = %#v", scope.issues)
+	}
+}
+
+func TestFromConfigKitPassesInvocationValuesAndNativeFacets(t *testing.T) {
+	type input struct{ Label string }
+	type state struct{ Calls int }
+	type settings struct {
+		Name string `yaml:"name"`
+	}
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+	selection := Selection{
+		Config:  commandkit.Supplied[string]{Value: "chosen.yaml", Set: true},
+		Overlay: commandkit.Supplied[string]{Value: "", Set: true},
+	}
+	gotContext, gotSelection, gotInput, gotState := context.Context(nil), Selection{}, input{}, (*state)(nil)
+	result, err := configkit.Load(configkit.Mapping("source.yaml", map[string]any{"name": "native"}), configkit.Options[settings]{Definition: configkit.Definition[settings]{}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	scope := FromConfigKit[input, *state, settings]("app", "Application configuration", func(got context.Context, selected Selection, in input, st *state) (*configkit.Result[settings], error) {
+		gotContext, gotSelection, gotInput, gotState = got, selected, in, st
+		st.Calls++
+		return result, nil
+	})
+	if len(scope.Operations) != 5 || scope.Operations[0] != Validate || scope.Operations[1] != Show || scope.Operations[2] != Sources || scope.Operations[3] != Explain || scope.Operations[4] != Diff {
+		t.Fatalf("operations = %#v", scope.Operations)
+	}
+	if gotContext != nil {
+		t.Fatal("loader ran during adapter construction")
+	}
+	stateValue := &state{}
+	acquired, err := scope.Acquire(ctx, Request{Operation: Show, Selection: selection}, input{Label: "typed"}, stateValue)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if gotContext != ctx || gotSelection != selection || gotInput.Label != "typed" || gotState != stateValue || stateValue.Calls != 1 {
+		t.Fatalf("loader arguments/context/state = %v, %#v, %#v, %p, %d", gotContext, gotSelection, gotInput, gotState, stateValue.Calls)
+	}
+	if acquired.Value.Effective != result || acquired.Value.Sources != result || acquired.Value.Explanation != result {
+		t.Fatal("adapter did not expose the native result facets directly")
+	}
+
+	var effective bytes.Buffer
+	if err := acquired.Value.Effective.WriteEffective(&effective); err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(effective.String(), "name: native") {
+		t.Fatalf("native effective output = %q", effective.String())
+	}
+	sources := acquired.Value.Sources.Sources()
+	if len(sources) != 1 || sources[0].Label != "source.yaml" {
+		t.Fatalf("native sources = %#v", sources)
+	}
+	path, err := configkit.ParsePath("/name")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, ok := acquired.Value.Explanation.Explain(path); !ok {
+		t.Fatal("native explanation facet did not resolve /name")
+	}
+	var explanation bytes.Buffer
+	if err := acquired.Value.Explanation.WriteExplanation(&explanation, path); err != nil {
+		t.Fatal(err)
+	}
+	if explanation.Len() == 0 {
+		t.Fatal("native explanation writer produced no output")
+	}
+}
+
+func TestFromConfigKitRetainsLoadErrorAndDiagnostics(t *testing.T) {
+	path := configkit.Keys("schema_version")
+	_, loadErr := configkit.Load(configkit.Bytes("bad source", []byte("{}\n")), configkit.Options[struct{}]{
+		Definition: configkit.Definition[struct{}]{Version: &configkit.VersionRule{
+			Path: path,
+			Check: func(_ configkit.Version, validation *configkit.Validation) error {
+				validation.Warning(path, "review schema compatibility")
+				return errors.New("private checker error")
+			},
+		}},
+	})
+	if loadErr == nil {
+		t.Fatal("fixture did not produce a ConfigKit load error")
+	}
+	scope := FromConfigKit[struct{}, struct{}, struct{}]("app", "", func(context.Context, Selection, struct{}, struct{}) (*configkit.Result[struct{}], error) {
+		return nil, loadErr
+	})
+	acquired, gotErr := scope.Acquire(context.Background(), Request{}, struct{}{}, struct{}{})
+	if gotErr != loadErr {
+		t.Fatalf("load error identity = %v, want original %v", gotErr, loadErr)
+	}
+	var typed *configkit.LoadError
+	if !errors.As(gotErr, &typed) {
+		t.Fatalf("load error type was not retained: %T", gotErr)
+	}
+	if len(acquired.Diagnostics) != 1 || acquired.Diagnostics[0].Severity != commandkit.SeverityWarning {
+		t.Fatalf("failure diagnostics = %#v", acquired.Diagnostics)
+	}
+	if acquired.Explanation.Message != "" || len(acquired.Explanation.Details) != 1 {
+		t.Fatalf("failure explanation = %#v", acquired.Explanation)
+	}
+	var warning, terminal bytes.Buffer
+	if err := acquired.Diagnostics[0].Write(&warning); err != nil {
+		t.Fatal(err)
+	}
+	if err := acquired.Explanation.Details[0](&terminal); err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(warning.String(), `Configuration scope "app":`) || !strings.Contains(warning.String(), `review schema compatibility`) {
+		t.Fatalf("warning output lost its scope or record: %q", warning.String())
+	}
+	if !strings.Contains(terminal.String(), `Configuration scope "app":`) || !strings.Contains(terminal.String(), `"bad source"`) || strings.Contains(terminal.String(), "review schema compatibility") {
+		t.Fatalf("terminal explanation lost native context or included an independent warning: %q", terminal.String())
+	}
+	if strings.Contains(terminal.String(), "private checker error") {
+		t.Fatalf("terminal explanation exposed the upstream cause: %q", terminal.String())
+	}
+}
+
+func TestFromConfigKitPreservesValueAndDiagnosticsAlongsideError(t *testing.T) {
+	result, err := adapterSettingsLoad(configkit.Mapping("partial source", map[string]any{"greeting": "Hello"}))
+	if err != nil {
+		t.Fatal(err)
+	}
+	loadErr := errors.New("loader returned a value with an error")
+	scope := FromConfigKit[struct{}, struct{}, adapterSettings]("app", "", func(context.Context, Selection, struct{}, struct{}) (*configkit.Result[adapterSettings], error) {
+		return result, loadErr
+	})
+
+	acquired, gotErr := scope.Acquire(context.Background(), Request{}, struct{}{}, struct{}{})
+	if gotErr != loadErr {
+		t.Fatalf("load error identity = %v, want %v", gotErr, loadErr)
+	}
+	if acquired.Value.Effective != result || acquired.Value.Sources != result || acquired.Value.Explanation != result {
+		t.Fatalf("acquired value facets were lost: %#v", acquired.Value)
+	}
+	if len(acquired.Diagnostics) != 1 || acquired.Diagnostics[0].Severity != commandkit.SeverityWarning {
+		t.Fatalf("independent diagnostics = %#v", acquired.Diagnostics)
+	}
+	if len(acquired.Explanation.Details) != 0 {
+		t.Fatalf("warning-only result acquired terminal context: %#v", acquired.Explanation)
+	}
+}
+
+func TestConfigKitDiagnosticsMapSeverityAndPropagateWriterFailures(t *testing.T) {
+	warning, noExplanation := configKitDiagnostics("app", nil, []configkit.Diagnostic{{Severity: configkit.SeverityWarning, Message: "safe warning"}})
+	if len(warning) != 1 || warning[0].Severity != commandkit.SeverityWarning {
+		t.Fatalf("warning diagnostics = %#v", warning)
+	}
+	if noExplanation.Message != "" || len(noExplanation.Details) != 0 {
+		t.Fatalf("warning-only explanation = %#v", noExplanation)
+	}
+	withWarning, withExplanation := configKitDiagnostics("app", nil, []configkit.Diagnostic{
+		{Severity: configkit.SeverityWarning, Message: "safe warning"},
+		{Severity: configkit.SeverityError, Message: "safe error"},
+	})
+	if len(withWarning) != 1 || withWarning[0].Severity != commandkit.SeverityWarning || len(withExplanation.Details) != 1 {
+		t.Fatalf("mixed diagnostics = %#v, explanation = %#v", withWarning, withExplanation)
+	}
+
+	if err := withWarning[0].Write(shortWriter{}); !errors.Is(err, io.ErrShortWrite) {
+		t.Fatalf("short writer error = %v, want %v", err, io.ErrShortWrite)
+	}
+	if err := withExplanation.Details[0](shortWriter{}); !errors.Is(err, io.ErrShortWrite) {
+		t.Fatalf("terminal short writer error = %v, want %v", err, io.ErrShortWrite)
+	}
+	wantErr := errors.New("writer failed")
+	if err := withWarning[0].Write(failingWriter{err: wantErr}); !errors.Is(err, wantErr) {
+		t.Fatalf("writer error = %v, want %v", err, wantErr)
+	}
+	if err := withExplanation.Details[0](failingWriter{err: wantErr}); !errors.Is(err, wantErr) {
+		t.Fatalf("terminal writer error = %v, want %v", err, wantErr)
+	}
+
+}
+
+func TestConfigKitTerminalContextRetainsRelatedLocationsAndSnapshots(t *testing.T) {
+	primary := &configkit.Location{SourceID: "primary-source", Line: 4, Column: 2}
+	related := []configkit.Location{{SourceID: "related-source", Line: 2, Column: 1}}
+	sources := []configkit.SourceInfo{
+		{ID: "primary-source", Label: "primary", Path: "primary.yml"},
+		{ID: "related-source", Label: "related", Path: "related.yml"},
+	}
+	records := []configkit.Diagnostic{{
+		Severity: configkit.SeverityError,
+		Path:     configkit.Keys("name"),
+		Message:  "native terminal context",
+		Primary:  primary,
+		Related:  related,
+	}}
+	_, explanation := configKitDiagnostics("app", sources, records)
+	primary.SourceID = "mutated-primary"
+	related[0].SourceID = "mutated-related"
+	sources[0].Path = "mutated.yml"
+
+	if len(explanation.Details) != 1 {
+		t.Fatalf("explanation = %#v", explanation)
+	}
+	var output bytes.Buffer
+	if err := explanation.Details[0](&output); err != nil {
+		t.Fatal(err)
+	}
+	for _, fragment := range []string{"primary.yml", "primary-source", "related-source", "native terminal context"} {
+		if !strings.Contains(output.String(), fragment) {
+			t.Errorf("terminal context %q omits %q", output.String(), fragment)
+		}
+	}
+	if strings.Contains(output.String(), "mutated-") || strings.Contains(output.String(), "mutated.yml") {
+		t.Fatalf("terminal renderer retained caller mutations: %q", output.String())
+	}
+}
+
+type shortWriter struct{}
+
+func (shortWriter) Write(value []byte) (int, error) { return len(value) - 1, nil }
+
+type failingWriter struct{ err error }
+
+func (w failingWriter) Write([]byte) (int, error) { return 0, w.err }

integrations/ckconfig/diff.go

@@ -0,0 +1,36 @@
+package ckconfig
+
+import (
+	"errors"
+	"fmt"
+
+	commandkit "go.maximumdirect.net/commandkit"
+)
+
+func runConfigDiff[I, S any](invocation commandkit.Invocation, plan *configOperationPlan[I, S], state S) commandkit.Outcome {
+	if plan.comparison == nil || plan.comparison.scope == nil {
+		cause := errors.New("configuration comparison was not prepared")
+		return configFailure("Configuration comparison was not prepared.", commandkit.Explanation{}, cause)
+	}
+	selected := plan.comparison
+	if err := invocation.Context.Err(); err != nil {
+		return configFailure("Configuration comparison was canceled.", commandkit.Explanation{}, err)
+	}
+	compare := selected.scope.scope.Compare
+	if compare == nil {
+		cause := fmt.Errorf("configuration scope %q has no comparison callback", selected.scope.scope.Name)
+		return configFailure("Configuration scope does not support comparison.", commandkit.Explanation{}, cause)
+	}
+	acquired, err := compare(invocation.Context, selected.request, state)
+	reporter := invocation.Reporter()
+	queueConfigDiagnostics(reporter, acquired.Diagnostics)
+	if err != nil {
+		return configFailure(fmt.Sprintf("Unable to compare configuration scope %q.", selected.scope.scope.Name), acquired.Explanation, err)
+	}
+	if err := invocation.Context.Err(); err != nil {
+		return configFailure("Configuration comparison was canceled.", acquired.Explanation, err)
+	}
+	return renderPreparedConfigReport(invocation, acquired.Explanation, func() ([]byte, error) {
+		return renderDiffReport(acquired.Value)
+	})
+}

integrations/ckconfig/diff_execution_test.go

@@ -0,0 +1,288 @@
+package ckconfig
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"strings"
+	"testing"
+
+	configkit "gitea.maximumdirect.net/eric/ConfigKit"
+	commandkit "go.maximumdirect.net/commandkit"
+	"go.yaml.in/yaml/v4"
+)
+
+func TestConfigDiffExecutesWithDefaultAndExplicitYAMLAndInheritedSelections(t *testing.T) {
+	type settings struct {
+		Greeting string `yaml:"greeting"`
+	}
+	var selections []Selection
+	app := newConfigTestApp(t, AppCommand(func(_ context.Context, selection Selection) (*configkit.Result[settings], error) {
+		selections = append(selections, selection)
+		value := "Hello"
+		if selection.Config.Set && selection.Config.Value == "after.yml" {
+			value = "Goodbye"
+		}
+		return configkit.Load(configkit.Mapping("selected configuration", map[string]any{"greeting": value}), configkit.Options[settings]{})
+	}))
+	var output bytes.Buffer
+	outcome := app.Execute(context.Background(), []string{"config", "diff", "--config", "before.yml", "--overlay", "base", "--against-config", "after.yml"}, commandkit.Streams{Out: &output, Err: io.Discard})
+	if outcome.Kind != commandkit.OutcomeSuccess {
+		t.Fatalf("default YAML comparison outcome = %#v", outcome)
+	}
+	if len(selections) != 2 || !selections[0].Config.Set || selections[0].Config.Value != "before.yml" || !selections[1].Config.Set || selections[1].Config.Value != "after.yml" || selections[1].Overlay != selections[0].Overlay {
+		t.Fatalf("comparison selections = %#v", selections)
+	}
+	var document yaml.Node
+	if err := yaml.Unmarshal(output.Bytes(), &document); err != nil {
+		t.Fatalf("default report is not YAML: %q: %v", output.String(), err)
+	}
+	changes := reportField(document.Content[0], "changes")
+	if value := reportField(changes, "greeting"); value == nil || value.Value != "Goodbye" {
+		t.Fatalf("public comparison output = %#v", document.Content[0])
+	}
+
+	output.Reset()
+	outcome = app.Execute(context.Background(), []string{"config", "diff", "--format", "yaml", "--config", "before.yml", "--against-config", "before.yml"}, commandkit.Streams{Out: &output, Err: io.Discard})
+	if outcome.Kind != commandkit.OutcomeSuccess {
+		t.Fatalf("explicit YAML comparison outcome = %#v", outcome)
+	}
+	var equal yaml.Node
+	if err := yaml.Unmarshal(output.Bytes(), &equal); err != nil {
+		t.Fatalf("explicit YAML report is not YAML: %q: %v", output.String(), err)
+	}
+	if len(reportField(equal.Content[0], "additions").Content) != 0 || len(reportField(equal.Content[0], "changes").Content) != 0 || len(reportField(equal.Content[0], "deletions").Content) != 0 {
+		t.Fatalf("equal comparison did not return empty categories: %q", output.String())
+	}
+
+	loadsBeforeText := len(selections)
+	output.Reset()
+	outcome = app.Execute(context.Background(), []string{"config", "diff", "--format", "text"}, commandkit.Streams{Out: &output, Err: io.Discard})
+	if outcome.Kind != commandkit.OutcomeUsage || len(selections) != loadsBeforeText || output.Len() != 0 {
+		t.Fatalf("text format outcome/work/output = %#v / %d / %q", outcome, len(selections)-loadsBeforeText, output.String())
+	}
+}
+
+func TestConfigDiffRunsComparisonOnlyScopeAndRejectsUnsupportedScopeBeforeWork(t *testing.T) {
+	var inputCalls, stateCalls, acquireCalls, compareCalls int
+	app := newConfigTestApp(t, Command(Suite[struct{}, struct{}]{
+		NewInput: func() struct{} { inputCalls++; return struct{}{} },
+		NewState: func() struct{} { stateCalls++; return struct{}{} },
+		Scopes: []Scope[struct{}, struct{}]{
+			{Name: "app", Operations: []Operation{Diff}, Compare: func(context.Context, ComparisonRequest[struct{}], struct{}) (commandkit.Acquired[[]configkit.Difference], error) {
+				compareCalls++
+				return commandkit.Acquired[[]configkit.Difference]{}, nil
+			}},
+			{Name: "plain", Operations: []Operation{Show}, Acquire: func(context.Context, Request, struct{}, struct{}) (commandkit.Acquired[View], error) {
+				acquireCalls++
+				return commandkit.Acquired[View]{}, nil
+			}},
+		},
+	}))
+	var output bytes.Buffer
+	outcome := app.Execute(context.Background(), []string{"config", "scopes"}, commandkit.Streams{Out: &output, Err: io.Discard})
+	if outcome.Kind != commandkit.OutcomeSuccess || !strings.Contains(output.String(), "app: diff") {
+		t.Fatalf("comparison-only discovery = %#v, %q", outcome, output.String())
+	}
+	output.Reset()
+	outcome = app.Execute(context.Background(), []string{"config", "diff", "--scope", "app"}, commandkit.Streams{Out: &output, Err: io.Discard})
+	if outcome.Kind != commandkit.OutcomeSuccess || compareCalls != 1 {
+		t.Fatalf("comparison-only execution = %#v calls=%d", outcome, compareCalls)
+	}
+	inputsBefore, statesBefore := inputCalls, stateCalls
+	output.Reset()
+	outcome = app.Execute(context.Background(), []string{"config", "diff", "--scope", "plain"}, commandkit.Streams{Out: &output, Err: io.Discard})
+	if outcome.Kind != commandkit.OutcomeUsage || inputCalls != inputsBefore || stateCalls != statesBefore || acquireCalls != 0 || compareCalls != 1 || output.Len() != 0 {
+		t.Fatalf("unsupported scope outcome/work/output = %#v / %d,%d,%d,%d / %q", outcome, inputCalls, stateCalls, acquireCalls, compareCalls, output.String())
+	}
+}
+
+func TestConfigDiffProviderFailureRetainsDiagnosticsAndCause(t *testing.T) {
+	wantErr := errors.New("provider unavailable")
+	diagnostic := commandkit.Diagnostic{Severity: commandkit.SeverityWarning, Write: func(writer io.Writer) error {
+		_, err := io.WriteString(writer, "provider warning\n")
+		return err
+	}}
+	app := newConfigTestApp(t, Command(Suite[struct{}, struct{}]{Scopes: []Scope[struct{}, struct{}]{{
+		Name: "app", Operations: []Operation{Diff},
+		Compare: func(context.Context, ComparisonRequest[struct{}], struct{}) (commandkit.Acquired[[]configkit.Difference], error) {
+			return commandkit.Acquired[[]configkit.Difference]{
+				Diagnostics: []commandkit.Diagnostic{diagnostic},
+				Explanation: commandkit.Explanation{Details: []commandkit.Detail{func(writer io.Writer) error {
+					_, err := io.WriteString(writer, "native comparison context\n")
+					return err
+				}}},
+			}, fmt.Errorf("comparison setup: %w", wantErr)
+		},
+	}}}))
+	var output, diagnosticOutput bytes.Buffer
+	outcome := app.Execute(context.Background(), []string{"config", "diff", "--verbose"}, commandkit.Streams{Out: &output, Err: &diagnosticOutput})
+	if outcome.Kind != commandkit.OutcomeOperational || !errors.Is(outcome.Cause, wantErr) || output.Len() != 0 {
+		t.Fatalf("provider failure outcome/output = %#v / %q", outcome, output.String())
+	}
+	if got := diagnosticOutput.String(); !strings.Contains(got, "provider warning") || !strings.Contains(got, "native comparison context") || strings.Index(got, "provider warning") > strings.Index(got, "native comparison context") || strings.Contains(got, wantErr.Error()) {
+		t.Fatalf("provider messages and terminal context = %q", got)
+	}
+}
+
+func TestConfigDiffReportPreparationFailureWritesNoReport(t *testing.T) {
+	app := newConfigTestApp(t, Command(Suite[struct{}, struct{}]{Scopes: []Scope[struct{}, struct{}]{{
+		Name: "app", Operations: []Operation{Diff},
+		Compare: func(context.Context, ComparisonRequest[struct{}], struct{}) (commandkit.Acquired[[]configkit.Difference], error) {
+			return commandkit.Acquired[[]configkit.Difference]{Value: []configkit.Difference{{
+				Path: configkit.Keys("invalid"), Right: configkit.ValueSnapshot{Present: true, YAML: "bad: ["},
+			}}}, nil
+		},
+	}}}))
+	var output bytes.Buffer
+	outcome := app.Execute(context.Background(), []string{"config", "diff", "--quiet"}, commandkit.Streams{Out: failingOutput{err: errors.New("quiet destination should not be called")}, Err: io.Discard})
+	if outcome.Kind != commandkit.OutcomeOperational || outcome.Cause != nil || outcome.Presentation.Output.State != commandkit.DeliveryIncomplete || outcome.Presentation.Output.RenderError == nil || output.Len() != 0 {
+		t.Fatalf("report preparation failure outcome/output = %#v / %q", outcome, output.String())
+	}
+}
+
+func TestConfigDiffCancellationAfterAcquisitionRetainsDiagnosticsWithoutWriting(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	diagnostic := commandkit.Diagnostic{Severity: commandkit.SeverityWarning, Write: func(io.Writer) error { return nil }}
+	app := newConfigTestApp(t, Command(Suite[struct{}, struct{}]{Scopes: []Scope[struct{}, struct{}]{{
+		Name: "app", Operations: []Operation{Diff},
+		Compare: func(context.Context, ComparisonRequest[struct{}], struct{}) (commandkit.Acquired[[]configkit.Difference], error) {
+			cancel()
+			return commandkit.Acquired[[]configkit.Difference]{Diagnostics: []commandkit.Diagnostic{diagnostic}}, nil
+		},
+	}}}))
+	defer cancel()
+	var output bytes.Buffer
+	outcome := app.Execute(ctx, []string{"config", "diff", "--verbose"}, commandkit.Streams{Out: &output, Err: io.Discard})
+	if outcome.Kind != commandkit.OutcomeOperational || !errors.Is(outcome.Cause, context.Canceled) || output.Len() != 0 {
+		t.Fatalf("cancelled comparison outcome/output = %#v / %q", outcome, output.String())
+	}
+}
+
+func TestConfigDiffOutputErrorsCarryIncompleteDeliveryOutcome(t *testing.T) {
+	app := newConfigTestApp(t, Command(Suite[struct{}, struct{}]{Scopes: []Scope[struct{}, struct{}]{{
+		Name: "app", Operations: []Operation{Diff},
+		Compare: func(context.Context, ComparisonRequest[struct{}], struct{}) (commandkit.Acquired[[]configkit.Difference], error) {
+			return commandkit.Acquired[[]configkit.Difference]{}, nil
+		},
+	}}}))
+	wantErr := errors.New("output failed")
+	for _, test := range []struct {
+		name   string
+		writer io.Writer
+		want   error
+	}{
+		{name: "writer error", writer: failingOutput{err: wantErr}, want: wantErr},
+		{name: "short write", writer: shortWriter{}, want: io.ErrShortWrite},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			outcome := app.Execute(context.Background(), []string{"config", "diff"}, commandkit.Streams{Out: test.writer, Err: io.Discard})
+			if outcome.Kind != commandkit.OutcomeOperational || outcome.Cause != nil || !errors.Is(outcome.Presentation.Output.WriteError, test.want) || outcome.Presentation.Output.State != commandkit.DeliveryIncomplete {
+				t.Fatalf("delivery failure outcome = %#v", outcome)
+			}
+		})
+	}
+}
+
+func TestConfigDiffDiagnosticDestinationFailureIsPresentationEvidence(t *testing.T) {
+	app := newConfigTestApp(t, Command(Suite[struct{}, struct{}]{Scopes: []Scope[struct{}, struct{}]{{
+		Name: "app", Operations: []Operation{Diff},
+		Compare: func(context.Context, ComparisonRequest[struct{}], struct{}) (commandkit.Acquired[[]configkit.Difference], error) {
+			return commandkit.Acquired[[]configkit.Difference]{
+				Diagnostics: []commandkit.Diagnostic{{Severity: commandkit.SeverityWarning, Write: func(writer io.Writer) error {
+					_, err := io.WriteString(writer, "provider warning\n")
+					return err
+				}}},
+			}, nil
+		},
+	}}}))
+	writeErr := errors.New("diagnostic destination failed")
+	var output bytes.Buffer
+	outcome := app.Execute(context.Background(), []string{"config", "diff", "--verbose"}, commandkit.Streams{Out: &output, Err: failingOutput{err: writeErr}})
+	if outcome.Kind != commandkit.OutcomeOperational || outcome.Cause != nil || !errors.Is(outcome.Presentation.Diagnostics.WriteError, writeErr) || outcome.Presentation.Diagnostics.State != commandkit.DeliveryIncomplete {
+		t.Fatalf("diagnostic delivery failure outcome = %#v", outcome)
+	}
+	if output.Len() == 0 {
+		t.Fatal("healthy result destination did not receive the diff report")
+	}
+}
+
+func TestConfigDiffRepeatedInvocationsPrepareFreshInputsAndState(t *testing.T) {
+	type input struct {
+		ID    int
+		Label string
+	}
+	type state struct{ ID int }
+	label := commandkit.ValueFlag(commandkit.FlagMeta{Name: "label"}, (*string)(nil), parseConfigString,
+		func(target *input, value commandkit.Supplied[string]) { target.Label = value.Value })
+	var inputID, stateID int
+	var observed []struct {
+		left, right input
+		state       *state
+	}
+	app := newConfigTestApp(t, Command(Suite[input, *state]{
+		NewInput:  func() input { inputID++; return input{ID: inputID} },
+		NewState:  func() *state { stateID++; return &state{ID: stateID} },
+		Selectors: []Selector[input]{{Binding: label, Scopes: []string{"app"}}},
+		Scopes: []Scope[input, *state]{{Name: "app", Operations: []Operation{Diff}, Compare: func(_ context.Context, request ComparisonRequest[input], shared *state) (commandkit.Acquired[[]configkit.Difference], error) {
+			observed = append(observed, struct {
+				left, right input
+				state       *state
+			}{request.Left.Input, request.Right.Input, shared})
+			left, err := configkit.Load[struct {
+				Label string `yaml:"label"`
+			}](configkit.Mapping("left", map[string]any{"label": request.Left.Input.Label}))
+			if err != nil {
+				return commandkit.Acquired[[]configkit.Difference]{}, err
+			}
+			right, err := configkit.Load[struct {
+				Label string `yaml:"label"`
+			}](configkit.Mapping("right", map[string]any{"label": request.Right.Input.Label + "-right"}))
+			if err != nil {
+				return commandkit.Acquired[[]configkit.Difference]{}, err
+			}
+			differences, err := configkit.Diff(left, right)
+			return commandkit.Acquired[[]configkit.Difference]{Value: differences}, err
+		}}},
+	}))
+	for range 2 {
+		outcome := app.Execute(context.Background(), []string{"config", "diff", "--label", "current"}, commandkit.Streams{Out: io.Discard, Err: io.Discard})
+		if outcome.Kind != commandkit.OutcomeSuccess {
+			t.Fatalf("comparison invocation outcome = %#v", outcome)
+		}
+	}
+	if len(observed) != 2 || observed[0].left.ID == observed[0].right.ID || observed[1].left.ID == observed[1].right.ID || observed[0].left.ID == observed[1].left.ID || observed[0].right.ID == observed[1].right.ID {
+		t.Fatalf("input instances were reused: %#v", observed)
+	}
+	if observed[0].left.Label != "current" || observed[0].right.Label != "current" || observed[1].left.Label != "current" || observed[1].right.Label != "current" {
+		t.Fatalf("comparison inputs missed captured flag values: %#v", observed)
+	}
+	if observed[0].state == nil || observed[1].state == nil || observed[0].state == observed[1].state || observed[0].state.ID != 1 || observed[1].state.ID != 2 {
+		t.Fatalf("state was not fresh per invocation: %#v", observed)
+	}
+}
+
+func TestConfigDiffExecutesConcealedChangesAndEmptyResults(t *testing.T) {
+	type settings struct {
+		Secret string `yaml:"secret"`
+	}
+	app := newConfigTestApp(t, AppCommand(func(_ context.Context, selection Selection) (*configkit.Result[settings], error) {
+		value := "same"
+		if selection.Config.Set && selection.Config.Value == "after" {
+			value = "changed-secret"
+		}
+		return configkit.Load(configkit.Mapping("selected", map[string]any{"secret": value}), configkit.Options[settings]{Definition: configkit.Definition[settings]{Secret: func(path configkit.Path) bool { return path.String() == "/secret" }}})
+	}))
+	var output bytes.Buffer
+	outcome := app.Execute(context.Background(), []string{"config", "diff", "--config", "before", "--against-config", "after"}, commandkit.Streams{Out: &output, Err: io.Discard})
+	if outcome.Kind != commandkit.OutcomeSuccess || !strings.Contains(output.String(), "[REDACTED]") || strings.Contains(output.String(), "changed-secret") {
+		t.Fatalf("concealed comparison outcome/report = %#v / %q", outcome, output.String())
+	}
+	output.Reset()
+	outcome = app.Execute(context.Background(), []string{"config", "diff", "--config", "before", "--against-config", "before"}, commandkit.Streams{Out: &output, Err: io.Discard})
+	if outcome.Kind != commandkit.OutcomeSuccess || !strings.Contains(output.String(), "additions:") || !strings.Contains(output.String(), "changes:") || !strings.Contains(output.String(), "deletions:") {
+		t.Fatalf("empty comparison outcome/report = %#v / %q", outcome, output.String())
+	}
+}

integrations/ckconfig/diff_report.go

@@ -0,0 +1,194 @@
+package ckconfig
+
+import (
+	"bytes"
+	"fmt"
+	"strings"
+
+	configkit "gitea.maximumdirect.net/eric/ConfigKit"
+	"go.yaml.in/yaml/v4"
+)
+
+func decodeSafeSnapshot(snapshot string) (*yaml.Node, error) {
+	var document yaml.Node
+	decoder := yaml.NewDecoder(strings.NewReader(snapshot))
+	if err := decoder.Decode(&document); err != nil {
+		return nil, fmt.Errorf("decode safe YAML snapshot: %w", err)
+	}
+	if document.Kind != yaml.DocumentNode || len(document.Content) == 0 {
+		return nil, fmt.Errorf("decode safe YAML snapshot: document has no value")
+	}
+	return document.Content[0], nil
+}
+
+func decodeJSONPointer(pointer string) ([]string, error) {
+	if pointer == "" {
+		return nil, nil
+	}
+	if pointer[0] != '/' {
+		return nil, fmt.Errorf("decode JSON pointer %q: path must start with /", pointer)
+	}
+
+	parts := strings.Split(pointer[1:], "/")
+	for index, part := range parts {
+		var decoded strings.Builder
+		decoded.Grow(len(part))
+		for offset := 0; offset < len(part); offset++ {
+			if part[offset] != '~' {
+				decoded.WriteByte(part[offset])
+				continue
+			}
+			if offset+1 >= len(part) {
+				return nil, fmt.Errorf("decode JSON pointer %q: incomplete escape in token %d", pointer, index)
+			}
+			offset++
+			switch part[offset] {
+			case '0':
+				decoded.WriteByte('~')
+			case '1':
+				decoded.WriteByte('/')
+			default:
+				return nil, fmt.Errorf("decode JSON pointer %q: invalid escape in token %d", pointer, index)
+			}
+		}
+		parts[index] = decoded.String()
+	}
+	return parts, nil
+}
+
+// yamlValuePlacer indexes each mapping once while assembling one report.
+// Content remains the ordered representation used by the YAML encoder.
+type yamlValuePlacer struct {
+	keys map[*yaml.Node]map[string]int
+}
+
+func (placer *yamlValuePlacer) placeValue(category *yaml.Node, path []string, value *yaml.Node) (*yaml.Node, error) {
+	if value == nil {
+		return nil, fmt.Errorf("place YAML value: value node is nil")
+	}
+	if len(path) == 0 {
+		return value, nil
+	}
+	if category == nil || category.Kind != yaml.MappingNode {
+		return nil, fmt.Errorf("place YAML value at %q: category ancestor is not a mapping", pointerFromTokens(path[:1]))
+	}
+
+	current := category
+	for index, token := range path {
+		keys := placer.mappingKeys(current)
+		keyIndex, exists := keys[token]
+		if index == len(path)-1 {
+			if exists {
+				current.Content[keyIndex+1] = value
+			} else {
+				keys[token] = len(current.Content)
+				current.Content = append(current.Content, stringKey(token), value)
+			}
+			return category, nil
+		}
+
+		if !exists {
+			child := &yaml.Node{Kind: yaml.MappingNode, Tag: "!!map"}
+			keys[token] = len(current.Content)
+			current.Content = append(current.Content, stringKey(token), child)
+			current = child
+			continue
+		}
+
+		child := current.Content[keyIndex+1]
+		if child.Kind != yaml.MappingNode {
+			return nil, fmt.Errorf("place YAML value at %q: ancestor %q is not a mapping", pointerFromTokens(path), pointerFromTokens(path[:index+1]))
+		}
+		current = child
+	}
+	return category, nil
+}
+
+func (placer *yamlValuePlacer) mappingKeys(mapping *yaml.Node) map[string]int {
+	if keys, exists := placer.keys[mapping]; exists {
+		return keys
+	}
+	if placer.keys == nil {
+		placer.keys = make(map[*yaml.Node]map[string]int)
+	}
+	keys := make(map[string]int, len(mapping.Content)/2)
+	for index := 0; index+1 < len(mapping.Content); index += 2 {
+		candidate := mapping.Content[index]
+		if candidate.Kind == yaml.ScalarNode && candidate.Tag == "!!str" {
+			if _, exists := keys[candidate.Value]; !exists {
+				keys[candidate.Value] = index
+			}
+		}
+	}
+	placer.keys[mapping] = keys
+	return keys
+}
+
+func stringKey(value string) *yaml.Node {
+	return &yaml.Node{Kind: yaml.ScalarNode, Tag: "!!str", Value: value}
+}
+
+func pointerFromTokens(tokens []string) string {
+	if len(tokens) == 0 {
+		return ""
+	}
+	var pointer strings.Builder
+	for _, token := range tokens {
+		pointer.WriteByte('/')
+		pointer.WriteString(strings.ReplaceAll(strings.ReplaceAll(token, "~", "~0"), "/", "~1"))
+	}
+	return pointer.String()
+}
+
+func renderDiffReport(differences []configkit.Difference) ([]byte, error) {
+	var placer yamlValuePlacer
+	additions := &yaml.Node{Kind: yaml.MappingNode, Tag: "!!map"}
+	changes := &yaml.Node{Kind: yaml.MappingNode, Tag: "!!map"}
+	deletions := &yaml.Node{Kind: yaml.SequenceNode, Tag: "!!seq"}
+
+	for _, difference := range differences {
+		path := difference.Path.String()
+		switch {
+		case !difference.Left.Present && difference.Right.Present:
+			tokens, err := decodeJSONPointer(path)
+			if err != nil {
+				return nil, fmt.Errorf("render addition at %q: %w", path, err)
+			}
+			value, err := decodeSafeSnapshot(difference.Right.YAML)
+			if err != nil {
+				return nil, fmt.Errorf("render addition at %q: %w", path, err)
+			}
+			additions, err = placer.placeValue(additions, tokens, value)
+			if err != nil {
+				return nil, fmt.Errorf("render addition at %q: %w", path, err)
+			}
+		case difference.Left.Present && difference.Right.Present:
+			tokens, err := decodeJSONPointer(path)
+			if err != nil {
+				return nil, fmt.Errorf("render change at %q: %w", path, err)
+			}
+			value, err := decodeSafeSnapshot(difference.Right.YAML)
+			if err != nil {
+				return nil, fmt.Errorf("render change at %q: %w", path, err)
+			}
+			changes, err = placer.placeValue(changes, tokens, value)
+			if err != nil {
+				return nil, fmt.Errorf("render change at %q: %w", path, err)
+			}
+		case difference.Left.Present && !difference.Right.Present:
+			deletions.Content = append(deletions.Content, stringKey(path))
+		}
+	}
+
+	root := &yaml.Node{Kind: yaml.MappingNode, Tag: "!!map", Content: []*yaml.Node{
+		stringKey("additions"), additions,
+		stringKey("changes"), changes,
+		stringKey("deletions"), deletions,
+	}}
+	document := &yaml.Node{Kind: yaml.DocumentNode, Content: []*yaml.Node{root}}
+	var output bytes.Buffer
+	if err := encodeYAML(&output, document); err != nil {
+		return nil, fmt.Errorf("encode configuration diff report: %w", err)
+	}
+	return output.Bytes(), nil
+}

integrations/ckconfig/diff_report_render_test.go

@@ -0,0 +1,173 @@
+package ckconfig
+
+import (
+	"bytes"
+	"reflect"
+	"strings"
+	"testing"
+
+	configkit "gitea.maximumdirect.net/eric/ConfigKit"
+	"go.yaml.in/yaml/v4"
+)
+
+func renderAndDecode(t *testing.T, differences []configkit.Difference) (*yaml.Node, []byte) {
+	t.Helper()
+	report, err := renderDiffReport(differences)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var document yaml.Node
+	if err := yaml.Unmarshal(report, &document); err != nil {
+		t.Fatalf("decode rendered report %q: %v", report, err)
+	}
+	return document.Content[0], report
+}
+
+func reportField(mapping *yaml.Node, key string) *yaml.Node {
+	for index := 0; index+1 < len(mapping.Content); index += 2 {
+		if mapping.Content[index].Value == key {
+			return mapping.Content[index+1]
+		}
+	}
+	return nil
+}
+
+func TestRenderDiffReportClassifiesAndOrdersNativeRecords(t *testing.T) {
+	differences := []configkit.Difference{
+		{Path: configkit.Keys("z-added"), Right: configkit.ValueSnapshot{Present: true, YAML: "false\n"}},
+		{Path: configkit.Keys("count"), Left: configkit.ValueSnapshot{Present: true, YAML: "1\n"}, Right: configkit.ValueSnapshot{Present: true, YAML: "9007199254740993\n"}},
+		{Path: configkit.Keys("removed"), Left: configkit.ValueSnapshot{Present: true, YAML: "unused"}},
+		{Path: configkit.Keys("a-added"), Right: configkit.ValueSnapshot{Present: true, YAML: "'123'\n"}},
+	}
+	root, _ := renderAndDecode(t, differences)
+	if root.Kind != yaml.MappingNode || len(root.Content) != 6 {
+		t.Fatalf("report root = %#v", root)
+	}
+	if got := []string{root.Content[0].Value, root.Content[2].Value, root.Content[4].Value}; !reflect.DeepEqual(got, []string{"additions", "changes", "deletions"}) {
+		t.Fatalf("report category order = %#v", got)
+	}
+	additions := reportField(root, "additions")
+	if additions.Kind != yaml.MappingNode || additions.Content[0].Value != "z-added" || additions.Content[2].Value != "a-added" {
+		t.Fatalf("addition order/value = %#v", additions)
+	}
+	if additions.Content[1].Kind != yaml.ScalarNode || additions.Content[1].Tag != "!!bool" || additions.Content[1].Value != "false" {
+		t.Fatalf("boolean addition lost its type: %#v", additions.Content[1])
+	}
+	if additions.Content[3].Tag != "!!str" || additions.Content[3].Value != "123" {
+		t.Fatalf("numeric-looking string lost its type: %#v", additions.Content[3])
+	}
+	changes := reportField(root, "changes")
+	if changes.Kind != yaml.MappingNode || changes.Content[1].Tag != "!!int" || changes.Content[1].Value != "9007199254740993" {
+		t.Fatalf("change value/type = %#v", changes)
+	}
+	deletions := reportField(root, "deletions")
+	if deletions.Kind != yaml.SequenceNode || len(deletions.Content) != 1 || deletions.Content[0].Tag != "!!str" || deletions.Content[0].Value != "/removed" {
+		t.Fatalf("deletion records = %#v", deletions)
+	}
+}
+
+func TestRenderDiffReportEmitsEmptyCategoriesAndRootValue(t *testing.T) {
+	root, _ := renderAndDecode(t, nil)
+	if got := []string{root.Content[0].Value, root.Content[2].Value, root.Content[4].Value}; !reflect.DeepEqual(got, []string{"additions", "changes", "deletions"}) {
+		t.Fatalf("empty report keys = %#v", got)
+	}
+	if reportField(root, "additions").Kind != yaml.MappingNode || len(reportField(root, "additions").Content) != 0 || reportField(root, "changes").Kind != yaml.MappingNode || len(reportField(root, "changes").Content) != 0 || reportField(root, "deletions").Kind != yaml.SequenceNode || len(reportField(root, "deletions").Content) != 0 {
+		t.Fatalf("empty report categories = %#v", root)
+	}
+
+	root, _ = renderAndDecode(t, []configkit.Difference{{Right: configkit.ValueSnapshot{Present: true, YAML: "null\n"}}})
+	additions := reportField(root, "additions")
+	if additions.Tag != "!!null" || additions.Value != "null" {
+		t.Fatalf("whole-root addition was wrapped: %#v", additions)
+	}
+}
+
+func TestRenderDiffReportDistinguishesDeletionFromNullAndEmptyMappings(t *testing.T) {
+	differences := []configkit.Difference{
+		{Path: configkit.Keys("nullable"), Right: configkit.ValueSnapshot{Present: true, YAML: "null\n"}},
+		{Path: configkit.Keys("settings", "first"), Left: configkit.ValueSnapshot{Present: true, YAML: "intentionally not parsed"}},
+		{Path: configkit.Keys("settings", "second"), Left: configkit.ValueSnapshot{Present: true, YAML: "also not parsed"}},
+	}
+	root, _ := renderAndDecode(t, differences)
+	if got := reportField(root, "additions").Content; len(got) != 2 || got[0].Value != "nullable" || got[1].Tag != "!!null" {
+		t.Fatalf("explicit null addition = %#v", got)
+	}
+	deletions := reportField(root, "deletions")
+	if len(deletions.Content) != 2 || deletions.Content[0].Value != "/settings/first" || deletions.Content[1].Value != "/settings/second" {
+		t.Fatalf("mapping-to-empty deletion records = %#v", deletions)
+	}
+}
+
+func TestRenderDiffReportKeepsAtomicSequencesAndStructuralValues(t *testing.T) {
+	differences := []configkit.Difference{
+		{Path: configkit.Keys("items"), Left: configkit.ValueSnapshot{Present: true}, Right: configkit.ValueSnapshot{Present: true, YAML: "- one\n- two\n"}},
+		{Path: configkit.Keys("settings"), Left: configkit.ValueSnapshot{Present: true}, Right: configkit.ValueSnapshot{Present: true, YAML: "nested:\n  enabled: true\n"}},
+	}
+	root, _ := renderAndDecode(t, differences)
+	changes := reportField(root, "changes")
+	if changes.Content[1].Kind != yaml.SequenceNode || len(changes.Content[1].Content) != 2 {
+		t.Fatalf("sequence change was expanded or altered: %#v", changes.Content[1])
+	}
+	settings := reportField(changes, "settings")
+	if settings.Kind != yaml.MappingNode || reportField(settings, "nested").Kind != yaml.MappingNode || reportField(reportField(settings, "nested"), "enabled").Tag != "!!bool" {
+		t.Fatalf("structural replacement was altered: %#v", settings)
+	}
+}
+
+func TestRenderDiffReportPreservesNativeMasksAndMarkerLookingStrings(t *testing.T) {
+	type settings struct {
+		Public string `yaml:"public"`
+		Secret string `yaml:"secret"`
+	}
+	definition := configkit.Definition[settings]{Secret: func(path configkit.Path) bool { return path.String() == "/secret" }}
+	load := func(public, secret string) *configkit.Result[settings] {
+		result, err := configkit.Load(configkit.Mapping("configuration", map[string]any{"public": public, "secret": secret}), configkit.Options[settings]{Definition: definition})
+		if err != nil {
+			t.Fatal(err)
+		}
+		return result
+	}
+	left := load("visible", "old-secret")
+	right := load("[REDACTED]", "new-secret")
+	differences, err := configkit.Diff(left, right)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(differences) != 2 || differences[0].Path.String() != "/public" || differences[1].Path.String() != "/secret" || !differences[1].HiddenChanged || !differences[1].Right.Redacted {
+		t.Fatalf("native changes/mask metadata = %#v", differences)
+	}
+	root, report := renderAndDecode(t, differences)
+	changes := reportField(root, "changes")
+	for _, key := range []string{"public", "secret"} {
+		value := reportField(changes, key)
+		if value == nil || value.Tag != "!!str" || value.Value != "[REDACTED]" {
+			t.Fatalf("safe value for %q = %#v", key, value)
+		}
+	}
+	if bytes.Contains(report, []byte("HiddenChanged")) || bytes.Contains(report, []byte("Redacted")) || strings.Contains(string(report), "old-secret") || strings.Contains(string(report), "new-secret") {
+		t.Fatalf("report exposed native metadata or secret contents: %q", report)
+	}
+
+	concealedOnly := load("[REDACTED]", "later-secret")
+	concealedDifferences, err := configkit.Diff(right, concealedOnly)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(concealedDifferences) != 1 || concealedDifferences[0].Path.String() != "/secret" || !concealedDifferences[0].HiddenChanged {
+		t.Fatalf("concealed-only native records = %#v", concealedDifferences)
+	}
+	concealedRoot, _ := renderAndDecode(t, concealedDifferences)
+	if value := reportField(reportField(concealedRoot, "changes"), "secret"); value == nil || value.Tag != "!!str" || value.Value != "[REDACTED]" {
+		t.Fatalf("concealed-only safe value = %#v", value)
+	}
+}
+
+func TestRenderDiffReportReportsMalformedPresentSnapshot(t *testing.T) {
+	report, err := renderDiffReport([]configkit.Difference{{
+		Path:  configkit.Keys("setting"),
+		Right: configkit.ValueSnapshot{Present: true, YAML: "setting: [unterminated\n"},
+	}})
+	if err == nil || report != nil || !strings.Contains(err.Error(), "/setting") {
+		t.Fatalf("malformed snapshot report/error = %q / %v", report, err)
+	}
+}

integrations/ckconfig/diff_report_test.go

@@ -0,0 +1,146 @@
+package ckconfig
+
+import (
+	"reflect"
+	"strings"
+	"testing"
+
+	"go.yaml.in/yaml/v4"
+)
+
+func TestDecodeSafeSnapshotPreservesYAMLTypes(t *testing.T) {
+	tests := []struct {
+		name  string
+		text  string
+		kind  yaml.Kind
+		tag   string
+		value string
+	}{
+		{name: "null", text: "null\n", kind: yaml.ScalarNode, tag: "!!null", value: "null"},
+		{name: "boolean", text: "true\n", kind: yaml.ScalarNode, tag: "!!bool", value: "true"},
+		{name: "large integer", text: "9007199254740993\n", kind: yaml.ScalarNode, tag: "!!int", value: "9007199254740993"},
+		{name: "numeric string", text: "'123'\n", kind: yaml.ScalarNode, tag: "!!str", value: "123"},
+		{name: "boolean-like string", text: "'false'\n", kind: yaml.ScalarNode, tag: "!!str", value: "false"},
+		{name: "empty mapping", text: "{}\n", kind: yaml.MappingNode, tag: "!!map"},
+		{name: "empty sequence", text: "[]\n", kind: yaml.SequenceNode, tag: "!!seq"},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			node, err := decodeSafeSnapshot(test.text)
+			if err != nil {
+				t.Fatal(err)
+			}
+			if node.Kind != test.kind || node.Tag != test.tag || node.Value != test.value {
+				t.Fatalf("node kind/tag/value = %v/%q/%q, want %v/%q/%q", node.Kind, node.Tag, node.Value, test.kind, test.tag, test.value)
+			}
+		})
+	}
+
+	nested, err := decodeSafeSnapshot("items:\n  - name: example\n    enabled: false\n")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if nested.Kind != yaml.MappingNode || nested.Content[1].Kind != yaml.SequenceNode || nested.Content[1].Content[0].Content[3].Tag != "!!bool" {
+		t.Fatalf("nested collection/scalar tags were not preserved: %#v", nested)
+	}
+}
+
+func TestDecodeJSONPointerPreservesSemanticTokens(t *testing.T) {
+	tests := []struct {
+		pointer string
+		want    []string
+	}{
+		{pointer: "", want: nil},
+		{pointer: "/", want: []string{""}},
+		{pointer: "/parent/child", want: []string{"parent", "child"}},
+		{pointer: "/0/../a.b/50%", want: []string{"0", "..", "a.b", "50%"}},
+		{pointer: "/a~1b/c~0d", want: []string{"a/b", "c~d"}},
+		{pointer: "/~01", want: []string{"~1"}},
+	}
+	for _, test := range tests {
+		got, err := decodeJSONPointer(test.pointer)
+		if err != nil {
+			t.Fatalf("decode %q: %v", test.pointer, err)
+		}
+		if !reflect.DeepEqual(got, test.want) {
+			t.Errorf("decode %q = %#v, want %#v", test.pointer, got, test.want)
+		}
+	}
+	for _, pointer := range []string{"missing-leading-slash", "/bad~", "/bad~2escape"} {
+		if _, err := decodeJSONPointer(pointer); err == nil {
+			t.Errorf("decode %q unexpectedly succeeded", pointer)
+		}
+	}
+}
+
+func TestPlaceYAMLValueBuildsOrderedSemanticMappings(t *testing.T) {
+	var placer yamlValuePlacer
+	category := &yaml.Node{Kind: yaml.MappingNode, Tag: "!!map"}
+	paths := [][]string{
+		{"parent", "0", "dot.name", "50%"},
+		{"parent", "second"},
+		{"a/b", "~1"},
+		{""},
+	}
+	for index, path := range paths {
+		value := &yaml.Node{Kind: yaml.ScalarNode, Tag: "!!str", Value: string(rune('a' + index))}
+		updated, err := placer.placeValue(category, path, value)
+		if err != nil {
+			t.Fatalf("place %q: %v", pointerFromTokens(path), err)
+		}
+		category = updated
+	}
+
+	if len(category.Content) != 6 || category.Content[0].Value != "parent" || category.Content[2].Value != "a/b" || category.Content[4].Value != "" {
+		t.Fatalf("mapping insertion order or empty key = %#v", category.Content)
+	}
+	parent := category.Content[1]
+	if parent.Kind != yaml.MappingNode || len(parent.Content) != 4 || parent.Content[0].Value != "0" || parent.Content[2].Value != "second" {
+		t.Fatalf("nested shared ancestor/order = %#v", parent)
+	}
+	numeric := parent.Content[1]
+	dotted := numeric.Content[1]
+	if numeric.Kind != yaml.MappingNode || numeric.Content[0].Value != "dot.name" || dotted.Kind != yaml.MappingNode || dotted.Content[0].Value != "50%" {
+		t.Fatalf("semantic tokens were changed: numeric=%#v dotted=%#v", numeric, dotted)
+	}
+	if category.Content[1].Content[0].Tag != "!!str" || category.Content[2].Tag != "!!str" || category.Content[4].Tag != "!!str" {
+		t.Fatal("mapping keys are not explicitly tagged as YAML strings")
+	}
+}
+
+func TestPlaceYAMLValueHandlesRootAndEmptyKey(t *testing.T) {
+	var placer yamlValuePlacer
+	category := &yaml.Node{Kind: yaml.MappingNode, Tag: "!!map"}
+	root := &yaml.Node{Kind: yaml.ScalarNode, Tag: "!!null", Value: "null"}
+	updated, err := placer.placeValue(category, nil, root)
+	if err != nil || updated != root {
+		t.Fatalf("root placement = %#v, %v", updated, err)
+	}
+
+	category = &yaml.Node{Kind: yaml.MappingNode, Tag: "!!map"}
+	value := &yaml.Node{Kind: yaml.ScalarNode, Tag: "!!str", Value: "empty-key"}
+	updated, err = placer.placeValue(category, []string{""}, value)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if updated != category || len(category.Content) != 2 || category.Content[0].Value != "" || category.Content[0].Tag != "!!str" || category.Content[1] != value {
+		t.Fatalf("slash path placement = %#v", category)
+	}
+}
+
+func TestPlaceYAMLValueRejectsIncompatibleAncestors(t *testing.T) {
+	var placer yamlValuePlacer
+	category := &yaml.Node{Kind: yaml.MappingNode, Tag: "!!map", Content: []*yaml.Node{
+		stringKey("parent"), {Kind: yaml.ScalarNode, Tag: "!!str", Value: "leaf"},
+	}}
+	_, err := placer.placeValue(category, []string{"parent", "child"}, &yaml.Node{Kind: yaml.ScalarNode, Tag: "!!null", Value: "null"})
+	if err == nil || !strings.Contains(err.Error(), "/parent/child") || !strings.Contains(err.Error(), "/parent") {
+		t.Fatalf("incompatible ancestor error = %v", err)
+	}
+}
+
+func TestDecodeSafeSnapshotRejectsMalformedYAML(t *testing.T) {
+	if _, err := decodeSafeSnapshot("value: [unterminated\n"); err == nil {
+		t.Fatal("malformed snapshot unexpectedly decoded")
+	}
+}

integrations/ckconfig/doc.go

@@ -0,0 +1,10 @@
+// Package ckconfig, provided by go.maximumdirect.net/ckconfig, provides
+// CommandKit's optional ConfigKit integration. Its
+// canonical Command declaration installs the standard config command family
+// through the core commandkit package. Applications can install CommandKit
+// RoutingRule declarations alongside it through commandkit.New or
+// App.Register. Source reports preserve ConfigKit's destination, placement,
+// and version-check evidence. Invocation reporting applies CommandKit's shared
+// visibility and delivery policy; provider warnings remain independent of
+// failure explanations. Importing ckconfig alone installs no commands.
+package ckconfig

integrations/ckconfig/docs/oss/attribution.md

@@ -0,0 +1,204 @@
+# Open Source Attribution Notices
+
+## ConfigKit
+
+Selected module: `gitea.maximumdirect.net/eric/ConfigKit` at `v0.8.0`.
+
+Copyright (C) 2026 Eric Rakestraw
+
+SPDX-License-Identifier: LGPL-3.0-or-later
+
+License and notices: [LGPL v3.0](../../LICENSE) |
+[LICENSE](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/137769f3f18a370c68444242fb5d88e620e307e5/LICENSE).
+
+[Source](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/137769f3f18a370c68444242fb5d88e620e307e5).
+
+## go-yaml v4
+
+Selected module: `go.yaml.in/yaml/v4` at `v4.0.0-rc.6`.
+
+Copyright 2006-2010 Kirill Simonov
+
+Copyright 2011-2019 Canonical Ltd
+
+Copyright 2025 The go-yaml Project Contributors
+
+License and notices: [Apache 2.0](licenses/Apache-2.0.txt) |
+[MIT](licenses/MIT.txt) |
+[LICENSE](https://github.com/yaml/go-yaml/blob/1c17b9cee72bf81ae73a8be50fbd7dd3a9985125/LICENSE) |
+[NOTICE](https://github.com/yaml/go-yaml/blob/1c17b9cee72bf81ae73a8be50fbd7dd3a9985125/NOTICE).
+
+[Source](https://github.com/yaml/go-yaml/tree/1c17b9cee72bf81ae73a8be50fbd7dd3a9985125).
+
+## Cobra
+
+Selected module: `github.com/spf13/cobra` at `v1.10.1`.
+
+SPDX-License-Identifier: Apache-2.0
+
+License and notices: [Apache 2.0](licenses/Apache-2.0.txt) |
+[LICENSE.txt](https://github.com/spf13/cobra/blob/7da941c3547e93b8c9f70bbd3befca79c6335388/LICENSE.txt).
+
+[Source](https://github.com/spf13/cobra/tree/7da941c3547e93b8c9f70bbd3befca79c6335388).
+
+## pflag
+
+Selected module: `github.com/spf13/pflag` at `v1.0.9`.
+
+Copyright (c) 2012 Alex Ogier. All rights reserved.
+
+Copyright (c) 2012 The Go Authors. All rights reserved.
+
+SPDX-License-Identifier: BSD-3-Clause
+
+License and notices: [BSD 3-Clause](licenses/BSD-3-Clause.txt) |
+[LICENSE](https://github.com/spf13/pflag/blob/10438578954bba2527fe5cae3684d4532b064bbe/LICENSE).
+
+[Source](https://github.com/spf13/pflag/tree/10438578954bba2527fe5cae3684d4532b064bbe).
+
+## go-md2man
+
+Selected module: `github.com/cpuguy83/go-md2man/v2` at `v2.0.6` (transitive dependency).
+
+Copyright (c) 2014 Brian Goff
+
+SPDX-License-Identifier: MIT
+
+License and notices: [MIT](licenses/MIT.txt) |
+[LICENSE.md](https://github.com/cpuguy83/go-md2man/blob/441631534462b74c098953dbd8d5f6210994b0bf/LICENSE.md).
+
+[Source](https://github.com/cpuguy83/go-md2man/tree/441631534462b74c098953dbd8d5f6210994b0bf).
+
+## mousetrap
+
+Selected module: `github.com/inconshreveable/mousetrap` at `v1.1.0` (transitive dependency).
+
+SPDX-License-Identifier: Apache-2.0
+
+License and notices: [Apache 2.0](licenses/Apache-2.0.txt) |
+[LICENSE](https://github.com/inconshreveable/mousetrap/blob/4e8053ee7ef85a6bd26368364a6d27f1641c1d21/LICENSE).
+
+[Source](https://github.com/inconshreveable/mousetrap/tree/4e8053ee7ef85a6bd26368364a6d27f1641c1d21).
+
+## Blackfriday
+
+Selected module: `github.com/russross/blackfriday/v2` at `v2.1.0` (transitive dependency).
+
+Copyright © 2011 Russ Ross
+
+SPDX-License-Identifier: BSD-2-Clause
+
+License and notices: [BSD 2-Clause](licenses/BSD-2-Clause.txt) |
+[LICENSE.txt](https://github.com/russross/blackfriday/blob/4c9bf9512682b995722660a4196c0013228e2049/LICENSE.txt).
+
+[Source](https://github.com/russross/blackfriday/tree/4c9bf9512682b995722660a4196c0013228e2049).
+
+## gocheck
+
+Selected module: `gopkg.in/check.v1` at `v0.0.0-20161208181325-20d25e280405` (transitive test dependency).
+
+Gocheck - A rich testing framework for Go
+
+Copyright (c) 2010-2013 Gustavo Niemeyer <gustavo@niemeyer.net>
+
+SPDX-License-Identifier: BSD-2-Clause
+
+License and notices: [BSD 2-Clause](licenses/BSD-2-Clause.txt) |
+[LICENSE](https://github.com/go-check/check/blob/20d25e280405/LICENSE).
+
+[Source](https://github.com/go-check/check/commit/20d25e280405).
+
+## Standard Repository Policies
+
+Material in the CommandKit core dependency (paths relative to the repository
+root): `docs/policy/meta.md`, `docs/policy/agents.md`,
+`docs/policy/architecture.md`, `docs/policy/testing.md`,
+`docs/policy/documentation.md`, `docs/policy/release.md`, and
+`docs/policy/oss.md`; the root `AGENTS.md` orientation after the knowledge-graph
+instructions; and the Policy Reading Guide in `docs/development.md`, adapted for
+the core module. The release policy uses baseline
+`e833faddf120c789a9b45348edaf75720de16348`; the remaining material uses baseline
+`d84a38ebab26f048cafbe59a2246700c35d29843`.
+
+Copyright (C) 2026 Eric Rakestraw
+
+SPDX-License-Identifier: CC-BY-SA-4.0
+
+License and notices: [CC BY-SA 4.0](licenses/CC-BY-SA-4.0.txt) |
+[COPYRIGHT](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/COPYRIGHT) |
+[LICENSE](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/LICENSE) |
+[COPYRIGHT](https://gitea.maximumdirect.net/eric/policy/src/commit/e833faddf120c789a9b45348edaf75720de16348/COPYRIGHT) |
+[LICENSE](https://gitea.maximumdirect.net/eric/policy/src/commit/e833faddf120c789a9b45348edaf75720de16348/LICENSE).
+
+[Source](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843).
+
+[Source](https://gitea.maximumdirect.net/eric/policy/src/commit/e833faddf120c789a9b45348edaf75720de16348).
+
+## go-yaml v3
+
+Selected module: `gopkg.in/yaml.v3` at `v3.0.1` (transitive dependency).
+
+Copyright (c) 2006-2010 Kirill Simonov
+
+Copyright (c) 2006-2011 Kirill Simonov
+
+Copyright 2011-2016 Canonical Ltd.
+
+License and notices: [MIT](licenses/MIT.txt) |
+[Apache 2.0](licenses/Apache-2.0.txt) |
+[LICENSE](https://github.com/go-yaml/yaml/blob/f6f7691b1fdeb513f56608cd2c32c51f8194bf51/LICENSE) |
+[NOTICE](https://github.com/go-yaml/yaml/blob/f6f7691b1fdeb513f56608cd2c32c51f8194bf51/NOTICE).
+
+[Source](https://github.com/go-yaml/yaml/tree/f6f7691b1fdeb513f56608cd2c32c51f8194bf51).
+
+## ReleaseKit
+
+Selected module: `gitea.maximumdirect.net/eric/ReleaseKit` at `v0.4.1` (transitive Go tool requirement; not a runtime import).
+
+Copyright (C) 2026 Eric Rakestraw
+
+SPDX-License-Identifier: LGPL-3.0-or-later
+
+License and notices: [LGPL v3.0](../../LICENSE) |
+[LICENSE](https://gitea.maximumdirect.net/eric/ReleaseKit/src/commit/2d5a8110c61e31daf8698766114ae305d0e0e469/LICENSE).
+
+[Source](https://gitea.maximumdirect.net/eric/ReleaseKit/src/commit/2d5a8110c61e31daf8698766114ae305d0e0e469).
+
+## ReleaseKit (vanity module)
+
+Selected module: `go.maximumdirect.net/releasekit` at `v0.9.0` (transitive Go tool requirement; not a runtime import).
+
+Copyright (C) 2026 Eric Rakestraw
+
+SPDX-License-Identifier: LGPL-3.0-or-later
+
+License and notices: [LGPL v3.0](../../LICENSE) |
+[LICENSE](https://forge.maximumdirect.net/base-layer/releasekit/src/commit/2180aa868ec2caa95fc8279fd59d5f0ebac41bd4/LICENSE).
+
+[Source](https://forge.maximumdirect.net/base-layer/releasekit/src/commit/2180aa868ec2caa95fc8279fd59d5f0ebac41bd4).
+
+## Goldmark
+
+Selected module: `github.com/yuin/goldmark/v2` at `v2.1.6` (ReleaseKit tool dependency).
+
+Copyright (c) 2019 Yusuke Inuzuka
+
+SPDX-License-Identifier: MIT
+
+License and notices: [MIT](licenses/MIT.txt) |
+[LICENSE](https://github.com/yuin/goldmark/blob/a8d4ee5a0bd7d5493fdd1e339b4e75df92f8684c/LICENSE).
+
+[Source](https://github.com/yuin/goldmark/tree/a8d4ee5a0bd7d5493fdd1e339b4e75df92f8684c).
+
+## Go modules
+
+Selected module: `golang.org/x/mod` at `v0.40.0` (ReleaseKit tool dependency).
+
+Copyright 2009 The Go Authors.
+
+SPDX-License-Identifier: BSD-3-Clause
+
+License and notices: [BSD 3-Clause](licenses/BSD-3-Clause.txt) |
+[LICENSE](https://go.googlesource.com/mod/+/d3398d06de5fa5c71083d3d1c26f2cda73508e0f/LICENSE).
+
+[Source](https://go.googlesource.com/mod/+/d3398d06de5fa5c71083d3d1c26f2cda73508e0f).

integrations/ckconfig/docs/oss/licenses/Apache-2.0.txt

@@ -0,0 +1,73 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions:
+
+     (a) You must give any other recipients of the Work or Derivative Works a copy of this License; and
+
+     (b) You must cause any modified files to carry prominent notices stating that You changed the files; and
+
+     (c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and
+
+     (d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License.
+
+     You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets "[]" replaced with your own identifying information. (Don't include the brackets!)  The text should be enclosed in the appropriate comment syntax for the file format. We also recommend that a file or class name and description of purpose be included on the same "printed page" as the copyright notice for easier identification within third-party archives.
+
+Copyright [yyyy] [name of copyright owner]
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

integrations/ckconfig/docs/oss/licenses/BSD-2-Clause.txt

@@ -0,0 +1,9 @@
+Copyright (c) <year> <owner> 
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

integrations/ckconfig/docs/oss/licenses/BSD-3-Clause.txt

@@ -0,0 +1,11 @@
+Copyright (c) <year> <owner>. 
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

integrations/ckconfig/docs/oss/licenses/CC-BY-SA-4.0.txt

@@ -0,0 +1,170 @@
+Creative Commons Attribution-ShareAlike 4.0 International
+
+ Creative Commons Corporation (“Creative Commons”) is not a law firm and does not provide legal services or legal advice. Distribution of Creative Commons public licenses does not create a lawyer-client or other relationship. Creative Commons makes its licenses and related information available on an “as-is” basis. Creative Commons gives no warranties regarding its licenses, any material licensed under their terms and conditions, or any related information. Creative Commons disclaims all liability for damages resulting from their use to the fullest extent possible.
+
+Using Creative Commons Public Licenses
+
+Creative Commons public licenses provide a standard set of terms and conditions that creators and other rights holders may use to share original works of authorship and other material subject to copyright and certain other rights specified in the public license below. The following considerations are for informational purposes only, are not exhaustive, and do not form part of our licenses.
+
+Considerations for licensors: Our public licenses are intended for use by those authorized to give the public permission to use material in ways otherwise restricted by copyright and certain other rights. Our licenses are irrevocable. Licensors should read and understand the terms and conditions of the license they choose before applying it. Licensors should also secure all rights necessary before applying our licenses so that the public can reuse the material as expected. Licensors should clearly mark any material not subject to the license. This includes other CC-licensed material, or material used under an exception or limitation to copyright. More considerations for licensors.
+
+Considerations for the public: By using one of our public licenses, a licensor grants the public permission to use the licensed material under specified terms and conditions. If the licensor’s permission is not necessary for any reason–for example, because of any applicable exception or limitation to copyright–then that use is not regulated by the license. Our licenses grant only permissions under copyright and certain other rights that a licensor has authority to grant. Use of the licensed material may still be restricted for other reasons, including because others have copyright or other rights in the material. A licensor may make special requests, such as asking that all changes be marked or described.
+
+Although not required by our licenses, you are encouraged to respect those requests where reasonable. More considerations for the public.
+
+Creative Commons Attribution-ShareAlike 4.0 International Public License
+
+By exercising the Licensed Rights (defined below), You accept and agree to be bound by the terms and conditions of this Creative Commons Attribution-ShareAlike 4.0 International Public License ("Public License"). To the extent this Public License may be interpreted as a contract, You are granted the Licensed Rights in consideration of Your acceptance of these terms and conditions, and the Licensor grants You such rights in consideration of benefits the Licensor receives from making the Licensed Material available under these terms and conditions.
+
+Section 1 – Definitions.
+
+     a.	Adapted Material means material subject to Copyright and Similar Rights that is derived from or based upon the Licensed Material and in which the Licensed Material is translated, altered, arranged, transformed, or otherwise modified in a manner requiring permission under the Copyright and Similar Rights held by the Licensor. For purposes of this Public License, where the Licensed Material is a musical work, performance, or sound recording, Adapted Material is always produced where the Licensed Material is synched in timed relation with a moving image.
+
+     b.	Adapter's License means the license You apply to Your Copyright and Similar Rights in Your contributions to Adapted Material in accordance with the terms and conditions of this Public License.
+
+     c.	BY-SA Compatible License means a license listed at creativecommons.org/compatiblelicenses, approved by Creative Commons as essentially the equivalent of this Public License.
+
+     d.	Copyright and Similar Rights means copyright and/or similar rights closely related to copyright including, without limitation, performance, broadcast, sound recording, and Sui Generis Database Rights, without regard to how the rights are labeled or categorized. For purposes of this Public License, the rights specified in Section 2(b)(1)-(2) are not Copyright and Similar Rights.
+
+     e.	Effective Technological Measures means those measures that, in the absence of proper authority, may not be circumvented under laws fulfilling obligations under Article 11 of the WIPO Copyright Treaty adopted on December 20, 1996, and/or similar international agreements.
+
+     f.	Exceptions and Limitations means fair use, fair dealing, and/or any other exception or limitation to Copyright and Similar Rights that applies to Your use of the Licensed Material.
+
+     g.	License Elements means the license attributes listed in the name of a Creative Commons Public License. The License Elements of this Public License are Attribution and ShareAlike.
+
+     h.	Licensed Material means the artistic or literary work, database, or other material to which the Licensor applied this Public License.
+
+     i.	Licensed Rights means the rights granted to You subject to the terms and conditions of this Public License, which are limited to all Copyright and Similar Rights that apply to Your use of the Licensed Material and that the Licensor has authority to license.
+
+     j.	Licensor means the individual(s) or entity(ies) granting rights under this Public License.
+
+     k.	Share means to provide material to the public by any means or process that requires permission under the Licensed Rights, such as reproduction, public display, public performance, distribution, dissemination, communication, or importation, and to make material available to the public including in ways that members of the public may access the material from a place and at a time individually chosen by them.
+
+     l.	Sui Generis Database Rights means rights other than copyright resulting from Directive 96/9/EC of the European Parliament and of the Council of 11 March 1996 on the legal protection of databases, as amended and/or succeeded, as well as other essentially equivalent rights anywhere in the world.
+
+     m.	You means the individual or entity exercising the Licensed Rights under this Public License. Your has a corresponding meaning.
+
+Section 2 – Scope.
+
+     a.	License grant.
+
+          1. Subject to the terms and conditions of this Public License, the Licensor hereby grants You a worldwide, royalty-free, non-sublicensable, non-exclusive, irrevocable license to exercise the Licensed Rights in the Licensed Material to:
+
+               A. reproduce and Share the Licensed Material, in whole or in part; and
+
+               B. produce, reproduce, and Share Adapted Material.
+
+          2. Exceptions and Limitations. For the avoidance of doubt, where Exceptions and Limitations apply to Your use, this Public License does not apply, and You do not need to comply with its terms and conditions.
+
+          3. Term. The term of this Public License is specified in Section 6(a).
+
+          4. Media and formats; technical modifications allowed. The Licensor authorizes You to exercise the Licensed Rights in all media and formats whether now known or hereafter created, and to make technical modifications necessary to do so. The Licensor waives and/or agrees not to assert any right or authority to forbid You from making technical modifications necessary to exercise the Licensed Rights, including technical modifications necessary to circumvent Effective Technological Measures. For purposes of this Public License, simply making modifications authorized by this Section 2(a)(4) never produces Adapted Material.
+
+          5. Downstream recipients.
+
+               A. Offer from the Licensor – Licensed Material. Every recipient of the Licensed Material automatically receives an offer from the Licensor to exercise the Licensed Rights under the terms and conditions of this Public License.
+
+               B. Additional offer from the Licensor – Adapted Material. Every recipient of Adapted Material from You automatically receives an offer from the Licensor to exercise the Licensed Rights in the Adapted Material under the conditions of the Adapter’s License You apply.
+
+               C. No downstream restrictions. You may not offer or impose any additional or different terms or conditions on, or apply any Effective Technological Measures to, the Licensed Material if doing so restricts exercise of the Licensed Rights by any recipient of the Licensed Material.
+
+          6. No endorsement. Nothing in this Public License constitutes or may be construed as permission to assert or imply that You are, or that Your use of the Licensed Material is, connected with, or sponsored, endorsed, or granted official status by, the Licensor or others designated to receive attribution as provided in Section 3(a)(1)(A)(i).
+
+     b.	Other rights.
+
+          1. Moral rights, such as the right of integrity, are not licensed under this Public License, nor are publicity, privacy, and/or other similar personality rights; however, to the extent possible, the Licensor waives and/or agrees not to assert any such rights held by the Licensor to the limited extent necessary to allow You to exercise the Licensed Rights, but not otherwise.
+
+          2. Patent and trademark rights are not licensed under this Public License.
+
+          3. To the extent possible, the Licensor waives any right to collect royalties from You for the exercise of the Licensed Rights, whether directly or through a collecting society under any voluntary or waivable statutory or compulsory licensing scheme. In all other cases the Licensor expressly reserves any right to collect such royalties.
+
+Section 3 – License Conditions.
+
+Your exercise of the Licensed Rights is expressly made subject to the following conditions.
+
+     a.	Attribution.
+
+          1. If You Share the Licensed Material (including in modified form), You must:
+
+               A. retain the following if it is supplied by the Licensor with the Licensed Material:
+
+                    i.	identification of the creator(s) of the Licensed Material and any others designated to receive attribution, in any reasonable manner requested by the Licensor (including by pseudonym if designated);
+
+                    ii.	a copyright notice;
+
+                    iii. a notice that refers to this Public License;
+
+                    iv.	a notice that refers to the disclaimer of warranties;
+
+                    v.	a URI or hyperlink to the Licensed Material to the extent reasonably practicable;
+
+               B. indicate if You modified the Licensed Material and retain an indication of any previous modifications; and
+
+               C. indicate the Licensed Material is licensed under this Public License, and include the text of, or the URI or hyperlink to, this Public License.
+
+          2. You may satisfy the conditions in Section 3(a)(1) in any reasonable manner based on the medium, means, and context in which You Share the Licensed Material. For example, it may be reasonable to satisfy the conditions by providing a URI or hyperlink to a resource that includes the required information.
+
+          3. If requested by the Licensor, You must remove any of the information required by Section 3(a)(1)(A) to the extent reasonably practicable.
+
+     b.	ShareAlike.In addition to the conditions in Section 3(a), if You Share Adapted Material You produce, the following conditions also apply.
+
+          1. The Adapter’s License You apply must be a Creative Commons license with the same License Elements, this version or later, or a BY-SA Compatible License.
+
+          2. You must include the text of, or the URI or hyperlink to, the Adapter's License You apply. You may satisfy this condition in any reasonable manner based on the medium, means, and context in which You Share Adapted Material.
+
+          3. You may not offer or impose any additional or different terms or conditions on, or apply any Effective Technological Measures to, Adapted Material that restrict exercise of the rights granted under the Adapter's License You apply.
+
+Section 4 – Sui Generis Database Rights.
+
+Where the Licensed Rights include Sui Generis Database Rights that apply to Your use of the Licensed Material:
+
+     a.	for the avoidance of doubt, Section 2(a)(1) grants You the right to extract, reuse, reproduce, and Share all or a substantial portion of the contents of the database;
+
+     b.	if You include all or a substantial portion of the database contents in a database in which You have Sui Generis Database Rights, then the database in which You have Sui Generis Database Rights (but not its individual contents) is Adapted Material, including for purposes of Section 3(b); and
+
+     c.	You must comply with the conditions in Section 3(a) if You Share all or a substantial portion of the contents of the database.
+For the avoidance of doubt, this Section 4 supplements and does not replace Your obligations under this Public License where the Licensed Rights include other Copyright and Similar Rights.
+
+Section 5 – Disclaimer of Warranties and Limitation of Liability.
+
+     a.	Unless otherwise separately undertaken by the Licensor, to the extent possible, the Licensor offers the Licensed Material as-is and as-available, and makes no representations or warranties of any kind concerning the Licensed Material, whether express, implied, statutory, or other. This includes, without limitation, warranties of title, merchantability, fitness for a particular purpose, non-infringement, absence of latent or other defects, accuracy, or the presence or absence of errors, whether or not known or discoverable. Where disclaimers of warranties are not allowed in full or in part, this disclaimer may not apply to You.
+
+     b.	To the extent possible, in no event will the Licensor be liable to You on any legal theory (including, without limitation, negligence) or otherwise for any direct, special, indirect, incidental, consequential, punitive, exemplary, or other losses, costs, expenses, or damages arising out of this Public License or use of the Licensed Material, even if the Licensor has been advised of the possibility of such losses, costs, expenses, or damages. Where a limitation of liability is not allowed in full or in part, this limitation may not apply to You.
+
+     c.	The disclaimer of warranties and limitation of liability provided above shall be interpreted in a manner that, to the extent possible, most closely approximates an absolute disclaimer and waiver of all liability.
+
+Section 6 – Term and Termination.
+
+     a.	This Public License applies for the term of the Copyright and Similar Rights licensed here. However, if You fail to comply with this Public License, then Your rights under this Public License terminate automatically.
+
+     b.	Where Your right to use the Licensed Material has terminated under Section 6(a), it reinstates:
+
+          1. automatically as of the date the violation is cured, provided it is cured within 30 days of Your discovery of the violation; or
+
+          2. upon express reinstatement by the Licensor.
+
+     c.	For the avoidance of doubt, this Section 6(b) does not affect any right the Licensor may have to seek remedies for Your violations of this Public License.
+
+     d.	For the avoidance of doubt, the Licensor may also offer the Licensed Material under separate terms or conditions or stop distributing the Licensed Material at any time; however, doing so will not terminate this Public License.
+
+     e.	Sections 1, 5, 6, 7, and 8 survive termination of this Public License.
+
+Section 7 – Other Terms and Conditions.
+
+     a.	The Licensor shall not be bound by any additional or different terms or conditions communicated by You unless expressly agreed.
+
+     b.	Any arrangements, understandings, or agreements regarding the Licensed Material not stated herein are separate from and independent of the terms and conditions of this Public License.
+
+Section 8 – Interpretation.
+
+     a.	For the avoidance of doubt, this Public License does not, and shall not be interpreted to, reduce, limit, restrict, or impose conditions on any use of the Licensed Material that could lawfully be made without permission under this Public License.
+
+     b.	To the extent possible, if any provision of this Public License is deemed unenforceable, it shall be automatically reformed to the minimum extent necessary to make it enforceable. If the provision cannot be reformed, it shall be severed from this Public License without affecting the enforceability of the remaining terms and conditions.
+
+     c.	No term or condition of this Public License will be waived and no failure to comply consented to unless expressly agreed to by the Licensor.
+
+     d.	Nothing in this Public License constitutes or may be interpreted as a limitation upon, or waiver of, any privileges and immunities that apply to the Licensor or You, including from the legal processes of any jurisdiction or authority.
+
+Creative Commons is not a party to its public licenses. Notwithstanding, Creative Commons may elect to apply one of its public licenses to material it publishes and in those instances will be considered the “Licensor.” Except for the limited purpose of indicating that material is shared under a Creative Commons public license or as otherwise permitted by the Creative Commons policies published at creativecommons.org/policies, Creative Commons does not authorize the use of the trademark “Creative Commons” or any other trademark or logo of Creative Commons without its prior written consent including, without limitation, in connection with any unauthorized modifications to any of its public licenses or any other arrangements, understandings, or agreements concerning use of licensed material. For the avoidance of doubt, this paragraph does not form part of the public licenses.
+
+Creative Commons may be contacted at creativecommons.org.

integrations/ckconfig/docs/oss/licenses/MIT.txt

@@ -0,0 +1,18 @@
+MIT License
+
+Copyright (c) <year> <copyright holders>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
+associated documentation files (the "Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the
+following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial
+portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
+LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
+EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+USE OR OTHER DEALINGS IN THE SOFTWARE.

integrations/ckconfig/docs/releases/v0.1.0.md

@@ -0,0 +1,45 @@
+# CommandKit ckconfig v0.1.0
+
+## Summary
+
+The initial independently versioned ConfigKit integration provides configuration
+inspection and native comparison through CommandKit command declarations. It
+uses CommandKit v0.2.0 and ConfigKit v0.8.0 and is distributed as a source-only
+Go module.
+
+## Features
+
+- `ckconfig.AppCommand`, `ckconfig.Command`, and `ckconfig.FromConfigKit` adapt
+  application loaders and named scopes into explicitly installed declarations.
+- The `config` family exposes scopes, validation, effective YAML, sources, and
+  path explanation according to each scope's declared capabilities.
+- `config diff` compares two selections through ConfigKit's native API and emits
+  YAML additions, right-side changes, and deletion paths. Comparison can be
+  provided independently of ordinary configuration acquisition; differences
+  alone do not make the command fail.
+- Source reports expose native destination, placement, unresolved destination,
+  and version-check evidence alongside the source inventory.
+- Typed selectors, per-side comparison inputs, and invocation state support
+  application-specific acquisition without transferring configuration semantics
+  to CommandKit.
+
+## Requirements and adoption
+
+**Go 1.26.0 or newer is required.** Add
+`gitea.maximumdirect.net/eric/CommandKit/integrations/ckconfig@v0.1.0`, then pass
+the returned declaration to `commandkit.New` or `App.Register`. Importing the
+module does not install commands.
+
+Applications migrating from the ConfigKit helpers in CommandKit v0.1.0 must
+move to the separate module and update scope, loader, binding, and installation
+wiring for the core v0.2.0 API. Update report consumers for the added source
+evidence and any newly installed comparison commands. ConfigKit remains the
+authority on configuration loading, inspection, and comparison semantics.
+
+See the [module README](https://gitea.maximumdirect.net/eric/CommandKit/src/tag/integrations/ckconfig/v0.1.0/integrations/ckconfig/README.md),
+[consumer guide](https://gitea.maximumdirect.net/eric/CommandKit/src/tag/integrations/ckconfig/v0.1.0/docs/consumers/guide.md),
+and [CLI reference](https://gitea.maximumdirect.net/eric/CommandKit/src/tag/integrations/ckconfig/v0.1.0/docs/cli.md).
+
+[COPYRIGHT](https://gitea.maximumdirect.net/eric/CommandKit/src/tag/integrations/ckconfig/v0.1.0/integrations/ckconfig/COPYRIGHT) |
+[LICENSE](https://gitea.maximumdirect.net/eric/CommandKit/src/tag/integrations/ckconfig/v0.1.0/integrations/ckconfig/LICENSE) |
+[ATTRIBUTION](https://gitea.maximumdirect.net/eric/CommandKit/src/tag/integrations/ckconfig/v0.1.0/integrations/ckconfig/docs/oss/attribution.md)