Document PromptKit requirements discovery

integrations/ckprompt/README.md

@@ -1,8 +1,9 @@
 # CommandKit ckprompt
 
 `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.
+PromptKit engine configuration, native comparison, prompt/profile catalogs,
+named inspection, and prompt requirements discovery. Importing it does not
+install either command family.
 
 ## Module
 
@@ -19,12 +20,13 @@ 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 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)
+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)
 for operator commands and report semantics. The maintained
 [composed example](examples/composed) shows complete application wiring.
 

integrations/ckprompt/adapters.go

@@ -36,7 +36,9 @@ type ProfileRequest struct {
 type RequirementsRequest struct {
 	// Selection carries the configuration and overlay values supplied to the command.
 	Selection ckconfig.Selection
-	// Inspection carries PromptKit's discovery context for the selected prompt.
+	// Inspection forwards PromptKit's native prompt, version, profile, variable,
+	// and session discovery context. Optional version, profile, and session
+	// strings retain PromptKit's empty-value semantics.
 	Inspection promptkit.RequirementInspectionRequest
 }
 
@@ -156,13 +158,15 @@ func promptKitContextError(ctx context.Context) error {
 	return ctx.Err()
 }
 
-// FromEngine supplies callbacks for prompt and profile catalogs, named
-// inspections, and requirements inspection 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. Applications can narrow these callbacks before Command
-// captures them. A nil loader is retained as an adapter issue.
+// FromEngine supplies prompt and profile catalog callbacks, named inspection
+// callbacks, and a requirements inspection callback backed by a PromptKit engine
+// loader. The requirements callback forwards RequirementsRequest.Inspection to
+// Engine.InspectRequirements. 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.
 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/command.go

@@ -49,8 +49,10 @@ type variableAssignment struct {
 // 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.
+// suite factories or providers. Command captures suite callbacks and selector
+// metadata; callback-referenced objects and effects remain caller-owned. 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.

integrations/ckprompt/doc.go

@@ -1,5 +1,5 @@
 // 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.
+// definition catalogs, named inspections, and prompt requirements inspection
+// for CommandKit. Importing ckprompt installs neither family; callers compose
+// its declarations with core and ckconfig explicitly.
 package ckprompt

integrations/ckprompt/examples/composed/README.md

@@ -1,8 +1,8 @@
 # Composed consumer
 
 This example composes application configuration, PromptKit configuration,
-PromptKit comparison and catalogs, definition inspection, and one
-application-owned command:
+PromptKit comparison and catalogs, definition and requirements inspection, and
+one application-owned command:
 
 ```sh
 go run . config scopes
@@ -14,6 +14,8 @@ go run . promptkit list prompts --config fixtures/before.yml --campaign spring
 go run . promptkit list profiles --config fixtures/after.yml --campaign autumn --format yaml
 go run . promptkit show prompt briefing --campaign spring --format yaml
 go run . promptkit show profile spring --campaign spring
+go run . promptkit requirements show briefing --campaign spring
+go run . promptkit requirements show briefing --campaign spring --var mode=full --format yaml
 go run . session restore session-42 --campaign spring
 ```
 
@@ -38,3 +40,11 @@ supplied configuration/overlay selection and the supplied campaign, including
 presence. The campaign override is applied through ConfigKit before loading.
 These are choices for this example's loader and do not define a CommandKit cache
 policy.
+
+The first requirements command reports incomplete discovery: PromptKit records
+the conditional `notes` input and a missing `mode` issue. Supplying `mode=full`
+selects that branch, classifies the undeclared `notes` input as required, and
+completes discovery. Both commands return successful reports; the result does
+not execute the prompt or establish input, credential, or execution readiness.
+See the [CLI reference](../../../../docs/cli.md#promptkit-requirements) for the
+command and report contract.