Document PromptKit comparison and catalogs

integrations/ckprompt/README.md

@@ -1,9 +1,8 @@
 # CommandKit ckprompt
 
-`ckprompt` is the optional PromptKit integration for CommandKit. It can adapt
-PromptKit engine configuration into a `ckconfig.Scope` and create core command
-declarations for named prompt and profile inspection. Importing it does not
-install either command family.
+`ckprompt` is the optional PromptKit integration for CommandKit. It adapts
+PromptKit engine configuration, native comparison, prompt/profile catalogs, and
+named inspection. Importing it does not install either command family.
 
 ## Module
 
@@ -17,15 +16,16 @@ for callback, input, state, and acquisition contracts.
 ## Example
 
 Add `ckprompt.ConfigScope(loadEngine)` to the scopes passed to
-`ckconfig.Command` when the application wants PromptKit engine configuration in
-the `config` family. Install `ckprompt.Command(ckprompt.FromEngine(loadEngine))`
-separately for named prompt and profile inspection. `FromEngine` supplies
-PromptKit-backed callbacks; applications may provide their own callbacks with
-`ckprompt.Suite`. CommandKit-owned inspection code does not execute prompts,
-contact model providers, or resolve credentials; application loaders and direct
-callbacks retain their own effects. See the
+`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 and named inspections. `FromEngine` supplies all four PromptKit-backed
+callbacks; applications may narrow them before capture or provide their own
+callbacks with `ckprompt.Suite`. 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-definition-inspection)
-for the inspection boundary and report semantics. The maintained
+for operator commands and report semantics. The maintained
 [composed example](examples/composed) shows complete application wiring.
 
 ## License and attribution

integrations/ckprompt/adapters.go

@@ -36,15 +36,18 @@ type ProfileRequest struct {
 // construction failures.
 // Factory results and callback effects remain caller-owned: Command does not
 // deep-copy arbitrary objects or repair aliases returned by factories.
+// A reached operation prepares one input, applies its captured selectors, and
+// checks the input before creating state and calling the selected provider.
 // 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 input preparation is reached,
-	// before applying selectors and calling CheckInput.
+	// NewInput is called once when definition 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 inspection is reached, after input checks
-	// pass. If nil, state is the zero value of S, including nil for pointer types.
+	// NewState is called once when an inspection 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 and
 	// catalog commands.
@@ -69,11 +72,12 @@ type Suite[I, S any] struct {
 type engineLoader[I, S any] func(context.Context, ckconfig.Selection, I, S) (*promptkit.Engine, error)
 
 // ConfigScope adapts PromptKit's captured configuration inspection to the
-// standard configuration commands. The loader is not called during declaration
-// construction or installation; it is called only when a config operation
-// selects the promptkit scope, with that operation's input and shared state.
-// PromptKit diagnostics and error identity are returned through ckconfig's
-// acquisition contract.
+// standard configuration commands, including native comparison when the scope
+// declares Diff. The loader is not called during declaration construction or
+// installation; it is called only when a config operation selects the
+// promptkit scope, with that operation's input and shared state. PromptKit
+// diagnostics and supported error identity are returned through ckconfig's
+// acquisition and comparison contracts.
 func ConfigScope[I, S any](load func(context.Context, ckconfig.Selection, I, S) (*promptkit.Engine, error)) ckconfig.Scope[I, S] {
 	scope := ckconfig.Scope[I, S]{
 		Name:       "promptkit",
@@ -139,11 +143,12 @@ func promptKitContextError(ctx context.Context) error {
 	return ctx.Err()
 }
 
-// FromEngine creates prompt and profile catalog and inspection callbacks backed
-// by a PromptKit engine loader. It 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. A nil loader is retained as an adapter
+// FromEngine supplies callbacks for prompt and profile catalogs and named
+// inspections backed by a PromptKit engine loader. It 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. The callbacks can be
+// narrowed before Command captures them. A nil loader is retained as an adapter
 // issue.
 func FromEngine[I, S any](load func(context.Context, ckconfig.Selection, I, S) (*promptkit.Engine, error)) Suite[I, S] {
 	if load == nil {

integrations/ckprompt/command.go

@@ -31,11 +31,16 @@ type catalogInput[I any] struct {
 	selected  I
 }
 
-// Command captures the optional PromptKit catalog and named inspection trees
-// and adds only the operations present in suite. It adds no configuration
-// family; callers compose ConfigScope independently. Construction and
-// installation do not run suite callbacks. Suite documents invocation input
-// and state initialization, zero values, and caller ownership of returned objects.
+// Command captures the optional PromptKit catalog and named inspection
+// callbacks and adds only supplied operations, generating list and show groups
+// independently. An absent suite claims no namespace; attached construction
+// issues remain reportable. It adds no configuration family; callers compose
+// ConfigScope independently. Construction, installation, help, and version do
+// not run suite factories or providers. Suite documents invocation input and
+// state initialization, zero values, and caller ownership of returned objects.
+// Catalog commands accept config/overlay selection and suite selectors, and
+// render YAML with `yaml` as the only format and default. Named-show formats are
+// unchanged.
 func Command[I, S any](suite Suite[I, S]) commandkit.Command {
 	if suite.InspectPrompt == nil && suite.InspectProfile == nil && suite.ListPrompts == nil && suite.ListProfiles == nil {
 		command := commandkit.NoCommand()

integrations/ckprompt/doc.go

@@ -1,4 +1,5 @@
-// Package ckprompt provides optional PromptKit configuration and named
-// definition inspections for CommandKit. Importing ckprompt installs neither
-// family; callers compose its declarations with core and ckconfig explicitly.
+// Package ckprompt provides optional PromptKit configuration comparison,
+// definition catalogs, and named inspections for CommandKit. Importing ckprompt
+// installs neither family; callers compose its declarations with core and
+// ckconfig explicitly.
 package ckprompt