docs: document llm runtime logs

README.md

@@ -48,6 +48,23 @@ All API requests require the configured access key:
 x-api-key: <API_ACCESS_KEY>
 ```
 
+## LLM Runtime Logs
+
+LLM calls emit regular server-side logs from `src/lib/llm/client.ts`. These logs
+are intended for local development, customer demos, and production
+troubleshooting.
+
+Example:
+
+```text
+[llm:start] provider=deepseek model=deepseek-v4-pro task=article_optimizer
+[llm:response] task=article_optimizer duration_ms=18342 raw={"title":"..."}
+[llm:validated] task=article_optimizer ok=true
+```
+
+The `raw=` field is truncated to 4000 characters to avoid log explosions. API
+keys, prompts, system messages, and environment secrets are not logged.
+
 ## Commands
 
 ```bash