Document PromptKit catalogs and smoke testing

integrations/ckprompt/README.md

@@ -1,9 +1,9 @@
 # CommandKit ckprompt
 
 `ckprompt` is the optional PromptKit integration for CommandKit. It adapts
-PromptKit engine configuration, native comparison, prompt/profile catalogs,
-named inspection, and prompt requirements discovery. Importing it does not
-install either command family.
+PromptKit engine configuration, native comparison, five catalogs, named
+inspection, requirements discovery and validation, and native smoke tests.
+Importing it does not install either command family.
 
 ## Module
 
@@ -19,14 +19,17 @@ for callback, input, state, and acquisition contracts.
 Add `ckprompt.ConfigScope(loadEngine)` to the scopes passed to
 `ckconfig.Command` when the application wants PromptKit engine configuration
 and native comparison in the `config` family. Install
-`ckprompt.Command(ckprompt.FromEngine(loadEngine))` separately for prompt/profile
-catalogs, named inspections, and requirements discovery. `FromEngine` supplies
-all five PromptKit-backed callbacks; applications may narrow, wrap, or replace
-them before capture or provide custom callbacks with `ckprompt.Suite`.
-Requirements is independently optional. CommandKit-owned inspection and
-listing code does not execute prompts or contact model providers; application
-loaders and direct callbacks retain their own effects. See the
-[CLI reference](https://gitea.maximumdirect.net/eric/CommandKit/src/branch/main/docs/cli.md#promptkit-requirements)
+`ckprompt.Command(ckprompt.FromEngine(loadEngine))` separately for catalogs,
+named inspections, and requirements discovery. `FromEngine` supplies eight
+PromptKit-backed callbacks: three inspections and five catalogs. Applications
+may narrow, wrap, or replace them before capture or provide custom callbacks
+with `ckprompt.Suite`. Add concrete request validation and smoke testing
+explicitly with `WithRequestValidation` and `WithSmokeTesting`. Inspection,
+requirements, and catalog operations do not execute prompts or contact model
+providers; application loaders and callbacks retain their own effects. Smoke
+testing invokes the selected native PromptKit operation; the
+application retains ownership of client and configuration choices. See the
+[CLI reference](https://gitea.maximumdirect.net/eric/CommandKit/src/branch/main/docs/cli.md#promptkit-smoke-testing)
 for operator commands and report semantics. The maintained
 [composed example](examples/composed) shows complete application wiring.
 

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")}}

integrations/ckprompt/doc.go

@@ -1,5 +1,5 @@
 // Package ckprompt provides optional PromptKit configuration comparison,
-// definition catalogs, named inspections, requirements discovery, and concrete
-// request validation for CommandKit. Importing ckprompt installs neither
+// prompt catalogs, named inspections, requirements discovery and validation,
+// and native smoke testing for CommandKit. Importing ckprompt installs neither
 // family; callers compose its declarations with core and ckconfig explicitly.
 package ckprompt

integrations/ckprompt/smoke.go

@@ -10,8 +10,9 @@ import (
 	promptkit "gitea.maximumdirect.net/eric/promptkit"
 )
 
-// SmokeRequest carries the configuration selection and seed request for one
-// concrete PromptKit smoke-test operation.
+// SmokeRequest pairs the configuration selection with the seed request for one
+// concrete PromptKit smoke-test operation. It is passed to the optional
+// builder and the Suite.SmokeTest callback.
 type SmokeRequest struct {
 	// Selection identifies the configuration sources used to load the engine.
 	Selection ckconfig.Selection
@@ -25,7 +26,8 @@ type SmokeRequest struct {
 // invocation context. Its complete returned request is passed to PromptKit;
 // without a builder, the seed is forwarded unchanged. Reports and errors from
 // PromptKit are both retained. A nil loader is kept as a suite wiring issue and
-// does not install a smoke-test callback.
+// does not install a smoke-test callback. The callback also retains engine
+// loading diagnostics with the report and error.
 func WithSmokeTesting[I, S any](
 	suite Suite[I, S],
 	load func(context.Context, ckconfig.Selection, I, S) (*promptkit.Engine, error),