Add completion hints to maintained commands

integrations/ckprompt/examples/composed/README.md

@@ -40,6 +40,13 @@ shortens the PromptKit group. `--fmt` is scoped to named prompt inspection and
 `--hlep` is available globally. The `smoke` shortcut retains the canonical
 `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
+[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`
+alias selects the PromptKit command context without loading an engine.
+
 The composition calls `ckconfig.Command(suite)` and `ckprompt.Command(definitions)`
 directly in a `[]commandkit.Declaration` with root-installed routing rules.
 Group children remain canonical `Command` values. For command-only slices,

integrations/ckprompt/examples/composed/main.go

@@ -290,6 +290,7 @@ func newAppWithEngineLoader(
 	declarations := []commandkit.Declaration{
 		configCommand,
 		definitionCommand,
+		commandkit.Completion("composed-example"),
 		commandkit.Group("session", "Manage saved sessions.", restore),
 		commandkit.Alias("list collections", "promptkit list collections"),
 		commandkit.Alias("promptkit list bundles", "promptkit list collections"),

integrations/ckprompt/examples/composed/main_test.go

@@ -352,6 +352,34 @@ func TestComposedCatalogsAndSmokeUseInjectedClientOnlyForInference(t *testing.T)
 	}
 }
 
+func TestComposedCompletionUsesHintsWithoutLoadingEngine(t *testing.T) {
+	var loads, calls int
+	loader := func(ctx context.Context, selection ckconfig.Selection, input *inspectionInput, cache *runCache) (*promptkit.Engine, error) {
+		loads++
+		return loadPromptEngine(ctx, selection, input, cache)
+	}
+	app, err := newAppWithEngineLoader(&exampleLLMClient{calls: &calls}, loader, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, tc := range []struct {
+		args []string
+		want string
+	}{
+		{[]string{"__complete", "pk", "show", "prompt", "briefing", "--fmt=y"}, "yaml\n"},
+		{[]string{"__complete", "pk", "show", "prompt", "briefing", "--config=fixtures/"}, ":0\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.want) {
+			t.Fatalf("query %q outcome=%#v output=%q", tc.args, outcome, output.String())
+		}
+	}
+	if loads != 0 || calls != 0 {
+		t.Fatalf("completion loaded engine %d times and invoked client %d times", loads, calls)
+	}
+}
+
 func TestComposedSmokeReportSurvivesInferenceFailure(t *testing.T) {
 	wantCause := errors.New("local example inference failed")
 	smokeTest := func(_ context.Context, request ckprompt.SmokeRequest, _ *inspectionInput, _ *runCache) (commandkit.Acquired[*promptkit.SmokeTestReport], error) {