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

examples/core/README.md

@@ -19,7 +19,8 @@ alias. Its declaration slice mixes the canonical group and routing rules as
 are visible in the output.
 
 The example also installs `Completion("core-example")` and gives the `report`
-scenario argument static choices. Build it with the basename shown above, load
+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`.
 

integrations/ckprompt/examples/composed/README.md

@@ -41,7 +41,8 @@ shortens the PromptKit group. `--fmt` is scoped to named prompt inspection and
 `promptkit test KIND` operand, including the special `all` aggregate.
 
 The example installs `Completion("composed-example")`. Build it as
-`go build -o composed-example .`, then load a shell script as described in the
+`go build -o composed-example .`. Initialize `bash-completion` first if using
+Bash, then load a shell script as described in the
 [CLI reference](../../../../docs/cli.md#shell-completion). Try completion after
 `composed-example pk show prompt briefing --fmt=` or after the filename prefix
 in `composed-example config show --config=fixtures/`. The already-entered `pk`

internal/cobra/testdata/completion_terminal.py

@@ -15,7 +15,10 @@ if executable is None:
 quoted_script = shlex.quote(script)
 if shell == "bash":
     args = ["--noprofile", "--norc", "-i"]
-    setup = 'PS1="PROMPT> "; source /usr/share/bash-completion/bash_completion; source ' + quoted_script
+    bash_init = os.environ.get("COMPLETION_BASH_INIT", "/usr/share/bash-completion/bash_completion")
+    if not os.path.isfile(bash_init):
+        raise SystemExit("Set COMPLETION_BASH_INIT to the bash-completion initialization file")
+    setup = 'PS1="PROMPT> "; source ' + shlex.quote(bash_init) + "; source " + quoted_script
 elif shell == "zsh":
     args = ["-f"]
     setup = 'PROMPT="PROMPT> "; '