Document optional API key environment behavior

docs/consumers/pkg-promptkit.md

@@ -231,7 +231,7 @@ if err != nil {
 
 target := inspection.EffectiveModelParams
 if target.APIKeyEnv != "" {
-	// Apply application policy for the named environment variable.
+	// This is a configured optional environment lookup source.
 } else if inspection.APIKeyRequired {
 	// Arrange a direct credential before later execution.
 }
@@ -240,9 +240,11 @@ if target.APIKeyEnv != "" {
 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. Inspection reports credential requirements but leaves the
-timing of credential enforcement to the application. The method's
-[GoDoc](../../engine.go) owns its exact result and error contract.
+later execution. A reported `APIKeyEnv` is a configured optional source, while
+`APIKeyRequired` is the explicit local requirement. The
+[credential format reference](../formats.md#credentials) and the method's
+[GoDoc](../../engine.go) own the exact precedence, timing, result, and error
+contracts.
 
 ### Set A Per-Run Session And Reasoning
 

docs/formats.md

@@ -185,7 +185,7 @@ extra_params:
 | `timeout_seconds` | no | Per-generation deadline in whole seconds; integer zero or greater. |
 | `service_tier` | no | Provider-specific request tier. |
 | `reasoning_effort` | no | Provider-specific reasoning setting. |
-| `api_key_env` | no | Name of an environment variable containing the API key. |
+| `api_key_env` | no | Optional environment-variable lookup source for an API key. |
 | `extra_params` | no | JSON-compatible provider-specific outbound fields. |
 
 Raw `api_key` is prohibited in profile YAML. Store only an environment
@@ -318,16 +318,25 @@ schema produces a failed validation result.
 Credential values belong at the request or environment boundary, never in
 prompt, profile, schema, or example files:
 
-- a file profile names an environment variable with `api_key_env`;
-- an in-memory profile may set `APIKeyRequired`;
-- a request can provide a direct `APIKey` or override `APIKeyEnv`; and
+- a backend or file profile can name an optional environment lookup source
+  with `APIKeyEnv` or `api_key_env`;
+- an in-memory profile may set `APIKeyRequired` as an explicit local
+  requirement;
+- a request can provide a direct `APIKey` or override the optional `APIKeyEnv`
+  source; and
 - a direct request key takes precedence over environment lookup.
 
 After a direct request key, the credential-source precedence is request
 `APIKeyEnv`, profile `api_key_env`, then the backend default. An in-memory
 profile with `APIKeyRequired` clears an inherited backend environment name and
 requires a direct key unless the request explicitly supplies `APIKeyEnv`.
-Promptkit validates required credential availability during preparation.
+Named environment sources are optional: when the selected source is absent,
+empty, or whitespace-only, the built-in client omits the `Authorization`
+header and handles the provider response normally. `APIKeyRequired` is the
+only explicit local availability requirement. Promptkit validates required
+credential availability during preparation and rechecks it when a prepared
+execution runs. Injected clients receive resolved source metadata but define
+their own credential-resolution behavior.
 Direct keys are excluded from JSON results and redacted by public string
 formatters. Environment-variable names may appear in prepared metadata, but
 their values do not.

docs/integrations/openai-compatible-chat.md

@@ -31,11 +31,13 @@ does not serialize it in the provider request.
 
 ## Authentication
 
-A non-empty API key supplied directly on the execution target takes
-precedence. Otherwise, when an API-key environment-variable name is supplied,
-the client reads that variable and requires a non-empty value. The selected
-key is sent as `Authorization: Bearer <key>`. No authorization header is sent
-when neither mechanism is configured.
+A usable API key supplied directly on the execution target takes precedence.
+Otherwise, when an API-key environment-variable name is supplied, the client
+reads and trims that variable. A bearer header is sent only when the resolved
+direct or environment credential is non-empty. When neither source is usable,
+the client omits `Authorization` and handles the provider response normally.
+An explicitly required target with no usable source is rejected before
+transport.
 
 The target contains the already resolved environment-variable name: an
 explicit request override takes precedence over profile metadata, which takes

docs/internal/llm.md

@@ -55,12 +55,14 @@ the target, rendered messages, and structured-output constraint retained by
 executable preparation. Execution does not reopen or rerender consumer
 sources.
 
-Before backend admission, the runner rechecks that the frozen credential
-environment-variable name is available. The handle does not retain the
-environment value; the model client resolves the value visible when generation
-begins. A direct request key remains in private execution state only until the
-claimed execution finishes or an unclaimed handle is discarded. Exact public
-ownership and redaction semantics belong to the
+Before backend admission, the runner rechecks a frozen credential
+environment-variable name only when the target explicitly requires a
+credential. The handle does not retain the environment value; the model client
+resolves the value visible when generation begins. For optional sources with no
+usable value, the built-in client omits `Authorization` and continues to the
+provider. A direct request key remains in private execution state only until
+the claimed execution finishes or an unclaimed handle is discarded. Exact
+public ownership and redaction semantics belong to the
 [`PreparedExecution` GoDoc](../../prepared_execution.go).
 
 ## Failure Categories
@@ -74,6 +76,12 @@ Invalid nonempty configured endpoints are configuration failures. A missing or
 invalid final selected endpoint is an invalid generation request and is
 rejected before transport.
 
+Authentication resolves a trimmed direct key before a trimmed configured
+environment value. Optional missing, empty, or whitespace-only sources do not
+block transport and produce no `Authorization` header. An explicitly required
+target with no usable source is rejected before transport with the existing
+invalid-request diagnostics.
+
 Successful response bodies have a fixed 16 MiB limit enforced by declared
 length and by reading at most one byte beyond the boundary. The decoder accepts
 exactly one JSON object plus trailing whitespace and EOF. Size overflow,

docs/roadmap/implementation.md

@@ -323,6 +323,8 @@ validation, repository-hygiene checks, ignored-file check, credential scan, and
 Stage 3 is complete when the public workflow, documentation, and full
 maintainer validation all match the target outcome.
 
+**Status:** Complete.
+
 ## Open Questions
 
 None. Optional environment lookup, explicit requirement behavior, precedence,