Add completion hints to maintained commands

docs/cli.md

@@ -66,6 +66,31 @@ 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
+source <(app completion bash)
+# Zsh, after initializing its completion system with compinit
+source <(app completion zsh)
+# Fish
+app completion fish | source
+```
+
+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,

docs/consumers/guide.md

@@ -87,6 +87,34 @@ 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.
 
+## Shell completion
+
+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:
+
+```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()}
+```
+
+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.
+
 ## Invocation reporting
 
 `Invocation.Reporter()` supplies the reporter for the current handler. Use

docs/roadmap/completion.md

@@ -1,8 +1,8 @@
 # Shell completion
 
-Status: initial scope and all four product decisions selected; implementation
-has not started. Provide canonical suggestions with alias-aware interpretation
-for Bash, Zsh, and Fish through explicitly installed completion support.
+Status: the selected initial scope is implemented; final sprint validation
+remains. Canonical suggestions and alias-aware interpretation are available for
+Bash, Zsh, and Fish through explicitly installed completion support.
 
 ## Purpose
 
@@ -14,7 +14,7 @@ Completion helps an operator construct an invocation. It does not execute the
 selected application command. Preserve application ownership of runtime behavior
 and upstream ownership of configuration and prompt semantics.
 
-## Current baseline
+## Planning baseline
 
 Reviewed baseline: `2301872` (`Stop flag interpretation at unknown flags`).
 

docs/roadmap/deferred.md

@@ -33,7 +33,7 @@ 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.
 
-Alias discovery may be omitted from the MVP. This deferral does not establish a
+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
@@ -46,7 +46,8 @@ operator or consumer need and an appropriate ownership/behavior decision:
 
 - JSON reports and output-file management or reloadable export.
 - Shell-completion extensions beyond the initial scope in the
-  [completion roadmap](completion.md), including alias discovery described above.
+  [completion roadmap](completion.md), 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 beyond PromptKit's native smoke checks and additional

docs/roadmap/implementation.md

@@ -1,6 +1,6 @@
 # Shell completion implementation plan
 
-Status: Stages 1–6 complete. Stage 7 is next.
+Status: Stages 1–7 complete. Stage 8 is next.
 
 Implement the [shell completion roadmap](completion.md) from baseline
 `2301872`. Follow the stages in order in one sprint. Intermediate stages may
@@ -274,6 +274,8 @@ interactive Bash, Zsh, and Fish transport matrix pass.
 
 ## Stage 7: Annotate maintained commands and examples
 
+Status: complete.
+
 1. Annotate static format/scope flags where their choices already come from
    fixed command metadata or literals. Use the same values as the existing
    version, config, and PromptKit command implementations; omit scope hints
@@ -291,6 +293,16 @@ interactive Bash, Zsh, and Fish transport matrix pass.
    update the feature status and keep alias discovery and dynamic discovery
    in deferred work.
 
+Completion: annotated built-in version, configuration, and PromptKit formats,
+supported configuration scopes, and filename selections. The core and composed
+examples install completion and demonstrate choices, paths, and entered
+aliases. Integration tests verify scope availability and completion without
+input, state, acquisition, comparison, engine, or client callbacks. GoDoc, CLI,
+consumer, example, and roadmap documentation now describe the delivered scope;
+alias and dynamic discovery remain deferred. Root and both integration package
+tests pass in the local workspace, and changed Markdown links and whitespace
+checks pass.
+
 ## Stage 8: Validate the assembled sprint
 
 1. Exercise the generated scripts in Bash, Zsh, and Fish using a built fixture