Document PromptKit request validation

integrations/ckprompt/adapters.go

@@ -43,7 +43,7 @@ type RequirementsRequest struct {
 }
 
 // Suite describes application-owned input, shared state, and optional catalog,
-// named inspection, requirements inspection, and concrete request validation
+// named inspection, requirements discovery, and concrete request validation
 // capabilities. Its private issues retain adapter construction failures.
 // Factory results and callback effects remain caller-owned: Command does not
 // deep-copy arbitrary objects or repair aliases returned by factories.
@@ -52,13 +52,14 @@ 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 calling CheckInput.
+	// NewInput is called once when definition, requirements, validation, 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 callback 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, validation, 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.
@@ -71,12 +72,15 @@ type Suite[I, S any] struct {
 	// InspectProfile inspects the selected profile after input and state preparation.
 	InspectProfile func(context.Context, ProfileRequest, I, S) (commandkit.Acquired[*promptkit.ProfileInspection], error)
 	// InspectRequirements inspects native PromptKit requirements after input and
-	// state preparation. It is optional; a nil callback omits the requirements
-	// command without disabling other capabilities.
+	// state preparation. It is optional; a nil callback omits
+	// `promptkit requirements show` without disabling validation or other
+	// capabilities.
 	InspectRequirements func(context.Context, RequirementsRequest, I, S) (commandkit.Acquired[*promptkit.RequirementInspection], error)
-	// ValidateRequest validates a concrete PromptKit request after input and state
-	// preparation. It is optional; a nil callback omits request validation without
-	// disabling other capabilities.
+	// ValidateRequest validates a concrete PromptKit request after input and
+	// state preparation. It is optional; a nil callback omits
+	// `promptkit requirements validate` without disabling discovery or other
+	// capabilities. The acquisition carries diagnostics and an empty value on
+	// success; PromptKit errors are returned unchanged where supported.
 	ValidateRequest func(context.Context, ValidationRequest, I, S) (commandkit.Acquired[struct{}], error)
 	// ListPrompts lists prompt identities after input and state preparation.
 	// It is optional; a nil callback does not install a prompt catalog command.
@@ -89,13 +93,18 @@ type Suite[I, S any] struct {
 }
 
 // WithRequestValidation attaches PromptKit-backed concrete request validation
-// to suite. The loader receives the request's original selection; the builder,
-// when present, runs first and its returned request is passed to PromptKit
-// unchanged. A nil builder forwards the seed request. PromptKit's native
-// validation errors and the engine loader's configuration diagnostics are
-// returned through the acquisition. A nil loader is retained as a suite wiring
-// issue and does not install a validation callback. Caller-owned callback
-// references and objects remain caller-owned.
+// to suite while preserving its other capabilities and retained issues. Those
+// issues remain attached if capabilities are narrowed before Command captures
+// the suite. The
+// builder, when present, runs before the engine loader and receives the seed,
+// input, state, and invocation context. Its returned request is passed to
+// PromptKit unchanged; the loader receives the seed's original configuration
+// selection. A nil builder forwards the seed request unchanged. A builder
+// failure prevents engine loading and preserves its supported error identity.
+// Native validation errors are returned with supported identity, and
+// configuration diagnostics from engine loading remain in the acquisition. A
+// nil loader is retained as a suite wiring issue and does not install a
+// validation callback. Callback references and objects remain caller-owned.
 func WithRequestValidation[I, S any](
 	suite Suite[I, S],
 	load func(context.Context, ckconfig.Selection, I, S) (*promptkit.Engine, error),
@@ -218,15 +227,17 @@ func promptKitContextError(ctx context.Context) error {
 	return ctx.Err()
 }
 
-// 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.
+// FromEngine supplies five PromptKit-backed callbacks: prompt and profile
+// catalogs, named prompt and profile inspection, and requirements discovery.
+// The requirements callback forwards RequirementsRequest.Inspection to
+// Engine.InspectRequirements. Concrete request validation is an independent
+// capability and can be composed explicitly with WithRequestValidation.
+// 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

@@ -50,14 +50,16 @@ type inputAssignment struct {
 }
 
 // Command captures the optional PromptKit catalog, named inspection,
-// requirements inspection, and concrete request validation callbacks and adds
-// only supplied operations. 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. 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.
+// requirements discovery, and concrete request validation callbacks and adds
+// only supplied operations. Discovery and validation share the
+// `requirements` group and remain independently optional. 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. 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, named inspections, and prompt requirements inspection
-// for CommandKit. Importing ckprompt installs neither family; callers compose
-// its declarations with core and ckconfig explicitly.
+// definition catalogs, named inspections, requirements discovery, and concrete
+// request validation for CommandKit. Importing ckprompt installs neither
+// family; callers compose its declarations with core and ckconfig explicitly.
 package ckprompt

integrations/ckprompt/validation.go

@@ -5,12 +5,12 @@ import (
 	promptkit "gitea.maximumdirect.net/eric/promptkit"
 )
 
-// ValidationRequest carries the configuration selection and concrete
-// PromptKit request to validate.
+// ValidationRequest carries the configuration selection and seed PromptKit
+// request populated by the standard validation command inputs.
 type ValidationRequest struct {
 	// Selection identifies the configuration sources used to load the engine.
 	Selection ckconfig.Selection
-	// Request is the seed request, or the request returned by a validation
-	// builder when one is configured.
+	// Request contains the prompt identity, scalar context, variables, and
+	// artifact references supplied to the command.
 	Request promptkit.RunRequest
 }