Clarify inspection input ownership and documentation

docs/consumers/guide.md

@@ -103,10 +103,12 @@ values.
 
 Use `ckconfig.Command(ckconfig.Suite[I, S]{...})` when the application needs
 multiple named scopes, selector flags, scope-aware input checks, or shared
-acquisition state. Each selected scope receives its own initialized input. The
-suite's `NewState` runs once for the inspection invocation after selected input
-checks pass, and the resulting state is shared by selected acquisitions. The
-application owns the state type and what it caches. `ckconfig.FromConfigKit`
+acquisition state. Input is initialized separately for each selected scope;
+state is shared by selected acquisitions. Factory results remain caller-owned,
+so separate initialization calls do not guarantee distinct objects. See
+[ckconfig.Suite's GoDoc](../../integrations/ckconfig/contracts.go) for factory
+timing, omitted-factory zero values (including nil pointers), and ownership.
+The application owns the state type and what it caches. `ckconfig.FromConfigKit`
 adapts a typed ConfigKit loader without calling it during construction.
 
 The `config` family provides scope discovery, validation, native effective YAML,
@@ -124,16 +126,19 @@ it under `config`; it does not install named definition commands.
 inspection callbacks. Set its `NewInput`, `NewState`, selectors, or validation
 when the application needs them, then pass `ckprompt.Command(suite)` to core.
 Prompt and profile capabilities can be installed independently by providing
-only the corresponding callback. Each selected inspection gets a fresh input
-and one shared state value for that invocation. The loader receives the
-invocation context, explicitly supplied selection, input, and state. The adapter
+only the corresponding callback. Each selected inspection prepares one input
+and one state value when those steps are reached. See
+[ckprompt.Suite's GoDoc](../../integrations/ckprompt/adapters.go) for factory
+timing, omitted-factory zero values, and caller-owned objects and effects.
+The loader receives invocation context, explicitly supplied selection, input,
+and state. The adapter
 uses PromptKit's public inspection methods and preserves acquisition diagnostics
 and error identity.
 
-Definition inspection does not execute a prompt, contact a model provider, or
-resolve credential values. Credential fields in reports identify environment
-variable names and requirements only; they do not report credential
-availability.
+CommandKit-owned inspection code does not execute prompts, contact model
+providers, or resolve credential values; application loaders and direct callbacks
+retain their own effects. The [CLI reference](../cli.md#promptkit-definition-inspection)
+owns the inspection boundary and credential-report semantics.
 
 The [composed example](../../integrations/ckprompt/examples/composed/README.md)
 combines app and PromptKit config scopes, independently registers profile

docs/roadmap/remediation.md

@@ -126,7 +126,17 @@ require callbacks to run after failure.
 
 ## R3: Make public documentation precise about ownership and the final API
 
-**Status:** Open. **Priority:** P2.
+**Status:** Completed (2026-10-11). **Priority:** P2.
+
+**Completed work:** the suites' GoDoc now specifies initialization timing,
+omitted-factory zero values (including nil pointers), early-failure limits, and
+caller ownership of objects, aliases, and effects. Family GoDoc and consumer
+guidance link to those owners. Inspection claims are qualified, the composed
+example describes `NewInput`/`NewState`, and `Scope.Summary` no longer promises
+discovery output. Reviewed against current preparation/acquisition code and the
+example; current consumer/example Markdown has no obsolete context API names.
+Changed local links/fragments and whitespace checks pass. Runtime rules and
+report fields are unchanged.
 
 **Evidence and corrections:**