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,