Add request API key support

docs/consumers/pkg-scriptorium.md

@@ -54,6 +54,7 @@ Input helpers:
 ```go
 result, err := engine.Run(ctx, scriptorium.RunRequest{
 	PromptID: "generic.markdown_summary",
+	APIKey:   apiKey,
 	Inputs: map[string]scriptorium.ArtifactRef{
 		"transcript": scriptorium.File("./examples/fixtures/transcript.md"),
 		"glossary":   scriptorium.File("./examples/fixtures/glossary.yml"),
@@ -67,6 +68,8 @@ _ = result.Artifact
 
 `RunResult` includes the run ID, output artifact, raw output, validation result, prompt/profile/model metadata, effective model parameters, input hashes, token/cache usage, and timing fields. Validation content failures return a successful `RunResult` with failed validation status. Runtime validation errors return `ErrValidation`.
 
+For the public Go API, pass provider credentials with `RunRequest.APIKey`. The value is request-scoped, uses `json:"-"`, is preferred over profile `api_key_env` by the default OpenAI-compatible client, and is not included in `PreparedRun` or `RunResult` JSON. Do not store raw keys in config, prompt files, or profile YAML.
+
 ## Inject An LLM Client
 
 Use `WithLLMClient` for tests or custom model integrations:
@@ -84,7 +87,7 @@ func (fakeLLM) Generate(ctx context.Context, req scriptorium.GenerateRequest) (*
 engine, err := scriptorium.NewEngine(cfg, scriptorium.WithLLMClient(fakeLLM{}))
 ```
 
-The injected client receives the rendered prompt, effective execution target, target presence metadata for explicit numeric overrides, and structured-output spec. `WithLLMClient(nil)` returns `ErrInvalidConfig`.
+The injected client receives the rendered prompt, effective execution target, target presence metadata for explicit numeric overrides, structured-output spec, and request API key when provided. `GenerateRequest.APIKey` also uses `json:"-"`; custom and fake clients should avoid logging or serializing it. `WithLLMClient(nil)` returns `ErrInvalidConfig`.
 
 ## Request Overrides
 

docs/internal/adapters.md

@@ -37,6 +37,7 @@ Public library facade:
 - Input: typed `scriptorium.RunRequest` values.
 - Output: typed `PreparedRun` and `RunResult` values plus public sentinel errors.
 - Custom LLM behavior is injected with `WithLLMClient`; otherwise the default OpenAI-compatible client is used.
+- `RunRequest.APIKey` is a request-scoped Go value only; it is converted into internal execution state for LLM generation and stripped from public result types.
 - Public types are facade types converted at the package boundary; internal domain types remain internal.
 
 Filesystem repositories:
@@ -60,6 +61,7 @@ LLM adapter:
 
 - Input: `domain.GenerateRequest`.
 - Output: `domain.GenerateResponse`.
+- Direct API-key values are preferred when present; otherwise `api_key_env` is resolved from the process environment.
 
 Validator:
 
@@ -123,6 +125,7 @@ LLM adapter:
 - compatible cache usage response fields are parsed into domain token usage.
 - non-2xx responses map to request failure errors.
 - malformed responses (including missing/empty first choice content) are errors.
+- direct API-key values are never serialized in provider request bodies.
 
 Validator:
 

docs/internal/runner.md

@@ -104,9 +104,10 @@ Validation content failures are not run errors:
    - selected profile values
    - request overrides
    - request numeric overrides are presence-aware, so omitted values preserve the current effective value and explicit zero values override it
-6. verify required `api_key_env` environment variable:
-   - missing/empty env value returns an invalid request with `ErrAPIKeyEnvMissing`
-   - only the environment-variable name is retained; secret value is never returned
+6. verify credentials when the effective target names `api_key_env`:
+   - a request-scoped direct API key satisfies the credential requirement
+   - otherwise a missing/empty env value returns an invalid request with `ErrAPIKeyEnvMissing`
+   - only the environment-variable name is returned in public output; secret values are never returned
 7. resolve output contract and structured-output schema payload when `json_schema` mode is active.
 8. read input artifacts.
 9. render prompt messages, including any normalized message cache-control metadata.
@@ -122,7 +123,8 @@ Runtime target notes:
 - The OpenAI-compatible client serializes non-empty `reasoning_effort` as a top-level provider request field.
 - The OpenAI-compatible client flattens `extra_params` into provider-specific top-level JSON request fields.
 - Empty `extra_params` keys, reserved outbound field names, and values that cannot be JSON-encoded fail before the provider request.
-- Resolved API-key values are never stored in `PreparedRun`, `RunResult`, logs, or HTTP responses.
+- Resolved API-key values are never serialized in prepared/run output, public results, logs, or HTTP responses.
+- Public direct API-key values are carried only far enough to call the configured LLM client and are excluded from JSON/YAML serialization.
 
 ## Run Flow