Document PromptKit catalogs and smoke testing

integrations/ckprompt/adapters.go

@@ -73,20 +73,20 @@ type RequirementsRequest struct {
 // Factories are not invoked during construction, installation, help, or version,
 // and need not run after failure.
 type Suite[I, S any] struct {
-	// NewInput is called once when definition, requirements, validation, or
-	// catalog input preparation is reached, before applying selectors and
+	// NewInput is called once when inspection, requirements, validation, smoke,
+	// or catalog input preparation is reached, before applying selectors and
 	// calling CheckInput.
 	// If nil, input is the zero value of I, including nil for pointer types.
 	NewInput func() I
-	// NewState is called once when an inspection, validation, or catalog
+	// NewState is called once when an inspection, validation, smoke, or catalog
 	// callback is reached, after input checks pass. If nil, state is the zero
 	// value of S, including nil for pointer types.
 	NewState func() S
-	// Selectors declares the original typed flags accepted by definition,
-	// requirements, validation, and catalog commands.
+	// Selectors declares the original typed flags accepted by inspection,
+	// requirements, validation, smoke, and catalog commands.
 	Selectors []commandkit.Flag[I]
-	// CheckInput validates selected definition, requirements, validation, or catalog input
-	// before state creation.
+	// CheckInput validates selected inspection, requirements, validation, smoke,
+	// or catalog input before state creation.
 	CheckInput func(ckconfig.Selection, I) error
 	// InspectPrompt inspects the selected prompt after input and state preparation.
 	InspectPrompt func(context.Context, PromptRequest, I, S) (commandkit.Acquired[*promptkit.PromptInspection], error)
@@ -106,7 +106,8 @@ type Suite[I, S any] struct {
 	// SmokeTest runs one concrete native smoke-test operation after input and
 	// state preparation. It is optional; nil omits only the smoke-test command.
 	// The acquisition retains a native report even when the callback also
-	// returns an error.
+	// returns an error. For `test all`, CommandKit calls the captured callback
+	// sequentially for each selected kind after preparing input and state once.
 	SmokeTest func(context.Context, SmokeRequest, I, S) (commandkit.Acquired[*promptkit.SmokeTestReport], error)
 	// ListPrompts lists prompt identities after input and state preparation.
 	// It is optional independently of the other catalogs; nil omits only this
@@ -273,13 +274,14 @@ func promptKitContextError(ctx context.Context) error {
 // The requirements callback forwards RequirementsRequest.Inspection to
 // Engine.InspectRequirements. Concrete request validation is an independent
 // capability and can be composed explicitly with WithRequestValidation. Smoke
-// testing is also an explicit capability installed by its helper.
+// testing is also an explicit capability installed with WithSmokeTesting.
 // FromEngine does not call the loader during construction. Each selected
 // operation passes its context, supplied selection, initialized input, and
 // shared invocation state to the loader before calling PromptKit's public
 // listing or inspection method. Applications can narrow, wrap, or replace these
 // callbacks before Command captures them. A nil loader is retained as an
-// adapter issue.
+// adapter issue. Each callback returns loader diagnostics with the native
+// operation's value and error.
 func FromEngine[I, S any](load func(context.Context, ckconfig.Selection, I, S) (*promptkit.Engine, error)) Suite[I, S] {
 	if load == nil {
 		return Suite[I, S]{issues: []error{errors.New("PromptKit engine loader is nil")}}