docs(aicore): add Credential Rotation section to user-guide

Documents watch_aicore_config, patch_litellm_for_credential_rotation,
and the recommended startup pattern for LangGraph/ChatLiteLLM agents.

Author: tiagoek

src/sap_cloud_sdk/aicore/user-guide.md

@@ -47,6 +47,81 @@ set_aicore_config(instance_name="aicore-production")
 
 ---
 
+## Credential Rotation
+
+BTP rotates AI Core service binding credentials automatically. The SDK
+handles this transparently — no pod restart required.
+
+### Reactive reload (completion wrapper)
+
+`sap_cloud_sdk.aicore.completion` / `acompletion` catch `AuthenticationError`
+(HTTP 401), reload credentials via `set_aicore_config()`, and retry the call
+once. The caller never sees the error.
+
+```python
+from sap_cloud_sdk.aicore import completion, set_aicore_config
+
+set_aicore_config()
+
+# 401s are retried transparently — no extra code needed
+response = completion(model="sap/anthropic--claude-4.5-sonnet", messages=[...])
+```
+
+### Proactive reload (recommended for all agents)
+
+`watch_aicore_config()` starts a daemon thread that polls the mounted secret
+directory every 60 seconds. When the directory mtime changes (Kubernetes
+performs an atomic symlink swap on rotation), it calls `set_aicore_config()`
+before the cached OAuth token expires — so agents never see a 401 at all.
+
+```python
+import threading
+from sap_cloud_sdk.aicore import set_aicore_config, watch_aicore_config
+
+set_aicore_config()          # load credentials at startup
+watch_aicore_config()        # proactive reload on secret rotation
+
+# Optional: stop cleanly at shutdown
+_stop = threading.Event()
+watch_aicore_config(stop_event=_stop)
+# at shutdown: _stop.set()
+```
+
+### LangGraph / ChatLiteLLM agents
+
+`ChatLiteLLM` (used in LangGraph agent templates) calls `litellm.completion`
+directly, bypassing the SDK's reactive handler. Two options:
+
+**Option A — proactive watcher only (recommended, one line):**
+
+```python
+from sap_cloud_sdk.aicore import set_aicore_config, watch_aicore_config
+
+set_aicore_config()
+watch_aicore_config()   # ADD THIS — no other changes needed
+```
+
+**Option B — also add reactive reload for ChatLiteLLM:**
+
+```python
+from sap_cloud_sdk.aicore import (
+    set_aicore_config,
+    patch_litellm_for_credential_rotation,
+    watch_aicore_config,
+)
+
+set_aicore_config()
+patch_litellm_for_credential_rotation()   # patches litellm.completion globally
+watch_aicore_config()
+```
+
+`patch_litellm_for_credential_rotation()` wraps `litellm.completion` /
+`litellm.acompletion` globally so every caller in the process — including
+`ChatLiteLLM` — gets transparent 401 reload. Idempotent; call it once at
+startup.
+
+---
+
 ## What It Does
 
 The `set_aicore_config()` function: