Add a roadmap, implementation plan, and built-in profile defaults for a production-ready public library package

.gitignore

@@ -1,6 +1,5 @@
 # ---> Codex
 .codex
-AGENTS.md
 
 # ---> Go
 # If you prefer the allow list template instead of the deny list, see community template:

.woodpecker/release.yml

@@ -28,10 +28,6 @@ steps:
 
         build_binary linux amd64 ""
         build_binary linux arm64 ""
-        build_binary darwin amd64 ""
-        build_binary darwin arm64 ""
-        build_binary windows amd64 ".exe"
-        build_binary windows arm64 ".exe"
 
   - name: publish-release
     image: woodpeckerci/plugin-release

AGENTS.md

@@ -0,0 +1,4 @@
+Please carefully review the relevant documents in `docs/policy` before making any changes to this repository.
+ - `development.md` defines the contributor workflow for this application.
+ - `architecture.md` provides the canonical high-level architecture policy for this repository, and should be reviewed before writing or changing any code.
+ - `documentation.md` provides the canonical documentation policy for this repository, and should be reviewed before writing or changing any documentation.

README.md

@@ -25,6 +25,7 @@ This command renders the prepared prompt and effective runtime settings without
 - [Configuration reference](docs/config.md)
 - [Operations guide](docs/operations.md)
 - [Troubleshooting](docs/troubleshooting.md)
+- [Go library package](docs/consumers/pkg-scriptorium.md)
 - [HTTP API integration](docs/integrations/http-api.md)
 - [OpenAI-compatible chat integration](docs/integrations/openai-compatible-chat.md)
 - [Narratio subprocess integration](docs/integrations/narratio.md)
@@ -34,3 +35,4 @@ This command renders the prepared prompt and effective runtime settings without
 
 - `examples/render-markdown-summary.sh`
 - `examples/http-run.json`
+- `examples/go-library/prepare`

convert.go

@@ -0,0 +1,396 @@
+package scriptorium
+
+import (
+	"reflect"
+
+	"gitea.maximumdirect.net/eric/scriptorium/internal/domain"
+)
+
+func toDomainRunRequest(req RunRequest) domain.RunRequest {
+	return domain.RunRequest{
+		PromptID:      req.PromptID,
+		PromptVersion: req.PromptVersion,
+		ProfileID:     req.ProfileID,
+		Inputs:        toDomainArtifactRefMap(req.Inputs),
+		Vars:          copyStringMap(req.Vars),
+		Execution:     toDomainExecutionTargetOverride(req.Execution),
+		Validation:    toDomainOutputContractPtr(req.Validation),
+		Metadata:      copyStringMap(req.Metadata),
+	}
+}
+
+func fromDomainPreparedRun(prepared *domain.PreparedRun) *PreparedRun {
+	if prepared == nil {
+		return nil
+	}
+	return &PreparedRun{
+		PromptID:             prepared.PromptID,
+		PromptVersion:        prepared.PromptVersion,
+		PromptHash:           prepared.PromptHash,
+		SelectedProfileID:    prepared.SelectedProfileID,
+		EffectiveModelParams: fromDomainExecutionTarget(prepared.EffectiveModelParams),
+		OutputContract:       fromDomainOutputContract(prepared.OutputContract),
+		StructuredOutput:     fromDomainStructuredOutputSpec(prepared.StructuredOutput),
+		InputHashes:          copyStringMap(prepared.InputHashes),
+		SessionID:            prepared.SessionID,
+		RenderedPromptHash:   prepared.RenderedPromptHash,
+		Messages:             fromDomainRenderedMessages(prepared.Messages),
+		StartTime:            prepared.StartTime,
+		EndTime:              prepared.EndTime,
+		DurationMS:           prepared.DurationMS,
+	}
+}
+
+func fromDomainRunResult(result *domain.RunResult) *RunResult {
+	if result == nil {
+		return nil
+	}
+	return &RunResult{
+		RunID:                result.RunID,
+		Artifact:             fromDomainArtifact(result.Artifact),
+		RawOutput:            result.RawOutput,
+		Validation:           fromDomainValidationResult(result.Validation),
+		PromptID:             result.PromptID,
+		PromptVersion:        result.PromptVersion,
+		PromptHash:           result.PromptHash,
+		RenderedPromptHash:   result.RenderedPromptHash,
+		SelectedProfileID:    result.SelectedProfileID,
+		ModelName:            result.ModelName,
+		Endpoint:             result.Endpoint,
+		EffectiveModelParams: fromDomainExecutionTarget(result.EffectiveModelParams),
+		InputHashes:          copyStringMap(result.InputHashes),
+		Usage:                fromDomainTokenUsage(result.Usage),
+		StartTime:            result.StartTime,
+		EndTime:              result.EndTime,
+		Duration:             result.Duration,
+	}
+}
+
+func fromDomainGenerateRequest(req domain.GenerateRequest) GenerateRequest {
+	return GenerateRequest{
+		Prompt:           fromDomainRenderedPrompt(req.Prompt),
+		Target:           fromDomainExecutionTarget(req.Target),
+		TargetPresence:   fromDomainExecutionTargetPresence(req.TargetPresence),
+		StructuredOutput: fromDomainStructuredOutputSpec(req.StructuredOutput),
+	}
+}
+
+func toDomainGenerateResponse(resp *GenerateResponse) *domain.GenerateResponse {
+	if resp == nil {
+		return nil
+	}
+	return &domain.GenerateResponse{
+		Content: resp.Content,
+		Usage:   toDomainTokenUsage(resp.Usage),
+	}
+}
+
+func fromDomainRenderedPrompt(prompt domain.RenderedPrompt) RenderedPrompt {
+	return RenderedPrompt{
+		SessionID: prompt.SessionID,
+		Messages:  fromDomainRenderedMessages(prompt.Messages),
+	}
+}
+
+func toDomainArtifactRefMap(src map[string]ArtifactRef) map[string]domain.ArtifactRef {
+	if src == nil {
+		return nil
+	}
+	out := make(map[string]domain.ArtifactRef, len(src))
+	for k, v := range src {
+		out[k] = toDomainArtifactRef(v)
+	}
+	return out
+}
+
+func toDomainArtifactRef(ref ArtifactRef) domain.ArtifactRef {
+	return domain.ArtifactRef{
+		Type: domain.ArtifactRefType(ref.Type),
+		URI:  ref.URI,
+		Body: ref.Body,
+	}
+}
+
+func fromDomainArtifact(artifact domain.Artifact) Artifact {
+	return Artifact{
+		Name:        artifact.Name,
+		ContentType: artifact.ContentType,
+		Body:        copyBytes(artifact.Body),
+		URI:         artifact.URI,
+		Size:        artifact.Size,
+		Hash:        artifact.Hash,
+	}
+}
+
+func toDomainExecutionTargetOverride(override *ExecutionTargetOverride) *domain.ExecutionTargetOverride {
+	if override == nil {
+		return nil
+	}
+	return &domain.ExecutionTargetOverride{
+		Endpoint:        override.Endpoint,
+		Model:           override.Model,
+		Temperature:     copyFloat64Ptr(override.Temperature),
+		MaxTokens:       copyIntPtr(override.MaxTokens),
+		TopP:            copyFloat64Ptr(override.TopP),
+		TimeoutSeconds:  copyIntPtr(override.TimeoutSeconds),
+		ServiceTier:     override.ServiceTier,
+		ReasoningEffort: override.ReasoningEffort,
+		APIKeyEnv:       override.APIKeyEnv,
+		ExtraParams:     copyAnyMap(override.ExtraParams),
+	}
+}
+
+func fromDomainExecutionTarget(target domain.ExecutionTarget) ExecutionTarget {
+	return ExecutionTarget{
+		Endpoint:        target.Endpoint,
+		Model:           target.Model,
+		Temperature:     target.Temperature,
+		MaxTokens:       target.MaxTokens,
+		TopP:            target.TopP,
+		TimeoutSeconds:  target.TimeoutSeconds,
+		ServiceTier:     target.ServiceTier,
+		ReasoningEffort: target.ReasoningEffort,
+		APIKeyEnv:       target.APIKeyEnv,
+		ExtraParams:     copyAnyMap(target.ExtraParams),
+	}
+}
+
+func fromDomainExecutionTargetPresence(presence domain.ExecutionTargetPresence) ExecutionTargetPresence {
+	return ExecutionTargetPresence{
+		Temperature:    presence.Temperature,
+		MaxTokens:      presence.MaxTokens,
+		TopP:           presence.TopP,
+		TimeoutSeconds: presence.TimeoutSeconds,
+	}
+}
+
+func toDomainOutputContractPtr(contract *OutputContract) *domain.OutputContract {
+	if contract == nil {
+		return nil
+	}
+	out := toDomainOutputContract(*contract)
+	return &out
+}
+
+func toDomainOutputContract(contract OutputContract) domain.OutputContract {
+	return domain.OutputContract{
+		Format:         domain.OutputFormat(contract.Format),
+		ValidationMode: domain.ValidationMode(contract.ValidationMode),
+		SchemaPath:     contract.SchemaPath,
+		RepairAttempts: contract.RepairAttempts,
+	}
+}
+
+func fromDomainOutputContract(contract domain.OutputContract) OutputContract {
+	return OutputContract{
+		Format:         OutputFormat(contract.Format),
+		ValidationMode: ValidationMode(contract.ValidationMode),
+		SchemaPath:     contract.SchemaPath,
+		RepairAttempts: contract.RepairAttempts,
+	}
+}
+
+func fromDomainValidationResult(result domain.ValidationResult) ValidationResult {
+	return ValidationResult{
+		Status:         ValidationStatus(result.Status),
+		Mode:           ValidationMode(result.Mode),
+		Errors:         copyStringSlice(result.Errors),
+		SchemaPath:     result.SchemaPath,
+		RepairAttempts: result.RepairAttempts,
+		IsValid:        result.IsValid,
+	}
+}
+
+func fromDomainTokenUsage(usage domain.TokenUsage) TokenUsage {
+	return TokenUsage{
+		PromptTokens:     usage.PromptTokens,
+		CompletionTokens: usage.CompletionTokens,
+		TotalTokens:      usage.TotalTokens,
+		CachedTokens:     usage.CachedTokens,
+		CacheWriteTokens: usage.CacheWriteTokens,
+	}
+}
+
+func toDomainTokenUsage(usage TokenUsage) domain.TokenUsage {
+	return domain.TokenUsage{
+		PromptTokens:     usage.PromptTokens,
+		CompletionTokens: usage.CompletionTokens,
+		TotalTokens:      usage.TotalTokens,
+		CachedTokens:     usage.CachedTokens,
+		CacheWriteTokens: usage.CacheWriteTokens,
+	}
+}
+
+func fromDomainRenderedMessages(messages []domain.RenderedMessage) []RenderedMessage {
+	if messages == nil {
+		return nil
+	}
+	out := make([]RenderedMessage, len(messages))
+	for i, msg := range messages {
+		out[i] = RenderedMessage{
+			Role:         msg.Role,
+			Content:      msg.Content,
+			CacheControl: fromDomainCacheControl(msg.CacheControl),
+		}
+	}
+	return out
+}
+
+func fromDomainCacheControl(cacheControl *domain.CacheControl) *CacheControl {
+	if cacheControl == nil {
+		return nil
+	}
+	return &CacheControl{
+		Type: CacheControlType(cacheControl.Type),
+		TTL:  cacheControl.TTL,
+	}
+}
+
+func fromDomainStructuredOutputSpec(spec *domain.StructuredOutputSpec) *StructuredOutputSpec {
+	if spec == nil {
+		return nil
+	}
+	out := &StructuredOutputSpec{
+		Type: StructuredOutputType(spec.Type),
+	}
+	if spec.JSONSchema != nil {
+		out.JSONSchema = &StructuredOutputJSONSpec{
+			Name:   spec.JSONSchema.Name,
+			Strict: spec.JSONSchema.Strict,
+			Schema: copyAny(spec.JSONSchema.Schema),
+		}
+	}
+	return out
+}
+
+func copyStringMap(src map[string]string) map[string]string {
+	if src == nil {
+		return nil
+	}
+	out := make(map[string]string, len(src))
+	for k, v := range src {
+		out[k] = v
+	}
+	return out
+}
+
+func copyAnyMap(src map[string]any) map[string]any {
+	if src == nil {
+		return nil
+	}
+	out := make(map[string]any, len(src))
+	for k, v := range src {
+		out[k] = copyAny(v)
+	}
+	return out
+}
+
+func copyAny(value any) any {
+	if value == nil {
+		return nil
+	}
+	switch v := value.(type) {
+	case map[string]any:
+		return copyAnyMap(v)
+	case []any:
+		out := make([]any, len(v))
+		for i, item := range v {
+			out[i] = copyAny(item)
+		}
+		return out
+	case []string:
+		return copyStringSlice(v)
+	case []byte:
+		return copyBytes(v)
+	default:
+		return copyReflectValue(reflect.ValueOf(value)).Interface()
+	}
+}
+
+func copyReflectValue(value reflect.Value) reflect.Value {
+	if !value.IsValid() {
+		return value
+	}
+
+	switch value.Kind() {
+	case reflect.Interface:
+		if value.IsNil() {
+			return reflect.Zero(value.Type())
+		}
+		copied := copyReflectValue(value.Elem())
+		if copied.IsValid() && copied.Type().AssignableTo(value.Type()) {
+			return copied
+		}
+		out := reflect.New(value.Type()).Elem()
+		out.Set(copied)
+		return out
+	case reflect.Pointer:
+		if value.IsNil() {
+			return reflect.Zero(value.Type())
+		}
+		out := reflect.New(value.Type().Elem())
+		out.Elem().Set(copyReflectValue(value.Elem()))
+		return out
+	case reflect.Map:
+		if value.IsNil() {
+			return reflect.Zero(value.Type())
+		}
+		out := reflect.MakeMapWithSize(value.Type(), value.Len())
+		iter := value.MapRange()
+		for iter.Next() {
+			out.SetMapIndex(copyReflectValue(iter.Key()), copyReflectValue(iter.Value()))
+		}
+		return out
+	case reflect.Slice:
+		if value.IsNil() {
+			return reflect.Zero(value.Type())
+		}
+		out := reflect.MakeSlice(value.Type(), value.Len(), value.Cap())
+		for i := 0; i < value.Len(); i++ {
+			out.Index(i).Set(copyReflectValue(value.Index(i)))
+		}
+		return out
+	case reflect.Array:
+		out := reflect.New(value.Type()).Elem()
+		for i := 0; i < value.Len(); i++ {
+			out.Index(i).Set(copyReflectValue(value.Index(i)))
+		}
+		return out
+	default:
+		return value
+	}
+}
+
+func copyStringSlice(src []string) []string {
+	if src == nil {
+		return nil
+	}
+	out := make([]string, len(src))
+	copy(out, src)
+	return out
+}
+
+func copyBytes(src []byte) []byte {
+	if src == nil {
+		return nil
+	}
+	out := make([]byte, len(src))
+	copy(out, src)
+	return out
+}
+
+func copyFloat64Ptr(src *float64) *float64 {
+	if src == nil {
+		return nil
+	}
+	v := *src
+	return &v
+}
+
+func copyIntPtr(src *int) *int {
+	if src == nil {
+		return nil
+	}
+	v := *src
+	return &v
+}

docs/cli.md

@@ -32,6 +32,8 @@ Integration references:
   - an effective `prompt_dir` and `profile_dir` (from flags or config)
 - `serve` requires an effective `prompt_dir` and `profile_dir` (from flags or config).
 - Positional arguments are rejected.
+- Prompt cache control is configured in prompt YAML (`messages[].cache_control`), not with CLI flags.
+- Provider-specific `reasoning_effort` and `extra_params` are configured in profile YAML or HTTP model overrides, not with CLI flags.
 
 ## Flag Reference
 
@@ -56,6 +58,11 @@ Integration references:
 - `--top-p <float>`: runtime top-p override.
 - `--timeout <duration>`: runtime timeout override (Go duration syntax, for example `30s`, `2m`).
 
+Numeric runtime override flags are presence-aware:
+
+- omitted numeric flags preserve the selected profile/default value
+- explicit zero values override the selected profile/default value (`--temperature 0`, `--max-tokens 0`, `--top-p 0`, `--timeout 0s`)
+
 ### `scriptorium render`
 
 - Supports the same flags as `run`, except:
@@ -82,6 +89,7 @@ Notes:
 
 - `--input name=path` maps prompt input names to local file paths.
 - `--var name=value` maps template variable names to values.
+- If a prompt defines `session_id: "{{ .session_id }}"`, pass the OpenRouter sticky-routing value with `--var session_id=<value>`.
 - Both flags can be repeated.
 - Both flags also support comma-separated batches, for example:
   - `--input transcript=./t.md,glossary=./g.yml`
@@ -93,6 +101,7 @@ Notes:
 - Writes generated artifact content to stdout by default.
 - Writes generated artifact content to `--out` when provided.
 - Prints run summary metadata to stderr on success.
+- Appends `cached_tokens=<n> cache_write_tokens=<n>` to the summary only when the provider reports non-zero cache usage.
 - Prints errors to stderr on failure.
 
 `render`:

docs/config.md

@@ -104,6 +104,7 @@ Field reference:
 - `version` (required): prompt version.
 - `default_profile` (optional): profile ID used when request does not provide `profile_id`.
 - `description` (optional): prompt description.
+- `session_id` (optional): Go-template string for OpenRouter sticky-routing `session_id`; rendered from request vars.
 - `inputs` (optional list): expected named inputs.
 - `messages` (required list): prompt message templates.
 - `output` (required object): output contract.
@@ -119,6 +120,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 +130,35 @@ 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.
+
+Example prompt-level session ID:
+
+```yaml
+session_id: "{{ .session_id }}"
+```
+
+When configured, `session_id` is rendered with the same variable context as messages. The rendered value is trimmed, omitted when empty, and rejected if longer than 256 characters. CLI callers pass the value through `--var session_id=<value>`; HTTP callers pass it through `"vars": {"session_id": "<value>"}`.
+
 `output` fields:
 
 - `format` (required): `text`, `markdown`, or `json`.
@@ -158,6 +189,11 @@ top_p: 1.0
 timeout_seconds: 90
 api_key_env: SCRIPTORIUM_API_KEY
 service_tier: priority
+reasoning_effort: medium
+extra_params:
+  provider_route: primary
+  provider_options:
+    retry_budget: 2
 ```
 
 Field reference:
@@ -170,9 +206,9 @@ Field reference:
 - `top_p` (optional): range `0..1`
 - `timeout_seconds` (optional): `>= 0`
 - `service_tier` (optional): provider-specific request tier such as OpenRouter `flex` or `priority`
-- `reasoning_effort` (optional)
+- `reasoning_effort` (optional): serialized as top-level `reasoning_effort` in outbound chat-completions requests
 - `api_key_env` (optional)
-- `extra_params` (optional map of strings)
+- `extra_params` (optional map): JSON-compatible provider-specific parameters. Values may be strings, numbers, booleans, objects, or arrays.
 
 Profile rules:
 
@@ -180,11 +216,14 @@ Profile rules:
 - Raw `api_key` is rejected; use `api_key_env`.
 - If `api_key_env` is set, that environment variable must be set when preparing/running.
 - Duplicate profile IDs are invalid. If multiple files declare the requested profile ID, Scriptorium fails instead of choosing one.
+- `extra_params` keys must not be empty and must not collide with reserved outbound request fields: `model`, `session_id`, `messages`, `temperature`, `max_tokens`, `top_p`, `service_tier`, `reasoning_effort`, or `response_format`.
 
 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.
-- `reasoning_effort` and `extra_params` are parsed and carried in effective settings, but are not currently serialized into outbound chat-completions requests.
+- The OpenAI-compatible client currently serializes: `model`, optional `session_id`, `messages`, `temperature`, `max_tokens`, `top_p`, `service_tier`, `reasoning_effort`, optional `response_format` for `json_schema` prompts, and `extra_params`.
+- `extra_params` are flattened into provider-specific top-level JSON request fields. They are not wrapped in an `extra_params` object on the outbound provider request.
+- Messages without `cache_control` serialize with string `content`.
+- Messages with `cache_control` serialize as a single text content-block array containing `cache_control`.
 
 ## Schema Behavior
 

docs/consumers/api.md

@@ -0,0 +1,13 @@
+# Consumer API Overview
+
+Scriptorium can be used by consumers through three implemented surfaces:
+
+- CLI commands, documented in [CLI reference](../cli.md).
+- HTTP `POST /v1/runs`, documented in [HTTP API integration](../integrations/http-api.md).
+- Go package `gitea.maximumdirect.net/eric/scriptorium`, documented in [pkg-scriptorium](pkg-scriptorium.md).
+
+The Go package is the typed in-process API. It prepares prompts, runs prompts, accepts file or inline artifacts, supports per-request execution overrides, and exposes stable public errors for `errors.Is`.
+
+Use the Go package when the caller is a Go program that wants typed requests/results, context cancellation, repeated calls without subprocess overhead, or fake LLM injection for tests. Use the CLI or HTTP surfaces when process isolation, language neutrality, or an HTTP boundary is preferred.
+
+Raw API key values are not accepted in public payloads and are not returned in prepared or run results. Execution profiles may reference an environment variable name through `api_key_env`.

docs/consumers/pkg-scriptorium.md

@@ -0,0 +1,129 @@
+# Package scriptorium
+
+Import path:
+
+```go
+import "gitea.maximumdirect.net/eric/scriptorium"
+```
+
+The root package is a public facade over Scriptorium's prompt execution use case. It keeps `internal/*` packages private while exposing typed construction, preparation, execution, inputs, results, and errors.
+
+## Construct An Engine
+
+```go
+engine, err := scriptorium.NewEngine(scriptorium.Config{
+	PromptDir:  "./examples/prompts",
+	ProfileDir: "./examples/profiles",
+	SchemaDir:  "./examples/schemas",
+})
+if err != nil {
+	return err
+}
+```
+
+`PromptDir` and `ProfileDir` are required. `SchemaDir` defaults to the built-in schema directory. `Timeout` and `HTTPClient` configure the default OpenAI-compatible client used by `Run` when no custom LLM client is supplied.
+
+## Prepare A Prompt
+
+`Prepare` resolves the prompt definition, profile, inputs, variables, output contract, structured-output metadata, and rendered messages without calling an LLM.
+
+```go
+prepared, err := engine.Prepare(ctx, scriptorium.RunRequest{
+	PromptID: "generic.markdown_summary",
+	Inputs: map[string]scriptorium.ArtifactRef{
+		"transcript": scriptorium.File("./examples/fixtures/transcript.md"),
+		"glossary":   scriptorium.File("./examples/fixtures/glossary.yml"),
+	},
+})
+if err != nil {
+	return err
+}
+_ = prepared.Messages
+```
+
+Input helpers:
+
+- `scriptorium.File(path)` loads an input artifact from a file.
+- `scriptorium.Inline(body)` passes inline input content.
+- `scriptorium.InlineWithURI(uri, body)` passes inline content with URI metadata.
+
+## Run A Prompt
+
+`Run` prepares the prompt, calls the configured LLM client, builds the output artifact, and validates the output.
+
+```go
+result, err := engine.Run(ctx, scriptorium.RunRequest{
+	PromptID: "generic.markdown_summary",
+	Inputs: map[string]scriptorium.ArtifactRef{
+		"transcript": scriptorium.File("./examples/fixtures/transcript.md"),
+		"glossary":   scriptorium.File("./examples/fixtures/glossary.yml"),
+	},
+})
+if err != nil {
+	return err
+}
+_ = 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`.
+
+## Inject An LLM Client
+
+Use `WithLLMClient` for tests or custom model integrations:
+
+```go
+type fakeLLM struct{}
+
+func (fakeLLM) Generate(ctx context.Context, req scriptorium.GenerateRequest) (*scriptorium.GenerateResponse, error) {
+	return &scriptorium.GenerateResponse{
+		Content: "generated text",
+		Usage:   scriptorium.TokenUsage{TotalTokens: 12},
+	}, nil
+}
+
+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`.
+
+## Request Overrides
+
+`RunRequest.Execution` accepts per-request overrides. Numeric override fields are pointers so explicit zero values are preserved:
+
+```go
+zero := 0
+req.Execution = &scriptorium.ExecutionTargetOverride{
+	MaxTokens: &zero,
+}
+```
+
+## Errors
+
+Public methods wrap context while preserving stable sentinel checks with `errors.Is`:
+
+- `ErrInvalidConfig`
+- `ErrInvalidRequest`
+- `ErrPromptNotFound`
+- `ErrProfileNotFound`
+- `ErrPromptLoad`
+- `ErrProfileLoad`
+- `ErrArtifactLoad`
+- `ErrPromptRender`
+- `ErrLLMGenerate`
+- `ErrValidation`
+
+Example:
+
+```go
+if errors.Is(err, scriptorium.ErrPromptNotFound) {
+	return err
+}
+```
+
+## Examples
+
+Run the prepare-only example from the repository root:
+
+```bash
+go run ./examples/go-library/prepare
+```

docs/integrations/http-api.md

@@ -50,7 +50,10 @@ Copyable request example file:
     "reasoning_effort": "medium",
     "api_key_env": "SCRIPTORIUM_API_KEY",
     "extra_params": {
-      "route": "primary"
+      "route": "primary",
+      "provider_options": {
+        "retry_budget": 2
+      }
     }
   },
   "include_raw_output": false
@@ -67,6 +70,14 @@ Input reference types currently supported by runtime artifact loading:
 - `file`
 - `inline`
 
+Model override notes:
+
+- Numeric model override fields distinguish omitted values from explicit zero values. For example, omitting `temperature` preserves the selected profile/default value, while `"temperature": 0` explicitly sets the effective temperature to zero.
+- `extra_params` accepts JSON-compatible values: strings, numbers, booleans, objects, and arrays.
+- `extra_params` are passed through effective model metadata and flattened into top-level provider request fields by the OpenAI-compatible client.
+- `extra_params` keys must not be empty and must not collide with reserved outbound fields: `model`, `session_id`, `messages`, `temperature`, `max_tokens`, `top_p`, `service_tier`, `reasoning_effort`, or `response_format`.
+- Raw API-key values are not accepted. Use `api_key_env` to name an environment variable.
+
 ## Strict JSON Rules
 
 Request decoding uses strict JSON field checks:
@@ -119,7 +130,10 @@ Response shape:
       "reasoning_effort": "medium",
       "api_key_env": "SCRIPTORIUM_API_KEY",
       "extra_params": {
-        "route": "primary"
+        "route": "primary",
+        "provider_options": {
+          "retry_budget": 2
+        }
       }
     },
     "input_hashes": {
@@ -128,7 +142,9 @@ Response shape:
     "usage": {
       "prompt_tokens": 11,
       "completion_tokens": 22,
-      "total_tokens": 33
+      "total_tokens": 33,
+      "cached_tokens": 0,
+      "cache_write_tokens": 0
     },
     "start_time": "2026-05-04T12:00:00Z",
     "end_time": "2026-05-04T12:00:01Z",
@@ -142,6 +158,8 @@ Response shape:
 
 `raw_model_output` is omitted by default.
 
+`metadata.usage.cached_tokens` and `metadata.usage.cache_write_tokens` are always present as numbers. They are `0` when the provider omits compatible cache usage fields or reports no cache activity.
+
 To include it, send:
 
 - `"include_raw_output": true`

docs/integrations/openai-compatible-chat.md

@@ -26,15 +26,85 @@ Example:
 Serialized JSON fields:
 
 - `model` (required after fallback resolution)
-- `messages` (role/content pairs from rendered prompt)
-- `temperature` (only when non-zero)
-- `max_tokens` (only when non-zero)
-- `top_p` (only when non-zero)
+- `session_id` (only when the rendered prompt includes a non-empty session ID)
+- `messages` (rendered prompt messages)
+- `temperature` (when non-zero, or when explicitly overridden to zero)
+- `max_tokens` (when non-zero, or when explicitly overridden to zero)
+- `top_p` (when non-zero, or when explicitly overridden to 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`:
+
+```json
+{
+  "role": "system",
+  "content": "rendered text"
+}
+```
+
+Messages with prompt cache control serialize as a single text content-block array:
+
+```json
+{
+  "role": "system",
+  "content": [
+    {
+      "type": "text",
+      "text": "rendered text",
+      "cache_control": {
+        "type": "ephemeral",
+        "ttl": "1h"
+      }
+    }
+  ]
+}
+```
+
+When cache-control `ttl` is unset in the prompt definition, `ttl` is omitted from the outbound payload.
+
 Structured output is currently `json_schema` only, serialized as:
 
 ```json
@@ -72,6 +142,7 @@ Base timeout comes from client configuration.
 Per-request override:
 
 - if `Target.TimeoutSeconds > 0`, use that value for request timeout
+- if `Target.TimeoutSeconds == 0` and the value came from an explicit request override, disable the HTTP client timeout
 - if `Target.TimeoutSeconds < 0`, request is rejected (`ErrInvalidRequest`)
 
 ## Response Expectations
@@ -82,6 +153,13 @@ Expected successful response shape (subset used):
 - `usage.prompt_tokens`
 - `usage.completion_tokens`
 - `usage.total_tokens`
+- `usage.prompt_tokens_details.cached_tokens` (optional)
+- `usage.cache_write_tokens` (optional)
+
+Absent cache usage fields are treated as zero. Parsed cache usage is exposed through run results and adapter response surfaces as:
+
+- `cached_tokens`
+- `cache_write_tokens`
 
 Malformed response conditions include:
 
@@ -99,10 +177,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 does not serialize top-level `cache_control`.
 
 No built-in retries, tool-calls, or multi-request payload modes are implemented in this client.
 

docs/internal/adapters.md

@@ -8,6 +8,7 @@ This document describes implemented adapter/repository boundaries and their curr
 
 - `internal/adapter/cli`: CLI command parsing, app wiring, stdout/stderr handling, exit codes.
 - `internal/adapter/http`: HTTP request/response mapping for `POST /v1/runs`.
+- root package `scriptorium`: public Go library facade for preparing and running prompt requests.
 - `internal/promptdef`: filesystem prompt-definition repository.
 - `internal/profile`: filesystem execution-profile repository.
 - `internal/artifact`: input artifact reader.
@@ -22,11 +23,20 @@ CLI adapter:
 
 - Input: process args, filesystem config/assets, environment.
 - Output: exit code, stdout artifact/prepared output, stderr summaries/errors.
+- `run` summaries include cache usage counters only when either parsed cache counter is non-zero.
 
 HTTP adapter:
 
 - Input: JSON request body (`runRequestDTO`).
 - Output: JSON success/error body with mapped status codes.
+- Success metadata includes token usage plus cache usage counters.
+
+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.
+- Public types are facade types converted at the package boundary; internal domain types remain internal.
 
 Filesystem repositories:
 
@@ -67,6 +77,8 @@ Primary app settings consumed by adapters:
 Execution profile/request settings used through runner:
 
 - `endpoint`, `model`, `temperature`, `max_tokens`, `top_p`, `timeout_seconds`, `service_tier`, `api_key_env`, `reasoning_effort`, `extra_params`
+- CLI and HTTP request adapters preserve caller intent for numeric runtime overrides. Omitted values remain absent; explicit zero values are mapped as explicit overrides.
+- HTTP `extra_params` accepts JSON-compatible values and maps them to domain request overrides without provider-specific adapter logic.
 
 ## External Dependencies
 
@@ -93,6 +105,13 @@ Artifact refs:
 LLM adapter:
 
 - endpoint appends `/chat/completions`.
+- rendered messages without cache control serialize with string `content`.
+- rendered messages with cache control serialize as one text content block with `cache_control`.
+- non-empty `reasoning_effort` serializes as a top-level provider request field.
+- `extra_params` flatten into provider-specific top-level JSON request fields.
+- reserved `extra_params` keys are rejected before the provider call: `model`, `session_id`, `messages`, `temperature`, `max_tokens`, `top_p`, `service_tier`, `reasoning_effort`, and `response_format`.
+- empty `extra_params` keys and values that cannot be JSON-encoded are rejected before the provider call.
+- 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.
 
@@ -141,4 +160,5 @@ Behavior highlights:
 - Adapter packages do not own runner decision logic.
 - External request/response strictness is part of contract stability.
 - Prepared-render output never includes resolved API key values.
-- Outbound OpenAI-compatible request includes only currently serialized fields (`model`, `messages`, optional `temperature`, `max_tokens`, `top_p`, optional `service_tier`, optional `response_format`).
+- Outbound OpenAI-compatible request includes currently serialized first-class fields (`model`, optional `session_id`, `messages`, optional `temperature`, `max_tokens`, `top_p`, optional `service_tier`, optional `reasoning_effort`, optional `response_format`) plus validated `extra_params` flattened as provider-specific top-level fields.
+- Outbound cache control is message-level only; no top-level cache-control field is serialized.

docs/internal/runner.md

@@ -103,16 +103,27 @@ Validation content failures are not run errors:
    - built-in execution defaults
    - 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
 7. resolve output contract and structured-output schema payload when `json_schema` mode is active.
 8. read input artifacts.
-9. render prompt messages.
+9. render prompt messages, including any normalized message cache-control metadata.
 10. compute prompt/input/render hashes and return `PreparedRun`.
 
+`rendered_prompt_hash` includes cache-control metadata when present because it affects the outbound provider request. Prompts without cache control keep the role/content hash behavior.
+
 `Prepare` does not call the LLM.
 
+Runtime target notes:
+
+- Profile `extra_params` and request `extra_params` carry JSON-compatible values through prepared output, run metadata, and `domain.GenerateRequest.Target`.
+- 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.
+
 ## Run Flow
 
 `Run` performs:
@@ -123,7 +134,7 @@ Validation content failures are not run errors:
 4. build output artifact content type from output format.
 5. validate output.
 6. optionally attempt bounded repair when repairer is injected and contract allows it.
-7. return `RunResult` with artifact, raw output, validation, hashes, profile/model metadata, usage, and timestamps.
+7. return `RunResult` with artifact, raw output, validation, hashes, profile/model metadata, token/cache usage, and timestamps.
 
 ## Repair Hook Boundary
 

docs/policy/documentation.md

@@ -2,12 +2,13 @@
 
 ## Purpose
 
-Project documentation must help four audiences:
+Project documentation must help five audiences:
 
 1. users who need to run the application;
 2. administrators/operators who need to configure and operate it;
 3. developers who need to understand and change it safely;
-4. LLM coding agents that need clear scope, boundaries, and invariants.
+4. LLM coding agents that need clear scope, boundaries, and invariants;
+5. developers and LLM coding agents integrating this project from another codebase.
 
 Docs should be accurate, concise, task-oriented, and organized by audience. Prefer links to canonical docs over repetition.
 
@@ -42,11 +43,14 @@ Canonical homes:
 
 - project purpose and quickstart: `README.md`
 - development principles: `docs/policy/architecture.md`
+- public HTTP API reference: `docs/api.md`
 - configuration reference: `docs/config.md`
 - CLI reference: `docs/cli.md`
 - operations and recovery: `docs/operations.md`
 - troubleshooting: `docs/troubleshooting.md`
+- public API/package consumer guidance: `docs/consumers/`
 - implemented internals: `docs/internal/`
+- external protocol, service, and file-format contracts: `docs/integrations/`
 - future work: `docs/roadmap/`
 - contributor workflow: `docs/policy/development.md`
 - copyable examples: `examples/`
@@ -106,7 +110,7 @@ Recommended:
 - `examples/`
 - `docs/policy/development.md`
 
-### Modular, staged, service-oriented, or orchestration application
+### Modular, service-oriented, or orchestration application
 
 Required:
 - `docs/cli.md`, if CLI-based
@@ -119,6 +123,31 @@ Recommended:
 - `docs/troubleshooting.md`
 - validated examples under `examples/`
 
+### Public HTTP API service
+
+Required:
+- `docs/api.md`
+- `docs/cli.md`, if CLI-based
+- `docs/config.md`, if config-driven
+- `docs/operations.md`
+- `docs/internal/`
+- `docs/policy/development.md`
+
+Recommended:
+- `docs/troubleshooting.md`
+- `docs/consumers/`, for task-oriented client integration guides
+- `docs/integrations/`, for upstream/downstream service contracts
+- validated examples under `examples/`
+
+### Project with public packages or consumer APIs
+
+Required:
+- `docs/consumers/api.md`
+- one `docs/consumers/pkg-<name>.md` file per public package, if public packages exist
+
+Recommended:
+- copyable consumer examples under `examples/`, if practical
+
 ## Required Documents
 
 ### README.md
@@ -159,7 +188,35 @@ It should include:
 - architectural invariants;
 - explicit non-goals, if useful.
 
-For small projects, this file may be brief. It may simply state that the project is intentionally narrow, monolithic, and dependency-light.
+Notably, this file should prescribe a core development *policy* that should remain unchanged as the application evolves. It is not a place for details (e.g., CLI flags) that could change over time.
+
+The contents of `architecture.md` should be trim and concise. LLMs may be directed to review it routinely via AGENTS.md, CLAUDE.md, or similar.
+
+### docs/api.md
+
+**Audience:** external HTTP API consumers, developers, LLM coding agents integrating by HTTP
+
+Required for projects whose primary public interface is HTTP.
+
+`docs/api.md` is the canonical public HTTP API contract. It should be normative for external consumers and should not be duplicated by README, operations docs, consumer guides, or integration docs.
+
+It should include:
+
+1. base URL conventions;
+2. authentication and authorization behavior, if implemented;
+3. response envelope;
+4. supported media types and content negotiation behavior;
+5. shared query parameters;
+6. endpoint reference grouped by route family;
+7. request parameters and validation rules;
+8. response fields, units, nullability, and optionality;
+9. error response shape and status codes;
+10. pagination, caching, rate-limit, idempotency, and retry behavior, if implemented;
+11. compact request and response examples.
+
+It must document only implemented endpoints and behavior. Planned endpoints, proposed fields, future filters, and experimental response shapes belong only under `docs/roadmap/`.
+
+For HTTP API projects, `docs/consumers/` may provide task-oriented client integration guides, but those guides should link to `docs/api.md` for the authoritative endpoint contract.
 
 ### docs/policy/development.md
 
@@ -175,7 +232,7 @@ It should include:
 - dependency policy;
 - how to add config fields;
 - how to add CLI flags;
-- how to add stages/modules/adapters, if applicable;
+- how to add modules or adapters, if applicable;
 - how to update examples;
 - documentation update expectations.
 
@@ -216,7 +273,7 @@ Explain when commands are useful, not just their syntax.
 
 **Audience:** administrators, operators
 
-Required for applications that maintain state, support resume behavior, run multiple stages, write durable artifacts, use remote storage, or require recovery procedures.
+Required for applications that maintain state, support resume behavior, run multi-step workflows, write durable artifacts, use remote storage, or require recovery procedures.
 
 It should cover:
 
@@ -244,11 +301,40 @@ Each entry should include:
 - safe fix;
 - relevant links.
 
+### docs/consumers/
+
+**Audience:** developers and LLM coding agents integrating this project from another codebase
+
+Required for projects with public packages, SDKs, client APIs, plugin APIs, or other application-facing integration surfaces.
+
+This directory describes how an external codebase should consume the project's public API. It should be task-oriented and copyable where useful. It is not the place for internal implementation details or operator procedures.
+
+For projects whose public API is HTTP, `docs/consumers/` is not required, and it should not duplicate the endpoint reference in `docs/api.md`. If present, it may provide practical integration workflows, client-specific examples, or migration notes that link back to `docs/api.md`.
+
+`docs/consumers/api.md` should provide the consumer-facing overview and primary implementation workflow. It should include:
+
+1. intended consumer audience and use cases;
+2. required inputs supplied by operators or deployment configuration;
+3. recommended public package or API workflow;
+4. minimal copyable example;
+5. consumer responsibilities and boundaries;
+6. retry, idempotency, or status behavior, if applicable;
+7. links to package-specific docs and canonical integration contracts.
+
+Package-specific docs should be named `pkg-<name>.md` and should include:
+
+1. import path;
+2. intended use cases;
+3. primary types and functions needed by consumers;
+4. minimal examples;
+5. validation, error, retry, and boundary behavior;
+6. links to canonical file-format or wire-protocol contracts.
+
 ### docs/internal/
 
 **Audience:** developers, LLM coding agents
 
-Required for modular, staged, service-oriented, or orchestration projects.
+Required for modular, service-oriented, or orchestration projects.
 
 This directory describes implemented internal components. It is not the roadmap.
 
@@ -289,7 +375,9 @@ Roadmap docs should not be confused with current behavior.
 
 Required for projects that depend on external CLIs, APIs, services, protocols, or file formats where the integration contract is important to maintain.
 
-This directory contains concise, versioned reference notes for external integration contracts. It should document only the parts of the external system that this project actually uses.
+This directory contains concise, versioned reference notes for external integration contracts. It should document only the parts of the external system that this project actually uses or exposes.
+
+For public HTTP API services, `docs/integrations/` should document upstream, downstream, storage, protocol, or runtime contracts that the service depends on or bridges. It should not become a second copy of the public HTTP endpoint reference; that belongs in `docs/api.md`.
 
 Use one file per integration where useful.
 
@@ -346,8 +434,10 @@ Before merging documentation changes, verify:
 
 - README is concise and orientation-focused.
 - `docs/policy/architecture.md` describes development principles.
+- `docs/api.md` is the canonical HTTP contract for HTTP API services.
 - Future work appears only under `docs/roadmap/`.
 - User-facing docs avoid unnecessary internals.
+- Consumer-facing docs explain public APIs without duplicating HTTP endpoint or integration contracts.
 - Developer-facing docs preserve boundaries and invariants.
 - Config examples match the schema.
 - CLI examples match real commands and flags.

docs/roadmap/builtins.md

@@ -0,0 +1,142 @@
+# Built-In Profiles Roadmap
+
+This roadmap defines the target behavior for adding built-in execution profiles to Scriptorium.
+
+Built-in profiles are useful for CLI, HTTP, subprocess, and library consumers, and they provide a clean foundation for public-package ergonomics.
+
+## Motivation
+
+Scriptorium currently requires a profile source for every run path. That is appropriate for fully custom deployments, but it creates unnecessary setup for common model targets where stable profile definitions can be shipped with the application.
+
+Built-in profiles should let callers select standard profile IDs without creating local profile files. Users and downstream applications should still be able to override any built-in profile by providing a custom profile with the same ID.
+
+## Target Behavior
+
+Scriptorium should include a built-in set of execution profiles compiled into the binary/package.
+
+Profile lookup should use this precedence:
+
+1. user-provided or downstream-provided profiles;
+2. built-in profiles;
+3. profile-not-found error.
+
+If a user profile and a built-in profile share the same ID, the user profile wins. This is intentional override behavior and should not be treated as a duplicate-profile error.
+
+Duplicate profile IDs within the user profile source should remain invalid. Duplicate profile IDs within the built-in profile set should be prevented by tests. Duplicate IDs across the user source and built-in source are valid because they express override intent.
+
+Once built-ins exist, `profile_dir` should no longer be required for CLI, HTTP, or public library engine construction. When no custom profile source is configured, Scriptorium should use the built-in profile repository alone. When a custom profile source is configured, Scriptorium should overlay it on top of the built-in repository.
+
+## Architecture
+
+Built-in profiles should be modeled as another implementation of the existing `profile.Repository` boundary.
+
+Recommended repository structure:
+
+- filesystem or custom profile repository for user-provided profiles;
+- built-in profile repository backed by embedded profile YAML;
+- overlay repository that checks the primary repository first and falls back to built-ins only when the primary returns `profile.ErrProfileNotFound`.
+
+The runner should continue to depend only on `profile.Repository`. It should not know whether a selected profile came from a file, a built-in definition, or a future public-package source.
+
+### Built-In Repository
+
+Built-in definitions should be stored as normal profile YAML and embedded into the binary with Go `embed`.
+
+Recommended package shape:
+
+- `internal/profile/builtin` owns embedded built-in profile assets and exposes a repository constructor.
+- built-in profile files live under that package in a stable asset directory.
+- the built-in repository reuses the same strict decoding and validation rules as normal profiles.
+
+Using YAML for built-ins keeps the built-in profile format aligned with the documented profile format and lets maintainers add stable definitions without duplicating profile construction logic in Go.
+
+### FS Repository
+
+The implementation should introduce or reuse an `fs.FS`-based profile repository rather than making the built-in loader special-purpose.
+
+That repository supports:
+
+- embedded built-in profile assets;
+- embedded or virtual profile sources in public library work;
+- fixture-based tests without temporary directory setup where useful.
+
+The existing filesystem repository can remain as a thin path-based adapter, or it can delegate internally to the `fs.FS` repository where that is clean and maintainable.
+
+### Overlay Repository
+
+An overlay repository should compose two repositories:
+
+- primary: user-provided, custom, or downstream profile source;
+- fallback: built-in profile source.
+
+Lookup behavior:
+
+- return the primary result if primary lookup succeeds;
+- if primary returns `profile.ErrProfileNotFound`, try fallback;
+- if primary returns any other error, return that error and do not try fallback;
+- return fallback result or fallback error.
+
+This preserves strict validation of user profile sources. A malformed selected user profile should not silently fall through to a built-in with the same ID.
+
+## CLI And HTTP Behavior
+
+The CLI and HTTP server should no longer require `profile_dir` once built-in profiles are available.
+
+Expected behavior:
+
+- `profile_dir` omitted: built-ins are available.
+- `profile_dir` provided: profiles from that directory override built-ins with the same ID.
+- selected profile ID present only in built-ins: run succeeds.
+- selected profile ID present in both custom profiles and built-ins: custom profile is used.
+- selected profile ID missing from both sources: existing profile-not-found behavior is preserved.
+- selected profile ID matches a malformed custom profile: profile-load failure is returned, not fallback to built-in.
+
+Configuration and CLI documentation should describe `profile_dir` as optional once built-in profiles are available.
+
+## Public Library Interaction
+
+This feature should support the current public package behavior and the production library roadmap.
+
+For the current public engine, `ProfileDir` should become optional once built-ins exist. A caller that does not configure a custom profile directory should still be able to use built-in profile IDs.
+
+The production library roadmap may add `fs.FS`, single-file, and in-memory profile sources. Those sources should become overlay primaries above the same built-in repository.
+
+Credential behavior for built-ins should follow the active execution path:
+
+- current CLI/HTTP behavior may continue to use `api_key_env` in profile definitions;
+- the public library API may supply direct API-key values without changing built-in profile IDs;
+- built-in profile files must never contain raw API keys.
+
+## Scope
+
+In scope:
+
+- built-in execution profile assets;
+- strict validation of all built-in profiles;
+- `fs.FS` profile repository support where needed for embedded assets;
+- overlay profile repository with user-over-built-in precedence;
+- optional `profile_dir` for CLI, HTTP, and public engine construction;
+- tests for lookup precedence, override behavior, duplicate handling, and error behavior;
+- documentation of CLI/config/profile behavior.
+
+Out of scope:
+
+- changing the profile YAML format;
+- accepting raw API keys in profile YAML;
+- adding a mutable runtime profile registry;
+- adding a provider/model catalog that must track rapidly changing model availability;
+- changing prompt `default_profile` semantics beyond allowing built-in IDs;
+- implementing the broader `fs.FS` prompt/schema/library source work from `docs/roadmap/library.md`.
+
+## Acceptance Criteria
+
+- Scriptorium can run or render using a built-in profile ID with no configured `profile_dir`.
+- CLI `run`, CLI `render`, and HTTP `serve` no longer fail solely because `profile_dir` is omitted.
+- A profile in `profile_dir` overrides a built-in profile with the same ID.
+- Duplicate profile IDs inside `profile_dir` remain invalid.
+- Duplicate profile IDs inside the built-in profile set are caught by tests.
+- A malformed selected custom profile does not fall back to a built-in profile with the same ID.
+- Profile-not-found behavior remains clear when an ID exists in neither custom profiles nor built-ins.
+- Built-in profiles are loaded through the same validation rules as file-based profiles.
+- Existing runtime override behavior continues to apply to built-in profiles.
+- Existing CLI, HTTP, and public error mapping remains consistent with current profile-load and profile-not-found semantics.

docs/roadmap/implementation.md

@@ -0,0 +1,451 @@
+# Built-In Profiles And Library API Implementation Plan
+
+This plan implements the target states in:
+
+- `docs/roadmap/builtins.md`
+- `docs/roadmap/library.md`
+
+Audience: LLM coding agents implementing the work in order. Review and follow `docs/policy/architecture.md`, `docs/policy/development.md`, and `docs/policy/documentation.md` before changing code.
+
+## Global Constraints
+
+- Implement built-in profiles before the public library production upgrades.
+- Keep orchestration in `internal/usecase`; adapters and the public package should translate inputs and wire components.
+- Keep `internal/*` packages internal. Public package types must remain facade types.
+- Do not add a mutable global profile registry.
+- Do not add a credential resolver or secret-manager abstraction.
+- Do not accept raw API keys in YAML/JSON config, profile files, prompt files, CLI flags, or HTTP request bodies.
+- Do not emit raw API keys in prepared output, run results, logs, or examples.
+- Prefer standard library APIs. Do not add dependencies unless a later implementation prompt explicitly approves one.
+- Keep each stage passing `go test ./...` before moving to the next stage.
+
+## Stage 1: Profile Repository Foundations
+
+Goal: add reusable profile repository primitives that support built-ins without changing runner behavior.
+
+### Implementation Steps
+
+1. Add an `fs.FS`-backed profile repository in `internal/profile`.
+   - Constructor shape should be similar to `NewFSRepository(fsys fs.FS, root string) Repository`.
+   - It must scan YAML files recursively below `root`.
+   - It must use the same strict YAML decoding, profile validation, raw `api_key` rejection, and duplicate-ID behavior as the existing filesystem repository.
+   - It must return the existing profile package sentinel errors where applicable.
+
+2. Refactor shared profile-loading behavior.
+   - Avoid duplicating validation and metadata logic between filesystem and `fs.FS` repositories.
+   - The existing `NewFilesystemRepository(dir)` API should remain available.
+   - It may either delegate to the `fs.FS` repository through `os.DirFS` or share unexported loader helpers.
+
+3. Add an overlay profile repository in `internal/profile`.
+   - Constructor shape should be similar to `NewOverlayRepository(primary, fallback Repository) Repository`.
+   - Lookup must return the primary result when primary succeeds.
+   - Lookup must fall back only when `errors.Is(err, profile.ErrProfileNotFound)` for the primary.
+   - Lookup must return primary load/validation errors directly and must not fall back after those errors.
+   - Nil repository inputs should be handled deliberately. Prefer treating nil primary as "no primary" and requiring a non-nil fallback for built-in-only operation.
+
+### Tests
+
+Add focused tests under `internal/profile`.
+
+Required coverage:
+
+- `NewFSRepository` loads valid profiles from nested directories.
+- `NewFSRepository` rejects unknown YAML fields.
+- `NewFSRepository` rejects raw `api_key` in the selected profile.
+- `NewFSRepository` ignores raw `api_key` in non-selected profiles, matching current filesystem behavior.
+- `NewFSRepository` rejects duplicate IDs within one source.
+- `NewFilesystemRepository` still satisfies all existing repository tests.
+- `NewOverlayRepository` returns primary matches before fallback matches.
+- `NewOverlayRepository` falls back on primary not found.
+- `NewOverlayRepository` does not fall back after a primary invalid YAML/profile/raw-key error.
+- `NewOverlayRepository` returns not found when both sources miss.
+
+### Verification
+
+Run:
+
+```bash
+go test ./internal/profile
+go test ./...
+```
+
+## Stage 2: Built-In Profile Assets And Wiring
+
+Goal: compile built-in profiles into Scriptorium and make profile lookup use user-over-built-in precedence.
+
+### Implementation Steps
+
+1. Add an `internal/profile/builtin` package.
+   - Store built-in profile YAML files in a stable asset directory under that package.
+   - Use Go `embed` to compile those files into the binary/package.
+   - Expose a constructor such as `builtin.NewRepository() profile.Repository`.
+   - The repository should use the `fs.FS` profile repository from Stage 1.
+
+2. Add built-in profile validation tests.
+   - Tests should load every built-in profile through the real profile loader.
+   - Tests should fail if the built-in profile set contains duplicate IDs.
+   - Tests should fail if any built-in profile contains raw `api_key`.
+
+3. Add built-in profiles.
+   - Use `docs/roadmap/profiles/` as the source catalog for the initial built-in profile set.
+   - Copy those YAML files into the built-in profile asset directory, preserving provider subdirectories unless the implementation has a clear reason to flatten them.
+   - Do not invent a broad provider/model catalog.
+   - Do not add raw API keys.
+   - Built-in profiles may use `api_key_env` for CLI/HTTP compatibility when the provider requires authentication.
+
+4. Wire repositories through a small helper.
+   - Add an internal helper near adapter wiring, or in `internal/profile`, that returns:
+     - built-in repository only when no custom profile source is configured;
+     - overlay repository when a custom profile source is configured.
+   - The runner should still receive only a `profile.Repository`.
+
+5. Make `profile_dir` optional.
+   - CLI `run`, CLI `render`, and HTTP `serve` argument/config validation should require `prompt_dir` but no longer require `profile_dir`.
+   - Public `NewEngine` should no longer reject an empty `Config.ProfileDir`.
+   - When `profile_dir` is empty, wire only built-ins.
+   - When `profile_dir` is non-empty, wire filesystem profiles over built-ins.
+
+### Tests
+
+Add or update tests under `internal/adapter/cli`, `internal/adapter/http`, root public package tests, and profile/builtin tests.
+
+Required coverage:
+
+- CLI parse/config tests accept missing `profile_dir` when `prompt_dir` is present.
+- HTTP serve parse/config tests accept missing `profile_dir` when `prompt_dir` is present.
+- Public `NewEngine` accepts missing `ProfileDir`.
+- A built-in profile ID can be selected with no custom `profile_dir`.
+- A prompt `default_profile` can refer to a built-in profile ID.
+- A custom profile in `profile_dir` overrides a built-in with the same ID.
+- A malformed selected custom profile does not fall back to a built-in with the same ID.
+- A missing profile ID still maps to the existing profile-not-found behavior.
+- Existing duplicate-ID tests for filesystem profiles continue to fail within the custom source.
+
+### Documentation
+
+After code behavior exists, update non-roadmap docs:
+
+- `docs/config.md`: document `profile_dir` as optional and describe built-in fallback/override behavior.
+- `docs/cli.md`: remove claims that `--profile-dir` is required.
+- `docs/internal/adapters.md`: document built-in profile repository composition.
+- Any affected examples or README snippets that imply `profile_dir` is mandatory.
+
+Do not document built-in profile IDs outside implemented assets.
+
+### Verification
+
+Run:
+
+```bash
+go test ./internal/profile ./internal/adapter/cli ./internal/adapter/http .
+go test ./...
+go run ./cmd/scriptorium render \
+  --config ./examples/config.yml \
+  --prompt generic.markdown_summary \
+  --input transcript=./examples/fixtures/transcript.md \
+  --input glossary=./examples/fixtures/glossary.yml \
+  --format json
+```
+
+Also run a new smoke command that uses a built-in profile without `--profile-dir` once a concrete built-in profile ID is available.
+
+## Stage 3: Public API Credential Value
+
+Goal: support the production library credential model: a direct API-key Go value, without adding a resolver or accepting raw keys in serialized config.
+
+### Public API Decision
+
+Use a single public credential-supply method:
+
+```go
+type RunRequest struct {
+	// existing fields...
+	APIKey string `json:"-"`
+}
+```
+
+Do not add `Config.APIKey`, `WithAPIKey`, or a credential resolver in this stage. A request-level value avoids storing secrets on long-lived engines and supports per-tenant callers.
+
+### Implementation Steps
+
+1. Add direct API-key plumbing through internal request/target types.
+   - Add an internal direct API-key field where needed, with `json:"-"` and `yaml:"-"` tags.
+   - Convert public `RunRequest.APIKey` into the internal request.
+   - Carry the value to the effective execution target used for LLM generation.
+   - Do not include the value in prepared/run public results, formatted output, logs, hashes, or docs examples.
+
+2. Update credential validation.
+   - If a selected/effective profile requires authentication and a direct API key is provided, do not require the environment variable to be set for the public path.
+   - Preserve existing CLI/HTTP behavior that uses `api_key_env`.
+   - Preserve existing errors for missing environment variables in CLI/HTTP paths.
+
+3. Update the OpenAI-compatible LLM client.
+   - Prefer the direct API-key value when present.
+   - Fall back to existing `api_key_env` behavior for CLI/HTTP compatibility.
+   - Never serialize or log the direct API-key value.
+
+4. Update public LLM injection conversion.
+   - Do not expose the raw API key to injected public `LLMClient` implementations unless that is strictly necessary for custom LLM execution.
+   - If custom LLM clients need the key, expose it only on the public `GenerateRequest` with `json:"-"` and document that fake/test clients should avoid logging it.
+
+### Tests
+
+Required coverage:
+
+- Public `Run` can call the default OpenAI-compatible client path with a direct API key without requiring the configured `api_key_env` environment variable.
+- CLI/HTTP behavior using `api_key_env` still works.
+- Missing credentials still fail clearly when a selected profile requires authentication and neither direct key nor usable env value is available.
+- Public `PreparedRun` and `RunResult` JSON do not include the direct API key.
+- Formatted prepared output does not include the direct API key.
+- Direct API-key values are not included in hashes.
+- Injected fake LLM tests either receive no key or receive it only through a `json:"-"` field, depending on the implementation choice above.
+
+### Verification
+
+Run:
+
+```bash
+go test ./internal/llm ./internal/usecase ./internal/adapter/cli ./internal/adapter/http .
+go test ./...
+```
+
+## Stage 4: Public Asset Source Options
+
+Goal: let library consumers load standard Scriptorium prompt/profile/schema assets from directories, single files, and `fs.FS` sources.
+
+### Public API
+
+Keep existing `Config` directory fields working. Add options:
+
+```go
+func WithPromptFS(fsys fs.FS, root string) Option
+func WithPromptFile(path string) Option
+func WithProfileFS(fsys fs.FS, root string) Option
+func WithProfileFile(path string) Option
+func WithSchemaFS(fsys fs.FS, root string) Option
+func WithSchemaFile(path string) Option
+```
+
+Rules:
+
+- Directory `Config` fields remain the compatibility path.
+- Explicit options override the corresponding `Config` directory field.
+- Prompt source is required.
+- Profile source is optional because built-in profiles exist.
+- Schema source is optional and should default to the current schema default behavior when not configured.
+- Nil `fs.FS` values, empty required roots, and invalid option combinations return `ErrInvalidConfig`.
+
+### Implementation Steps
+
+1. Add `fs.FS` prompt-definition support.
+   - Implement an `fs.FS` prompt repository that preserves existing strict prompt YAML behavior.
+   - Preserve prompt lookup by YAML `id`, not path.
+   - Preserve duplicate prompt ID errors within one source.
+   - Resolve `content_file` relative to the prompt file's directory inside the same source.
+   - Keep the existing filesystem repository API; it may delegate to the `fs.FS` implementation.
+
+2. Add public prompt source wiring.
+   - `Config.PromptDir` wires the filesystem repository.
+   - `WithPromptFS` wires the `fs.FS` repository.
+   - `WithPromptFile(path)` wires a single-file source and must still select by prompt YAML `id`.
+
+3. Add public profile source wiring.
+   - Reuse the Stage 1 profile `fs.FS` repository.
+   - `WithProfileFS` and `WithProfileFile` become overlay primaries above built-ins.
+   - Empty profile source still means built-ins only.
+
+4. Add schema `fs.FS` support.
+   - Extend or wrap the standard validator so schema files can be loaded from an `fs.FS` source.
+   - `WithSchemaFS` should preserve existing `schema_path` semantics.
+   - `WithSchemaFile(path)` should expose the file by its base name; prompts using it should set `schema_path` to that base name.
+
+5. Keep adapter scope narrow.
+   - This stage is for the public package and shared repositories/validators.
+   - Do not change CLI/HTTP request shapes for prompt or schema `fs.FS` sources.
+
+### Tests
+
+Required coverage:
+
+- Public `Prepare` works with prompt definitions from `embed.FS`.
+- `content_file` references resolve relative to the prompt file in `embed.FS`.
+- Public `Prepare` works with `WithPromptFile`.
+- Public `Run` or `Prepare` works with `WithProfileFS` over built-ins.
+- Public `Run` or `Prepare` works with `WithProfileFile` over built-ins.
+- Public structured-output schema validation works with `WithSchemaFS`.
+- `WithSchemaFile` works when the prompt's `schema_path` is the schema file base name.
+- Explicit source options override `Config` directory fields.
+- Invalid/nil source options return `ErrInvalidConfig`.
+- Existing filesystem prompt/profile/schema behavior remains unchanged.
+
+### Verification
+
+Run:
+
+```bash
+go test ./internal/promptdef ./internal/profile ./internal/validate .
+go test ./...
+```
+
+## Stage 5: Public In-Memory Profiles And Profile Templates
+
+Goal: allow library callers to provide typed profile values and construct stable OpenAI-compatible profile templates without generating YAML.
+
+### Public API
+
+Add a public profile facade aligned with the profile YAML contract:
+
+```go
+type Profile struct {
+	ID              string
+	Endpoint        string
+	Model           string
+	Temperature     float64
+	MaxTokens       int
+	TopP            float64
+	TimeoutSeconds  int
+	ServiceTier     string
+	ReasoningEffort string
+	APIKeyRequired  bool
+	ExtraParams     map[string]any
+}
+
+func WithProfiles(profiles ...Profile) Option
+```
+
+Add an OpenAI-compatible template constructor:
+
+```go
+type OpenAICompatibleProfileConfig struct {
+	ID              string
+	Endpoint        string
+	Model           string
+	APIKeyRequired  bool
+	Temperature     float64
+	MaxTokens       int
+	TopP            float64
+	TimeoutSeconds  int
+	ServiceTier     string
+	ReasoningEffort string
+	ExtraParams     map[string]any
+}
+
+func OpenAICompatibleProfile(cfg OpenAICompatibleProfileConfig) Profile
+```
+
+Rules:
+
+- `WithProfiles` profiles override built-ins with the same ID.
+- If `WithProfiles` and a file/FS profile source are both configured, in-memory profiles have highest precedence, then file/FS profiles, then built-ins.
+- Public profile values must not include raw API-key fields.
+- Use `APIKeyRequired` to indicate whether `RunRequest.APIKey` is required for the public path. Internal conversion may map this to the existing auth-required/profile credential model without exposing raw keys.
+
+### Implementation Steps
+
+1. Add a profile repository for public in-memory `Profile` values.
+   - Validate with the same effective rules as YAML profiles.
+   - Reject duplicate IDs within the provided values.
+   - Deep-copy `ExtraParams` across public/internal boundaries.
+
+2. Compose profile sources in public `NewEngine`.
+   - Highest: in-memory public profiles.
+   - Next: configured profile file/FS/directory source.
+   - Fallback: built-in profiles.
+
+3. Add template constructor conversion.
+   - `OpenAICompatibleProfile` should be a convenience constructor only.
+   - It should not register global state.
+   - It should not maintain a broad model catalog.
+
+4. Ensure direct API-key behavior works with in-memory/template profiles.
+   - Profiles marked `APIKeyRequired` should require `RunRequest.APIKey` for public default LLM execution.
+   - Profiles not marked `APIKeyRequired` should not require an API key.
+
+### Tests
+
+Required coverage:
+
+- Public `Prepare`/`Run` uses `WithProfiles` without any profile files.
+- In-memory profiles override built-ins.
+- In-memory profiles override file/FS profile sources when IDs collide.
+- Duplicate in-memory profile IDs return `ErrInvalidConfig`.
+- Template-created profiles execute through the same path as normal profiles.
+- Template-created profiles requiring an API key work with `RunRequest.APIKey`.
+- Template-created profiles that do not require an API key work without one.
+- `ExtraParams` in public profiles are deep-copied and isolated from caller mutation.
+
+### Verification
+
+Run:
+
+```bash
+go test .
+go test ./...
+```
+
+## Stage 6: Public Documentation And Examples
+
+Goal: document implemented behavior in canonical locations after code exists.
+
+### Documentation
+
+Update:
+
+- `README.md`: add a short pointer to library usage and built-in profiles without turning the README into a manual.
+- `docs/config.md`: document optional `profile_dir`, built-in override behavior, and implemented built-in profile IDs.
+- `docs/cli.md`: document optional `--profile-dir` and built-in profile selection.
+- `docs/internal/adapters.md`: document repository composition and public library adapter surface.
+- `docs/consumers/api.md`: describe public consumer surfaces at a high level.
+- `docs/consumers/pkg-scriptorium.md`: document root package usage, source options, direct API-key value, errors, and examples.
+- `docs/integrations/openai-compatible-chat.md`: update only if direct API-key plumbing changes provider-call semantics.
+
+Do not document unimplemented roadmap behavior outside `docs/roadmap/`.
+
+### Examples
+
+Add or update copyable examples that require no real provider credentials:
+
+- prepare with built-in profile and no `profile_dir`;
+- public library prepare from `embed.FS`;
+- public library run with injected fake LLM;
+- public library run with typed/template profile and direct API key, using a fake/local provider path so no real secret is required.
+
+Examples must be secret-free.
+
+### Tests And Smoke Commands
+
+Required verification:
+
+```bash
+go test ./...
+go run ./cmd/scriptorium render \
+  --config ./examples/config.yml \
+  --prompt generic.markdown_summary \
+  --input transcript=./examples/fixtures/transcript.md \
+  --input glossary=./examples/fixtures/glossary.yml \
+  --format json
+```
+
+Also run smoke commands for any new examples, such as:
+
+```bash
+go run ./examples/go-library/prepare
+```
+
+If an example relies on a specific built-in profile ID, use an ID from `docs/roadmap/profiles/` and include that smoke command in the implementing change.
+
+## Final Completion Checklist
+
+Before marking the combined feature complete:
+
+1. `go test ./...` passes.
+2. Existing CLI render smoke command passes.
+3. At least one smoke command proves built-in profile lookup works without `profile_dir`.
+4. Public package examples compile/run without real provider credentials.
+5. `profile_dir` is optional in CLI, HTTP, and public engine construction.
+6. Custom profiles override built-ins with the same ID.
+7. Malformed selected custom profiles do not fall back to built-ins.
+8. Built-in profiles use the same validation rules as file profiles.
+9. Public `RunRequest.APIKey` is the documented library credential method.
+10. Raw API keys do not appear in YAML/JSON config, prepared output, run results, logs, hashes, or examples.
+11. Non-roadmap docs describe only implemented behavior.

docs/roadmap/library.md

@@ -0,0 +1,176 @@
+# Library API Production Roadmap
+
+This roadmap defines the target state for making Scriptorium's public Go package production-ready for downstream applications while preserving the existing CLI and HTTP behavior.
+
+The library remains an additional adapter surface. It should not replace the subprocess, CLI, or HTTP contracts that already exist.
+
+## Motivation
+
+Many Go applications can use Scriptorium more cleanly as an imported package than as a subprocess. A downstream developer should be able to keep prompt assets in standard Scriptorium format, pass application data through a small adapter, and receive a typed response without reimplementing prompt rendering, profile resolution, validation, or OpenAI-compatible request construction.
+
+The core consumer story is:
+
+- the downstream app owns one or more `prompt.yml` files in standard Scriptorium format;
+- those prompts may use inline content, `content_file` references, variables, cache-control markers, and structured-output schemas;
+- the app may provide its own `profile.yml`, or select a standard built-in/profile-template configuration;
+- the app supplies an API key as a normal Go value when the selected profile requires one;
+- the app calls the public Go package to prepare or run the request and receives typed results.
+
+## Current State
+
+The public package already provides the first library facade:
+
+- root package import;
+- typed engine construction;
+- typed prepare/run requests and results;
+- file and inline artifact references;
+- execution overrides;
+- custom LLM injection for testing or alternate execution;
+- public error categories that map internal failures to stable caller-facing errors.
+
+The remaining production-readiness gaps are mostly about consumer ergonomics and asset sourcing:
+
+- callers are still oriented around filesystem prompt/profile/schema directories;
+- embedded prompt/profile/schema assets are not a first-class public use case;
+- standard or built-in profile selection is not yet available;
+- library credential supply is still tightly coupled to environment-variable lookup rather than direct API-key values;
+- public documentation and examples need to show the intended downstream app adapter pattern.
+
+## Target State
+
+The public package should let a downstream Go application use standard Scriptorium assets without temporary directories, subprocess invocation, or internal package imports.
+
+### Prompt Assets
+
+The library should support prompt definitions from:
+
+- existing prompt directories;
+- a single prompt file;
+- `fs.FS`, including `embed.FS`.
+
+Prompt syntax should remain the standard Scriptorium prompt YAML format. `content_file` references should continue to be supported and should resolve relative to the prompt definition's source location within the same asset source.
+
+The public API should not introduce a separate in-code prompt DSL as the primary path. YAML remains the canonical authoring format so prompts can be shared between CLI, HTTP, subprocess, and library usage.
+
+### Schema Assets
+
+Structured-output schemas should be loadable from the same kinds of sources as prompt definitions:
+
+- existing schema directories;
+- a single schema file where appropriate;
+- `fs.FS`, including `embed.FS`.
+
+Schema references should retain the existing prompt-format semantics. A schema referenced by a prompt should resolve through the configured schema source, not through ad hoc caller code.
+
+### Profile Assets
+
+The library should support both custom and standard profile configuration:
+
+- existing profile directories;
+- a single profile file;
+- `fs.FS`, including `embed.FS`;
+- direct public profile values for applications that already have profile configuration in memory;
+- built-in/profile-template helpers for common OpenAI-compatible targets.
+
+Custom profiles and built-in/template profiles should flow through the same internal profile resolution and request-construction path. The built-in path should not become a separate execution mode.
+
+### Built-In Profile Templates
+
+Built-in support should favor stable profile templates over a large registry of fixed model IDs.
+
+For example, the public package should make it easy to construct or select an OpenAI-compatible profile by supplying the durable parts of the profile:
+
+- profile ID or name;
+- base URL;
+- model;
+- whether the profile requires an API key;
+- default numeric parameters where desired;
+- structured-output and extra-parameter behavior consistent with normal profiles.
+
+The package may include a small set of named helpers for common OpenAI-compatible services, but those helpers should avoid hard-coding a broad and fast-changing list of model names.
+
+### Credentials
+
+The public package must keep raw API keys out of prompt/profile YAML, prepared-run output, run results, logs, and examples.
+
+For the public library API, the single supported credential-supply method should be a direct API-key value passed by the consuming Go application. The consuming application is responsible for loading and managing its own secrets before calling Scriptorium.
+
+This may be exposed as a field such as `Config.APIKey`, an option such as `WithAPIKey`, or an equivalent request/engine-level value that is easy to pass through an application adapter. The exact API should avoid accidental serialization in prepared output, run results, logs, and examples.
+
+The public package should not encourage raw API-key storage in prompt/profile YAML. Existing CLI behavior may continue to use environment-variable references for compatibility, but the production library path should not introduce a separate credential resolver or secret-manager abstraction.
+
+### Public API Shape
+
+The public API should remain narrow, idiomatic, and stable. Recommended additions include:
+
+- engine options for prompt/profile/schema directories;
+- engine options for prompt/profile/schema `fs.FS` sources;
+- engine options for single prompt/profile/schema files where useful;
+- public profile/template constructors that map to internal profile definitions;
+- a direct API-key value for profiles that require authentication;
+- examples showing `embed.FS`, custom profile files, template profile selection, and fake LLM testing.
+
+The public package should continue to expose facade types rather than exporting internal package types. Internal package layout should remain free to evolve.
+
+## Scope
+
+In scope:
+
+- first-class `fs.FS` support for public library prompt, profile, and schema sources;
+- ergonomic single-file asset options where they reduce caller boilerplate;
+- built-in/profile-template helpers for common OpenAI-compatible usage;
+- in-memory public profile values where appropriate;
+- direct API-key value support for the public library path;
+- consumer-facing examples under `examples/`;
+- consumer package documentation under `docs/consumers/` once behavior is implemented;
+- tests proving library behavior matches existing CLI/use-case behavior.
+
+Out of scope:
+
+- changing standard prompt, profile, or schema file formats;
+- exposing internal packages as public API;
+- replacing or removing CLI, HTTP, or subprocess support;
+- adding a multi-step workflow engine;
+- adding non-Go bindings;
+- maintaining a comprehensive provider/model catalog;
+- accepting raw API keys in serialized YAML/JSON configuration;
+- adding a credential resolver or secret-manager abstraction.
+
+## Acceptance Criteria
+
+- A Go caller can import the root package and run a standard Scriptorium prompt without invoking a subprocess.
+- A Go caller can use prompt definitions from `embed.FS`, including prompts with `content_file` references.
+- A Go caller can use structured-output schemas from `embed.FS` or filesystem sources.
+- A Go caller can provide a custom profile from filesystem, `fs.FS`, or public in-memory profile values.
+- A Go caller can select a standard OpenAI-compatible profile template without writing a full profile file.
+- A Go caller can supply an API key as a normal Go value without raw secrets appearing in serialized config, prepared output, or results.
+- Public library behavior remains consistent with CLI/HTTP semantics for rendering, validation, profile resolution, runtime overrides, structured output, cache control, and LLM invocation.
+- Existing CLI and HTTP behavior remains unchanged.
+- Library tests use fake or local LLM boundaries and do not require real provider credentials.
+- Public docs outside `docs/roadmap/` describe only implemented behavior after the feature is built.
+
+## Design Decisions
+
+### Asset Source API
+
+Add first-class `fs.FS` options for prompt, profile, and schema sources while keeping existing directory-based configuration. Also add single-file convenience options where they remove meaningful caller boilerplate. Resolve `content_file` references relative to the prompt file's location inside the same source.
+
+Reasoning:
+
+This is the most idiomatic path for production Go libraries because it supports `embed.FS`, `os.DirFS`, tests, and in-memory fixture files through the same abstraction. It also avoids requiring downstream applications to unpack embedded assets into temporary directories.
+
+### Built-In Profile Strategy
+
+Provide stable profile-template helpers for OpenAI-compatible endpoints rather than a broad registry of fixed provider/model profiles. Let callers choose the model and endpoint where those values are service-specific or fast-changing.
+
+Reasoning:
+
+Endpoint shape and credential mechanics are relatively stable; model catalogs change frequently. Templates give consumers a short, correct path without making Scriptorium responsible for tracking every provider's model list.
+
+### In-Memory Profile Values
+
+Expose a small public profile facade type for in-memory profile configuration and map it to internal profile definitions. Keep it intentionally aligned with the existing profile YAML contract.
+
+Reasoning:
+
+Many applications already hold configuration in typed structs and should not need to generate YAML files just to call Scriptorium. A public facade keeps internal types private while making the library practical for production use.

docs/roadmap/profiles/aion-labs/aion-2.yml

@@ -0,0 +1,9 @@
+id: aion-2
+endpoint: https://openrouter.ai/api/v1
+model: aion-labs/aion-2.0
+temperature: 0.72
+reasoning_effort: high
+top_p: 0.95
+timeout_seconds: 180
+api_key_env: OPENROUTER_API_KEY
+service_tier: flex

docs/roadmap/profiles/anthropic/claude-fable-latest.yml

@@ -0,0 +1,7 @@
+id: claude-fable-latest
+endpoint: https://openrouter.ai/api/v1
+model: "~anthropic/claude-fable-latest"
+reasoning_effort: high
+timeout_seconds: 600
+api_key_env: OPENROUTER_API_KEY
+service_tier: flex

docs/roadmap/profiles/anthropic/claude-haiku-latest.yml

@@ -0,0 +1,7 @@
+id: claude-haiku-latest
+endpoint: https://openrouter.ai/api/v1
+model: "~anthropic/claude-haiku-latest"
+reasoning_effort: medium
+timeout_seconds: 240
+api_key_env: OPENROUTER_API_KEY
+service_tier: flex

docs/roadmap/profiles/anthropic/claude-opus-latest.yml

@@ -0,0 +1,7 @@
+id: claude-opus-latest
+endpoint: https://openrouter.ai/api/v1
+model: "~anthropic/claude-opus-latest"
+reasoning_effort: high
+timeout_seconds: 240
+api_key_env: OPENROUTER_API_KEY
+service_tier: flex

docs/roadmap/profiles/anthropic/claude-sonnet-latest.yml

@@ -0,0 +1,7 @@
+id: claude-sonnet-latest
+endpoint: https://openrouter.ai/api/v1
+model: "~anthropic/claude-sonnet-latest"
+reasoning_effort: high
+timeout_seconds: 240
+api_key_env: OPENROUTER_API_KEY
+service_tier: flex

docs/roadmap/profiles/deepseek/deepseek-3-2.yml

@@ -0,0 +1,7 @@
+id: deepseek-3-2
+endpoint: https://openrouter.ai/api/v1
+model: deepseek/deepseek-v3.2
+reasoning_effort: high
+timeout_seconds: 180
+api_key_env: OPENROUTER_API_KEY
+service_tier: flex

docs/roadmap/profiles/deepseek/deepseek-4-pro.yml

@@ -0,0 +1,7 @@
+id: deepseek-4-pro
+endpoint: https://openrouter.ai/api/v1
+model: deepseek/deepseek-v4-pro
+reasoning_effort: high
+timeout_seconds: 180
+api_key_env: OPENROUTER_API_KEY
+service_tier: flex

docs/roadmap/profiles/google/gemini-2-flash-lite.yml

@@ -0,0 +1,9 @@
+id: gemini-2-flash-lite
+endpoint: https://openrouter.ai/api/v1
+model: "google/gemini-2.5-flash-lite"
+#temperature: 0.15
+reasoning_effort: high
+#top_p: 0.98
+timeout_seconds: 240
+api_key_env: OPENROUTER_API_KEY
+service_tier: flex

docs/roadmap/profiles/google/gemini-2-flash.yml

@@ -0,0 +1,9 @@
+id: gemini-2-flash
+endpoint: https://openrouter.ai/api/v1
+model: "google/gemini-2.5-flash"
+#temperature: 0.15
+reasoning_effort: high
+#top_p: 0.98
+timeout_seconds: 240
+api_key_env: OPENROUTER_API_KEY
+service_tier: flex

docs/roadmap/profiles/google/gemini-2-pro.yml

@@ -0,0 +1,9 @@
+id: gemini-2-pro
+endpoint: https://openrouter.ai/api/v1
+model: "google/gemini-2.5-pro"
+#temperature: 0.15
+reasoning_effort: high
+#top_p: 0.98
+timeout_seconds: 240
+api_key_env: OPENROUTER_API_KEY
+service_tier: flex

docs/roadmap/profiles/google/gemini-3-flash-lite.yml

@@ -0,0 +1,9 @@
+id: gemini-3-flash-lite
+endpoint: https://openrouter.ai/api/v1
+model: "google/gemini-3.1-flash-lite"
+#temperature: 0.15
+reasoning_effort: high
+#top_p: 0.98
+timeout_seconds: 240
+api_key_env: OPENROUTER_API_KEY
+service_tier: flex

docs/roadmap/profiles/google/gemini-flash-latest.yml

@@ -0,0 +1,9 @@
+id: gemini-flash-latest
+endpoint: https://openrouter.ai/api/v1
+model: "~google/gemini-flash-latest"
+#temperature: 0.15
+reasoning_effort: high
+#top_p: 0.98
+timeout_seconds: 240
+api_key_env: OPENROUTER_API_KEY
+service_tier: flex

docs/roadmap/profiles/google/gemini-pro-latest.yml

@@ -0,0 +1,9 @@
+id: gemini-pro-latest
+endpoint: https://openrouter.ai/api/v1
+model: "~google/gemini-pro-latest"
+#temperature: 0.15
+reasoning_effort: high
+#top_p: 0.98
+timeout_seconds: 240
+api_key_env: OPENROUTER_API_KEY
+service_tier: flex

docs/roadmap/profiles/google/gemma-4-31b.yml

@@ -0,0 +1,9 @@
+id: gemma-4-31b
+endpoint: https://openrouter.ai/api/v1
+model: google/gemma-4-31b-it:exacto
+temperature: 0.15
+reasoning_effort: high
+top_p: 0.98
+timeout_seconds: 240
+api_key_env: OPENROUTER_API_KEY
+service_tier: flex

docs/roadmap/profiles/minimax/minimax-m2.yml

@@ -0,0 +1,9 @@
+id: minimax-m2
+endpoint: https://openrouter.ai/api/v1
+model: minimax/minimax-m2.5
+temperature: 0.5
+reasoning_effort: high
+top_p: 0.95
+timeout_seconds: 180
+api_key_env: OPENROUTER_API_KEY
+service_tier: flex

docs/roadmap/profiles/minimax/minimax-m3.yml

@@ -0,0 +1,9 @@
+id: minimax-m3
+endpoint: https://openrouter.ai/api/v1
+model: minimax/minimax-m3
+#temperature: 0.5
+reasoning_effort: high
+#top_p: 0.95
+timeout_seconds: 180
+api_key_env: OPENROUTER_API_KEY
+service_tier: flex

docs/roadmap/profiles/mistral/mistral-large-2512.yml

@@ -0,0 +1,7 @@
+id: mistral-large-2512
+endpoint: https://openrouter.ai/api/v1
+model: mistralai/mistral-large-2512
+temperature: 0.15
+top_p: 0.98
+timeout_seconds: 180
+api_key_env: OPENROUTER_API_KEY

docs/roadmap/profiles/mistral/mistral-medium-3-5.yml

@@ -0,0 +1,8 @@
+id: mistral-medium-3-5
+endpoint: https://openrouter.ai/api/v1
+model: mistralai/mistral-medium-3-5
+temperature: 0.15
+reasoning_effort: high
+top_p: 0.98
+timeout_seconds: 180
+api_key_env: OPENROUTER_API_KEY

docs/roadmap/profiles/mistral/mistral-small-3.yml

@@ -0,0 +1,7 @@
+id: mistral-small-3
+endpoint: https://openrouter.ai/api/v1
+model: mistralai/mistral-small-3.2-24b-instruct
+temperature: 0.05
+top_p: 1.0
+timeout_seconds: 180
+api_key_env: OPENROUTER_API_KEY

docs/roadmap/profiles/mistral/mistral-small-4.yml

@@ -0,0 +1,8 @@
+id: mistral-small-4
+endpoint: https://openrouter.ai/api/v1
+model: mistralai/mistral-small-2603
+temperature: 0.1
+reasoning_effort: high
+top_p: 0.98
+timeout_seconds: 180
+api_key_env: OPENROUTER_API_KEY

docs/roadmap/profiles/nvidia/nemotron-3-ultra.yml

@@ -0,0 +1,7 @@
+id: nemotron-3-ultra
+endpoint: https://openrouter.ai/api/v1
+model: nvidia/nemotron-3-ultra-550b-a55b
+reasoning_effort: high
+timeout_seconds: 180
+api_key_env: OPENROUTER_API_KEY
+service_tier: flex

docs/roadmap/profiles/openai/gpt-5-mini.yml

@@ -0,0 +1,7 @@
+id: gpt-5-mini
+endpoint: https://openrouter.ai/api/v1
+model: "openai/gpt-5.4-mini"
+reasoning_effort: high
+timeout_seconds: 240
+api_key_env: OPENROUTER_API_KEY
+service_tier: flex

docs/roadmap/profiles/openai/gpt-5-nano.yml

@@ -0,0 +1,7 @@
+id: gpt-5-nano
+endpoint: https://openrouter.ai/api/v1
+model: "openai/gpt-5.4-nano"
+reasoning_effort: high
+timeout_seconds: 240
+api_key_env: OPENROUTER_API_KEY
+service_tier: flex

docs/troubleshooting.md

@@ -252,6 +252,39 @@ Relevant links:
 - [Configuration reference](config.md)
 - [Operations guide](operations.md)
 
+## Prompt Cache Misses Or No Cache Usage
+
+Symptom:
+
+- CLI run summary omits `cached_tokens` / `cache_write_tokens`.
+- HTTP `metadata.usage.cached_tokens` and `metadata.usage.cache_write_tokens` are both `0`.
+- Provider cost or latency does not improve after repeated similar runs.
+
+Likely cause:
+
+- The selected prompt has no `messages[].cache_control`.
+- Dynamic per-run input appears before the cache-controlled message and changes the provider cache key.
+- The provider does not support the serialized cache-control shape for the selected model.
+- The provider imposes minimum token thresholds or cache-breakpoint limits.
+
+Diagnostic step:
+
+- Run `render --format json` and verify the intended rendered message includes `cache_control`.
+- Confirm stable reusable context appears before the cache-controlled message, with dynamic input after it.
+- Check provider docs/logs for model support, minimum token thresholds, and breakpoint limits.
+
+Safe fix:
+
+- Move stable reusable context before the cache-controlled message.
+- Move highly dynamic input after the cache breakpoint.
+- Keep `cache_control.type: ephemeral` and, when using `ttl`, set `ttl: 1h`.
+- Use CLI cache counters or HTTP cache usage fields to verify cache reads/writes after rerunning.
+
+Relevant links:
+
+- [Configuration reference](config.md)
+- [OpenAI-compatible chat integration](integrations/openai-compatible-chat.md)
+
 ## Validation Status Failed (`run` Exit 2 Or HTTP 200 With Failed Status)
 
 Symptom:

engine.go

@@ -0,0 +1,141 @@
+package scriptorium
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"net/http"
+	"strings"
+	"time"
+
+	artifactadapter "gitea.maximumdirect.net/eric/scriptorium/internal/artifact"
+	"gitea.maximumdirect.net/eric/scriptorium/internal/defaults"
+	"gitea.maximumdirect.net/eric/scriptorium/internal/llm"
+	"gitea.maximumdirect.net/eric/scriptorium/internal/profile"
+	"gitea.maximumdirect.net/eric/scriptorium/internal/prompt"
+	"gitea.maximumdirect.net/eric/scriptorium/internal/promptdef"
+	"gitea.maximumdirect.net/eric/scriptorium/internal/usecase"
+	"gitea.maximumdirect.net/eric/scriptorium/internal/validate"
+)
+
+// ErrInvalidConfig indicates invalid public engine configuration.
+var ErrInvalidConfig = errors.New("invalid engine configuration")
+
+var (
+	ErrInvalidRequest  = errors.New("invalid run request")
+	ErrPromptNotFound  = errors.New("prompt not found")
+	ErrProfileNotFound = errors.New("profile not found")
+	ErrPromptLoad      = errors.New("failed to load prompt definition")
+	ErrProfileLoad     = errors.New("failed to load execution profile")
+	ErrArtifactLoad    = errors.New("failed to load artifact")
+	ErrPromptRender    = errors.New("failed to render prompt")
+	ErrLLMGenerate     = errors.New("failed to generate output")
+	ErrValidation      = errors.New("failed to validate output")
+)
+
+// Engine prepares and runs Scriptorium prompt requests.
+type Engine struct {
+	runner *usecase.Runner
+}
+
+// Config configures a public Scriptorium engine.
+type Config struct {
+	PromptDir  string
+	ProfileDir string
+	SchemaDir  string
+	Timeout    time.Duration
+	HTTPClient *http.Client
+}
+
+// Option customizes engine construction.
+type Option func(*engineOptions) error
+
+type engineOptions struct {
+	llmClient llm.Client
+}
+
+// WithLLMClient injects a custom LLM client for execution.
+func WithLLMClient(client LLMClient) Option {
+	return func(options *engineOptions) error {
+		if client == nil {
+			return ErrInvalidConfig
+		}
+		options.llmClient = publicLLMClientAdapter{client: client}
+		return nil
+	}
+}
+
+// NewEngine constructs an Engine using the same default internal components as
+// the CLI and HTTP adapters.
+func NewEngine(cfg Config, opts ...Option) (*Engine, error) {
+	if strings.TrimSpace(cfg.PromptDir) == "" {
+		return nil, fmt.Errorf("%w: prompt directory is required", ErrInvalidConfig)
+	}
+	if strings.TrimSpace(cfg.ProfileDir) == "" {
+		return nil, fmt.Errorf("%w: profile directory is required", ErrInvalidConfig)
+	}
+
+	var options engineOptions
+	for _, opt := range opts {
+		if opt == nil {
+			continue
+		}
+		if err := opt(&options); err != nil {
+			return nil, fmt.Errorf("%w: %v", ErrInvalidConfig, err)
+		}
+	}
+
+	schemaDir := cfg.SchemaDir
+	if strings.TrimSpace(schemaDir) == "" {
+		schemaDir = defaults.SchemaDirDefault
+	}
+
+	llmClient := options.llmClient
+	if llmClient == nil {
+		var err error
+		llmClient, err = llm.NewOpenAICompatibleClient(llm.OpenAICompatibleConfig{
+			Timeout:    cfg.Timeout,
+			HTTPClient: cfg.HTTPClient,
+		})
+		if err != nil {
+			return nil, fmt.Errorf("%w: %v", ErrInvalidConfig, err)
+		}
+	}
+
+	return &Engine{
+		runner: usecase.NewRunner(
+			promptdef.NewFilesystemRepository(cfg.PromptDir),
+			profile.NewFilesystemRepository(cfg.ProfileDir),
+			artifactadapter.NewCompositeReader(),
+			prompt.NewGoRenderer(),
+			llmClient,
+			validate.NewStandardValidator(schemaDir),
+		),
+	}, nil
+}
+
+// Prepare resolves a prompt request without calling an LLM.
+func (e *Engine) Prepare(ctx context.Context, req RunRequest) (*PreparedRun, error) {
+	if e == nil || e.runner == nil {
+		return nil, fmt.Errorf("%w: engine is nil", ErrInvalidConfig)
+	}
+
+	prepared, err := e.runner.Prepare(ctx, toDomainRunRequest(req))
+	if err != nil {
+		return nil, mapPublicError(err)
+	}
+	return fromDomainPreparedRun(prepared), nil
+}
+
+// Run executes a prompt request and returns the generated artifact and metadata.
+func (e *Engine) Run(ctx context.Context, req RunRequest) (*RunResult, error) {
+	if e == nil || e.runner == nil {
+		return nil, fmt.Errorf("%w: engine is nil", ErrInvalidConfig)
+	}
+
+	result, err := e.runner.Run(ctx, toDomainRunRequest(req))
+	if err != nil {
+		return nil, mapPublicError(err)
+	}
+	return fromDomainRunResult(result), nil
+}

engine_test.go

@@ -0,0 +1,559 @@
+package scriptorium_test
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"os"
+	"path/filepath"
+	"reflect"
+	"strings"
+	"testing"
+
+	"gitea.maximumdirect.net/eric/scriptorium"
+)
+
+func TestNewEngineRejectsMissingPromptDir(t *testing.T) {
+	_, err := scriptorium.NewEngine(scriptorium.Config{ProfileDir: "./examples/profiles"})
+	if !errors.Is(err, scriptorium.ErrInvalidConfig) {
+		t.Fatalf("expected ErrInvalidConfig, got %v", err)
+	}
+}
+
+func TestNewEngineRejectsMissingProfileDir(t *testing.T) {
+	_, err := scriptorium.NewEngine(scriptorium.Config{PromptDir: "./examples/prompts"})
+	if !errors.Is(err, scriptorium.ErrInvalidConfig) {
+		t.Fatalf("expected ErrInvalidConfig, got %v", err)
+	}
+}
+
+func TestPrepareWorksWithExampleDirectoriesAndFileInputs(t *testing.T) {
+	engine := newExampleEngine(t)
+
+	prepared, err := engine.Prepare(context.Background(), scriptorium.RunRequest{
+		PromptID: "generic.markdown_summary",
+		Inputs: map[string]scriptorium.ArtifactRef{
+			"transcript": scriptorium.File("./examples/fixtures/transcript.md"),
+			"glossary":   scriptorium.File("./examples/fixtures/glossary.yml"),
+		},
+	})
+	if err != nil {
+		t.Fatalf("expected prepare to succeed, got %v", err)
+	}
+	if prepared.PromptID != "generic.markdown_summary" {
+		t.Fatalf("unexpected prompt id: %q", prepared.PromptID)
+	}
+	if prepared.SelectedProfileID != "local-fast" {
+		t.Fatalf("unexpected selected profile: %q", prepared.SelectedProfileID)
+	}
+	if prepared.EffectiveModelParams.Model != "gpt-4o-mini" {
+		t.Fatalf("unexpected effective model: %q", prepared.EffectiveModelParams.Model)
+	}
+	if len(prepared.Messages) != 2 {
+		t.Fatalf("expected rendered messages, got %d", len(prepared.Messages))
+	}
+	if prepared.InputHashes["transcript"] == "" || prepared.InputHashes["glossary"] == "" {
+		t.Fatalf("expected input hashes, got %#v", prepared.InputHashes)
+	}
+}
+
+func TestPrepareWorksWithInlineInputs(t *testing.T) {
+	engine := newExampleEngine(t)
+
+	prepared, err := engine.Prepare(context.Background(), scriptorium.RunRequest{
+		PromptID: "generic.markdown_summary",
+		Inputs: map[string]scriptorium.ArtifactRef{
+			"transcript": scriptorium.Inline("Rin scouts the tower.\nKara lights a lantern."),
+			"glossary":   scriptorium.InlineWithURI("memory://glossary.yml", "party:\n  - Rin\n  - Kara\n"),
+		},
+	})
+	if err != nil {
+		t.Fatalf("expected prepare to succeed, got %v", err)
+	}
+	if len(prepared.Messages) != 2 {
+		t.Fatalf("expected rendered messages, got %d", len(prepared.Messages))
+	}
+	rendered := prepared.Messages[1].Content
+	if !strings.Contains(rendered, "Rin scouts the tower.") || !strings.Contains(rendered, "party:") {
+		t.Fatalf("expected inline inputs in rendered prompt, got %q", rendered)
+	}
+}
+
+func TestPreparedRunJSONDoesNotExposeSecretOrTargetPresence(t *testing.T) {
+	const envName = "SCRIPTORIUM_API_KEY"
+	const secret = "public-api-test-secret"
+	t.Setenv(envName, secret)
+
+	engine := newExampleEngine(t)
+	prepared, err := engine.Prepare(context.Background(), scriptorium.RunRequest{
+		PromptID: "generic.structured_events",
+		Inputs: map[string]scriptorium.ArtifactRef{
+			"transcript": scriptorium.File("./examples/fixtures/transcript.md"),
+			"glossary":   scriptorium.File("./examples/fixtures/glossary.yml"),
+		},
+	})
+	if err != nil {
+		t.Fatalf("expected prepare to succeed, got %v", err)
+	}
+
+	payload, err := json.Marshal(prepared)
+	if err != nil {
+		t.Fatalf("expected prepared run to marshal, got %v", err)
+	}
+	out := string(payload)
+	if strings.Contains(out, secret) {
+		t.Fatalf("prepared run JSON leaked raw API key value: %s", out)
+	}
+	if !strings.Contains(out, envName) {
+		t.Fatalf("prepared run JSON should retain api_key_env name, got %s", out)
+	}
+	for _, forbidden := range []string{"TargetPresence", "target_presence"} {
+		if strings.Contains(out, forbidden) {
+			t.Fatalf("prepared run JSON exposed internal target presence metadata %q: %s", forbidden, out)
+		}
+	}
+}
+
+func TestPreparePreservesExplicitZeroExecutionOverrides(t *testing.T) {
+	engine := newExampleEngine(t)
+	zeroFloat := 0.0
+	zeroInt := 0
+
+	prepared, err := engine.Prepare(context.Background(), scriptorium.RunRequest{
+		PromptID: "generic.markdown_summary",
+		Inputs: map[string]scriptorium.ArtifactRef{
+			"transcript": scriptorium.File("./examples/fixtures/transcript.md"),
+			"glossary":   scriptorium.File("./examples/fixtures/glossary.yml"),
+		},
+		Execution: &scriptorium.ExecutionTargetOverride{
+			Temperature:    &zeroFloat,
+			MaxTokens:      &zeroInt,
+			TopP:           &zeroFloat,
+			TimeoutSeconds: &zeroInt,
+		},
+	})
+	if err != nil {
+		t.Fatalf("expected prepare to succeed, got %v", err)
+	}
+	target := prepared.EffectiveModelParams
+	if target.Temperature != 0 || target.MaxTokens != 0 || target.TopP != 0 || target.TimeoutSeconds != 0 {
+		t.Fatalf("expected explicit zero overrides in effective target, got %+v", target)
+	}
+}
+
+func TestRunSucceedsWithInjectedLLMClient(t *testing.T) {
+	const envName = "SCRIPTORIUM_API_KEY"
+	const secret = "run-secret-value"
+	t.Setenv(envName, secret)
+
+	fake := &fakeLLMClient{
+		response: &scriptorium.GenerateResponse{
+			Content: "# Summary\n\nDone.",
+			Usage: scriptorium.TokenUsage{
+				PromptTokens:     10,
+				CompletionTokens: 5,
+				TotalTokens:      15,
+				CachedTokens:     3,
+				CacheWriteTokens: 2,
+			},
+		},
+	}
+	engine := newExampleEngineWithOptions(t, "./examples/schemas", scriptorium.WithLLMClient(fake))
+
+	result, err := engine.Run(context.Background(), scriptorium.RunRequest{
+		PromptID: "generic.markdown_summary",
+		Inputs: map[string]scriptorium.ArtifactRef{
+			"transcript": scriptorium.Inline("Rin opens the gate."),
+			"glossary":   scriptorium.Inline("gate: A guarded passage."),
+		},
+		Execution: &scriptorium.ExecutionTargetOverride{
+			APIKeyEnv: envName,
+		},
+	})
+	if err != nil {
+		t.Fatalf("expected run to succeed, got %v", err)
+	}
+	if result.RunID == "" {
+		t.Fatalf("expected run id")
+	}
+	if result.RawOutput != fake.response.Content {
+		t.Fatalf("unexpected raw output: %q", result.RawOutput)
+	}
+	if string(result.Artifact.Body) != fake.response.Content {
+		t.Fatalf("unexpected artifact body: %q", string(result.Artifact.Body))
+	}
+	if result.Artifact.ContentType != "text/markdown" {
+		t.Fatalf("unexpected artifact content type: %q", result.Artifact.ContentType)
+	}
+	if result.Validation.Status != scriptorium.ValidationPassed || !result.Validation.IsValid {
+		t.Fatalf("expected passed validation, got %+v", result.Validation)
+	}
+	if result.PromptID != "generic.markdown_summary" || result.SelectedProfileID != "local-fast" || result.ModelName != "gpt-4o-mini" {
+		t.Fatalf("unexpected run metadata: %+v", result)
+	}
+	if result.Usage.TotalTokens != 15 || result.Usage.CachedTokens != 3 || result.Usage.CacheWriteTokens != 2 {
+		t.Fatalf("unexpected usage: %+v", result.Usage)
+	}
+
+	payload, err := json.Marshal(result)
+	if err != nil {
+		t.Fatalf("expected run result to marshal, got %v", err)
+	}
+	if strings.Contains(string(payload), secret) {
+		t.Fatalf("run result JSON leaked raw API key value: %s", payload)
+	}
+}
+
+func TestRunPassesPreparedRequestToInjectedLLMClient(t *testing.T) {
+	fake := &fakeLLMClient{
+		response: &scriptorium.GenerateResponse{Content: "ok"},
+	}
+	engine := newExampleEngineWithOptions(t, "./examples/schemas", scriptorium.WithLLMClient(fake))
+	zeroFloat := 0.0
+	zeroInt := 0
+
+	_, err := engine.Run(context.Background(), scriptorium.RunRequest{
+		PromptID: "generic.markdown_summary",
+		Inputs: map[string]scriptorium.ArtifactRef{
+			"transcript": scriptorium.Inline("Rin opens the gate."),
+			"glossary":   scriptorium.Inline("gate: A guarded passage."),
+		},
+		Execution: &scriptorium.ExecutionTargetOverride{
+			Temperature:    &zeroFloat,
+			MaxTokens:      &zeroInt,
+			TopP:           &zeroFloat,
+			TimeoutSeconds: &zeroInt,
+		},
+	})
+	if err != nil {
+		t.Fatalf("expected run to succeed, got %v", err)
+	}
+	if len(fake.requests) != 1 {
+		t.Fatalf("expected one generate request, got %d", len(fake.requests))
+	}
+	req := fake.requests[0]
+	if len(req.Prompt.Messages) != 2 || !strings.Contains(req.Prompt.Messages[1].Content, "Rin opens the gate.") {
+		t.Fatalf("expected rendered prompt in generate request, got %+v", req.Prompt)
+	}
+	if req.Target.Model != "gpt-4o-mini" || req.Target.Temperature != 0 || req.Target.MaxTokens != 0 || req.Target.TopP != 0 || req.Target.TimeoutSeconds != 0 {
+		t.Fatalf("unexpected effective target: %+v", req.Target)
+	}
+	if !req.TargetPresence.Temperature || !req.TargetPresence.MaxTokens || !req.TargetPresence.TopP || !req.TargetPresence.TimeoutSeconds {
+		t.Fatalf("expected explicit zero target presence, got %+v", req.TargetPresence)
+	}
+	if req.StructuredOutput != nil {
+		t.Fatalf("did not expect structured output for markdown prompt: %+v", req.StructuredOutput)
+	}
+}
+
+func TestRunValidationFailureReturnsResult(t *testing.T) {
+	fake := &fakeLLMClient{
+		response: &scriptorium.GenerateResponse{Content: ""},
+	}
+	engine := newExampleEngineWithOptions(t, "./examples/schemas", scriptorium.WithLLMClient(fake))
+
+	result, err := engine.Run(context.Background(), scriptorium.RunRequest{
+		PromptID: "generic.markdown_summary",
+		Inputs: map[string]scriptorium.ArtifactRef{
+			"transcript": scriptorium.Inline("Rin opens the gate."),
+			"glossary":   scriptorium.Inline("gate: A guarded passage."),
+		},
+	})
+	if err != nil {
+		t.Fatalf("expected validation failure as successful result, got %v", err)
+	}
+	if result.Validation.Status != scriptorium.ValidationFailed || result.Validation.IsValid {
+		t.Fatalf("expected failed validation result, got %+v", result.Validation)
+	}
+	if len(result.Validation.Errors) == 0 {
+		t.Fatalf("expected validation errors")
+	}
+}
+
+func TestPublicErrorsSupportErrorsIs(t *testing.T) {
+	llmErr := errors.New("llm failed")
+
+	tests := []struct {
+		name      string
+		req       scriptorium.RunRequest
+		client    scriptorium.LLMClient
+		schemaDir string
+		want      error
+	}{
+		{
+			name:   "invalid request",
+			req:    scriptorium.RunRequest{},
+			client: &fakeLLMClient{response: &scriptorium.GenerateResponse{Content: "ok"}},
+			want:   scriptorium.ErrInvalidRequest,
+		},
+		{
+			name:   "prompt not found",
+			req:    scriptorium.RunRequest{PromptID: "missing.prompt"},
+			client: &fakeLLMClient{response: &scriptorium.GenerateResponse{Content: "ok"}},
+			want:   scriptorium.ErrPromptNotFound,
+		},
+		{
+			name: "profile not found",
+			req: scriptorium.RunRequest{
+				PromptID:  "generic.markdown_summary",
+				ProfileID: "missing-profile",
+				Inputs: map[string]scriptorium.ArtifactRef{
+					"transcript": scriptorium.Inline("Rin opens the gate."),
+				},
+			},
+			client: &fakeLLMClient{response: &scriptorium.GenerateResponse{Content: "ok"}},
+			want:   scriptorium.ErrProfileNotFound,
+		},
+		{
+			name: "artifact load",
+			req: scriptorium.RunRequest{
+				PromptID: "generic.markdown_summary",
+				Inputs: map[string]scriptorium.ArtifactRef{
+					"transcript": scriptorium.File("./examples/fixtures/does-not-exist.md"),
+				},
+			},
+			client: &fakeLLMClient{response: &scriptorium.GenerateResponse{Content: "ok"}},
+			want:   scriptorium.ErrArtifactLoad,
+		},
+		{
+			name: "prompt render",
+			req: scriptorium.RunRequest{
+				PromptID: "generic.markdown_summary",
+			},
+			client: &fakeLLMClient{response: &scriptorium.GenerateResponse{Content: "ok"}},
+			want:   scriptorium.ErrPromptRender,
+		},
+		{
+			name: "llm failure",
+			req: scriptorium.RunRequest{
+				PromptID: "generic.markdown_summary",
+				Inputs: map[string]scriptorium.ArtifactRef{
+					"transcript": scriptorium.Inline("Rin opens the gate."),
+					"glossary":   scriptorium.Inline("gate: A guarded passage."),
+				},
+			},
+			client: &fakeLLMClient{err: llmErr},
+			want:   scriptorium.ErrLLMGenerate,
+		},
+		{
+			name: "validation runtime failure",
+			req: scriptorium.RunRequest{
+				PromptID: "generic.structured_events",
+				Inputs: map[string]scriptorium.ArtifactRef{
+					"transcript": scriptorium.Inline("Rin opens the gate."),
+				},
+			},
+			client:    &fakeLLMClient{response: &scriptorium.GenerateResponse{Content: `{"events":[]}`}},
+			schemaDir: t.TempDir(),
+			want:      scriptorium.ErrValidation,
+		},
+	}
+
+	t.Setenv("SCRIPTORIUM_API_KEY", "test-secret")
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			schemaDir := tc.schemaDir
+			if schemaDir == "" {
+				schemaDir = "./examples/schemas"
+			}
+			engine := newExampleEngineWithOptions(t, schemaDir, scriptorium.WithLLMClient(tc.client))
+			_, err := engine.Run(context.Background(), tc.req)
+			if !errors.Is(err, tc.want) {
+				t.Fatalf("expected errors.Is(%v), got %v", tc.want, err)
+			}
+		})
+	}
+}
+
+func TestSelectedProfileRawAPIKeyMapsToProfileLoad(t *testing.T) {
+	profileDir := t.TempDir()
+	if err := os.WriteFile(filepath.Join(profileDir, "raw.yaml"), []byte(`
+id: raw-profile
+endpoint: http://localhost:8000/v1
+model: model
+api_key: secret
+`), 0644); err != nil {
+		t.Fatal(err)
+	}
+
+	engine, err := scriptorium.NewEngine(scriptorium.Config{
+		PromptDir:  "./examples/prompts",
+		ProfileDir: profileDir,
+		SchemaDir:  "./examples/schemas",
+	})
+	if err != nil {
+		t.Fatalf("expected engine construction to succeed, got %v", err)
+	}
+
+	_, err = engine.Prepare(context.Background(), scriptorium.RunRequest{
+		PromptID:  "generic.markdown_summary",
+		ProfileID: "raw-profile",
+		Inputs: map[string]scriptorium.ArtifactRef{
+			"transcript": scriptorium.Inline("Rin opens the gate."),
+			"glossary":   scriptorium.Inline("gate: A guarded passage."),
+		},
+	})
+	if !errors.Is(err, scriptorium.ErrProfileLoad) {
+		t.Fatalf("expected ErrProfileLoad, got %v", err)
+	}
+	if errors.Is(err, scriptorium.ErrPromptLoad) {
+		t.Fatalf("did not expect ErrPromptLoad, got %v", err)
+	}
+}
+
+func TestSelectedProfileInvalidYAMLMapsToProfileLoad(t *testing.T) {
+	profileDir := t.TempDir()
+	if err := os.WriteFile(filepath.Join(profileDir, "broken.yaml"), []byte(`
+id: broken-profile
+unknown_field: true
+`), 0644); err != nil {
+		t.Fatal(err)
+	}
+
+	engine, err := scriptorium.NewEngine(scriptorium.Config{
+		PromptDir:  "./examples/prompts",
+		ProfileDir: profileDir,
+		SchemaDir:  "./examples/schemas",
+	})
+	if err != nil {
+		t.Fatalf("expected engine construction to succeed, got %v", err)
+	}
+
+	_, err = engine.Prepare(context.Background(), scriptorium.RunRequest{
+		PromptID:  "generic.markdown_summary",
+		ProfileID: "broken-profile",
+		Inputs: map[string]scriptorium.ArtifactRef{
+			"transcript": scriptorium.Inline("Rin opens the gate."),
+			"glossary":   scriptorium.Inline("gate: A guarded passage."),
+		},
+	})
+	if !errors.Is(err, scriptorium.ErrProfileLoad) {
+		t.Fatalf("expected ErrProfileLoad, got %v", err)
+	}
+	if errors.Is(err, scriptorium.ErrPromptLoad) {
+		t.Fatalf("did not expect ErrPromptLoad, got %v", err)
+	}
+}
+
+func TestExtraParamsTypedNestedValuesAreCopiedAcrossPublicBoundary(t *testing.T) {
+	fake := &fakeLLMClient{response: &scriptorium.GenerateResponse{Content: "ok"}}
+	engine := newExampleEngineWithOptions(t, "./examples/schemas", scriptorium.WithLLMClient(fake))
+
+	labels := map[string]string{"route": "primary"}
+	counts := map[string]int{"retry_budget": 2}
+	weights := []float64{0.25, 0.75}
+	ids := []int{1, 2, 3}
+	nested := map[string]any{
+		"labels":  labels,
+		"counts":  counts,
+		"weights": weights,
+		"ids":     ids,
+	}
+	extraParams := map[string]any{
+		"labels": labels,
+		"counts": counts,
+		"nested": nested,
+	}
+
+	_, err := engine.Run(context.Background(), scriptorium.RunRequest{
+		PromptID: "generic.markdown_summary",
+		Inputs: map[string]scriptorium.ArtifactRef{
+			"transcript": scriptorium.Inline("Rin opens the gate."),
+			"glossary":   scriptorium.Inline("gate: A guarded passage."),
+		},
+		Execution: &scriptorium.ExecutionTargetOverride{ExtraParams: extraParams},
+	})
+	if err != nil {
+		t.Fatalf("expected run to succeed, got %v", err)
+	}
+	if len(fake.requests) != 1 {
+		t.Fatalf("expected one generate request, got %d", len(fake.requests))
+	}
+
+	captured := fake.requests[0].Target.ExtraParams
+	labels["route"] = "mutated"
+	counts["retry_budget"] = 99
+	weights[0] = 9.9
+	ids[0] = 99
+	nested["added"] = "mutated"
+	extraParams["new_top_level"] = "mutated"
+
+	want := map[string]any{
+		"labels": map[string]string{"route": "primary"},
+		"counts": map[string]int{"retry_budget": 2},
+		"nested": map[string]any{
+			"labels":  map[string]string{"route": "primary"},
+			"counts":  map[string]int{"retry_budget": 2},
+			"weights": []float64{0.25, 0.75},
+			"ids":     []int{1, 2, 3},
+		},
+	}
+	if !reflect.DeepEqual(captured, want) {
+		t.Fatalf("captured extra_params changed after mutating source:\ngot=%#v\nwant=%#v", captured, want)
+	}
+}
+
+func TestWithLLMClientRejectsNilClient(t *testing.T) {
+	_, err := scriptorium.NewEngine(exampleConfig("./examples/schemas"), scriptorium.WithLLMClient(nil))
+	if !errors.Is(err, scriptorium.ErrInvalidConfig) {
+		t.Fatalf("expected ErrInvalidConfig, got %v", err)
+	}
+}
+
+func TestNewEngineConstructsDefaultLLMClientWithoutCredentials(t *testing.T) {
+	if _, err := scriptorium.NewEngine(exampleConfig("./examples/schemas")); err != nil {
+		t.Fatalf("expected default engine construction without credentials to succeed, got %v", err)
+	}
+}
+
+func newExampleEngine(t *testing.T) *scriptorium.Engine {
+	t.Helper()
+
+	for _, path := range []string{
+		"./examples/prompts",
+		"./examples/profiles",
+		"./examples/schemas",
+	} {
+		if _, err := os.Stat(path); err != nil {
+			t.Fatalf("expected example path %s to exist: %v", path, err)
+		}
+	}
+
+	engine, err := scriptorium.NewEngine(exampleConfig("./examples/schemas"))
+	if err != nil {
+		t.Fatalf("expected engine construction to succeed, got %v", err)
+	}
+	return engine
+}
+
+func newExampleEngineWithOptions(t *testing.T, schemaDir string, opts ...scriptorium.Option) *scriptorium.Engine {
+	t.Helper()
+
+	engine, err := scriptorium.NewEngine(exampleConfig(schemaDir), opts...)
+	if err != nil {
+		t.Fatalf("expected engine construction to succeed, got %v", err)
+	}
+	return engine
+}
+
+func exampleConfig(schemaDir string) scriptorium.Config {
+	return scriptorium.Config{
+		PromptDir:  "./examples/prompts",
+		ProfileDir: "./examples/profiles",
+		SchemaDir:  schemaDir,
+	}
+}
+
+type fakeLLMClient struct {
+	response *scriptorium.GenerateResponse
+	err      error
+	requests []scriptorium.GenerateRequest
+}
+
+func (f *fakeLLMClient) Generate(_ context.Context, req scriptorium.GenerateRequest) (*scriptorium.GenerateResponse, error) {
+	f.requests = append(f.requests, req)
+	if f.err != nil {
+		return nil, f.err
+	}
+	return f.response, nil
+}

errors.go

@@ -0,0 +1,77 @@
+package scriptorium
+
+import (
+	"errors"
+	"fmt"
+
+	"gitea.maximumdirect.net/eric/scriptorium/internal/profile"
+	"gitea.maximumdirect.net/eric/scriptorium/internal/promptdef"
+	"gitea.maximumdirect.net/eric/scriptorium/internal/usecase"
+)
+
+func mapPublicError(err error) error {
+	if err == nil {
+		return nil
+	}
+	if hasPublicError(err) {
+		return err
+	}
+	publicErr := publicErrorFor(err)
+	if publicErr == nil {
+		return err
+	}
+	return fmt.Errorf("%w: %w", publicErr, err)
+}
+
+func hasPublicError(err error) bool {
+	for _, publicErr := range []error{
+		ErrInvalidConfig,
+		ErrInvalidRequest,
+		ErrPromptNotFound,
+		ErrProfileNotFound,
+		ErrPromptLoad,
+		ErrProfileLoad,
+		ErrArtifactLoad,
+		ErrPromptRender,
+		ErrLLMGenerate,
+		ErrValidation,
+	} {
+		if errors.Is(err, publicErr) {
+			return true
+		}
+	}
+	return false
+}
+
+func publicErrorFor(err error) error {
+	switch {
+	case errors.Is(err, promptdef.ErrPromptDefinitionNotFound):
+		return ErrPromptNotFound
+	case errors.Is(err, profile.ErrProfileNotFound):
+		return ErrProfileNotFound
+	case errors.Is(err, promptdef.ErrInvalidYAML), errors.Is(err, promptdef.ErrInvalidPromptDefinition):
+		return ErrPromptLoad
+	case isProfileLoadCause(err):
+		return ErrProfileLoad
+	case errors.Is(err, usecase.ErrArtifactLoad):
+		return ErrArtifactLoad
+	case errors.Is(err, usecase.ErrPromptRender):
+		return ErrPromptRender
+	case errors.Is(err, usecase.ErrLLMGenerate):
+		return ErrLLMGenerate
+	case errors.Is(err, usecase.ErrValidation):
+		return ErrValidation
+	case errors.Is(err, usecase.ErrInvalidRequest):
+		return ErrInvalidRequest
+	case errors.Is(err, usecase.ErrProfileLoad):
+		return ErrPromptLoad
+	default:
+		return nil
+	}
+}
+
+func isProfileLoadCause(err error) bool {
+	return errors.Is(err, profile.ErrInvalidYAML) ||
+		errors.Is(err, profile.ErrInvalidProfile) ||
+		errors.Is(err, profile.ErrRawAPIKeyNotAllowed)
+}

examples/go-library/prepare/main.go

@@ -0,0 +1,50 @@
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"log"
+	"os"
+
+	"gitea.maximumdirect.net/eric/scriptorium"
+)
+
+func main() {
+	engine, err := scriptorium.NewEngine(scriptorium.Config{
+		PromptDir:  "./examples/prompts",
+		ProfileDir: "./examples/profiles",
+		SchemaDir:  "./examples/schemas",
+	})
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	prepared, err := engine.Prepare(context.Background(), scriptorium.RunRequest{
+		PromptID: "generic.markdown_summary",
+		Inputs: map[string]scriptorium.ArtifactRef{
+			"transcript": scriptorium.File("./examples/fixtures/transcript.md"),
+			"glossary":   scriptorium.File("./examples/fixtures/glossary.yml"),
+		},
+	})
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	summary := struct {
+		PromptID          string            `json:"prompt_id"`
+		SelectedProfileID string            `json:"selected_profile_id"`
+		Model             string            `json:"model"`
+		MessageCount      int               `json:"message_count"`
+		InputHashes       map[string]string `json:"input_hashes"`
+	}{
+		PromptID:          prepared.PromptID,
+		SelectedProfileID: prepared.SelectedProfileID,
+		Model:             prepared.EffectiveModelParams.Model,
+		MessageCount:      len(prepared.Messages),
+		InputHashes:       prepared.InputHashes,
+	}
+
+	if err := json.NewEncoder(os.Stdout).Encode(summary); err != nil {
+		log.Fatal(err)
+	}
+}

internal/adapter/cli/run.go

@@ -513,18 +513,25 @@ func buildRunRequestFromConfig(cfg *runConfig) (domain.RunRequest, error) {
 		inputs[name] = domain.ArtifactRef{Type: domain.ArtifactRefFile, URI: path}
 	}
 
-	var modelOverride *domain.ExecutionTarget
+	var modelOverride *domain.ExecutionTargetOverride
 	if cfg.llmBaseURLSet || cfg.modelSet || cfg.temperatureSet || cfg.maxTokensSet || cfg.topPSet || cfg.apiKeyEnvSet || cfg.timeoutSet {
-		modelOverride = &domain.ExecutionTarget{
-			Endpoint:    cfg.llmBaseURL,
-			Model:       cfg.model,
-			Temperature: cfg.temperature,
-			MaxTokens:   cfg.maxTokens,
-			TopP:        cfg.topP,
-			APIKeyEnv:   cfg.apiKeyEnv,
+		modelOverride = &domain.ExecutionTargetOverride{
+			Endpoint:  cfg.llmBaseURL,
+			Model:     cfg.model,
+			APIKeyEnv: cfg.apiKeyEnv,
+		}
+		if cfg.temperatureSet {
+			modelOverride.Temperature = &cfg.temperature
+		}
+		if cfg.maxTokensSet {
+			modelOverride.MaxTokens = &cfg.maxTokens
+		}
+		if cfg.topPSet {
+			modelOverride.TopP = &cfg.topP
 		}
 		if cfg.timeoutSet {
-			modelOverride.TimeoutSeconds = int(cfg.timeout.Seconds())
+			timeoutSeconds := int(cfg.timeout.Seconds())
+			modelOverride.TimeoutSeconds = &timeoutSeconds
 		}
 	}
 
@@ -606,7 +613,7 @@ func printSummary(stderr io.Writer, res *domain.RunResult) {
 	if res == nil {
 		return
 	}
-	fmt.Fprintf(stderr, "prompt=%s@%s selected_profile=%s model=%s validation=%s mode=%s validation_errors=%d prompt_hash=%s inputs=%d usage=%d/%d/%d\n",
+	fmt.Fprintf(stderr, "prompt=%s@%s selected_profile=%s model=%s validation=%s mode=%s validation_errors=%d prompt_hash=%s inputs=%d usage=%d/%d/%d",
 		res.PromptID,
 		res.PromptVersion,
 		res.SelectedProfileID,
@@ -620,6 +627,10 @@ func printSummary(stderr io.Writer, res *domain.RunResult) {
 		res.Usage.CompletionTokens,
 		res.Usage.TotalTokens,
 	)
+	if res.Usage.CachedTokens != 0 || res.Usage.CacheWriteTokens != 0 {
+		fmt.Fprintf(stderr, " cached_tokens=%d cache_write_tokens=%d", res.Usage.CachedTokens, res.Usage.CacheWriteTokens)
+	}
+	fmt.Fprintln(stderr)
 }
 
 func printUsage(w io.Writer) {

internal/adapter/cli/run_test.go

@@ -747,6 +747,35 @@ func TestRenderCommandDefaultFormatTextIncludesPreparedDetailsAndNoSecrets(t *te
 	}
 }
 
+func TestRenderCommandExplicitZeroTemperatureReachesEffectiveSettings(t *testing.T) {
+	lib := newCLITestLibrary(t)
+	inputPath := lib.writeInputFile(t, "transcript.md", "hello transcript")
+
+	writePromptFile(t, lib.promptDir, "prompt.render", "local-default")
+	profile := `id: local-default
+endpoint: http://127.0.0.1:1/v1
+model: profile-model
+temperature: 0.7
+`
+	if err := os.WriteFile(filepath.Join(lib.profileDir, "local-default.yaml"), []byte(profile), 0o644); err != nil {
+		t.Fatalf("failed to write profile fixture: %v", err)
+	}
+
+	code, stdout, stderr := runCLICommand(t, renderCommand, []string{
+		"--prompt-dir", lib.promptDir,
+		"--profile-dir", lib.profileDir,
+		"--prompt", "prompt.render",
+		"--input", "transcript=" + inputPath,
+		"--temperature", "0",
+	})
+	if code != ExitOK {
+		t.Fatalf("expected ExitOK, got %d stderr=%q", code, stderr)
+	}
+	if !strings.Contains(stdout, "\n  temperature: 0\n") {
+		t.Fatalf("expected explicit zero temperature in effective settings, got:\n%s", stdout)
+	}
+}
+
 func TestRenderCommandSucceedsWithPromptAndProfileDirsFromConfig(t *testing.T) {
 	lib := newCLITestLibrary(t)
 	inputPath := lib.writeInputFile(t, "transcript.md", "hello transcript")
@@ -1064,6 +1093,38 @@ func TestWriteOutputAndSummaryUseSeparateWriters(t *testing.T) {
 	if !strings.Contains(stderr.String(), "prompt=p@1") {
 		t.Fatalf("expected summary on stderr, got %q", stderr.String())
 	}
+	if strings.Contains(stderr.String(), "cached_tokens=") || strings.Contains(stderr.String(), "cache_write_tokens=") {
+		t.Fatalf("expected zero cache usage to be omitted from summary, got %q", stderr.String())
+	}
+}
+
+func TestPrintSummaryIncludesCacheUsageWhenPresent(t *testing.T) {
+	var stderr bytes.Buffer
+
+	printSummary(&stderr, &domain.RunResult{
+		PromptID:           "p",
+		PromptVersion:      "1",
+		SelectedProfileID:  "exec",
+		ModelName:          "m",
+		Validation:         domain.ValidationResult{Status: domain.ValidationPassed, Mode: domain.ValidationBasic},
+		RenderedPromptHash: "h",
+		InputHashes:        map[string]string{"in": "x"},
+		Usage: domain.TokenUsage{
+			PromptTokens:     10,
+			CompletionTokens: 5,
+			TotalTokens:      15,
+			CachedTokens:     0,
+			CacheWriteTokens: 3,
+		},
+	})
+
+	summary := stderr.String()
+	if !strings.Contains(summary, "usage=10/5/15") {
+		t.Fatalf("expected base usage summary, got %q", summary)
+	}
+	if !strings.Contains(summary, "cached_tokens=0 cache_write_tokens=3") {
+		t.Fatalf("expected cache usage in summary, got %q", summary)
+	}
 }
 
 type cliTestLibrary struct {

internal/adapter/http/dto.go

@@ -21,16 +21,16 @@ type inputRefDTO struct {
 }
 
 type modelOverrideRequestDTO struct {
-	Endpoint        string            `json:"endpoint,omitempty"`
-	Model           string            `json:"model,omitempty"`
-	Temperature     float64           `json:"temperature,omitempty"`
-	MaxTokens       int               `json:"max_tokens,omitempty"`
-	TopP            float64           `json:"top_p,omitempty"`
-	TimeoutSeconds  int               `json:"timeout_seconds,omitempty"`
-	ServiceTier     string            `json:"service_tier,omitempty"`
-	ReasoningEffort string            `json:"reasoning_effort,omitempty"`
-	APIKeyEnv       string            `json:"api_key_env,omitempty"`
-	ExtraParams     map[string]string `json:"extra_params,omitempty"`
+	Endpoint        string         `json:"endpoint,omitempty"`
+	Model           string         `json:"model,omitempty"`
+	Temperature     *float64       `json:"temperature,omitempty"`
+	MaxTokens       *int           `json:"max_tokens,omitempty"`
+	TopP            *float64       `json:"top_p,omitempty"`
+	TimeoutSeconds  *int           `json:"timeout_seconds,omitempty"`
+	ServiceTier     string         `json:"service_tier,omitempty"`
+	ReasoningEffort string         `json:"reasoning_effort,omitempty"`
+	APIKeyEnv       string         `json:"api_key_env,omitempty"`
+	ExtraParams     map[string]any `json:"extra_params,omitempty"`
 }
 
 type runResponseDTO struct {
@@ -70,22 +70,24 @@ type metadataDTO struct {
 }
 
 type modelParamsDTO struct {
-	Endpoint        string            `json:"endpoint"`
-	Model           string            `json:"model"`
-	Temperature     float64           `json:"temperature"`
-	MaxTokens       int               `json:"max_tokens"`
-	TopP            float64           `json:"top_p"`
-	TimeoutSeconds  int               `json:"timeout_seconds"`
-	ServiceTier     string            `json:"service_tier,omitempty"`
-	ReasoningEffort string            `json:"reasoning_effort,omitempty"`
-	APIKeyEnv       string            `json:"api_key_env,omitempty"`
-	ExtraParams     map[string]string `json:"extra_params,omitempty"`
+	Endpoint        string         `json:"endpoint"`
+	Model           string         `json:"model"`
+	Temperature     float64        `json:"temperature"`
+	MaxTokens       int            `json:"max_tokens"`
+	TopP            float64        `json:"top_p"`
+	TimeoutSeconds  int            `json:"timeout_seconds"`
+	ServiceTier     string         `json:"service_tier,omitempty"`
+	ReasoningEffort string         `json:"reasoning_effort,omitempty"`
+	APIKeyEnv       string         `json:"api_key_env,omitempty"`
+	ExtraParams     map[string]any `json:"extra_params,omitempty"`
 }
 
 type tokenUsageDTO struct {
 	PromptTokens     int `json:"prompt_tokens"`
 	CompletionTokens int `json:"completion_tokens"`
 	TotalTokens      int `json:"total_tokens"`
+	CachedTokens     int `json:"cached_tokens"`
+	CacheWriteTokens int `json:"cache_write_tokens"`
 }
 
 type validationDTO struct {

internal/adapter/http/handler.go

@@ -61,9 +61,9 @@ func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 		}
 	}
 
-	var model *domain.ExecutionTarget
+	var model *domain.ExecutionTargetOverride
 	if req.Model != nil {
-		model = executionTargetFromModelOverrideDTO(req.Model)
+		model = executionTargetOverrideFromModelOverrideDTO(req.Model)
 	}
 
 	res, err := h.runner.Run(r.Context(), domain.RunRequest{
@@ -105,6 +105,8 @@ func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 				PromptTokens:     res.Usage.PromptTokens,
 				CompletionTokens: res.Usage.CompletionTokens,
 				TotalTokens:      res.Usage.TotalTokens,
+				CachedTokens:     res.Usage.CachedTokens,
+				CacheWriteTokens: res.Usage.CacheWriteTokens,
 			},
 			StartTime:          res.StartTime,
 			EndTime:            res.EndTime,
@@ -121,11 +123,11 @@ func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 	writeJSON(w, http.StatusOK, resp)
 }
 
-func executionTargetFromModelOverrideDTO(dto *modelOverrideRequestDTO) *domain.ExecutionTarget {
+func executionTargetOverrideFromModelOverrideDTO(dto *modelOverrideRequestDTO) *domain.ExecutionTargetOverride {
 	if dto == nil {
 		return nil
 	}
-	return &domain.ExecutionTarget{
+	return &domain.ExecutionTargetOverride{
 		Endpoint:        dto.Endpoint,
 		Model:           dto.Model,
 		Temperature:     dto.Temperature,

internal/adapter/http/handler_test.go

@@ -13,6 +13,7 @@ import (
 	"time"
 
 	"gitea.maximumdirect.net/eric/scriptorium/internal/domain"
+	"gitea.maximumdirect.net/eric/scriptorium/internal/llm"
 	"gitea.maximumdirect.net/eric/scriptorium/internal/profile"
 	"gitea.maximumdirect.net/eric/scriptorium/internal/promptdef"
 	"gitea.maximumdirect.net/eric/scriptorium/internal/usecase"
@@ -32,6 +33,34 @@ func (f *fakeRunner) Run(ctx context.Context, req domain.RunRequest) (*domain.Ru
 	return f.result, nil
 }
 
+type handlerPromptRepo struct {
+	def *domain.PromptDefinition
+}
+
+func (r handlerPromptRepo) GetPromptDefinition(ctx context.Context, id string, version string) (*domain.PromptDefinition, error) {
+	return r.def, nil
+}
+
+type handlerProfileRepo struct {
+	profile *domain.ExecutionProfile
+}
+
+func (r handlerProfileRepo) GetProfile(ctx context.Context, id string) (*domain.ExecutionProfile, error) {
+	return r.profile, nil
+}
+
+type handlerArtifactReader struct{}
+
+func (handlerArtifactReader) Read(ctx context.Context, ref domain.ArtifactRef) (*domain.Artifact, error) {
+	return &domain.Artifact{Name: "input", Body: []byte("input"), Hash: "hash"}, nil
+}
+
+type handlerRenderer struct{}
+
+func (handlerRenderer) Render(ctx context.Context, definition *domain.PromptDefinition, inputs map[string]*domain.Artifact, vars map[string]string) (*domain.RenderedPrompt, error) {
+	return &domain.RenderedPrompt{Messages: []domain.RenderedMessage{{Role: "user", Content: "hi"}}}, nil
+}
+
 func TestHandlerPostRunsSuccessWithExplicitProfileID(t *testing.T) {
 	start := time.Now().UTC()
 	end := start.Add(2 * time.Second)
@@ -66,11 +95,17 @@ func TestHandlerPostRunsSuccessWithExplicitProfileID(t *testing.T) {
 			APIKeyEnv:      envName,
 		},
 		InputHashes: map[string]string{"transcript": "h1"},
-		Usage:       domain.TokenUsage{PromptTokens: 1, CompletionTokens: 2, TotalTokens: 3},
-		StartTime:   start,
-		EndTime:     end,
-		Duration:    2 * time.Second,
-		RawOutput:   "hello",
+		Usage: domain.TokenUsage{
+			PromptTokens:     1,
+			CompletionTokens: 2,
+			TotalTokens:      3,
+			CachedTokens:     4,
+			CacheWriteTokens: 5,
+		},
+		StartTime: start,
+		EndTime:   end,
+		Duration:  2 * time.Second,
+		RawOutput: "hello",
 	}}
 
 	h := NewHandler(r)
@@ -111,6 +146,13 @@ func TestHandlerPostRunsSuccessWithExplicitProfileID(t *testing.T) {
 	if metadata["model_name"] != "m1" || metadata["endpoint"] != "http://llm/v1" {
 		t.Fatalf("unexpected model metadata: name=%#v endpoint=%#v", metadata["model_name"], metadata["endpoint"])
 	}
+	usage := metadata["usage"].(map[string]any)
+	if usage["prompt_tokens"] != float64(1) || usage["completion_tokens"] != float64(2) || usage["total_tokens"] != float64(3) {
+		t.Fatalf("unexpected base usage metadata: %#v", usage)
+	}
+	if usage["cached_tokens"] != float64(4) || usage["cache_write_tokens"] != float64(5) {
+		t.Fatalf("unexpected cache usage metadata: %#v", usage)
+	}
 	modelParams := metadata["model_params"].(map[string]any)
 	if modelParams["api_key_env"] != envName {
 		t.Fatalf("expected model_params.api_key_env=%q, got %#v", envName, modelParams["api_key_env"])
@@ -134,7 +176,7 @@ func TestHandlerPostRunsSuccessWithExplicitProfileID(t *testing.T) {
 	if r.last.Execution == nil || r.last.Execution.Model != "gpt-x" {
 		t.Fatalf("expected model override, got %#v", r.last.Execution)
 	}
-	if r.last.Execution.TimeoutSeconds != 120 {
+	if r.last.Execution.TimeoutSeconds == nil || *r.last.Execution.TimeoutSeconds != 120 {
 		t.Fatalf("expected timeout_seconds override 120, got %#v", r.last.Execution)
 	}
 	if r.last.Execution.ServiceTier != "flex" {
@@ -171,6 +213,10 @@ func TestHandlerPostRunsSuccessUsingPromptDefaultProfile(t *testing.T) {
 	if metadata["selected_profile_id"] != "prompt-default" {
 		t.Fatalf("expected selected_profile_id from result, got %#v", metadata["selected_profile_id"])
 	}
+	usage := metadata["usage"].(map[string]any)
+	if usage["cached_tokens"] != float64(0) || usage["cache_write_tokens"] != float64(0) {
+		t.Fatalf("expected zero cache usage fields to be included, got %#v", usage)
+	}
 }
 
 func TestHandlerModelOverrideMapsAllSupportedExecutionFields(t *testing.T) {
@@ -211,20 +257,136 @@ func TestHandlerModelOverrideMapsAllSupportedExecutionFields(t *testing.T) {
 	got := r.last.Execution
 	if got.Endpoint != "http://override/v1" ||
 		got.Model != "override-model" ||
-		got.Temperature != 0.6 ||
-		got.MaxTokens != 250 ||
-		got.TopP != 0.85 ||
-		got.TimeoutSeconds != 33 ||
 		got.ServiceTier != "flex" ||
 		got.ReasoningEffort != "medium" ||
 		got.APIKeyEnv != "SCRIPTORIUM_API_KEY" {
 		t.Fatalf("unexpected mapped execution target: %+v", got)
 	}
-	if !reflect.DeepEqual(got.ExtraParams, map[string]string{"provider_option": "on"}) {
+	if got.Temperature == nil || *got.Temperature != 0.6 {
+		t.Fatalf("unexpected mapped temperature: %#v", got.Temperature)
+	}
+	if got.MaxTokens == nil || *got.MaxTokens != 250 {
+		t.Fatalf("unexpected mapped max_tokens: %#v", got.MaxTokens)
+	}
+	if got.TopP == nil || *got.TopP != 0.85 {
+		t.Fatalf("unexpected mapped top_p: %#v", got.TopP)
+	}
+	if got.TimeoutSeconds == nil || *got.TimeoutSeconds != 33 {
+		t.Fatalf("unexpected mapped timeout_seconds: %#v", got.TimeoutSeconds)
+	}
+	if !reflect.DeepEqual(got.ExtraParams, map[string]any{"provider_option": "on"}) {
 		t.Fatalf("unexpected mapped extra_params: %#v", got.ExtraParams)
 	}
 }
 
+func TestHandlerModelOverrideAcceptsJSONCompatibleExtraParams(t *testing.T) {
+	r := &fakeRunner{result: &domain.RunResult{
+		Artifact:             domain.Artifact{Body: []byte("ok")},
+		Validation:           domain.ValidationResult{Status: domain.ValidationPassed, Mode: domain.ValidationBasic, IsValid: true},
+		EffectiveModelParams: domain.ExecutionTarget{Endpoint: "http://llm/v1", Model: "m1"},
+	}}
+	h := NewHandler(r)
+
+	reqBody := `{
+		"prompt_id": "prompt-1",
+		"inputs": {"transcript": {"type": "file", "uri": "./t.md"}},
+		"model": {
+			"extra_params": {
+				"string_value": "enabled",
+				"number_value": 42,
+				"boolean_value": true,
+				"object_value": {"nested": "value", "count": 2},
+				"array_value": ["first", 3, false]
+			}
+		}
+	}`
+	req := httptest.NewRequest(http.MethodPost, "/v1/runs", bytes.NewBufferString(reqBody))
+	w := httptest.NewRecorder()
+
+	h.ServeHTTP(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("expected 200, got %d body=%s", w.Code, w.Body.String())
+	}
+	if r.last.Execution == nil {
+		t.Fatal("expected execution override in run request")
+	}
+	want := map[string]any{
+		"string_value":  "enabled",
+		"number_value":  float64(42),
+		"boolean_value": true,
+		"object_value":  map[string]any{"nested": "value", "count": float64(2)},
+		"array_value":   []any{"first", float64(3), false},
+	}
+	if !reflect.DeepEqual(r.last.Execution.ExtraParams, want) {
+		t.Fatalf("unexpected mapped extra_params:\ngot=%#v\nwant=%#v", r.last.Execution.ExtraParams, want)
+	}
+}
+
+func TestHandlerModelOverrideExplicitZeroTemperatureMapsAsPresent(t *testing.T) {
+	r := &fakeRunner{result: &domain.RunResult{
+		Artifact:             domain.Artifact{Body: []byte("ok")},
+		Validation:           domain.ValidationResult{Status: domain.ValidationPassed, Mode: domain.ValidationBasic, IsValid: true},
+		EffectiveModelParams: domain.ExecutionTarget{Endpoint: "http://llm/v1", Model: "m1", Temperature: 0},
+	}}
+	h := NewHandler(r)
+
+	req := httptest.NewRequest(http.MethodPost, "/v1/runs", bytes.NewBufferString(`{
+		"prompt_id": "prompt-1",
+		"inputs": {"transcript": {"type": "file", "uri": "./t.md"}},
+		"model": {"temperature": 0}
+	}`))
+	w := httptest.NewRecorder()
+	h.ServeHTTP(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("expected 200, got %d body=%s", w.Code, w.Body.String())
+	}
+	if r.last.Execution == nil || r.last.Execution.Temperature == nil {
+		t.Fatalf("expected temperature override to be present, got %#v", r.last.Execution)
+	}
+	if *r.last.Execution.Temperature != 0 {
+		t.Fatalf("expected zero temperature override, got %v", *r.last.Execution.Temperature)
+	}
+}
+
+func TestHandlerModelOverrideOmittedTemperatureMapsAsAbsent(t *testing.T) {
+	r := &fakeRunner{result: &domain.RunResult{
+		Artifact:             domain.Artifact{Body: []byte("ok")},
+		Validation:           domain.ValidationResult{Status: domain.ValidationPassed, Mode: domain.ValidationBasic, IsValid: true},
+		EffectiveModelParams: domain.ExecutionTarget{Endpoint: "http://llm/v1", Model: "m1", Temperature: 0.7},
+	}}
+	h := NewHandler(r)
+
+	req := httptest.NewRequest(http.MethodPost, "/v1/runs", bytes.NewBufferString(`{
+		"prompt_id": "prompt-1",
+		"inputs": {"transcript": {"type": "file", "uri": "./t.md"}},
+		"model": {"model": "override-model"}
+	}`))
+	w := httptest.NewRecorder()
+	h.ServeHTTP(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("expected 200, got %d body=%s", w.Code, w.Body.String())
+	}
+	if r.last.Execution == nil {
+		t.Fatal("expected model override")
+	}
+	if r.last.Execution.Temperature != nil {
+		t.Fatalf("expected omitted temperature to remain absent, got %#v", r.last.Execution.Temperature)
+	}
+
+	var resp map[string]any
+	if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {
+		t.Fatalf("invalid JSON response: %v", err)
+	}
+	metadata := resp["metadata"].(map[string]any)
+	params := metadata["model_params"].(map[string]any)
+	if params["temperature"] != 0.7 {
+		t.Fatalf("expected effective profile/default temperature in response, got %#v", params["temperature"])
+	}
+}
+
 func TestHandlerResponseMetadataModelParamsIncludesAllSupportedFields(t *testing.T) {
 	r := &fakeRunner{result: &domain.RunResult{
 		Artifact: domain.Artifact{
@@ -245,8 +407,10 @@ func TestHandlerResponseMetadataModelParamsIncludesAllSupportedFields(t *testing
 			ServiceTier:     "priority",
 			ReasoningEffort: "high",
 			APIKeyEnv:       "SCRIPTORIUM_API_KEY",
-			ExtraParams: map[string]string{
+			ExtraParams: map[string]any{
 				"provider_option": "on",
+				"number_value":    42,
+				"object_value":    map[string]any{"nested": "value"},
 			},
 		},
 	}}
@@ -301,6 +465,13 @@ func TestHandlerResponseMetadataModelParamsIncludesAllSupportedFields(t *testing
 	if extraParams["provider_option"] != "on" {
 		t.Fatalf("unexpected extra_params.provider_option: %#v", extraParams["provider_option"])
 	}
+	if extraParams["number_value"] != float64(42) {
+		t.Fatalf("unexpected extra_params.number_value: %#v", extraParams["number_value"])
+	}
+	objectValue, ok := extraParams["object_value"].(map[string]any)
+	if !ok || objectValue["nested"] != "value" {
+		t.Fatalf("unexpected extra_params.object_value: %#v", extraParams["object_value"])
+	}
 }
 
 func TestHandlerInvalidJSON(t *testing.T) {
@@ -335,6 +506,54 @@ func TestHandlerMissingPromptID(t *testing.T) {
 	}
 }
 
+func TestHandlerReservedExtraParamsThroughRunnerMapsToInvalidRequest(t *testing.T) {
+	llmClient, err := llm.NewOpenAICompatibleClient(llm.OpenAICompatibleConfig{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	runner := usecase.NewRunner(
+		handlerPromptRepo{def: &domain.PromptDefinition{
+			ID:             "p",
+			Version:        "1",
+			DefaultProfile: "exec",
+			Templates:      []domain.PromptMessageTemplate{{Role: "user", Content: "hi"}},
+			OutputFormat:   domain.FormatText,
+			Validation:     domain.OutputContract{Format: domain.FormatText, ValidationMode: domain.ValidationNone},
+		}},
+		handlerProfileRepo{profile: &domain.ExecutionProfile{
+			ID:       "exec",
+			Endpoint: "http://example.invalid/v1",
+			Model:    "model",
+		}},
+		handlerArtifactReader{},
+		handlerRenderer{},
+		llmClient,
+		nil,
+	)
+	h := NewHandler(runner)
+
+	req := httptest.NewRequest(http.MethodPost, "/v1/runs", bytes.NewBufferString(`{
+		"prompt_id":"p",
+		"inputs":{"x":{"type":"file","uri":"a"}},
+		"model":{"extra_params":{"model":"collision"}}
+	}`))
+	w := httptest.NewRecorder()
+
+	h.ServeHTTP(w, req)
+
+	if w.Code != http.StatusBadRequest {
+		t.Fatalf("expected 400, got %d body=%s", w.Code, w.Body.String())
+	}
+	var resp map[string]any
+	if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {
+		t.Fatalf("invalid JSON response: %v", err)
+	}
+	errBody := resp["error"].(map[string]any)
+	if errBody["code"] != "invalid_request" {
+		t.Fatalf("expected invalid_request code, got %#v", errBody["code"])
+	}
+}
+
 func TestHandlerUsecaseErrorMapping(t *testing.T) {
 	tests := []struct {
 		name       string

internal/domain/domain.go

@@ -40,6 +40,24 @@ const (
 	ValidationSkipped ValidationStatus = "skipped"
 )
 
+// CacheControlType defines provider cache behavior for prompt content.
+type CacheControlType string
+
+const (
+	CacheControlEphemeral CacheControlType = "ephemeral"
+)
+
+const (
+	// SessionIDMaxLength is OpenRouter's documented maximum session_id length.
+	SessionIDMaxLength = 256
+)
+
+// CacheControl describes provider cache metadata attached to prompt content.
+type CacheControl struct {
+	Type CacheControlType `yaml:"type" json:"type"`
+	TTL  string           `yaml:"ttl,omitempty" json:"ttl,omitempty"`
+}
+
 // RunRequest represents a request to generate a single artifact.
 type RunRequest struct {
 	PromptID      string
@@ -47,7 +65,7 @@ type RunRequest struct {
 	ProfileID     string
 	Inputs        map[string]ArtifactRef
 	Vars          map[string]string
-	Execution     *ExecutionTarget
+	Execution     *ExecutionTargetOverride
 	Validation    *OutputContract
 	Metadata      map[string]string
 }
@@ -77,19 +95,21 @@ type RunResult struct {
 // PreparedRun contains pre-LLM execution state from the prepare/render phase.
 // It must never include resolved API key values, model output, or validation data.
 type PreparedRun struct {
-	PromptID             string                `json:"prompt_id"`
-	PromptVersion        string                `json:"prompt_version,omitempty"`
-	PromptHash           string                `json:"prompt_hash,omitempty"`
-	SelectedProfileID    string                `json:"selected_profile_id"`
-	EffectiveModelParams ExecutionTarget       `json:"effective_model_params"`
-	OutputContract       OutputContract        `json:"output_contract"`
-	StructuredOutput     *StructuredOutputSpec `json:"structured_output,omitempty"`
-	InputHashes          map[string]string     `json:"input_hashes,omitempty"`
-	RenderedPromptHash   string                `json:"rendered_prompt_hash"`
-	Messages             []RenderedMessage     `json:"messages"`
-	StartTime            time.Time             `json:"start_time,omitempty"`
-	EndTime              time.Time             `json:"end_time,omitempty"`
-	DurationMS           int64                 `json:"duration_ms,omitempty"`
+	PromptID             string                  `json:"prompt_id"`
+	PromptVersion        string                  `json:"prompt_version,omitempty"`
+	PromptHash           string                  `json:"prompt_hash,omitempty"`
+	SelectedProfileID    string                  `json:"selected_profile_id"`
+	EffectiveModelParams ExecutionTarget         `json:"effective_model_params"`
+	TargetPresence       ExecutionTargetPresence `json:"-"`
+	OutputContract       OutputContract          `json:"output_contract"`
+	StructuredOutput     *StructuredOutputSpec   `json:"structured_output,omitempty"`
+	InputHashes          map[string]string       `json:"input_hashes,omitempty"`
+	SessionID            string                  `json:"session_id,omitempty"`
+	RenderedPromptHash   string                  `json:"rendered_prompt_hash"`
+	Messages             []RenderedMessage       `json:"messages"`
+	StartTime            time.Time               `json:"start_time,omitempty"`
+	EndTime              time.Time               `json:"end_time,omitempty"`
+	DurationMS           int64                   `json:"duration_ms,omitempty"`
 }
 
 // ArtifactRef represents a reference to an input artifact.
@@ -115,6 +135,7 @@ type PromptDefinition struct {
 	Version        string                  `yaml:"version"`
 	DefaultProfile string                  `yaml:"default_profile"`
 	Description    string                  `yaml:"description"`
+	SessionID      string                  `yaml:"session_id" json:"session_id,omitempty"`
 	Inputs         []PromptInput           `yaml:"inputs"`
 	Templates      []PromptMessageTemplate `yaml:"templates"`
 	OutputFormat   OutputFormat            `yaml:"output_format"`
@@ -131,38 +152,62 @@ type PromptInput struct {
 
 // PromptMessageTemplate defines a template for a chat message.
 type PromptMessageTemplate struct {
-	Role        string `yaml:"role"`
-	Content     string `yaml:"content"`
-	ContentFile string `yaml:"content_file"`
+	Role         string        `yaml:"role"`
+	Content      string        `yaml:"content"`
+	ContentFile  string        `yaml:"content_file"`
+	CacheControl *CacheControl `yaml:"cache_control,omitempty" json:"cache_control,omitempty"`
 }
 
 // ExecutionProfile describes how and where to execute a model.
 type ExecutionProfile struct {
-	ID              string            `yaml:"id"`
-	Endpoint        string            `yaml:"endpoint"`
-	Model           string            `yaml:"model"`
-	Temperature     float64           `yaml:"temperature"`
-	MaxTokens       int               `yaml:"max_tokens"`
-	TopP            float64           `yaml:"top_p"`
-	TimeoutSeconds  int               `yaml:"timeout_seconds"`
-	ServiceTier     string            `yaml:"service_tier"`
-	ReasoningEffort string            `yaml:"reasoning_effort"`
-	APIKeyEnv       string            `yaml:"api_key_env"`
-	ExtraParams     map[string]string `yaml:"extra_params"`
+	ID              string         `yaml:"id"`
+	Endpoint        string         `yaml:"endpoint"`
+	Model           string         `yaml:"model"`
+	Temperature     float64        `yaml:"temperature"`
+	MaxTokens       int            `yaml:"max_tokens"`
+	TopP            float64        `yaml:"top_p"`
+	TimeoutSeconds  int            `yaml:"timeout_seconds"`
+	ServiceTier     string         `yaml:"service_tier"`
+	ReasoningEffort string         `yaml:"reasoning_effort"`
+	APIKeyEnv       string         `yaml:"api_key_env"`
+	ExtraParams     map[string]any `yaml:"extra_params"`
+}
+
+// ExecutionTargetOverride represents per-request runtime setting overrides.
+type ExecutionTargetOverride struct {
+	Endpoint        string         `json:"endpoint,omitempty"`
+	Model           string         `json:"model,omitempty"`
+	Temperature     *float64       `json:"temperature,omitempty"`
+	MaxTokens       *int           `json:"max_tokens,omitempty"`
+	TopP            *float64       `json:"top_p,omitempty"`
+	TimeoutSeconds  *int           `json:"timeout_seconds,omitempty"`
+	ServiceTier     string         `json:"service_tier,omitempty"`
+	ReasoningEffort string         `json:"reasoning_effort,omitempty"`
+	APIKeyEnv       string         `json:"api_key_env,omitempty"`
+	ExtraParams     map[string]any `json:"extra_params,omitempty"`
+}
+
+// ExecutionTargetPresence tracks which effective runtime fields came from an
+// explicit request override even when the resolved value is a zero value.
+type ExecutionTargetPresence struct {
+	Temperature    bool
+	MaxTokens      bool
+	TopP           bool
+	TimeoutSeconds bool
 }
 
 // ExecutionTarget represents effective model runtime settings for a run.
 type ExecutionTarget struct {
-	Endpoint        string            `yaml:"endpoint" json:"endpoint"`
-	Model           string            `yaml:"model" json:"model"`
-	Temperature     float64           `yaml:"temperature" json:"temperature"`
-	MaxTokens       int               `yaml:"max_tokens" json:"max_tokens"`
-	TopP            float64           `yaml:"top_p" json:"top_p"`
-	TimeoutSeconds  int               `yaml:"timeout_seconds" json:"timeout_seconds"`
-	ServiceTier     string            `yaml:"service_tier" json:"service_tier"`
-	ReasoningEffort string            `yaml:"reasoning_effort" json:"reasoning_effort"`
-	APIKeyEnv       string            `yaml:"api_key_env" json:"api_key_env"`
-	ExtraParams     map[string]string `yaml:"extra_params" json:"extra_params"`
+	Endpoint        string         `yaml:"endpoint" json:"endpoint"`
+	Model           string         `yaml:"model" json:"model"`
+	Temperature     float64        `yaml:"temperature" json:"temperature"`
+	MaxTokens       int            `yaml:"max_tokens" json:"max_tokens"`
+	TopP            float64        `yaml:"top_p" json:"top_p"`
+	TimeoutSeconds  int            `yaml:"timeout_seconds" json:"timeout_seconds"`
+	ServiceTier     string         `yaml:"service_tier" json:"service_tier"`
+	ReasoningEffort string         `yaml:"reasoning_effort" json:"reasoning_effort"`
+	APIKeyEnv       string         `yaml:"api_key_env" json:"api_key_env"`
+	ExtraParams     map[string]any `yaml:"extra_params" json:"extra_params"`
 }
 
 // OutputContract defines the requirements for the output artifact.
@@ -175,19 +220,22 @@ type OutputContract struct {
 
 // RenderedPrompt represents the prompt after template application.
 type RenderedPrompt struct {
-	Messages []RenderedMessage `json:"messages"`
+	SessionID string            `json:"session_id,omitempty"`
+	Messages  []RenderedMessage `json:"messages"`
 }
 
 // RenderedMessage is a single message in a rendered prompt.
 type RenderedMessage struct {
-	Role    string `json:"role"`
-	Content string `json:"content"`
+	Role         string        `json:"role"`
+	Content      string        `json:"content"`
+	CacheControl *CacheControl `json:"cache_control,omitempty"`
 }
 
 // GenerateRequest is the internal request passed to the LLM client.
 type GenerateRequest struct {
 	Prompt           RenderedPrompt
 	Target           ExecutionTarget
+	TargetPresence   ExecutionTargetPresence
 	StructuredOutput *StructuredOutputSpec
 }
 
@@ -222,6 +270,8 @@ type TokenUsage struct {
 	PromptTokens     int
 	CompletionTokens int
 	TotalTokens      int
+	CachedTokens     int
+	CacheWriteTokens int
 }
 
 // ValidationResult represents the outcome of an output validation.

internal/domain/prepared_run_test.go

@@ -53,3 +53,88 @@ func TestPreparedRunJSONDoesNotIncludeSecretValues(t *testing.T) {
 		}
 	}
 }
+
+func TestPreparedRunJSONIncludesMessageCacheControlOnlyWhenPresent(t *testing.T) {
+	prepared := PreparedRun{
+		PromptID:          "prompt.id",
+		SelectedProfileID: "local-fast",
+		EffectiveModelParams: ExecutionTarget{
+			Endpoint: "http://llm/v1",
+			Model:    "gpt-test",
+		},
+		RenderedPromptHash: "rendered-hash",
+		Messages: []RenderedMessage{
+			{
+				Role:    "system",
+				Content: "You are helpful.",
+				CacheControl: &CacheControl{
+					Type: CacheControlEphemeral,
+					TTL:  "1h",
+				},
+			},
+			{Role: "user", Content: "Summarize this."},
+		},
+	}
+
+	b, err := json.Marshal(prepared)
+	if err != nil {
+		t.Fatalf("marshal failed: %v", err)
+	}
+
+	var decoded struct {
+		Messages []map[string]any `json:"messages"`
+	}
+	if err := json.Unmarshal(b, &decoded); err != nil {
+		t.Fatalf("unmarshal failed: %v", err)
+	}
+	if len(decoded.Messages) != 2 {
+		t.Fatalf("expected 2 messages, got %d", len(decoded.Messages))
+	}
+
+	cacheControl, ok := decoded.Messages[0]["cache_control"].(map[string]any)
+	if !ok {
+		t.Fatalf("expected cache_control on first message, got %#v", decoded.Messages[0])
+	}
+	if cacheControl["type"] != string(CacheControlEphemeral) || cacheControl["ttl"] != "1h" {
+		t.Fatalf("unexpected cache_control payload: %#v", cacheControl)
+	}
+	if _, ok := decoded.Messages[1]["cache_control"]; ok {
+		t.Fatalf("expected second message to omit cache_control, got %#v", decoded.Messages[1])
+	}
+}
+
+func TestPreparedRunJSONIncludesSessionIDOnlyWhenPresent(t *testing.T) {
+	prepared := PreparedRun{
+		PromptID:          "prompt.id",
+		SelectedProfileID: "local-fast",
+		EffectiveModelParams: ExecutionTarget{
+			Endpoint: "http://llm/v1",
+			Model:    "gpt-test",
+		},
+		SessionID:          "session-123",
+		RenderedPromptHash: "rendered-hash",
+		Messages:           []RenderedMessage{{Role: "user", Content: "Summarize this."}},
+	}
+
+	b, err := json.Marshal(prepared)
+	if err != nil {
+		t.Fatalf("marshal failed: %v", err)
+	}
+
+	var decoded map[string]any
+	if err := json.Unmarshal(b, &decoded); err != nil {
+		t.Fatalf("unmarshal failed: %v", err)
+	}
+	if decoded["session_id"] != "session-123" {
+		t.Fatalf("expected session_id in prepared run JSON, got %#v", decoded["session_id"])
+	}
+
+	prepared.SessionID = ""
+	b, err = json.Marshal(prepared)
+	if err != nil {
+		t.Fatalf("marshal failed: %v", err)
+	}
+	if strings.Contains(string(b), "session_id") {
+		t.Fatalf("expected empty session_id to be omitted, got %s", b)
+	}
+}

internal/format/prepared_run.go

@@ -96,6 +96,9 @@ func (textPreparedRunFormatter) Format(prepared *domain.PreparedRun) ([]byte, er
 	if prepared.PromptHash != "" {
 		fmt.Fprintf(&b, "prompt_hash: %s\n", prepared.PromptHash)
 	}
+	if prepared.SessionID != "" {
+		fmt.Fprintf(&b, "session_id: %s\n", prepared.SessionID)
+	}
 	fmt.Fprintf(&b, "rendered_prompt_hash: %s\n", prepared.RenderedPromptHash)
 
 	target := prepared.EffectiveModelParams
@@ -123,7 +126,11 @@ func (textPreparedRunFormatter) Format(prepared *domain.PreparedRun) ([]byte, er
 		}
 		sort.Strings(keys)
 		for _, k := range keys {
-			fmt.Fprintf(&b, "    %s: %s\n", k, target.ExtraParams[k])
+			renderedValue, err := formatExtraParamTextValue(target.ExtraParams[k])
+			if err != nil {
+				return nil, fmt.Errorf("failed to format extra_params.%s: %w", k, err)
+			}
+			fmt.Fprintf(&b, "    %s: %s\n", k, renderedValue)
 		}
 	}
 
@@ -151,6 +158,13 @@ func (textPreparedRunFormatter) Format(prepared *domain.PreparedRun) ([]byte, er
 		messages := byRole[role]
 		for i, msg := range messages {
 			fmt.Fprintf(&b, "    - message: %d\n", i+1)
+			if msg.CacheControl != nil {
+				fmt.Fprintf(&b, "      cache_control: %s", msg.CacheControl.Type)
+				if msg.CacheControl.TTL != "" {
+					fmt.Fprintf(&b, " ttl=%s", msg.CacheControl.TTL)
+				}
+				fmt.Fprintln(&b)
+			}
 			fmt.Fprintln(&b, "      content: |")
 			content := msg.Content
 			if content == "" {
@@ -165,3 +179,15 @@ func (textPreparedRunFormatter) Format(prepared *domain.PreparedRun) ([]byte, er
 
 	return b.Bytes(), nil
 }
+
+func formatExtraParamTextValue(value any) (string, error) {
+	if s, ok := value.(string); ok {
+		return s, nil
+	}
+
+	b, err := json.Marshal(value)
+	if err != nil {
+		return "", err
+	}
+	return string(b), nil
+}

internal/format/prepared_run_test.go

@@ -49,6 +49,36 @@ func TestTextFormatterIncludesPreparedRunDetails(t *testing.T) {
 	}
 }
 
+func TestTextFormatterRendersExtraParamsDeterministically(t *testing.T) {
+	prepared := samplePreparedRun()
+	prepared.EffectiveModelParams.ExtraParams = map[string]any{
+		"z_string": "enabled",
+		"b_number": 42,
+		"a_object": map[string]any{
+			"nested": "value",
+			"count":  2,
+		},
+		"c_array": []any{"first", 3, false},
+	}
+
+	out, err := FormatPreparedRun(prepared, PreparedRunFormatText)
+	if err != nil {
+		t.Fatalf("expected no error, got %v", err)
+	}
+	s := string(out)
+
+	want := strings.Join([]string{
+		"  extra_params:",
+		"    a_object: {\"count\":2,\"nested\":\"value\"}",
+		"    b_number: 42",
+		"    c_array: [\"first\",3,false]",
+		"    z_string: enabled",
+	}, "\n")
+	if !strings.Contains(s, want) {
+		t.Fatalf("expected deterministic extra_params block %q, got:\n%s", want, s)
+	}
+}
+
 func TestTextFormatterDoesNotIncludeResolvedAPIKeyValue(t *testing.T) {
 	const secret = "super-secret-api-key"
 	t.Setenv("SCRIPTORIUM_API_KEY", secret)
@@ -62,8 +92,80 @@ func TestTextFormatterDoesNotIncludeResolvedAPIKeyValue(t *testing.T) {
 	}
 }
 
+func TestTextFormatterIncludesMessageCacheControlBeforeContent(t *testing.T) {
+	prepared := samplePreparedRun()
+	prepared.Messages = []domain.RenderedMessage{
+		{
+			Role:    "system",
+			Content: "System guidance.",
+			CacheControl: &domain.CacheControl{
+				Type: domain.CacheControlEphemeral,
+				TTL:  "1h",
+			},
+		},
+		{Role: "user", Content: "Summarize the transcript."},
+	}
+
+	out, err := FormatPreparedRun(prepared, PreparedRunFormatText)
+	if err != nil {
+		t.Fatalf("expected no error, got %v", err)
+	}
+	s := string(out)
+	if !strings.Contains(s, "  system:\n    - message: 1\n      cache_control: ephemeral ttl=1h\n      content: |") {
+		t.Fatalf("expected system message cache control before content, got:\n%s", s)
+	}
+	if strings.Count(s, "cache_control:") != 1 {
+		t.Fatalf("expected exactly one cache_control line, got:\n%s", s)
+	}
+}
+
+func TestTextFormatterIncludesSessionIDWhenPresent(t *testing.T) {
+	prepared := samplePreparedRun()
+	prepared.SessionID = "session-123"
+
+	out, err := FormatPreparedRun(prepared, PreparedRunFormatText)
+	if err != nil {
+		t.Fatalf("expected no error, got %v", err)
+	}
+	if !strings.Contains(string(out), "session_id: session-123\n") {
+		t.Fatalf("expected session_id in text output, got:\n%s", out)
+	}
+}
+
+func TestTextFormatterOmitsEmptyCacheControlTTL(t *testing.T) {
+	prepared := samplePreparedRun()
+	prepared.Messages = []domain.RenderedMessage{
+		{
+			Role:    "system",
+			Content: "System guidance.",
+			CacheControl: &domain.CacheControl{
+				Type: domain.CacheControlEphemeral,
+			},
+		},
+	}
+
+	out, err := FormatPreparedRun(prepared, PreparedRunFormatText)
+	if err != nil {
+		t.Fatalf("expected no error, got %v", err)
+	}
+	s := string(out)
+	if !strings.Contains(s, "      cache_control: ephemeral\n") {
+		t.Fatalf("expected cache_control line without ttl, got:\n%s", s)
+	}
+	if strings.Contains(s, "ttl=") {
+		t.Fatalf("expected empty ttl to be omitted, got:\n%s", s)
+	}
+}
+
 func TestJSONFormatterEmitsValidJSONAndIncludesPreparedRunFields(t *testing.T) {
 	prepared := samplePreparedRun()
+	prepared.SessionID = "session-123"
+	prepared.EffectiveModelParams.ExtraParams = map[string]any{
+		"number": 42,
+		"nested": map[string]any{
+			"enabled": true,
+		},
+	}
 
 	out, err := FormatPreparedRun(prepared, PreparedRunFormatJSON)
 	if err != nil {
@@ -87,9 +189,24 @@ func TestJSONFormatterEmitsValidJSONAndIncludesPreparedRunFields(t *testing.T) {
 	if decoded["rendered_prompt_hash"] != "rendered-hash" {
 		t.Fatalf("expected rendered_prompt_hash in json output, got %#v", decoded["rendered_prompt_hash"])
 	}
-	if _, ok := decoded["effective_model_params"]; !ok {
+	if decoded["session_id"] != "session-123" {
+		t.Fatalf("expected session_id in json output, got %#v", decoded["session_id"])
+	}
+	modelParams, ok := decoded["effective_model_params"].(map[string]any)
+	if !ok {
 		t.Fatalf("expected effective_model_params in json output, got %#v", decoded)
 	}
+	extraParams, ok := modelParams["extra_params"].(map[string]any)
+	if !ok {
+		t.Fatalf("expected extra_params in json output, got %#v", modelParams["extra_params"])
+	}
+	if extraParams["number"] != float64(42) {
+		t.Fatalf("unexpected numeric extra param in json output: %#v", extraParams["number"])
+	}
+	nested, ok := extraParams["nested"].(map[string]any)
+	if !ok || nested["enabled"] != true {
+		t.Fatalf("unexpected nested extra param in json output: %#v", extraParams["nested"])
+	}
 	if _, ok := decoded["input_hashes"]; !ok {
 		t.Fatalf("expected input_hashes in json output, got %#v", decoded)
 	}
@@ -98,6 +215,47 @@ func TestJSONFormatterEmitsValidJSONAndIncludesPreparedRunFields(t *testing.T) {
 	}
 }
 
+func TestJSONFormatterIncludesMessageCacheControlOnlyWhenPresent(t *testing.T) {
+	prepared := samplePreparedRun()
+	prepared.Messages = []domain.RenderedMessage{
+		{
+			Role:    "system",
+			Content: "System guidance.",
+			CacheControl: &domain.CacheControl{
+				Type: domain.CacheControlEphemeral,
+				TTL:  "1h",
+			},
+		},
+		{Role: "user", Content: "Summarize the transcript."},
+	}
+
+	out, err := FormatPreparedRun(prepared, PreparedRunFormatJSON)
+	if err != nil {
+		t.Fatalf("expected no error, got %v", err)
+	}
+
+	var decoded struct {
+		Messages []map[string]any `json:"messages"`
+	}
+	if err := json.Unmarshal(out, &decoded); err != nil {
+		t.Fatalf("expected valid json output, got %v", err)
+	}
+	if len(decoded.Messages) != 2 {
+		t.Fatalf("expected 2 messages, got %d", len(decoded.Messages))
+	}
+
+	cacheControl, ok := decoded.Messages[0]["cache_control"].(map[string]any)
+	if !ok {
+		t.Fatalf("expected first message cache_control, got %#v", decoded.Messages[0])
+	}
+	if cacheControl["type"] != string(domain.CacheControlEphemeral) || cacheControl["ttl"] != "1h" {
+		t.Fatalf("unexpected cache_control payload: %#v", cacheControl)
+	}
+	if _, ok := decoded.Messages[1]["cache_control"]; ok {
+		t.Fatalf("expected second message to omit cache_control, got %#v", decoded.Messages[1])
+	}
+}
+
 func TestJSONFormatterDoesNotIncludeResolvedAPIKeyValue(t *testing.T) {
 	const secret = "super-secret-api-key"
 	t.Setenv("SCRIPTORIUM_API_KEY", secret)

internal/llm/openai_compatible_client.go

@@ -12,6 +12,7 @@ import (
 	"os"
 	"strings"
 	"time"
+	"unicode/utf8"
 
 	"gitea.maximumdirect.net/eric/scriptorium/internal/defaults"
 	"gitea.maximumdirect.net/eric/scriptorium/internal/domain"
@@ -89,7 +90,12 @@ func (c *OpenAICompatibleClient) Generate(ctx context.Context, req domain.Genera
 		return nil, fmt.Errorf("%w: %v", ErrInvalidRequest, err)
 	}
 
-	payload, err := json.Marshal(wireReq)
+	wirePayload, err := openAIChatRequestPayload(wireReq)
+	if err != nil {
+		return nil, fmt.Errorf("%w: %v", ErrInvalidRequest, err)
+	}
+
+	payload, err := json.Marshal(wirePayload)
 	if err != nil {
 		return nil, fmt.Errorf("%w: failed to encode request: %v", ErrRequestFailed, err)
 	}
@@ -110,6 +116,8 @@ func (c *OpenAICompatibleClient) Generate(ctx context.Context, req domain.Genera
 	effectiveTimeout := c.timeout
 	if req.Target.TimeoutSeconds > 0 {
 		effectiveTimeout = time.Duration(req.Target.TimeoutSeconds) * time.Second
+	} else if req.TargetPresence.TimeoutSeconds {
+		effectiveTimeout = 0
 	}
 
 	httpClient := c.httpClient
@@ -151,6 +159,8 @@ func (c *OpenAICompatibleClient) Generate(ctx context.Context, req domain.Genera
 			PromptTokens:     wireResp.Usage.PromptTokens,
 			CompletionTokens: wireResp.Usage.CompletionTokens,
 			TotalTokens:      wireResp.Usage.TotalTokens,
+			CachedTokens:     wireResp.Usage.PromptTokensDetails.CachedTokens,
+			CacheWriteTokens: wireResp.Usage.CacheWriteTokens,
 		},
 	}, nil
 }
@@ -167,27 +177,36 @@ func openAIChatRequestFromGenerateRequest(req domain.GenerateRequest, defaultMod
 	wireReq := openAIChatRequest{
 		Model: model,
 	}
-
-	wireReq.Messages = make([]openAIChatMessage, 0, len(req.Prompt.Messages))
-	for _, msg := range req.Prompt.Messages {
-		wireReq.Messages = append(wireReq.Messages, openAIChatMessage{
-			Role:    msg.Role,
-			Content: msg.Content,
-		})
+	if sessionID := strings.TrimSpace(req.Prompt.SessionID); sessionID != "" {
+		if n := utf8.RuneCountInString(sessionID); n > domain.SessionIDMaxLength {
+			return openAIChatRequest{}, fmt.Errorf("session_id length %d exceeds maximum %d", n, domain.SessionIDMaxLength)
+		}
+		wireReq.SessionID = sessionID
 	}
 
-	if req.Target.Temperature != 0 {
+	wireReq.Messages = make([]openAIChatRequestMessage, 0, len(req.Prompt.Messages))
+	for _, msg := range req.Prompt.Messages {
+		wireReq.Messages = append(wireReq.Messages, openAIChatRequestMessageFromRenderedMessage(msg))
+	}
+
+	if req.Target.Temperature != 0 || req.TargetPresence.Temperature {
 		wireReq.Temperature = &req.Target.Temperature
 	}
-	if req.Target.MaxTokens != 0 {
+	if req.Target.MaxTokens != 0 || req.TargetPresence.MaxTokens {
 		wireReq.MaxTokens = &req.Target.MaxTokens
 	}
-	if req.Target.TopP != 0 {
+	if req.Target.TopP != 0 || req.TargetPresence.TopP {
 		wireReq.TopP = &req.Target.TopP
 	}
 	if strings.TrimSpace(req.Target.ServiceTier) != "" {
 		wireReq.ServiceTier = req.Target.ServiceTier
 	}
+	if strings.TrimSpace(req.Target.ReasoningEffort) != "" {
+		wireReq.ReasoningEffort = req.Target.ReasoningEffort
+	}
+	if len(req.Target.ExtraParams) > 0 {
+		wireReq.ExtraParams = req.Target.ExtraParams
+	}
 	if req.StructuredOutput != nil {
 		responseFormat, err := toOpenAIResponseFormat(req.StructuredOutput)
 		if err != nil {
@@ -200,28 +219,106 @@ func openAIChatRequestFromGenerateRequest(req domain.GenerateRequest, defaultMod
 }
 
 type openAIChatRequest struct {
-	Model          string                `json:"model"`
-	Messages       []openAIChatMessage   `json:"messages"`
-	Temperature    *float64              `json:"temperature,omitempty"`
-	MaxTokens      *int                  `json:"max_tokens,omitempty"`
-	TopP           *float64              `json:"top_p,omitempty"`
-	ServiceTier    string                `json:"service_tier,omitempty"`
-	ResponseFormat *openAIResponseFormat `json:"response_format,omitempty"`
+	Model           string                     `json:"model"`
+	SessionID       string                     `json:"session_id,omitempty"`
+	Messages        []openAIChatRequestMessage `json:"messages"`
+	Temperature     *float64                   `json:"temperature,omitempty"`
+	MaxTokens       *int                       `json:"max_tokens,omitempty"`
+	TopP            *float64                   `json:"top_p,omitempty"`
+	ServiceTier     string                     `json:"service_tier,omitempty"`
+	ReasoningEffort string                     `json:"reasoning_effort,omitempty"`
+	ResponseFormat  *openAIResponseFormat      `json:"response_format,omitempty"`
+	ExtraParams     map[string]any             `json:"-"`
 }
 
-type openAIChatMessage struct {
+func openAIChatRequestPayload(req openAIChatRequest) (map[string]any, error) {
+	out := map[string]any{
+		"model":    req.Model,
+		"messages": req.Messages,
+	}
+	if req.SessionID != "" {
+		out["session_id"] = req.SessionID
+	}
+	if req.Temperature != nil {
+		out["temperature"] = *req.Temperature
+	}
+	if req.MaxTokens != nil {
+		out["max_tokens"] = *req.MaxTokens
+	}
+	if req.TopP != nil {
+		out["top_p"] = *req.TopP
+	}
+	if req.ServiceTier != "" {
+		out["service_tier"] = req.ServiceTier
+	}
+	if req.ReasoningEffort != "" {
+		out["reasoning_effort"] = req.ReasoningEffort
+	}
+	if req.ResponseFormat != nil {
+		out["response_format"] = req.ResponseFormat
+	}
+
+	for key, value := range req.ExtraParams {
+		if key == "" {
+			return nil, errors.New("extra_params key must not be empty")
+		}
+		if _, reserved := reservedOpenAIChatRequestFields[key]; reserved {
+			return nil, fmt.Errorf("extra_params key %q collides with reserved request field", key)
+		}
+		if _, err := json.Marshal(value); err != nil {
+			return nil, fmt.Errorf("extra_params.%s must be JSON-serializable: %w", key, err)
+		}
+		out[key] = value
+	}
+
+	return out, nil
+}
+
+var reservedOpenAIChatRequestFields = map[string]struct{}{
+	"model":            {},
+	"session_id":       {},
+	"messages":         {},
+	"temperature":      {},
+	"max_tokens":       {},
+	"top_p":            {},
+	"service_tier":     {},
+	"reasoning_effort": {},
+	"response_format":  {},
+}
+
+type openAIChatRequestMessage struct {
+	Role    string `json:"role"`
+	Content any    `json:"content"`
+}
+
+type openAIChatTextContentBlock struct {
+	Type         string              `json:"type"`
+	Text         string              `json:"text"`
+	CacheControl *openAICacheControl `json:"cache_control,omitempty"`
+}
+
+type openAICacheControl struct {
+	Type string `json:"type"`
+	TTL  string `json:"ttl,omitempty"`
+}
+
+type openAIChatResponseMessage struct {
 	Role    string `json:"role"`
 	Content string `json:"content"`
 }
 
 type openAIChatResponse struct {
 	Choices []struct {
-		Message openAIChatMessage `json:"message"`
+		Message openAIChatResponseMessage `json:"message"`
 	} `json:"choices"`
 	Usage struct {
-		PromptTokens     int `json:"prompt_tokens"`
-		CompletionTokens int `json:"completion_tokens"`
-		TotalTokens      int `json:"total_tokens"`
+		PromptTokens        int `json:"prompt_tokens"`
+		CompletionTokens    int `json:"completion_tokens"`
+		TotalTokens         int `json:"total_tokens"`
+		PromptTokensDetails struct {
+			CachedTokens int `json:"cached_tokens"`
+		} `json:"prompt_tokens_details"`
+		CacheWriteTokens int `json:"cache_write_tokens"`
 	} `json:"usage"`
 }
 
@@ -236,6 +333,28 @@ type openAIJSONSchemaEnvelope struct {
 	Schema any    `json:"schema"`
 }
 
+func openAIChatRequestMessageFromRenderedMessage(msg domain.RenderedMessage) openAIChatRequestMessage {
+	wireMsg := openAIChatRequestMessage{
+		Role:    msg.Role,
+		Content: msg.Content,
+	}
+	if msg.CacheControl == nil {
+		return wireMsg
+	}
+
+	wireMsg.Content = []openAIChatTextContentBlock{
+		{
+			Type: "text",
+			Text: msg.Content,
+			CacheControl: &openAICacheControl{
+				Type: string(msg.CacheControl.Type),
+				TTL:  msg.CacheControl.TTL,
+			},
+		},
+	}
+	return wireMsg
+}
+
 func toOpenAIResponseFormat(spec *domain.StructuredOutputSpec) (*openAIResponseFormat, error) {
 	if spec == nil {
 		return nil, nil

internal/llm/openai_compatible_client_test.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"encoding/json"
 	"errors"
+	"math"
 	"net/http"
 	"net/http/httptest"
 	"strings"
@@ -89,6 +90,9 @@ func TestOpenAICompatibleClientGenerateSuccess(t *testing.T) {
 	if resp.Usage.PromptTokens != 11 || resp.Usage.CompletionTokens != 22 || resp.Usage.TotalTokens != 33 {
 		t.Fatalf("unexpected usage: %+v", resp.Usage)
 	}
+	if resp.Usage.CachedTokens != 0 || resp.Usage.CacheWriteTokens != 0 {
+		t.Fatalf("expected absent cache usage fields to remain zero, got %+v", resp.Usage)
+	}
 
 	if obs.Authorization != "Bearer secret-key" {
 		t.Fatalf("unexpected Authorization header: %q", obs.Authorization)
@@ -144,6 +148,245 @@ func TestOpenAICompatibleClientGenerateSuccess(t *testing.T) {
 	}
 }
 
+func TestOpenAICompatibleClientSerializesCacheControlledMessageAsContentBlock(t *testing.T) {
+	var observedBody map[string]any
+	ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		defer r.Body.Close()
+		if err := json.NewDecoder(r.Body).Decode(&observedBody); err != nil {
+			t.Fatalf("failed to decode request body: %v", err)
+		}
+		_, _ = w.Write([]byte(`{"choices":[{"message":{"content":"ok"}}]}`))
+	}))
+	defer ts.Close()
+
+	client, err := NewOpenAICompatibleClient(OpenAICompatibleConfig{BaseURL: ts.URL + "/v1"})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	_, err = client.Generate(context.Background(), domain.GenerateRequest{
+		Prompt: domain.RenderedPrompt{Messages: []domain.RenderedMessage{
+			{
+				Role:    "system",
+				Content: "Stable instructions.",
+				CacheControl: &domain.CacheControl{
+					Type: domain.CacheControlEphemeral,
+					TTL:  "1h",
+				},
+			},
+			{Role: "user", Content: "Dynamic request."},
+		}},
+		Target: domain.ExecutionTarget{Model: "model"},
+	})
+	if err != nil {
+		t.Fatalf("expected no error, got %v", err)
+	}
+
+	for _, forbidden := range []string{"cache_control", "extra_params"} {
+		if _, exists := observedBody[forbidden]; exists {
+			t.Fatalf("expected top-level %s to be omitted, got %#v", forbidden, observedBody[forbidden])
+		}
+	}
+
+	msgs, ok := observedBody["messages"].([]any)
+	if !ok || len(msgs) != 2 {
+		t.Fatalf("unexpected messages payload: %#v", observedBody["messages"])
+	}
+	msg0 := msgs[0].(map[string]any)
+	if msg0["role"] != "system" {
+		t.Fatalf("unexpected first message role: %#v", msg0["role"])
+	}
+	contentBlocks, ok := msg0["content"].([]any)
+	if !ok || len(contentBlocks) != 1 {
+		t.Fatalf("expected first message content block array, got %#v", msg0["content"])
+	}
+	block := contentBlocks[0].(map[string]any)
+	if block["type"] != "text" || block["text"] != "Stable instructions." {
+		t.Fatalf("unexpected text content block: %#v", block)
+	}
+	cacheControl, ok := block["cache_control"].(map[string]any)
+	if !ok {
+		t.Fatalf("expected cache_control on content block, got %#v", block)
+	}
+	if cacheControl["type"] != string(domain.CacheControlEphemeral) || cacheControl["ttl"] != "1h" {
+		t.Fatalf("unexpected cache_control payload: %#v", cacheControl)
+	}
+
+	msg1 := msgs[1].(map[string]any)
+	if msg1["role"] != "user" || msg1["content"] != "Dynamic request." {
+		t.Fatalf("expected uncached message to keep string content, got %#v", msg1)
+	}
+}
+
+func TestOpenAICompatibleClientOmitsEmptyCacheControlTTL(t *testing.T) {
+	var observedBody map[string]any
+	ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		defer r.Body.Close()
+		if err := json.NewDecoder(r.Body).Decode(&observedBody); err != nil {
+			t.Fatalf("failed to decode request body: %v", err)
+		}
+		_, _ = w.Write([]byte(`{"choices":[{"message":{"content":"ok"}}]}`))
+	}))
+	defer ts.Close()
+
+	client, err := NewOpenAICompatibleClient(OpenAICompatibleConfig{BaseURL: ts.URL + "/v1"})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	_, err = client.Generate(context.Background(), domain.GenerateRequest{
+		Prompt: domain.RenderedPrompt{Messages: []domain.RenderedMessage{
+			{
+				Role:    "system",
+				Content: "Stable instructions.",
+				CacheControl: &domain.CacheControl{
+					Type: domain.CacheControlEphemeral,
+				},
+			},
+		}},
+		Target: domain.ExecutionTarget{Model: "model"},
+	})
+	if err != nil {
+		t.Fatalf("expected no error, got %v", err)
+	}
+
+	msgs := observedBody["messages"].([]any)
+	msg0 := msgs[0].(map[string]any)
+	contentBlocks := msg0["content"].([]any)
+	block := contentBlocks[0].(map[string]any)
+	cacheControl := block["cache_control"].(map[string]any)
+	if cacheControl["type"] != string(domain.CacheControlEphemeral) {
+		t.Fatalf("unexpected cache_control type: %#v", cacheControl)
+	}
+	if _, exists := cacheControl["ttl"]; exists {
+		t.Fatalf("expected empty ttl to be omitted, got %#v", cacheControl)
+	}
+}
+
+func TestOpenAICompatibleClientSerializesSessionID(t *testing.T) {
+	var observedBody map[string]any
+	var observedSessionHeader string
+	ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		observedSessionHeader = r.Header.Get("x-session-id")
+		defer r.Body.Close()
+		if err := json.NewDecoder(r.Body).Decode(&observedBody); err != nil {
+			t.Fatalf("failed to decode request body: %v", err)
+		}
+		_, _ = w.Write([]byte(`{"choices":[{"message":{"content":"ok"}}]}`))
+	}))
+	defer ts.Close()
+
+	client, err := NewOpenAICompatibleClient(OpenAICompatibleConfig{BaseURL: ts.URL + "/v1"})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	_, err = client.Generate(context.Background(), domain.GenerateRequest{
+		Prompt: domain.RenderedPrompt{
+			SessionID: " session-123 ",
+			Messages:  []domain.RenderedMessage{{Role: "user", Content: "hi"}},
+		},
+		Target: domain.ExecutionTarget{Model: "model"},
+	})
+	if err != nil {
+		t.Fatalf("expected no error, got %v", err)
+	}
+	if observedBody["session_id"] != "session-123" {
+		t.Fatalf("expected top-level session_id, got %#v", observedBody["session_id"])
+	}
+	if observedSessionHeader != "" {
+		t.Fatalf("did not expect x-session-id header, got %q", observedSessionHeader)
+	}
+}
+
+func TestOpenAICompatibleClientOmitsEmptySessionID(t *testing.T) {
+	var observedBody map[string]any
+	ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		defer r.Body.Close()
+		if err := json.NewDecoder(r.Body).Decode(&observedBody); err != nil {
+			t.Fatalf("failed to decode request body: %v", err)
+		}
+		_, _ = w.Write([]byte(`{"choices":[{"message":{"content":"ok"}}]}`))
+	}))
+	defer ts.Close()
+
+	client, err := NewOpenAICompatibleClient(OpenAICompatibleConfig{BaseURL: ts.URL + "/v1"})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	_, err = client.Generate(context.Background(), domain.GenerateRequest{
+		Prompt: domain.RenderedPrompt{
+			SessionID: "   ",
+			Messages:  []domain.RenderedMessage{{Role: "user", Content: "hi"}},
+		},
+		Target: domain.ExecutionTarget{Model: "model"},
+	})
+	if err != nil {
+		t.Fatalf("expected no error, got %v", err)
+	}
+	if _, exists := observedBody["session_id"]; exists {
+		t.Fatalf("expected empty session_id to be omitted, got %#v", observedBody["session_id"])
+	}
+}
+
+func TestOpenAICompatibleClientRejectsTooLongSessionID(t *testing.T) {
+	client, err := NewOpenAICompatibleClient(OpenAICompatibleConfig{
+		BaseURL: "http://example.com/v1",
+		Model:   "model",
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	_, err = client.Generate(context.Background(), domain.GenerateRequest{
+		Prompt: domain.RenderedPrompt{
+			SessionID: strings.Repeat("x", domain.SessionIDMaxLength+1),
+			Messages:  []domain.RenderedMessage{{Role: "user", Content: "hi"}},
+		},
+	})
+	if err == nil {
+		t.Fatal("expected invalid request error")
+	}
+	if !errors.Is(err, ErrInvalidRequest) {
+		t.Fatalf("expected ErrInvalidRequest, got %v", err)
+	}
+}
+
+func TestOpenAICompatibleClientParsesCacheUsage(t *testing.T) {
+	ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		_, _ = w.Write([]byte(`{
+  "choices": [{"message": {"role": "assistant", "content": "ok"}}],
+  "usage": {
+    "prompt_tokens": 100,
+    "completion_tokens": 20,
+    "total_tokens": 120,
+    "prompt_tokens_details": {"cached_tokens": 80},
+    "cache_write_tokens": 60
+  }
+}`))
+	}))
+	defer ts.Close()
+
+	client, err := NewOpenAICompatibleClient(OpenAICompatibleConfig{BaseURL: ts.URL + "/v1", Model: "model"})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	resp, err := client.Generate(context.Background(), domain.GenerateRequest{
+		Prompt: domain.RenderedPrompt{Messages: []domain.RenderedMessage{{Role: "user", Content: "hi"}}},
+	})
+	if err != nil {
+		t.Fatalf("expected no error, got %v", err)
+	}
+	if resp.Usage.PromptTokens != 100 || resp.Usage.CompletionTokens != 20 || resp.Usage.TotalTokens != 120 {
+		t.Fatalf("unexpected base usage fields: %+v", resp.Usage)
+	}
+	if resp.Usage.CachedTokens != 80 || resp.Usage.CacheWriteTokens != 60 {
+		t.Fatalf("unexpected cache usage fields: %+v", resp.Usage)
+	}
+}
+
 func TestOpenAICompatibleClientOmitsResponseFormatWhenNoStructuredOutput(t *testing.T) {
 	var observedBody map[string]any
 	ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
@@ -175,7 +418,7 @@ func TestOpenAICompatibleClientOmitsResponseFormatWhenNoStructuredOutput(t *test
 	}
 }
 
-func TestOpenAICompatibleClientOmitsReasoningEffortAndExtraParams(t *testing.T) {
+func TestOpenAICompatibleClientSerializesReasoningEffortAndExtraParams(t *testing.T) {
 	var observedBody map[string]any
 	ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		defer r.Body.Close()
@@ -196,19 +439,257 @@ func TestOpenAICompatibleClientOmitsReasoningEffortAndExtraParams(t *testing.T)
 		Target: domain.ExecutionTarget{
 			Model:           "model",
 			ReasoningEffort: "high",
-			ExtraParams: map[string]string{
-				"provider_option": "on",
+			ExtraParams: map[string]any{
+				"string_value":  "on",
+				"number_value":  42,
+				"boolean_value": true,
+				"object_value":  map[string]any{"nested": "value", "count": 2},
+				"array_value":   []any{"first", 3, false},
 			},
 		},
 	})
 	if err != nil {
 		t.Fatalf("expected no error, got %v", err)
 	}
+	if observedBody["reasoning_effort"] != "high" {
+		t.Fatalf("expected reasoning_effort high, got %#v", observedBody["reasoning_effort"])
+	}
+	if observedBody["string_value"] != "on" {
+		t.Fatalf("unexpected string extra param: %#v", observedBody["string_value"])
+	}
+	if observedBody["number_value"] != float64(42) {
+		t.Fatalf("unexpected number extra param: %#v", observedBody["number_value"])
+	}
+	if observedBody["boolean_value"] != true {
+		t.Fatalf("unexpected boolean extra param: %#v", observedBody["boolean_value"])
+	}
+	objectValue, ok := observedBody["object_value"].(map[string]any)
+	if !ok || objectValue["nested"] != "value" || objectValue["count"] != float64(2) {
+		t.Fatalf("unexpected object extra param: %#v", observedBody["object_value"])
+	}
+	if _, exists := observedBody["extra_params"]; exists {
+		t.Fatalf("expected extra_params wrapper omitted, got %#v", observedBody["extra_params"])
+	}
+	arrayValue, ok := observedBody["array_value"].([]any)
+	if !ok || len(arrayValue) != 3 || arrayValue[0] != "first" || arrayValue[1] != float64(3) || arrayValue[2] != false {
+		t.Fatalf("unexpected array extra param: %#v", observedBody["array_value"])
+	}
+}
+
+func TestOpenAICompatibleClientOmitsReasoningEffortWhenUnset(t *testing.T) {
+	var observedBody map[string]any
+	ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		defer r.Body.Close()
+		if err := json.NewDecoder(r.Body).Decode(&observedBody); err != nil {
+			t.Fatalf("failed to decode request body: %v", err)
+		}
+		_, _ = w.Write([]byte(`{"choices":[{"message":{"content":"ok"}}]}`))
+	}))
+	defer ts.Close()
+
+	client, err := NewOpenAICompatibleClient(OpenAICompatibleConfig{BaseURL: ts.URL + "/v1"})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	_, err = client.Generate(context.Background(), domain.GenerateRequest{
+		Prompt: domain.RenderedPrompt{Messages: []domain.RenderedMessage{{Role: "user", Content: "hi"}}},
+		Target: domain.ExecutionTarget{Model: "model"},
+	})
+	if err != nil {
+		t.Fatalf("expected no error, got %v", err)
+	}
 	if _, exists := observedBody["reasoning_effort"]; exists {
 		t.Fatalf("expected reasoning_effort omitted, got %#v", observedBody["reasoning_effort"])
 	}
 	if _, exists := observedBody["extra_params"]; exists {
-		t.Fatalf("expected extra_params omitted, got %#v", observedBody["extra_params"])
+		t.Fatalf("expected extra_params wrapper omitted, got %#v", observedBody["extra_params"])
+	}
+}
+
+func TestOpenAICompatibleClientSerializesExplicitZeroNumericOverrides(t *testing.T) {
+	var observedBody map[string]any
+	ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		defer r.Body.Close()
+		if err := json.NewDecoder(r.Body).Decode(&observedBody); err != nil {
+			t.Fatalf("failed to decode request body: %v", err)
+		}
+		_, _ = w.Write([]byte(`{"choices":[{"message":{"content":"ok"}}]}`))
+	}))
+	defer ts.Close()
+
+	client, err := NewOpenAICompatibleClient(OpenAICompatibleConfig{BaseURL: ts.URL + "/v1"})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	_, err = client.Generate(context.Background(), domain.GenerateRequest{
+		Prompt: domain.RenderedPrompt{Messages: []domain.RenderedMessage{{Role: "user", Content: "hi"}}},
+		Target: domain.ExecutionTarget{Model: "model"},
+		TargetPresence: domain.ExecutionTargetPresence{
+			Temperature: true,
+			MaxTokens:   true,
+			TopP:        true,
+		},
+	})
+	if err != nil {
+		t.Fatalf("expected no error, got %v", err)
+	}
+	if observedBody["temperature"] != float64(0) {
+		t.Fatalf("expected explicit zero temperature, got %#v", observedBody["temperature"])
+	}
+	if observedBody["max_tokens"] != float64(0) {
+		t.Fatalf("expected explicit zero max_tokens, got %#v", observedBody["max_tokens"])
+	}
+	if observedBody["top_p"] != float64(0) {
+		t.Fatalf("expected explicit zero top_p, got %#v", observedBody["top_p"])
+	}
+}
+
+func TestOpenAICompatibleClientOmitsImplicitZeroNumericFields(t *testing.T) {
+	var observedBody map[string]any
+	ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		defer r.Body.Close()
+		if err := json.NewDecoder(r.Body).Decode(&observedBody); err != nil {
+			t.Fatalf("failed to decode request body: %v", err)
+		}
+		_, _ = w.Write([]byte(`{"choices":[{"message":{"content":"ok"}}]}`))
+	}))
+	defer ts.Close()
+
+	client, err := NewOpenAICompatibleClient(OpenAICompatibleConfig{BaseURL: ts.URL + "/v1"})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	_, err = client.Generate(context.Background(), domain.GenerateRequest{
+		Prompt: domain.RenderedPrompt{Messages: []domain.RenderedMessage{{Role: "user", Content: "hi"}}},
+		Target: domain.ExecutionTarget{Model: "model"},
+	})
+	if err != nil {
+		t.Fatalf("expected no error, got %v", err)
+	}
+	for _, field := range []string{"temperature", "max_tokens", "top_p"} {
+		if _, exists := observedBody[field]; exists {
+			t.Fatalf("expected implicit zero field %q to be omitted, got body %#v", field, observedBody)
+		}
+	}
+}
+
+func TestOpenAICompatibleClientExplicitZeroTimeoutDisablesClientTimeout(t *testing.T) {
+	ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		time.Sleep(20 * time.Millisecond)
+		_, _ = w.Write([]byte(`{"choices":[{"message":{"content":"ok"}}]}`))
+	}))
+	defer ts.Close()
+
+	client, err := NewOpenAICompatibleClient(OpenAICompatibleConfig{
+		BaseURL: ts.URL + "/v1",
+		Timeout: time.Nanosecond,
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	_, err = client.Generate(context.Background(), domain.GenerateRequest{
+		Prompt:         domain.RenderedPrompt{Messages: []domain.RenderedMessage{{Role: "user", Content: "hi"}}},
+		Target:         domain.ExecutionTarget{Model: "model", TimeoutSeconds: 0},
+		TargetPresence: domain.ExecutionTargetPresence{TimeoutSeconds: true},
+	})
+	if err != nil {
+		t.Fatalf("expected explicit zero timeout to disable client timeout, got %v", err)
+	}
+}
+
+func TestOpenAICompatibleClientOmittedTimeoutUsesClientTimeout(t *testing.T) {
+	ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		time.Sleep(20 * time.Millisecond)
+		_, _ = w.Write([]byte(`{"choices":[{"message":{"content":"ok"}}]}`))
+	}))
+	defer ts.Close()
+
+	client, err := NewOpenAICompatibleClient(OpenAICompatibleConfig{
+		BaseURL: ts.URL + "/v1",
+		Timeout: time.Nanosecond,
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	_, err = client.Generate(context.Background(), domain.GenerateRequest{
+		Prompt: domain.RenderedPrompt{Messages: []domain.RenderedMessage{{Role: "user", Content: "hi"}}},
+		Target: domain.ExecutionTarget{Model: "model", TimeoutSeconds: 0},
+	})
+	if err == nil {
+		t.Fatal("expected omitted timeout to use client timeout")
+	}
+	if !errors.Is(err, ErrRequestFailed) {
+		t.Fatalf("expected ErrRequestFailed, got %v", err)
+	}
+}
+
+func TestOpenAICompatibleClientRejectsInvalidExtraParamsBeforeProviderCall(t *testing.T) {
+	tests := []struct {
+		name        string
+		extraParams map[string]any
+		want        string
+	}{
+		{name: "empty key", extraParams: map[string]any{"": "empty"}, want: "key must not be empty"},
+		{name: "unserializable value", extraParams: map[string]any{"bad": math.Inf(1)}, want: "JSON-serializable"},
+	}
+	for _, key := range []string{
+		"model",
+		"session_id",
+		"messages",
+		"temperature",
+		"max_tokens",
+		"top_p",
+		"service_tier",
+		"reasoning_effort",
+		"response_format",
+	} {
+		tests = append(tests, struct {
+			name        string
+			extraParams map[string]any
+			want        string
+		}{
+			name:        "reserved key " + key,
+			extraParams: map[string]any{key: "collision"},
+			want:        "reserved request field",
+		})
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			called := false
+			ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+				called = true
+				_, _ = w.Write([]byte(`{"choices":[{"message":{"content":"ok"}}]}`))
+			}))
+			defer ts.Close()
+
+			client, err := NewOpenAICompatibleClient(OpenAICompatibleConfig{BaseURL: ts.URL + "/v1"})
+			if err != nil {
+				t.Fatal(err)
+			}
+
+			_, err = client.Generate(context.Background(), domain.GenerateRequest{
+				Prompt: domain.RenderedPrompt{Messages: []domain.RenderedMessage{{Role: "user", Content: "hi"}}},
+				Target: domain.ExecutionTarget{Model: "model", ExtraParams: tc.extraParams},
+			})
+			if err == nil {
+				t.Fatal("expected invalid request error")
+			}
+			if !errors.Is(err, ErrInvalidRequest) {
+				t.Fatalf("expected ErrInvalidRequest, got %v", err)
+			}
+			if !strings.Contains(err.Error(), tc.want) {
+				t.Fatalf("expected error to contain %q, got %v", tc.want, err)
+			}
+			if called {
+				t.Fatal("provider should not be called for invalid extra_params")
+			}
+		})
 	}
 }
 

internal/profile/repository_test.go

@@ -2,6 +2,7 @@ package profile
 
 import (
 	"context"
+	"encoding/json"
 	"errors"
 	"os"
 	"path/filepath"
@@ -85,6 +86,63 @@ temperature: 0.1
 		}
 	})
 
+	t.Run("valid profile with JSON-compatible extra params", func(t *testing.T) {
+		writeProfileTestFile(t, filepath.Join(tmpDir, "json-extra-params.yaml"), `
+id: json-extra-params
+endpoint: http://localhost:8000/v1
+model: nested-model
+extra_params:
+  string_value: enabled
+  number_value: 42
+  boolean_value: true
+  object_value:
+    nested: value
+    count: 2
+  array_value:
+    - first
+    - 3
+    - false
+`)
+
+		p, err := repo.GetProfile(ctx, "json-extra-params")
+		if err != nil {
+			t.Fatalf("expected no error, got %v", err)
+		}
+
+		var got map[string]any
+		encoded, err := json.Marshal(p.ExtraParams)
+		if err != nil {
+			t.Fatalf("expected extra_params to marshal as JSON, got %v", err)
+		}
+		if err := json.Unmarshal(encoded, &got); err != nil {
+			t.Fatalf("expected extra_params JSON to decode, got %v", err)
+		}
+
+		if got["string_value"] != "enabled" {
+			t.Fatalf("unexpected string extra param: %#v", got["string_value"])
+		}
+		if got["number_value"] != float64(42) {
+			t.Fatalf("unexpected number extra param: %#v", got["number_value"])
+		}
+		if got["boolean_value"] != true {
+			t.Fatalf("unexpected boolean extra param: %#v", got["boolean_value"])
+		}
+		objectValue, ok := got["object_value"].(map[string]any)
+		if !ok {
+			t.Fatalf("expected object extra param, got %#v", got["object_value"])
+		}
+		if objectValue["nested"] != "value" || objectValue["count"] != float64(2) {
+			t.Fatalf("unexpected object extra param: %#v", objectValue)
+		}
+		arrayValue, ok := got["array_value"].([]any)
+		if !ok {
+			t.Fatalf("expected array extra param, got %#v", got["array_value"])
+		}
+		if len(arrayValue) != 3 || arrayValue[0] != "first" || arrayValue[1] != float64(3) || arrayValue[2] != false {
+			t.Fatalf("unexpected array extra param: %#v", arrayValue)
+		}
+	})
+
 	t.Run("duplicate profile IDs fail as ambiguous", func(t *testing.T) {
 		writeProfileTestFile(t, filepath.Join(tmpDir, "duplicate-profile-a.yaml"), `
 id: duplicate-profile

internal/prompt/go_renderer.go

@@ -6,7 +6,9 @@ import (
 	"errors"
 	"fmt"
 	"gitea.maximumdirect.net/eric/scriptorium/internal/domain"
+	"strings"
 	"text/template"
+	"unicode/utf8"
 )
 
 var (
@@ -50,6 +52,11 @@ func (r *goRenderer) Render(ctx context.Context, definition *domain.PromptDefini
 		},
 	}
 
+	sessionID, err := renderSessionID(definition.SessionID, funcs, vars)
+	if err != nil {
+		return nil, err
+	}
+
 	var renderedMessages []domain.RenderedMessage
 
 	for i, tmplMsg := range definition.Templates {
@@ -75,12 +82,44 @@ func (r *goRenderer) Render(ctx context.Context, definition *domain.PromptDefini
 		}
 
 		renderedMessages = append(renderedMessages, domain.RenderedMessage{
-			Role:    tmplMsg.Role,
-			Content: buf.String(),
+			Role:         tmplMsg.Role,
+			Content:      buf.String(),
+			CacheControl: cloneCacheControl(tmplMsg.CacheControl),
 		})
 	}
 
 	return &domain.RenderedPrompt{
-		Messages: renderedMessages,
+		SessionID: sessionID,
+		Messages:  renderedMessages,
 	}, nil
 }
+
+func renderSessionID(raw string, funcs template.FuncMap, vars map[string]string) (string, error) {
+	if strings.TrimSpace(raw) == "" {
+		return "", nil
+	}
+
+	tmpl, err := template.New("session_id").Funcs(funcs).Option("missingkey=error").Parse(raw)
+	if err != nil {
+		return "", fmt.Errorf("%w: session_id: %v", ErrInvalidTemplate, err)
+	}
+
+	var buf bytes.Buffer
+	if err := tmpl.Execute(&buf, vars); err != nil {
+		return "", fmt.Errorf("%w: session_id: %w", ErrRenderFailure, err)
+	}
+
+	sessionID := strings.TrimSpace(buf.String())
+	if n := utf8.RuneCountInString(sessionID); n > domain.SessionIDMaxLength {
+		return "", fmt.Errorf("%w: session_id length %d exceeds maximum %d", ErrRenderFailure, n, domain.SessionIDMaxLength)
+	}
+	return sessionID, nil
+}
+
+func cloneCacheControl(in *domain.CacheControl) *domain.CacheControl {
+	if in == nil {
+		return nil
+	}
+	out := *in
+	return &out
+}

internal/prompt/renderer_test.go

@@ -3,6 +3,7 @@ package prompt
 import (
 	"context"
 	"errors"
+	"strings"
 	"testing"
 
 	"gitea.maximumdirect.net/eric/scriptorium/internal/domain"
@@ -78,6 +79,66 @@ func TestGoRenderer_Render(t *testing.T) {
 		}
 	})
 
+	t.Run("copying cache control to rendered messages", func(t *testing.T) {
+		def := &domain.PromptDefinition{
+			Inputs: []domain.PromptInput{{Name: "transcript", Required: true}},
+			Templates: []domain.PromptMessageTemplate{
+				{
+					Role:    "system",
+					Content: "You are concise.",
+					CacheControl: &domain.CacheControl{
+						Type: domain.CacheControlEphemeral,
+						TTL:  "1h",
+					},
+				},
+				{Role: "user", Content: "Analyze this: {{input \"transcript\"}}"},
+			},
+		}
+
+		res, err := renderer.Render(ctx, def, inputs, vars)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if len(res.Messages) != 2 {
+			t.Fatalf("expected 2 messages, got %d", len(res.Messages))
+		}
+		if res.Messages[0].CacheControl == nil {
+			t.Fatal("expected rendered cache control")
+		}
+		if res.Messages[0].CacheControl.Type != domain.CacheControlEphemeral {
+			t.Fatalf("unexpected cache control type: %q", res.Messages[0].CacheControl.Type)
+		}
+		if res.Messages[0].CacheControl.TTL != "1h" {
+			t.Fatalf("unexpected cache control ttl: %q", res.Messages[0].CacheControl.TTL)
+		}
+		if res.Messages[1].CacheControl != nil {
+			t.Fatalf("expected no cache control on second message, got %#v", res.Messages[1].CacheControl)
+		}
+	})
+
+	t.Run("rendered cache control does not alias source template", func(t *testing.T) {
+		source := &domain.CacheControl{Type: domain.CacheControlEphemeral, TTL: "1h"}
+		def := &domain.PromptDefinition{
+			Inputs: []domain.PromptInput{{Name: "transcript", Required: true}},
+			Templates: []domain.PromptMessageTemplate{
+				{Role: "system", Content: "You are concise.", CacheControl: source},
+			},
+		}
+
+		res, err := renderer.Render(ctx, def, inputs, vars)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if res.Messages[0].CacheControl == source {
+			t.Fatal("expected rendered cache control to be cloned")
+		}
+
+		res.Messages[0].CacheControl.TTL = ""
+		if source.TTL != "1h" {
+			t.Fatalf("source cache control was mutated, ttl=%q", source.TTL)
+		}
+	})
+
 	t.Run("accessing vars", func(t *testing.T) {
 		def := &domain.PromptDefinition{
 			Inputs: []domain.PromptInput{{Name: "transcript", Required: true}},
@@ -95,6 +156,78 @@ func TestGoRenderer_Render(t *testing.T) {
 		}
 	})
 
+	t.Run("rendering session id from vars", func(t *testing.T) {
+		def := &domain.PromptDefinition{
+			SessionID: "  {{ .session_id }}  ",
+			Inputs:    []domain.PromptInput{{Name: "transcript", Required: true}},
+			Templates: []domain.PromptMessageTemplate{
+				{Role: "system", Content: "Speak in a {{.tone}} tone."},
+			},
+		}
+
+		res, err := renderer.Render(ctx, def, inputs, map[string]string{
+			"tone":       "concise",
+			"session_id": "agent-session-123",
+		})
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if res.SessionID != "agent-session-123" {
+			t.Fatalf("unexpected session id: %q", res.SessionID)
+		}
+	})
+
+	t.Run("empty rendered session id is omitted", func(t *testing.T) {
+		def := &domain.PromptDefinition{
+			SessionID: "   ",
+			Inputs:    []domain.PromptInput{{Name: "transcript", Required: true}},
+			Templates: []domain.PromptMessageTemplate{
+				{Role: "system", Content: "Speak in a {{.tone}} tone."},
+			},
+		}
+
+		res, err := renderer.Render(ctx, def, inputs, vars)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if res.SessionID != "" {
+			t.Fatalf("expected empty session id, got %q", res.SessionID)
+		}
+	})
+
+	t.Run("missing session id var fails rendering", func(t *testing.T) {
+		def := &domain.PromptDefinition{
+			SessionID: "{{ .session_id }}",
+			Inputs:    []domain.PromptInput{{Name: "transcript", Required: true}},
+			Templates: []domain.PromptMessageTemplate{
+				{Role: "system", Content: "Speak in a {{.tone}} tone."},
+			},
+		}
+
+		_, err := renderer.Render(ctx, def, inputs, vars)
+		if !errors.Is(err, ErrRenderFailure) {
+			t.Fatalf("expected ErrRenderFailure, got %v", err)
+		}
+	})
+
+	t.Run("too long rendered session id fails rendering", func(t *testing.T) {
+		def := &domain.PromptDefinition{
+			SessionID: "{{ .session_id }}",
+			Inputs:    []domain.PromptInput{{Name: "transcript", Required: true}},
+			Templates: []domain.PromptMessageTemplate{
+				{Role: "system", Content: "Speak in a {{.tone}} tone."},
+			},
+		}
+
+		_, err := renderer.Render(ctx, def, inputs, map[string]string{
+			"tone":       "concise",
+			"session_id": strings.Repeat("x", domain.SessionIDMaxLength+1),
+		})
+		if !errors.Is(err, ErrRenderFailure) {
+			t.Fatalf("expected ErrRenderFailure, got %v", err)
+		}
+	})
+
 	t.Run("inserting required input artifact", func(t *testing.T) {
 		def := &domain.PromptDefinition{
 			Inputs: []domain.PromptInput{{Name: "transcript", Required: true}},

internal/promptdef/filesystem_repository.go

@@ -29,6 +29,7 @@ type promptDefinitionFile struct {
 	Version        string                   `yaml:"version"`
 	DefaultProfile *string                  `yaml:"default_profile"`
 	Description    string                   `yaml:"description"`
+	SessionID      string                   `yaml:"session_id"`
 	Inputs         []promptInputFile        `yaml:"inputs"`
 	Messages       []promptMessageFile      `yaml:"messages"`
 	Output         promptOutputContractFile `yaml:"output"`
@@ -42,9 +43,15 @@ type promptInputFile struct {
 }
 
 type promptMessageFile struct {
-	Role        string `yaml:"role"`
-	Content     string `yaml:"content"`
-	ContentFile string `yaml:"content_file"`
+	Role         string            `yaml:"role"`
+	Content      string            `yaml:"content"`
+	ContentFile  string            `yaml:"content_file"`
+	CacheControl *cacheControlFile `yaml:"cache_control"`
+}
+
+type cacheControlFile struct {
+	Type string `yaml:"type"`
+	TTL  string `yaml:"ttl"`
 }
 
 type promptOutputContractFile struct {
@@ -212,6 +219,11 @@ func normalizePromptDefinition(raw *promptDefinitionFile, sourcePath string) (*d
 			return nil, fmt.Errorf("message %d (%s) must set exactly one of content or content_file", i, role)
 		}
 
+		cacheControl, err := normalizeCacheControl(msg.CacheControl)
+		if err != nil {
+			return nil, fmt.Errorf("message %d (%s) cache_control: %w", i, role, err)
+		}
+
 		templateContent := msg.Content
 		resolvedContentFile := ""
 		if hasContentFile {
@@ -230,9 +242,10 @@ func normalizePromptDefinition(raw *promptDefinitionFile, sourcePath string) (*d
 		}
 
 		templates = append(templates, domain.PromptMessageTemplate{
-			Role:        role,
-			Content:     templateContent,
-			ContentFile: resolvedContentFile,
+			Role:         role,
+			Content:      templateContent,
+			ContentFile:  resolvedContentFile,
+			CacheControl: cacheControl,
 		})
 	}
 
@@ -262,6 +275,7 @@ func normalizePromptDefinition(raw *promptDefinitionFile, sourcePath string) (*d
 		Version:        version,
 		DefaultProfile: defaultProfile,
 		Description:    strings.TrimSpace(raw.Description),
+		SessionID:      strings.TrimSpace(raw.SessionID),
 		Inputs:         inputs,
 		Templates:      templates,
 		OutputFormat:   raw.Output.Format,
@@ -274,6 +288,30 @@ func normalizePromptDefinition(raw *promptDefinitionFile, sourcePath string) (*d
 	}, nil
 }
 
+func normalizeCacheControl(raw *cacheControlFile) (*domain.CacheControl, error) {
+	if raw == nil {
+		return nil, nil
+	}
+
+	cacheType := strings.TrimSpace(raw.Type)
+	if cacheType == "" {
+		return nil, errors.New("type is required")
+	}
+	if domain.CacheControlType(cacheType) != domain.CacheControlEphemeral {
+		return nil, fmt.Errorf("unsupported type %q", cacheType)
+	}
+
+	ttl := strings.TrimSpace(raw.TTL)
+	if ttl != "" && ttl != "1h" {
+		return nil, fmt.Errorf("unsupported ttl %q", ttl)
+	}
+
+	return &domain.CacheControl{
+		Type: domain.CacheControlType(cacheType),
+		TTL:  ttl,
+	}, nil
+}
+
 func isValidOutputFormat(f domain.OutputFormat) bool {
 	switch f {
 	case domain.FormatText, domain.FormatMarkdown, domain.FormatJSON:

internal/promptdef/repository_test.go

@@ -68,6 +68,44 @@ func TestFilesystemRepository_GetPromptDefinition(t *testing.T) {
 		}
 	})
 
+	t.Run("valid cache control with ttl", func(t *testing.T) {
+		p, err := repo.GetPromptDefinition(ctx, "valid-cache-control-ttl", "")
+		if err != nil {
+			t.Fatalf("expected no error, got %v", err)
+		}
+		if len(p.Templates) != 2 {
+			t.Fatalf("expected 2 messages, got %d", len(p.Templates))
+		}
+		assertCacheControl(t, p.Templates[0].CacheControl, domain.CacheControlEphemeral, "1h")
+		if p.Templates[1].CacheControl != nil {
+			t.Fatalf("expected second message cache control to be nil, got %#v", p.Templates[1].CacheControl)
+		}
+	})
+
+	t.Run("valid cache control without ttl", func(t *testing.T) {
+		p, err := repo.GetPromptDefinition(ctx, "valid-cache-control-without-ttl", "")
+		if err != nil {
+			t.Fatalf("expected no error, got %v", err)
+		}
+		if len(p.Templates) != 2 {
+			t.Fatalf("expected 2 messages, got %d", len(p.Templates))
+		}
+		assertCacheControl(t, p.Templates[0].CacheControl, domain.CacheControlEphemeral, "")
+		if p.Templates[1].CacheControl != nil {
+			t.Fatalf("expected second message cache control to be nil, got %#v", p.Templates[1].CacheControl)
+		}
+	})
+
+	t.Run("valid session id template", func(t *testing.T) {
+		p, err := repo.GetPromptDefinition(ctx, "valid-session-id", "")
+		if err != nil {
+			t.Fatalf("expected no error, got %v", err)
+		}
+		if p.SessionID != "{{ .session_id }}" {
+			t.Fatalf("expected trimmed session_id template, got %q", p.SessionID)
+		}
+	})
+
 	t.Run("valid nested file-backed prompt resolves content file relative to nested YAML", func(t *testing.T) {
 		nestedDir := filepath.Join(tmpDir, "dnd", "recap")
 		if err := os.MkdirAll(nestedDir, 0o755); err != nil {
@@ -258,6 +296,10 @@ output:
 		{name: "invalid validation mode", id: "invalid_validation_mode", targetErr: ErrInvalidPromptDefinition, errSubstrs: []string{"invalid validation mode"}},
 		{name: "json_schema without schema_path", id: "json_schema_without_schema_path", targetErr: ErrInvalidPromptDefinition, errSubstrs: []string{"schema_path"}},
 		{name: "unknown input field", id: "unknown_input_field", targetErr: ErrInvalidYAML, errSubstrs: []string{"field unknown_input_setting not found"}},
+		{name: "empty cache control type", id: "empty_cache_control_type", targetErr: ErrInvalidPromptDefinition, errSubstrs: []string{"cache_control", "type is required"}},
+		{name: "unsupported cache control type", id: "unsupported_cache_control_type", targetErr: ErrInvalidPromptDefinition, errSubstrs: []string{"cache_control", "unsupported type"}},
+		{name: "unsupported cache control ttl", id: "unsupported_cache_control_ttl", targetErr: ErrInvalidPromptDefinition, errSubstrs: []string{"cache_control", "unsupported ttl"}},
+		{name: "unknown cache control field", id: "unknown_cache_control_field", targetErr: ErrInvalidYAML, errSubstrs: []string{"field unexpected not found"}},
 	}
 
 	for _, tc := range cases {
@@ -282,6 +324,19 @@ output:
 	})
 }
 
+func assertCacheControl(t *testing.T, got *domain.CacheControl, wantType domain.CacheControlType, wantTTL string) {
+	t.Helper()
+	if got == nil {
+		t.Fatal("expected cache control, got nil")
+	}
+	if got.Type != wantType {
+		t.Fatalf("unexpected cache control type: got %q want %q", got.Type, wantType)
+	}
+	if got.TTL != wantTTL {
+		t.Fatalf("unexpected cache control ttl: got %q want %q", got.TTL, wantTTL)
+	}
+}
+
 func writePromptTestFile(t *testing.T, path string, content string) {
 	t.Helper()
 	if err := os.WriteFile(path, []byte(strings.TrimLeft(content, "\n")), 0o644); err != nil {

internal/promptdef/testdata/empty_cache_control_type.yaml

@@ -0,0 +1,10 @@
+id: empty-cache-control-type
+version: "1.0.0"
+messages:
+  - role: system
+    content: "Use cached instructions."
+    cache_control: {}
+output:
+  format: markdown
+  validation_mode: basic
+  repair_attempts: 0

internal/promptdef/testdata/unknown_cache_control_field.yaml

@@ -0,0 +1,12 @@
+id: unknown-cache-control-field
+version: "1.0.0"
+messages:
+  - role: system
+    content: "Use cached instructions."
+    cache_control:
+      type: ephemeral
+      unexpected: true
+output:
+  format: markdown
+  validation_mode: basic
+  repair_attempts: 0

internal/promptdef/testdata/unsupported_cache_control_ttl.yaml

@@ -0,0 +1,12 @@
+id: unsupported-cache-control-ttl
+version: "1.0.0"
+messages:
+  - role: system
+    content: "Use cached instructions."
+    cache_control:
+      type: ephemeral
+      ttl: 5m
+output:
+  format: markdown
+  validation_mode: basic
+  repair_attempts: 0

internal/promptdef/testdata/unsupported_cache_control_type.yaml

@@ -0,0 +1,11 @@
+id: unsupported-cache-control-type
+version: "1.0.0"
+messages:
+  - role: system
+    content: "Use cached instructions."
+    cache_control:
+      type: persistent
+output:
+  format: markdown
+  validation_mode: basic
+  repair_attempts: 0

internal/promptdef/testdata/valid_cache_control_ttl.yaml

@@ -0,0 +1,14 @@
+id: valid-cache-control-ttl
+version: "1.0.0"
+messages:
+  - role: system
+    content: "Use cached instructions."
+    cache_control:
+      type: ephemeral
+      ttl: 1h
+  - role: user
+    content: "Summarize the input."
+output:
+  format: markdown
+  validation_mode: basic
+  repair_attempts: 0

internal/promptdef/testdata/valid_cache_control_without_ttl.yaml

@@ -0,0 +1,13 @@
+id: valid-cache-control-without-ttl
+version: "1.0.0"
+messages:
+  - role: system
+    content: "Use cached instructions."
+    cache_control:
+      type: ephemeral
+  - role: user
+    content: "Summarize the input."
+output:
+  format: markdown
+  validation_mode: basic
+  repair_attempts: 0

internal/promptdef/testdata/valid_session_id.yaml

@@ -0,0 +1,10 @@
+id: valid-session-id
+version: "1.0.0"
+session_id: "  {{ .session_id }}  "
+messages:
+  - role: user
+    content: Hello.
+output:
+  format: markdown
+  validation_mode: basic
+  repair_attempts: 0

internal/usecase/runner.go

@@ -90,11 +90,15 @@ func (r *Runner) Run(ctx context.Context, req domain.RunRequest) (*domain.RunRes
 	}
 
 	genResp, err := r.llm.Generate(ctx, domain.GenerateRequest{
-		Prompt:           domain.RenderedPrompt{Messages: prepared.Messages},
+		Prompt:           domain.RenderedPrompt{SessionID: prepared.SessionID, Messages: prepared.Messages},
 		Target:           prepared.EffectiveModelParams,
+		TargetPresence:   prepared.TargetPresence,
 		StructuredOutput: prepared.StructuredOutput,
 	})
 	if err != nil {
+		if errors.Is(err, llm.ErrInvalidRequest) {
+			return nil, fmt.Errorf("%w: %w", ErrInvalidRequest, err)
+		}
 		return nil, fmt.Errorf("%w: %w", ErrLLMGenerate, err)
 	}
 
@@ -187,7 +191,10 @@ func (r *Runner) Prepare(ctx context.Context, req domain.RunRequest) (*domain.Pr
 		return nil, fmt.Errorf("%w: %w", ErrProfileLoad, err)
 	}
 
-	effectiveModel := resolveExecutionTarget(execProfile, req.Execution)
+	effectiveModel, targetPresence, err := resolveExecutionTarget(execProfile, req.Execution)
+	if err != nil {
+		return nil, fmt.Errorf("%w: %w", ErrInvalidRequest, err)
+	}
 	if strings.TrimSpace(effectiveModel.Endpoint) == "" {
 		return nil, fmt.Errorf("%w: execution endpoint is required", ErrInvalidRequest)
 	}
@@ -230,9 +237,11 @@ func (r *Runner) Prepare(ctx context.Context, req domain.RunRequest) (*domain.Pr
 		PromptHash:           promptDefinitionHash,
 		SelectedProfileID:    selectedProfileID,
 		EffectiveModelParams: effectiveModel,
+		TargetPresence:       targetPresence,
 		OutputContract:       effectiveContract,
 		StructuredOutput:     structuredOutput,
 		InputHashes:          inputHashes,
+		SessionID:            renderedPrompt.SessionID,
 		RenderedPromptHash:   hashRenderedPrompt(*renderedPrompt),
 		Messages:             renderedPrompt.Messages,
 		StartTime:            start,
@@ -354,22 +363,75 @@ func mergeExecutionTarget(base domain.ExecutionTarget, override domain.Execution
 		out.APIKeyEnv = override.APIKeyEnv
 	}
 	if len(override.ExtraParams) > 0 {
-		cp := make(map[string]string, len(override.ExtraParams))
-		for k, v := range override.ExtraParams {
-			cp[k] = v
-		}
-		out.ExtraParams = cp
+		out.ExtraParams = copyExtraParams(override.ExtraParams)
 	}
 	return out
 }
 
-func resolveExecutionTarget(profileValue *domain.ExecutionProfile, override *domain.ExecutionTarget) domain.ExecutionTarget {
+func mergeExecutionTargetOverride(base domain.ExecutionTarget, override domain.ExecutionTargetOverride) (domain.ExecutionTarget, domain.ExecutionTargetPresence, error) {
+	out := base
+	var presence domain.ExecutionTargetPresence
+	if override.Endpoint != "" {
+		out.Endpoint = override.Endpoint
+	}
+	if override.Model != "" {
+		out.Model = override.Model
+	}
+	if override.Temperature != nil {
+		if *override.Temperature < 0 || *override.Temperature > 2 {
+			return domain.ExecutionTarget{}, domain.ExecutionTargetPresence{}, errors.New("temperature must be between 0 and 2")
+		}
+		out.Temperature = *override.Temperature
+		presence.Temperature = true
+	}
+	if override.MaxTokens != nil {
+		if *override.MaxTokens < 0 {
+			return domain.ExecutionTarget{}, domain.ExecutionTargetPresence{}, errors.New("max_tokens must be greater than or equal to 0")
+		}
+		out.MaxTokens = *override.MaxTokens
+		presence.MaxTokens = true
+	}
+	if override.TopP != nil {
+		if *override.TopP < 0 || *override.TopP > 1 {
+			return domain.ExecutionTarget{}, domain.ExecutionTargetPresence{}, errors.New("top_p must be between 0 and 1")
+		}
+		out.TopP = *override.TopP
+		presence.TopP = true
+	}
+	if override.TimeoutSeconds != nil {
+		if *override.TimeoutSeconds < 0 {
+			return domain.ExecutionTarget{}, domain.ExecutionTargetPresence{}, errors.New("timeout_seconds must be greater than or equal to 0")
+		}
+		out.TimeoutSeconds = *override.TimeoutSeconds
+		presence.TimeoutSeconds = true
+	}
+	if strings.TrimSpace(override.ServiceTier) != "" {
+		out.ServiceTier = override.ServiceTier
+	}
+	if strings.TrimSpace(override.ReasoningEffort) != "" {
+		out.ReasoningEffort = override.ReasoningEffort
+	}
+	if strings.TrimSpace(override.APIKeyEnv) != "" {
+		out.APIKeyEnv = override.APIKeyEnv
+	}
+	if len(override.ExtraParams) > 0 {
+		out.ExtraParams = copyExtraParams(override.ExtraParams)
+	}
+	return out, presence, nil
+}
+
+func resolveExecutionTarget(profileValue *domain.ExecutionProfile, override *domain.ExecutionTargetOverride) (domain.ExecutionTarget, domain.ExecutionTargetPresence, error) {
 	out := defaults.ExecutionTargetDefault()
 	out = mergeExecutionTarget(out, executionProfileToTarget(profileValue))
+	var presence domain.ExecutionTargetPresence
 	if override != nil {
-		out = mergeExecutionTarget(out, *override)
+		var err error
+		out, presence, err = mergeExecutionTargetOverride(out, *override)
+		if err != nil {
+			return domain.ExecutionTarget{}, domain.ExecutionTargetPresence{}, err
+		}
 	}
-	return out
+	return out, presence, nil
 }
 
 func validateAPIKeyEnv(apiKeyEnv string) error {
@@ -387,13 +449,6 @@ func executionProfileToTarget(p *domain.ExecutionProfile) domain.ExecutionTarget
 	if p == nil {
 		return domain.ExecutionTarget{}
 	}
-	cp := map[string]string(nil)
-	if len(p.ExtraParams) > 0 {
-		cp = make(map[string]string, len(p.ExtraParams))
-		for k, v := range p.ExtraParams {
-			cp[k] = v
-		}
-	}
 	return domain.ExecutionTarget{
 		Endpoint:        p.Endpoint,
 		Model:           p.Model,
@@ -404,10 +459,21 @@ func executionProfileToTarget(p *domain.ExecutionProfile) domain.ExecutionTarget
 		ServiceTier:     p.ServiceTier,
 		ReasoningEffort: p.ReasoningEffort,
 		APIKeyEnv:       p.APIKeyEnv,
-		ExtraParams:     cp,
+		ExtraParams:     copyExtraParams(p.ExtraParams),
 	}
 }
 
+func copyExtraParams(src map[string]any) map[string]any {
+	if len(src) == 0 {
+		return nil
+	}
+	cp := make(map[string]any, len(src))
+	for k, v := range src {
+		cp[k] = v
+	}
+	return cp
+}
+
 func resolveOutputContract(def *domain.PromptDefinition, override *domain.OutputContract) domain.OutputContract {
 	contract := def.Validation
 	if contract.Format == "" {
@@ -424,10 +490,23 @@ func resolveOutputContract(def *domain.PromptDefinition, override *domain.Output
 
 func hashRenderedPrompt(p domain.RenderedPrompt) string {
 	var b strings.Builder
+	if p.SessionID != "" {
+		b.WriteString("session_id=")
+		b.WriteString(p.SessionID)
+		b.WriteString("\n---\n")
+	}
 	for _, msg := range p.Messages {
 		b.WriteString(msg.Role)
 		b.WriteByte('\n')
 		b.WriteString(msg.Content)
+		if msg.CacheControl != nil {
+			b.WriteString("\ncache_control.type=")
+			b.WriteString(string(msg.CacheControl.Type))
+			if msg.CacheControl.TTL != "" {
+				b.WriteString("\ncache_control.ttl=")
+				b.WriteString(msg.CacheControl.TTL)
+			}
+		}
 		b.WriteString("\n---\n")
 	}
 	h := sha256.Sum256([]byte(b.String()))

internal/usecase/runner_test.go

@@ -14,6 +14,7 @@ import (
 
 	"gitea.maximumdirect.net/eric/scriptorium/internal/defaults"
 	"gitea.maximumdirect.net/eric/scriptorium/internal/domain"
+	"gitea.maximumdirect.net/eric/scriptorium/internal/llm"
 	"gitea.maximumdirect.net/eric/scriptorium/internal/profile"
 	"gitea.maximumdirect.net/eric/scriptorium/internal/prompt"
 	"gitea.maximumdirect.net/eric/scriptorium/internal/promptdef"
@@ -160,7 +161,7 @@ func TestRunnerPrepareWithExplicitProfileSelection(t *testing.T) {
 		"a://t": {Body: []byte("transcript"), Hash: hashString("transcript")},
 		"a://g": {Body: []byte("glossary"), Hash: hashString("glossary")},
 	}}
-	renderer := &fakeRenderer{rendered: &domain.RenderedPrompt{Messages: []domain.RenderedMessage{{Role: "system", Content: "sys"}, {Role: "user", Content: "usr"}}}}
+	renderer := &fakeRenderer{rendered: &domain.RenderedPrompt{SessionID: "session-123", Messages: []domain.RenderedMessage{{Role: "system", Content: "sys"}, {Role: "user", Content: "usr"}}}}
 	llmClient := &fakeLLM{forbid: true}
 
 	runner := NewRunner(promptRepo, execRepo, reader, renderer, llmClient, nil)
@@ -172,7 +173,7 @@ func TestRunnerPrepareWithExplicitProfileSelection(t *testing.T) {
 			"transcript": {Type: domain.ArtifactRefFile, URI: "a://t"},
 			"glossary":   {Type: domain.ArtifactRefFile, URI: "a://g"},
 		},
-		Execution: &domain.ExecutionTarget{Endpoint: "http://override/v1", Model: "m", Temperature: 0.3, TimeoutSeconds: 90},
+		Execution: &domain.ExecutionTargetOverride{Endpoint: "http://override/v1", Model: "m", Temperature: float64Ptr(0.3), TimeoutSeconds: intPtr(90)},
 	})
 	if err != nil {
 		t.Fatalf("expected no error, got %v", err)
@@ -198,6 +199,9 @@ func TestRunnerPrepareWithExplicitProfileSelection(t *testing.T) {
 	if len(prepared.Messages) != 2 {
 		t.Fatalf("expected two messages, got %d", len(prepared.Messages))
 	}
+	if prepared.SessionID != "session-123" {
+		t.Fatalf("expected prepared session id, got %q", prepared.SessionID)
+	}
 	if llmClient.calls != 0 {
 		t.Fatalf("prepare should not call llm, calls=%d", llmClient.calls)
 	}
@@ -269,11 +273,11 @@ func TestRunnerPrepareRuntimeOverrideBeatsSelectedProfileValue(t *testing.T) {
 		PromptID:  "p",
 		ProfileID: "exec",
 		Inputs:    singleInputRef(),
-		Execution: &domain.ExecutionTarget{
+		Execution: &domain.ExecutionTargetOverride{
 			Endpoint:       "http://override/v1",
 			Model:          "override-model",
-			Temperature:    0.7,
-			TimeoutSeconds: 30,
+			Temperature:    float64Ptr(0.7),
+			TimeoutSeconds: intPtr(30),
 			ServiceTier:    "flex",
 		},
 	})
@@ -291,6 +295,143 @@ func TestRunnerPrepareRuntimeOverrideBeatsSelectedProfileValue(t *testing.T) {
 	}
 }
 
+func TestRunnerPrepareRequestNumericOverridePresence(t *testing.T) {
+	tests := []struct {
+		name            string
+		override        *domain.ExecutionTargetOverride
+		wantTemperature float64
+		wantMaxTokens   int
+		wantTopP        float64
+		wantTimeoutSecs int
+		wantPresence    domain.ExecutionTargetPresence
+	}{
+		{
+			name:            "omitted preserves profile values",
+			override:        &domain.ExecutionTargetOverride{},
+			wantTemperature: 0.7,
+			wantMaxTokens:   321,
+			wantTopP:        0.8,
+			wantTimeoutSecs: 45,
+		},
+		{
+			name:            "explicit zero temperature",
+			override:        &domain.ExecutionTargetOverride{Temperature: float64Ptr(0)},
+			wantTemperature: 0,
+			wantMaxTokens:   321,
+			wantTopP:        0.8,
+			wantTimeoutSecs: 45,
+			wantPresence:    domain.ExecutionTargetPresence{Temperature: true},
+		},
+		{
+			name:            "explicit zero max tokens",
+			override:        &domain.ExecutionTargetOverride{MaxTokens: intPtr(0)},
+			wantTemperature: 0.7,
+			wantMaxTokens:   0,
+			wantTopP:        0.8,
+			wantTimeoutSecs: 45,
+			wantPresence:    domain.ExecutionTargetPresence{MaxTokens: true},
+		},
+		{
+			name:            "explicit zero top p",
+			override:        &domain.ExecutionTargetOverride{TopP: float64Ptr(0)},
+			wantTemperature: 0.7,
+			wantMaxTokens:   321,
+			wantTopP:        0,
+			wantTimeoutSecs: 45,
+			wantPresence:    domain.ExecutionTargetPresence{TopP: true},
+		},
+		{
+			name:            "explicit zero timeout",
+			override:        &domain.ExecutionTargetOverride{TimeoutSeconds: intPtr(0)},
+			wantTemperature: 0.7,
+			wantMaxTokens:   321,
+			wantTopP:        0.8,
+			wantTimeoutSecs: 0,
+			wantPresence:    domain.ExecutionTargetPresence{TimeoutSeconds: true},
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			runner := NewRunner(
+				&fakePromptRepo{def: promptDef(domain.FormatText, domain.ValidationNone, 0)},
+				&fakeExecutionProfileRepo{profiles: map[string]*domain.ExecutionProfile{
+					"exec": {
+						ID:             "exec",
+						Endpoint:       "http://profile/v1",
+						Model:          "profile-model",
+						Temperature:    0.7,
+						MaxTokens:      321,
+						TopP:           0.8,
+						TimeoutSeconds: 45,
+					},
+				}},
+				defaultArtifactReader(),
+				defaultRenderer(),
+				&fakeLLM{forbid: true},
+				nil,
+			)
+
+			prepared, err := runner.Prepare(context.Background(), domain.RunRequest{
+				PromptID:  "p",
+				ProfileID: "exec",
+				Inputs:    singleInputRef(),
+				Execution: tc.override,
+			})
+			if err != nil {
+				t.Fatalf("expected no error, got %v", err)
+			}
+			got := prepared.EffectiveModelParams
+			if got.Temperature != tc.wantTemperature ||
+				got.MaxTokens != tc.wantMaxTokens ||
+				got.TopP != tc.wantTopP ||
+				got.TimeoutSeconds != tc.wantTimeoutSecs {
+				t.Fatalf("unexpected effective numeric settings: %+v", got)
+			}
+			if prepared.TargetPresence != tc.wantPresence {
+				t.Fatalf("unexpected target presence: got %+v want %+v", prepared.TargetPresence, tc.wantPresence)
+			}
+		})
+	}
+}
+
+func TestRunnerPrepareInvalidRequestNumericOverridesFail(t *testing.T) {
+	tests := []struct {
+		name     string
+		override *domain.ExecutionTargetOverride
+	}{
+		{name: "temperature below range", override: &domain.ExecutionTargetOverride{Temperature: float64Ptr(-0.1)}},
+		{name: "temperature above range", override: &domain.ExecutionTargetOverride{Temperature: float64Ptr(2.1)}},
+		{name: "max tokens below range", override: &domain.ExecutionTargetOverride{MaxTokens: intPtr(-1)}},
+		{name: "top p below range", override: &domain.ExecutionTargetOverride{TopP: float64Ptr(-0.1)}},
+		{name: "top p above range", override: &domain.ExecutionTargetOverride{TopP: float64Ptr(1.1)}},
+		{name: "timeout below range", override: &domain.ExecutionTargetOverride{TimeoutSeconds: intPtr(-1)}},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			runner := NewRunner(
+				&fakePromptRepo{def: promptDef(domain.FormatText, domain.ValidationNone, 0)},
+				&fakeExecutionProfileRepo{profiles: map[string]*domain.ExecutionProfile{"exec": defaultExecutionProfile()}},
+				defaultArtifactReader(),
+				defaultRenderer(),
+				&fakeLLM{forbid: true},
+				nil,
+			)
+
+			_, err := runner.Prepare(context.Background(), domain.RunRequest{
+				PromptID:  "p",
+				ProfileID: "exec",
+				Inputs:    singleInputRef(),
+				Execution: tc.override,
+			})
+			if !errors.Is(err, ErrInvalidRequest) {
+				t.Fatalf("expected ErrInvalidRequest, got %v", err)
+			}
+		})
+	}
+}
+
 func TestRunnerPrepareSelectedProfileBeatsBuiltInDefault(t *testing.T) {
 	promptRepo := &fakePromptRepo{def: promptDef(domain.FormatText, domain.ValidationNone, 0)}
 	execRepo := &fakeExecutionProfileRepo{profiles: map[string]*domain.ExecutionProfile{
@@ -577,6 +718,100 @@ func TestDeriveStructuredSchemaName(t *testing.T) {
 	}
 }
 
+func TestHashRenderedPromptIncludesCacheControlWhenPresent(t *testing.T) {
+	uncached := domain.RenderedPrompt{Messages: []domain.RenderedMessage{
+		{Role: "system", Content: "sys"},
+		{Role: "user", Content: "usr"},
+	}}
+	wantLegacyHash := hashString("system\nsys\n---\nuser\nusr\n---\n")
+	if got := hashRenderedPrompt(uncached); got != wantLegacyHash {
+		t.Fatalf("expected no-cache hash to preserve legacy input, got %q want %q", got, wantLegacyHash)
+	}
+
+	withCache := domain.RenderedPrompt{Messages: []domain.RenderedMessage{
+		{
+			Role:    "system",
+			Content: "sys",
+			CacheControl: &domain.CacheControl{
+				Type: domain.CacheControlEphemeral,
+				TTL:  "1h",
+			},
+		},
+		{Role: "user", Content: "usr"},
+	}}
+	alsoWithCache := domain.RenderedPrompt{Messages: []domain.RenderedMessage{
+		{
+			Role:    "system",
+			Content: "sys",
+			CacheControl: &domain.CacheControl{
+				Type: domain.CacheControlEphemeral,
+				TTL:  "1h",
+			},
+		},
+		{Role: "user", Content: "usr"},
+	}}
+	withoutTTL := domain.RenderedPrompt{Messages: []domain.RenderedMessage{
+		{
+			Role:    "system",
+			Content: "sys",
+			CacheControl: &domain.CacheControl{
+				Type: domain.CacheControlEphemeral,
+			},
+		},
+		{Role: "user", Content: "usr"},
+	}}
+
+	cachedHash := hashRenderedPrompt(withCache)
+	if cachedHash == hashRenderedPrompt(uncached) {
+		t.Fatal("expected cache control to change rendered prompt hash")
+	}
+	if cachedHash != hashRenderedPrompt(alsoWithCache) {
+		t.Fatal("expected identical cache control metadata to produce stable hash")
+	}
+	if cachedHash == hashRenderedPrompt(withoutTTL) {
+		t.Fatal("expected ttl changes to affect rendered prompt hash")
+	}
+}
+
+func TestHashRenderedPromptIncludesSessionIDWhenPresent(t *testing.T) {
+	withoutSession := domain.RenderedPrompt{Messages: []domain.RenderedMessage{
+		{Role: "system", Content: "sys"},
+		{Role: "user", Content: "usr"},
+	}}
+	withSession := domain.RenderedPrompt{
+		SessionID: "session-123",
+		Messages: []domain.RenderedMessage{
+			{Role: "system", Content: "sys"},
+			{Role: "user", Content: "usr"},
+		},
+	}
+	alsoWithSession := domain.RenderedPrompt{
+		SessionID: "session-123",
+		Messages: []domain.RenderedMessage{
+			{Role: "system", Content: "sys"},
+			{Role: "user", Content: "usr"},
+		},
+	}
+	otherSession := domain.RenderedPrompt{
+		SessionID: "session-456",
+		Messages: []domain.RenderedMessage{
+			{Role: "system", Content: "sys"},
+			{Role: "user", Content: "usr"},
+		},
+	}
+
+	sessionHash := hashRenderedPrompt(withSession)
+	if sessionHash == hashRenderedPrompt(withoutSession) {
+		t.Fatal("expected session_id to change rendered prompt hash")
+	}
+	if sessionHash != hashRenderedPrompt(alsoWithSession) {
+		t.Fatal("expected identical session_id to produce stable hash")
+	}
+	if sessionHash == hashRenderedPrompt(otherSession) {
+		t.Fatal("expected session_id value changes to affect rendered prompt hash")
+	}
+}
+
 func TestRunnerRunSuccessful(t *testing.T) {
 	promptRepo := &fakePromptRepo{def: promptDef(domain.FormatMarkdown, domain.ValidationBasic, 0)}
 	execRepo := &fakeExecutionProfileRepo{profiles: map[string]*domain.ExecutionProfile{"exec": defaultExecutionProfile()}}
@@ -584,7 +819,7 @@ func TestRunnerRunSuccessful(t *testing.T) {
 		"a://t": {Body: []byte("transcript"), Hash: hashString("transcript")},
 		"a://g": {Body: []byte("glossary"), Hash: hashString("glossary")},
 	}}
-	renderer := &fakeRenderer{rendered: &domain.RenderedPrompt{Messages: []domain.RenderedMessage{{Role: "system", Content: "sys"}, {Role: "user", Content: "usr"}}}}
+	renderer := &fakeRenderer{rendered: &domain.RenderedPrompt{SessionID: "session-123", Messages: []domain.RenderedMessage{{Role: "system", Content: "sys"}, {Role: "user", Content: "usr"}}}}
 	llmClient := &fakeLLM{resp: &domain.GenerateResponse{Content: "# recap", Usage: domain.TokenUsage{TotalTokens: 7}}}
 
 	runner := NewRunner(promptRepo, execRepo, reader, renderer, llmClient, nil)
@@ -596,7 +831,7 @@ func TestRunnerRunSuccessful(t *testing.T) {
 			"transcript": {Type: domain.ArtifactRefFile, URI: "a://t"},
 			"glossary":   {Type: domain.ArtifactRefFile, URI: "a://g"},
 		},
-		Execution: &domain.ExecutionTarget{Endpoint: "http://override/v1", Model: "m", Temperature: 0.3, TimeoutSeconds: 90},
+		Execution: &domain.ExecutionTargetOverride{Endpoint: "http://override/v1", Model: "m", Temperature: float64Ptr(0.3), TimeoutSeconds: intPtr(90)},
 	})
 	if err != nil {
 		t.Fatalf("expected no error, got %v", err)
@@ -631,6 +866,48 @@ func TestRunnerRunSuccessful(t *testing.T) {
 	if llmClient.lastReq.Target.TimeoutSeconds != 90 {
 		t.Fatalf("expected timeout propagation, got %d", llmClient.lastReq.Target.TimeoutSeconds)
 	}
+	if !llmClient.lastReq.TargetPresence.Temperature || !llmClient.lastReq.TargetPresence.TimeoutSeconds {
+		t.Fatalf("expected numeric override presence to be sent to llm, got %+v", llmClient.lastReq.TargetPresence)
+	}
+	if llmClient.lastReq.Prompt.SessionID != "session-123" {
+		t.Fatalf("expected session id to be sent to llm, got %q", llmClient.lastReq.Prompt.SessionID)
+	}
+}
+
+func TestRunnerRunPassesExtraParamsToGenerateRequestTarget(t *testing.T) {
+	extraParams := map[string]any{
+		"string_value":  "enabled",
+		"number_value":  42,
+		"boolean_value": true,
+		"object_value":  map[string]any{"nested": "value"},
+		"array_value":   []any{"first", 3, false},
+	}
+	promptRepo := &fakePromptRepo{def: promptDef(domain.FormatText, domain.ValidationNone, 0)}
+	execRepo := &fakeExecutionProfileRepo{profiles: map[string]*domain.ExecutionProfile{
+		"exec": {
+			ID:          "exec",
+			Endpoint:    "http://profile/v1",
+			Model:       "profile-model",
+			ExtraParams: extraParams,
+		},
+	}}
+	llmClient := &fakeLLM{resp: &domain.GenerateResponse{Content: "ok"}}
+	runner := NewRunner(promptRepo, execRepo, defaultArtifactReader(), defaultRenderer(), llmClient, nil)
+
+	res, err := runner.Run(context.Background(), domain.RunRequest{
+		PromptID:  "p",
+		ProfileID: "exec",
+		Inputs:    singleInputRef(),
+	})
+	if err != nil {
+		t.Fatalf("expected no error, got %v", err)
+	}
+	if !reflect.DeepEqual(res.EffectiveModelParams.ExtraParams, extraParams) {
+		t.Fatalf("expected run result extra_params to match profile values, got %#v", res.EffectiveModelParams.ExtraParams)
+	}
+	if !reflect.DeepEqual(llmClient.lastReq.Target.ExtraParams, extraParams) {
+		t.Fatalf("expected generate request extra_params to match profile values, got %#v", llmClient.lastReq.Target.ExtraParams)
+	}
 }
 
 func TestRunnerRunAndPrepareResolveSameProfileAndEffectiveSettings(t *testing.T) {
@@ -649,7 +926,7 @@ func TestRunnerRunAndPrepareResolveSameProfileAndEffectiveSettings(t *testing.T)
 		Inputs: map[string]domain.ArtifactRef{
 			"transcript": {Type: domain.ArtifactRefFile, URI: "a://t"},
 		},
-		Execution: &domain.ExecutionTarget{Endpoint: "http://override/v1", Model: "m", Temperature: 0.3, TimeoutSeconds: 90},
+		Execution: &domain.ExecutionTargetOverride{Endpoint: "http://override/v1", Model: "m", Temperature: float64Ptr(0.3), TimeoutSeconds: intPtr(90)},
 	}
 
 	prepared, err := runner.Prepare(context.Background(), req)
@@ -777,11 +1054,11 @@ func TestRunnerRunExplicitRuntimeOverrideBeatsSelectedProfileValue(t *testing.T)
 		PromptID:  "p",
 		ProfileID: "exec",
 		Inputs:    singleInputRef(),
-		Execution: &domain.ExecutionTarget{
+		Execution: &domain.ExecutionTargetOverride{
 			Endpoint:       "http://override/v1",
 			Model:          "override-model",
-			Temperature:    0.7,
-			TimeoutSeconds: 30,
+			Temperature:    float64Ptr(0.7),
+			TimeoutSeconds: intPtr(30),
 			ServiceTier:    "flex",
 		},
 	})
@@ -916,7 +1193,7 @@ func TestRunnerRunRuntimeAPIKeyEnvOverrideWorks(t *testing.T) {
 		PromptID:  "p",
 		ProfileID: "exec",
 		Inputs:    singleInputRef(),
-		Execution: &domain.ExecutionTarget{APIKeyEnv: envName},
+		Execution: &domain.ExecutionTargetOverride{APIKeyEnv: envName},
 	})
 	if err != nil {
 		t.Fatalf("expected no error, got %v", err)
@@ -941,7 +1218,7 @@ func TestRunnerRunRuntimeAPIKeyEnvOverrideBeatsProfile(t *testing.T) {
 		PromptID:  "p",
 		ProfileID: "exec",
 		Inputs:    singleInputRef(),
-		Execution: &domain.ExecutionTarget{APIKeyEnv: runtimeEnv},
+		Execution: &domain.ExecutionTargetOverride{APIKeyEnv: runtimeEnv},
 	})
 	if err != nil {
 		t.Fatalf("expected no error, got %v", err)
@@ -1040,6 +1317,28 @@ func TestRunnerRunLLMFailure(t *testing.T) {
 	}
 }
 
+func TestRunnerRunLLMInvalidRequestMapsToUsecaseInvalidRequest(t *testing.T) {
+	runner := NewRunner(
+		&fakePromptRepo{def: promptDef(domain.FormatText, domain.ValidationNone, 0)},
+		&fakeExecutionProfileRepo{profiles: map[string]*domain.ExecutionProfile{"exec": defaultExecutionProfile()}},
+		defaultArtifactReader(),
+		defaultRenderer(),
+		&fakeLLM{err: llm.ErrInvalidRequest},
+		nil,
+	)
+	_, err := runner.Run(context.Background(), domain.RunRequest{
+		PromptID:  "p",
+		ProfileID: "exec",
+		Inputs:    singleInputRef(),
+	})
+	if !errors.Is(err, ErrInvalidRequest) {
+		t.Fatalf("expected ErrInvalidRequest, got %v", err)
+	}
+	if errors.Is(err, ErrLLMGenerate) {
+		t.Fatalf("did not expect ErrLLMGenerate, got %v", err)
+	}
+}
+
 func TestRunnerRunValidationStillWorks(t *testing.T) {
 	validator := &fakeValidator{result: domain.ValidationResult{Status: domain.ValidationFailed, Mode: domain.ValidationBasic, Errors: []string{"bad"}, IsValid: false}}
 	runner := NewRunner(
@@ -1082,7 +1381,7 @@ func TestRunnerRunStructuredRepairRemainsBoundedAndUsesEffectiveModelSettings(t
 		PromptID:  "p",
 		ProfileID: "exec",
 		Inputs:    singleInputRef(),
-		Execution: &domain.ExecutionTarget{Endpoint: "http://override/v1", Model: "override-model", TimeoutSeconds: 22},
+		Execution: &domain.ExecutionTargetOverride{Endpoint: "http://override/v1", Model: "override-model", TimeoutSeconds: intPtr(22)},
 	})
 	if err != nil {
 		t.Fatalf("expected no error, got %v", err)
@@ -1169,7 +1468,7 @@ func TestExecutionProfileToTargetPopulatesAllFieldsAndCopiesExtraParams(t *testi
 		ServiceTier:     "priority",
 		ReasoningEffort: "medium",
 		APIKeyEnv:       "SCRIPTORIUM_API_KEY",
-		ExtraParams: map[string]string{
+		ExtraParams: map[string]any{
 			"provider_option": "on",
 		},
 	}
@@ -1208,12 +1507,18 @@ func TestResolveExecutionTargetProfileValuesPopulateAllSupportedFields(t *testin
 		ServiceTier:     "priority",
 		ReasoningEffort: "low",
 		APIKeyEnv:       "PROFILE_KEY",
-		ExtraParams: map[string]string{
+		ExtraParams: map[string]any{
 			"profile_option": "enabled",
 		},
 	}
 
-	target := resolveExecutionTarget(profileValue, nil)
+	target, presence, err := resolveExecutionTarget(profileValue, nil)
+	if err != nil {
+		t.Fatalf("expected no error, got %v", err)
+	}
+	if presence != (domain.ExecutionTargetPresence{}) {
+		t.Fatalf("expected no request override presence, got %+v", presence)
+	}
 	if target.Endpoint != profileValue.Endpoint ||
 		target.Model != profileValue.Model ||
 		target.Temperature != profileValue.Temperature ||
@@ -1242,32 +1547,38 @@ func TestResolveExecutionTargetRuntimeOverridesBeatProfileForAllOverrideableFiel
 		ServiceTier:     "priority",
 		ReasoningEffort: "medium",
 		APIKeyEnv:       "PROFILE_KEY",
-		ExtraParams: map[string]string{
+		ExtraParams: map[string]any{
 			"profile_only": "yes",
 		},
 	}
-	override := &domain.ExecutionTarget{
+	override := &domain.ExecutionTargetOverride{
 		Endpoint:        "http://override/v1",
 		Model:           "override-model",
-		Temperature:     0.9,
-		MaxTokens:       111,
-		TopP:            0.5,
-		TimeoutSeconds:  30,
+		Temperature:     float64Ptr(0.9),
+		MaxTokens:       intPtr(111),
+		TopP:            float64Ptr(0.5),
+		TimeoutSeconds:  intPtr(30),
 		ServiceTier:     "flex",
 		ReasoningEffort: "high",
 		APIKeyEnv:       "RUNTIME_KEY",
-		ExtraParams: map[string]string{
+		ExtraParams: map[string]any{
 			"runtime_only": "yes",
 		},
 	}
 
-	target := resolveExecutionTarget(profileValue, override)
+	target, presence, err := resolveExecutionTarget(profileValue, override)
+	if err != nil {
+		t.Fatalf("expected no error, got %v", err)
+	}
+	if presence != (domain.ExecutionTargetPresence{Temperature: true, MaxTokens: true, TopP: true, TimeoutSeconds: true}) {
+		t.Fatalf("unexpected override presence: %+v", presence)
+	}
 	if target.Endpoint != override.Endpoint ||
 		target.Model != override.Model ||
-		target.Temperature != override.Temperature ||
-		target.MaxTokens != override.MaxTokens ||
-		target.TopP != override.TopP ||
-		target.TimeoutSeconds != override.TimeoutSeconds ||
+		target.Temperature != *override.Temperature ||
+		target.MaxTokens != *override.MaxTokens ||
+		target.TopP != *override.TopP ||
+		target.TimeoutSeconds != *override.TimeoutSeconds ||
 		target.ServiceTier != override.ServiceTier ||
 		target.ReasoningEffort != override.ReasoningEffort ||
 		target.APIKeyEnv != override.APIKeyEnv {
@@ -1311,12 +1622,12 @@ func TestMergeExecutionTargetEmptyStringOverridesDoNotErase(t *testing.T) {
 
 func TestMergeExecutionTargetEmptyExtraParamsDoesNotErase(t *testing.T) {
 	base := domain.ExecutionTarget{
-		ExtraParams: map[string]string{
+		ExtraParams: map[string]any{
 			"keep": "value",
 		},
 	}
 	override := domain.ExecutionTarget{
-		ExtraParams: map[string]string{},
+		ExtraParams: map[string]any{},
 	}
 
 	merged := mergeExecutionTarget(base, override)
@@ -1392,6 +1703,14 @@ func singleInputRef() map[string]domain.ArtifactRef {
 	return map[string]domain.ArtifactRef{"transcript": {Type: domain.ArtifactRefFile, URI: "a://ok"}}
 }
 
+func float64Ptr(v float64) *float64 {
+	return &v
+}
+
+func intPtr(v int) *int {
+	return &v
+}
+
 func newMinimalRunner(promptRepo *fakePromptRepo, execRepo *fakeExecutionProfileRepo) *Runner {
 	return NewRunner(
 		promptRepo,

llm_adapter.go

@@ -0,0 +1,23 @@
+package scriptorium
+
+import (
+	"context"
+	"fmt"
+
+	"gitea.maximumdirect.net/eric/scriptorium/internal/domain"
+)
+
+type publicLLMClientAdapter struct {
+	client LLMClient
+}
+
+func (a publicLLMClientAdapter) Generate(ctx context.Context, req domain.GenerateRequest) (*domain.GenerateResponse, error) {
+	resp, err := a.client.Generate(ctx, fromDomainGenerateRequest(req))
+	if err != nil {
+		return nil, err
+	}
+	if resp == nil {
+		return nil, fmt.Errorf("%w: llm client returned nil response", ErrLLMGenerate)
+	}
+	return toDomainGenerateResponse(resp), nil
+}

types.go

@@ -0,0 +1,256 @@
+package scriptorium
+
+import (
+	"context"
+	"time"
+)
+
+// ArtifactRefType defines how an artifact is referenced.
+type ArtifactRefType string
+
+const (
+	ArtifactRefInline ArtifactRefType = "inline"
+	ArtifactRefFile   ArtifactRefType = "file"
+)
+
+// OutputFormat defines the desired output format.
+type OutputFormat string
+
+const (
+	FormatText     OutputFormat = "text"
+	FormatMarkdown OutputFormat = "markdown"
+	FormatJSON     OutputFormat = "json"
+)
+
+// ValidationMode defines the output validation strategy.
+type ValidationMode string
+
+const (
+	ValidationNone       ValidationMode = "none"
+	ValidationBasic      ValidationMode = "basic"
+	ValidationJSON       ValidationMode = "json"
+	ValidationJSONSchema ValidationMode = "json_schema"
+)
+
+// ValidationStatus defines the result of a validation check.
+type ValidationStatus string
+
+const (
+	ValidationPassed  ValidationStatus = "passed"
+	ValidationFailed  ValidationStatus = "failed"
+	ValidationSkipped ValidationStatus = "skipped"
+)
+
+// CacheControlType defines provider cache behavior for prompt content.
+type CacheControlType string
+
+const (
+	CacheControlEphemeral CacheControlType = "ephemeral"
+)
+
+// StructuredOutputType identifies provider-level structured output modes.
+type StructuredOutputType string
+
+const (
+	StructuredOutputJSONSchema StructuredOutputType = "json_schema"
+)
+
+// RunRequest represents a request to prepare or run a single prompt.
+type RunRequest struct {
+	PromptID      string
+	PromptVersion string
+	ProfileID     string
+	Inputs        map[string]ArtifactRef
+	Vars          map[string]string
+	Execution     *ExecutionTargetOverride
+	Validation    *OutputContract
+	Metadata      map[string]string
+}
+
+// PreparedRun contains prepared prompt execution state. It does not include
+// resolved API key values, model output, validation results, or internal target
+// presence metadata.
+type PreparedRun struct {
+	PromptID             string                `json:"prompt_id"`
+	PromptVersion        string                `json:"prompt_version,omitempty"`
+	PromptHash           string                `json:"prompt_hash,omitempty"`
+	SelectedProfileID    string                `json:"selected_profile_id"`
+	EffectiveModelParams ExecutionTarget       `json:"effective_model_params"`
+	OutputContract       OutputContract        `json:"output_contract"`
+	StructuredOutput     *StructuredOutputSpec `json:"structured_output,omitempty"`
+	InputHashes          map[string]string     `json:"input_hashes,omitempty"`
+	SessionID            string                `json:"session_id,omitempty"`
+	RenderedPromptHash   string                `json:"rendered_prompt_hash"`
+	Messages             []RenderedMessage     `json:"messages"`
+	StartTime            time.Time             `json:"start_time,omitempty"`
+	EndTime              time.Time             `json:"end_time,omitempty"`
+	DurationMS           int64                 `json:"duration_ms,omitempty"`
+}
+
+// RunResult contains generated output, validation state, and run metadata.
+type RunResult struct {
+	RunID                string            `json:"run_id"`
+	Artifact             Artifact          `json:"artifact"`
+	RawOutput            string            `json:"raw_output"`
+	Validation           ValidationResult  `json:"validation"`
+	PromptID             string            `json:"prompt_id"`
+	PromptVersion        string            `json:"prompt_version,omitempty"`
+	PromptHash           string            `json:"prompt_hash,omitempty"`
+	RenderedPromptHash   string            `json:"rendered_prompt_hash"`
+	SelectedProfileID    string            `json:"selected_profile_id"`
+	ModelName            string            `json:"model_name"`
+	Endpoint             string            `json:"endpoint"`
+	EffectiveModelParams ExecutionTarget   `json:"effective_model_params"`
+	InputHashes          map[string]string `json:"input_hashes,omitempty"`
+	Usage                TokenUsage        `json:"usage"`
+	StartTime            time.Time         `json:"start_time,omitempty"`
+	EndTime              time.Time         `json:"end_time,omitempty"`
+	Duration             time.Duration     `json:"duration,omitempty"`
+}
+
+// ArtifactRef represents a reference to prompt input content.
+type ArtifactRef struct {
+	Type ArtifactRefType
+	URI  string
+	Body string
+}
+
+// Artifact represents loaded artifact content.
+type Artifact struct {
+	Name        string
+	ContentType string
+	Body        []byte
+	URI         string
+	Size        int64
+	Hash        string
+}
+
+// ExecutionTarget represents effective model runtime settings.
+type ExecutionTarget struct {
+	Endpoint        string         `json:"endpoint"`
+	Model           string         `json:"model"`
+	Temperature     float64        `json:"temperature"`
+	MaxTokens       int            `json:"max_tokens"`
+	TopP            float64        `json:"top_p"`
+	TimeoutSeconds  int            `json:"timeout_seconds"`
+	ServiceTier     string         `json:"service_tier"`
+	ReasoningEffort string         `json:"reasoning_effort"`
+	APIKeyEnv       string         `json:"api_key_env"`
+	ExtraParams     map[string]any `json:"extra_params"`
+}
+
+// ExecutionTargetOverride represents per-request runtime setting overrides.
+type ExecutionTargetOverride struct {
+	Endpoint        string
+	Model           string
+	Temperature     *float64
+	MaxTokens       *int
+	TopP            *float64
+	TimeoutSeconds  *int
+	ServiceTier     string
+	ReasoningEffort string
+	APIKeyEnv       string
+	ExtraParams     map[string]any
+}
+
+// ExecutionTargetPresence tracks which numeric runtime settings were explicit
+// request overrides.
+type ExecutionTargetPresence struct {
+	Temperature    bool
+	MaxTokens      bool
+	TopP           bool
+	TimeoutSeconds bool
+}
+
+// OutputContract defines output and validation requirements.
+type OutputContract struct {
+	Format         OutputFormat   `json:"format"`
+	ValidationMode ValidationMode `json:"validation_mode"`
+	SchemaPath     string         `json:"schema_path"`
+	RepairAttempts int            `json:"repair_attempts"`
+}
+
+// ValidationResult represents output validation state.
+type ValidationResult struct {
+	Status         ValidationStatus `json:"status"`
+	Mode           ValidationMode   `json:"mode"`
+	Errors         []string         `json:"errors,omitempty"`
+	SchemaPath     string           `json:"schema_path,omitempty"`
+	RepairAttempts int              `json:"repair_attempts"`
+	IsValid        bool             `json:"is_valid"`
+}
+
+// TokenUsage tracks token consumption.
+type TokenUsage struct {
+	PromptTokens     int `json:"prompt_tokens"`
+	CompletionTokens int `json:"completion_tokens"`
+	TotalTokens      int `json:"total_tokens"`
+	CachedTokens     int `json:"cached_tokens"`
+	CacheWriteTokens int `json:"cache_write_tokens"`
+}
+
+// RenderedPrompt is the fully rendered prompt passed to an LLM client.
+type RenderedPrompt struct {
+	SessionID string            `json:"session_id,omitempty"`
+	Messages  []RenderedMessage `json:"messages"`
+}
+
+// RenderedMessage is a rendered chat message.
+type RenderedMessage struct {
+	Role         string        `json:"role"`
+	Content      string        `json:"content"`
+	CacheControl *CacheControl `json:"cache_control,omitempty"`
+}
+
+// CacheControl describes provider cache metadata attached to prompt content.
+type CacheControl struct {
+	Type CacheControlType `json:"type"`
+	TTL  string           `json:"ttl,omitempty"`
+}
+
+// StructuredOutputSpec describes provider-level structured output.
+type StructuredOutputSpec struct {
+	Type       StructuredOutputType      `json:"type"`
+	JSONSchema *StructuredOutputJSONSpec `json:"json_schema,omitempty"`
+}
+
+// StructuredOutputJSONSpec contains JSON Schema output constraints.
+type StructuredOutputJSONSpec struct {
+	Name   string `json:"name"`
+	Strict bool   `json:"strict"`
+	Schema any    `json:"schema"`
+}
+
+// LLMClient executes rendered prompts for Engine.Run.
+type LLMClient interface {
+	Generate(context.Context, GenerateRequest) (*GenerateResponse, error)
+}
+
+// GenerateRequest is passed to an injected LLM client.
+type GenerateRequest struct {
+	Prompt           RenderedPrompt          `json:"prompt"`
+	Target           ExecutionTarget         `json:"target"`
+	TargetPresence   ExecutionTargetPresence `json:"target_presence"`
+	StructuredOutput *StructuredOutputSpec   `json:"structured_output,omitempty"`
+}
+
+// GenerateResponse is returned by an injected LLM client.
+type GenerateResponse struct {
+	Content string     `json:"content"`
+	Usage   TokenUsage `json:"usage"`
+}
+
+// File returns a file-backed artifact reference.
+func File(path string) ArtifactRef {
+	return ArtifactRef{Type: ArtifactRefFile, URI: path}
+}
+
+// Inline returns an inline artifact reference.
+func Inline(body string) ArtifactRef {
+	return ArtifactRef{Type: ArtifactRefInline, Body: body}
+}
+
+// InlineWithURI returns an inline artifact reference with URI metadata.
+func InlineWithURI(uri string, body string) ArtifactRef {
+	return ArtifactRef{Type: ArtifactRefInline, URI: uri, Body: body}
+}