Clarify credential inspection and protect request privacy

docs/consumers/pkg-promptkit.md

@@ -719,18 +719,19 @@ if err != nil {
 }
 
 target := inspection.EffectiveModelParams
+if inspection.APIKeyRequired {
+	// Arrange a usable direct or configured environment credential.
+}
 if target.APIKeyEnv != "" {
-	// This is a configured optional environment lookup source.
-} else if inspection.APIKeyRequired {
-	// Arrange a direct credential before later execution.
+	// This is the configured environment lookup source, not its value.
 }
 ```
 
 Use this configuration-time boundary when only the profile and its target need
 checking. Use `Prepare` when the application also needs prompt, input, schema,
 or rendering work; use prepared execution when that work must remain tied to a
-later execution. A reported `APIKeyEnv` is a configured optional source, while
-`APIKeyRequired` is the explicit local requirement. The
+later execution. A reported `APIKeyEnv` identifies a configured source, while
+`APIKeyRequired` is the explicit requirement; both may be present. The
 [credential format reference](../formats.md#credentials) and the method's
 [GoDoc](../../engine.go) own the exact precedence, timing, result, and error
 contracts.

docs/integrations/openai-compatible-chat.md

@@ -115,9 +115,10 @@ The client conditionally includes:
   strict flag, and schema document. Plain JSON validation does not add an
   object-only response constraint.
 
-The engine resolves backend, profile, and request extra-parameter maps by
-whole-map replacement rather than key merging. The resulting effective map is
-merged into the top-level body. Empty keys, values that cannot be encoded, and
+Configured profile maps recursively overlay backend defaults, while a nonempty
+runtime override replaces the complete configured map. The [format reference](../formats.md#defaults-and-overrides)
+owns these resolution rules. The resulting effective map is merged into the
+top-level body. Empty keys, values that cannot be encoded, and
 collisions with these reserved fields are rejected before any provider call:
 
 - `model`

docs/roadmap/implementation.md

@@ -715,6 +715,11 @@ Go 1.27.3; an injected-observer test verifies permit release before callbacks.
 boundary, and changed documentation links and semantics agree with canonical
 GoDoc/formats. Do not snapshot whole diagnostic strings or unrelated JSON fields.
 
+Completion: marker-based request formatting and JSON checks cover value and
+pointer forms. Profile credential inspection, exact IDs, prompt listing, and
+provider-map precedence prose now match the implemented contracts. Focused
+privacy, profile, inheritance, and provider tests pass on Go 1.27.3.
+
 ## Stage 28: Give Bundled Catalog Expectations One Test Owner
 
 **Catalog:** 28. **Scope:** catalog tests, not bundled asset changes.