diff --git a/agents.md b/agents.md
index ed9b933..8c56fbc 100644
--- a/agents.md
+++ b/agents.md
@@ -1,4 +1,3 @@
 # Agents Upgrade Plan
 
-- docs: clarify cloud vs local env configuration (api key precedence, insecure toggle) in configuration guide
 - ci: add targeted regression job for ollama providers covering chat, streaming, and tool execution paths
diff --git a/docs/configuration.md b/docs/configuration.md
index 9ae2e68..59fe7b7 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -198,7 +198,12 @@ list_ttl_secs = 60
 default_context_window = 8192
 ```
 
-Requests target the same `/api/chat` endpoint documented by Ollama and automatically include the API key using a `Bearer` authorization header. If you prefer not to store the key in the config file, either rely on `api_key_env` or export the `OLLAMA_API_KEY` environment variable manually (legacy names `OLLAMA_CLOUD_API_KEY` and `OWLEN_OLLAMA_CLOUD_API_KEY` continue to work, but Owlen will emit a warning). Owlen normalises the base URL automatically—it enforces HTTPS, trims trailing slashes, and accepts both `https://ollama.com` and `https://api.ollama.com` without rewriting the host.
+Key points to keep in mind:
+
+-   **Base URL normalisation** – Owlen accepts `https://ollama.com`, `https://ollama.com/api`, `https://ollama.com/v1`, and the legacy `https://api.ollama.com`, canonicalising them to the correct HTTPS host. Local deployments get the same treatment for `http://localhost:11434`, `/api`, or `/v1`. You only need to customise `base_url` when the service is proxied elsewhere.
+-   **Credential precedence** – The resolver prefers an inline `api_key` first, then `api_key_env`, then the process environment in the order `OLLAMA_API_KEY`, `OLLAMA_CLOUD_API_KEY`, and `OWLEN_OLLAMA_CLOUD_API_KEY`. Set exactly one source to avoid surprises. When the `ollama` (local) provider is selected, any API key is ignored.
+-   **Transport security** – Hosted requests must use HTTPS unless the development-only flag `OWLEN_ALLOW_INSECURE_CLOUD=1` is set. Leave this unset in production to avoid leaking credentials over cleartext channels.
+-   **Web search endpoint** – By default Owlen calls `/api/web_search`. If your deployment exposes the tool at `/v1/web/search` (Codex CLI style) or any other path, set `providers.ollama_cloud.extra.web_search_endpoint`. The session layer reuses the same normalisation logic, so whatever URL the provider accepts will also be used for tool consent checks.
 
 The quota fields are optional and purely informational—they are never sent to the provider. Owlen uses them to display hourly/weekly token usage in the chat header, emit pre-limit toasts at 80% and 95%, and power the `:limits` command. Adjust the numbers to reflect the soft limits on your account or remove the keys altogether if you do not want usage tracking.