Document runtime provider parameters

docs/integrations/openai-compatible-chat.md

@@ -32,10 +32,48 @@ Serialized JSON fields:
 - `max_tokens` (only when non-zero)
 - `top_p` (only when non-zero)
 - `service_tier` (only when non-empty)
+- `reasoning_effort` (only when non-empty)
 - `response_format` (only when structured output is provided)
+- profile/request `extra_params` as additional provider-specific top-level fields
 
 `service_tier` is provider-specific. OpenRouter currently documents request values such as `flex` and `priority`; Scriptorium forwards any non-empty configured value and lets the backend validate support.
 
+`reasoning_effort` is provider-specific. Scriptorium forwards any non-empty configured value as top-level `reasoning_effort` and lets the backend validate support.
+
+`extra_params` are flattened into the outbound JSON object. They are not wrapped in an `extra_params` object:
+
+```json
+{
+  "model": "gpt-4o-mini",
+  "messages": [
+    {
+      "role": "user",
+      "content": "rendered text"
+    }
+  ],
+  "provider_route": "primary",
+  "provider_options": {
+    "retry_budget": 2
+  }
+}
+```
+
+`extra_params` values must be JSON-compatible. Supported value shapes include strings, numbers, booleans, objects, and arrays.
+
+Reserved `extra_params` keys are rejected before the HTTP request is made:
+
+- `model`
+- `session_id`
+- `messages`
+- `temperature`
+- `max_tokens`
+- `top_p`
+- `service_tier`
+- `reasoning_effort`
+- `response_format`
+
+Empty `extra_params` keys and values that cannot be encoded as JSON are also rejected before the HTTP request is made.
+
 `session_id` is rendered from prompt YAML using request variables and serialized as a top-level JSON request field. Scriptorium does not send an `x-session-id` header. Empty rendered session IDs are omitted, and values longer than 256 characters are rejected before the HTTP request.
 
 Messages without prompt cache control serialize with string `content`:
@@ -138,12 +176,7 @@ Malformed responses return `ErrMalformedResponse`.
 
 ## Unsupported Or Non-Serialized Fields
 
-The following fields may exist in profile/effective settings but are not currently serialized into outbound chat-completions payloads:
-
-- `reasoning_effort`
-- `extra_params`
-
-The client also does not serialize top-level `cache_control`.
+The client does not serialize top-level `cache_control`.
 
 No built-in retries, tool-calls, or multi-request payload modes are implemented in this client.