docs(aicore): document proxy mode and destination mode routing in user-guide

Author: tiagoek

src/sap_cloud_sdk/aicore/user-guide.md

@@ -47,6 +47,60 @@ set_aicore_config(instance_name="aicore-production")
 
 ---
 
+## Routing Modes
+
+`set_aicore_config()` detects which routing mode to activate based on environment variables.
+**Agent code is identical in all three modes** — the deployer controls routing by choosing which
+env vars to inject.
+
+### Direct mode (default)
+
+No extra env vars required. Credentials are loaded from the mounted K8s secret volume
+(`/etc/secrets/appfnd/aicore/<instance>/`) or from `AICORE_*` environment variables.
+This is the standard mode for agents deployed on BTP managed runtime.
+
+```python
+set_aicore_config()  # reads mounted secret or AICORE_* env vars
+```
+
+### Proxy mode (`AICORE_PROXY_URL`)
+
+Set `AICORE_PROXY_URL` to route all LiteLLM calls through a LiteLLM-compatible proxy.
+No AI Core credentials are written to the process environment — the proxy handles
+authentication. Optionally set `AICORE_PROXY_API_KEY` for proxy-level auth.
+
+```bash
+# Injected by the deployer (e.g. K8s ConfigMap / Helm values)
+AICORE_PROXY_URL=https://your-litellm-proxy.example.com
+AICORE_PROXY_API_KEY=sk-...  # optional
+```
+
+```python
+set_aicore_config()  # detects AICORE_PROXY_URL, sets litellm.api_base
+# AICORE_CLIENT_SECRET is NOT written to env in this mode
+```
+
+Model strings (`sap/<model>`) are passed verbatim — no rewriting.
+
+### Destination mode (`AICORE_DESTINATION_NAME`)
+
+Set `AICORE_DESTINATION_NAME` to load AI Core credentials at startup from a BTP Destination
+Service destination. The deployer only needs to inject Destination Service binding credentials;
+the AI Core `client_secret` never needs to be in the K8s Secret directly.
+
+```bash
+AICORE_DESTINATION_NAME=aicore-destination  # name of the BTP destination
+```
+
+```python
+set_aicore_config()  # calls Destination Service, writes AICORE_* env vars
+```
+
+The destination must use **OAuth2ClientCredentials** authentication with `clientId`,
+`clientSecret`, and `tokenServiceURL` as destination configuration properties.
+
+---
+
 ## Credential Rotation
 
 BTP rotates AI Core service binding credentials automatically. The SDK