Document Bash completion setup

docs/cli.md

@@ -72,7 +72,7 @@ Applications may install shell completion explicitly. When installed, generate
 and load the script for the executable name chosen by the application:
 
 ```sh
-# Bash
+# Bash, after initializing bash-completion
 source <(app completion bash)
 # Zsh, after initializing its completion system with compinit
 source <(app completion zsh)
@@ -80,6 +80,18 @@ source <(app completion zsh)
 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

docs/development.md

@@ -168,3 +168,17 @@ go run ./examples/core workspace greet --count=0 --tag=first --tag second
 
 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/roadmap/remediation.md

@@ -107,7 +107,9 @@ semantic equality between separately constructed nonzero choice hints.
 
 ### 5. Document the Bash initialization prerequisite
 
-Priority: P3. Status: open.
+Priority: P3. Status: complete.
+
+- [x] Completed: CLI setup, examples, and validation guidance now explain Bash completion initialization. The harness accepts a package-specific init path; both required helper functions were verified in clean Bash.
 
 The [CLI instructions](../cli.md#shell-completion) tell operators to source the
 generated Bash script without mentioning Bash completion helpers. The