Clarify inspection input ownership and documentation

integrations/ckconfig/contracts.go

@@ -69,7 +69,7 @@ type View struct {
 type Scope[I, S any] struct {
 	// Name identifies the scope in CLI selection and reports.
 	Name string
-	// Summary is shown when the scope is listed.
+	// Summary describes the scope. Scope discovery reports name and operations only.
 	Summary string
 	// Operations selects the standard handlers exposed for this scope.
 	Operations []Operation
@@ -89,10 +89,21 @@ type Selector[I any] struct {
 
 // Suite declares the typed input, shared state, selectors, and configuration
 // scopes used to assemble configuration commands.
+//
+// Input initialization is separate for each selected scope; state is shared
+// by that invocation's acquisitions. Factory results and callback effects remain
+// caller-owned: Command does not deep-copy arbitrary objects or repair aliases
+// returned by factories. Core-owned repeated flag collections are copied when
+// applied to separate inputs. Factories are not invoked during construction,
+// installation, help, version, or scope discovery, and need not run after failure.
 type Suite[I, S any] struct {
-	// NewInput creates fresh input storage for each selected scope.
+	// NewInput is called once for each selected scope reached after operation
+	// preflight, before applying its selectors and calling CheckInput.
+	// If nil, input is the zero value of I, including nil for pointer types.
 	NewInput func() I
-	// NewState creates shared acquisition state once per inspection invocation.
+	// NewState is called once when acquisition is reached, after all selected
+	// inputs pass their checks. The result is shared by selected acquisitions.
+	// If nil, state is the zero value of S, including nil for pointer types.
 	NewState func() S
 	// Selectors declares typed flags and their applicable scopes.
 	Selectors []Selector[I]

integrations/ckconfig/family.go

@@ -43,9 +43,9 @@ type preparedSuite[I, S any] struct {
 // Command eagerly captures a configuration suite as a root-only config family.
 // It copies suite slices, retains callback references, and returns a reusable
 // declaration; installation does not invoke factories or providers. During an
-// inspection, it creates separate input for each selected scope, validates
-// those inputs before acquisition, and creates shared state once for that
-// invocation.
+// inspection, it initializes input separately for each selected scope and
+// validates those inputs before acquisition. Suite documents factory timing,
+// zero values, shared state, and caller ownership of returned objects.
 func Command[I, S any](suite Suite[I, S]) commandkit.Command {
 	prepared := captureSuite(suite)
 	if len(prepared.scopes) == 0 {