Document prompt cache control behavior

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: