Document prompt cache control behavior

docs/config.md

@@ -119,6 +119,7 @@ Field reference:
 
 - `role` (required)
 - `content` or `content_file` (exactly one is required)
+- `cache_control` (optional object): provider prompt-cache metadata for this message
 
 Message rules:
 
@@ -128,6 +129,27 @@ Message rules:
 - Prompt decoding is strict; unknown YAML fields are rejected.
 - Duplicate prompt IDs are invalid. If multiple files declare the requested prompt ID, Scriptorium fails instead of choosing one.
 
+`messages[].cache_control` fields:
+
+- `type` (required when `cache_control` is present): currently only `ephemeral`.
+- `ttl` (optional): currently only `1h`; omitted from outbound requests when unset.
+
+Example cache-controlled message:
+
+```yaml
+messages:
+  - role: system
+    content_file: ./stable_context.md
+    cache_control:
+      type: ephemeral
+      ttl: 1h
+  - role: user
+    content: |
+      {{input "transcript"}}
+```
+
+Use cache control on stable reusable prompt content. Dynamic per-run inputs before the cache-controlled message change the provider cache key.
+
 `output` fields:
 
 - `format` (required): `text`, `markdown`, or `json`.
@@ -184,6 +206,8 @@ Profile rules:
 Current outbound request behavior:
 
 - The OpenAI-compatible client currently serializes: `model`, `messages`, `temperature`, `max_tokens`, `top_p`, `service_tier`, and optional `response_format` for `json_schema` prompts.
+- Messages without `cache_control` serialize with string `content`.
+- Messages with `cache_control` serialize as a single text content-block array containing `cache_control`.
 - `reasoning_effort` and `extra_params` are parsed and carried in effective settings, but are not currently serialized into outbound chat-completions requests.
 
 ## Schema Behavior