docs: align env-var fallback messaging as deprecated across surfaces (#1324)

Reconcile .env.example, ollama.md and environment-reference.md on a single
story for AI provider environment variables: they are a deprecated fallback
that still works today, with no guarantee it keeps working, and new
automation should not be built on it. Settings → API Keys is the supported
path; the declarative provisioning contract for headless setups is tracked
in Discussion #765.

Closes #1135


Claude-Session: https://claude.ai/code/session_01Bd92gaJSdXogEBiRMEQYXQ

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>

Author: lfnovo

.env.example

@@ -23,10 +23,17 @@ SURREAL_NAMESPACE=open_notebook
 SURREAL_DATABASE=open_notebook
 
 # =============================================================================
-# OPTIONAL: AI Provider API Keys
+# DEPRECATED: AI Provider API Keys (environment-variable fallback)
 # =============================================================================
-# You can configure these via the UI (Settings → API Keys) or set them here
-# UI configuration is recommended for better security and flexibility
+# Configure AI providers via the UI: Settings → API Keys. Credentials are
+# stored encrypted, can be rotated without restarts, and support multiple
+# credentials per provider.
+#
+# The environment variables below are a DEPRECATED fallback. They still work
+# today, but there is no guarantee they keep working in future releases, and
+# new automation should not be built on them. A declarative provisioning
+# contract for headless/CI/Docker setups is being designed in
+# https://github.com/lfnovo/open-notebook/discussions/765
 
 # OpenAI
 # OPENAI_API_KEY=sk-...
@@ -47,10 +54,11 @@ SURREAL_DATABASE=open_notebook
 # External API URL (for webhooks, callbacks, etc.)
 # API_URL=http://localhost:5055
 
-# Ollama endpoint (if running locally)
+# Ollama endpoint — DEPRECATED fallback, configure via Settings → API Keys instead
 # OLLAMA_API_BASE=http://localhost:11434
 
-# oMLX (Apple Silicon) — prefer Settings → API Keys; port 11435 avoids SurrealDB on 8000
+# oMLX (Apple Silicon) — DEPRECATED fallback, configure via Settings → API Keys instead
+# Port 11435 avoids clashing with SurrealDB on 8000
 # OMLX_API_BASE=http://localhost:11435/v1
 # OMLX_API_KEY=  # optional; only if oMLX was started with --api-key
 

docs/5-CONFIGURATION/environment-reference.md

@@ -259,7 +259,7 @@ env | grep -E "^[A-Z_]+=" | sort
 - **Quote values:** Use quotes for values with spaces: `API_URL="http://my server:5055"`
 - **Restart required:** Changes take effect after restarting services
 - **Secrets:** Don't commit encryption keys or passwords to git
-- **AI Providers:** Configure via **Settings → API Keys** in the browser (not via env vars)
+- **AI Providers:** Configure via **Settings → API Keys** in the browser. The provider env vars listed under [Legacy](#legacy-ai-provider-environment-variables-deprecated) are a deprecated fallback
 - **Migration:** Use Settings UI to migrate existing env vars to the credential system. See [API Configuration](../3-USER-GUIDE/api-configuration.md#migrating-from-environment-variables)
 
 ---
@@ -283,7 +283,11 @@ Done!
 
 ## Legacy: AI Provider Environment Variables (Deprecated)
 
-> **Deprecated**: The following AI provider API key environment variables are deprecated. Configure providers via the Settings UI instead. These variables may still work as a fallback but are no longer recommended.
+> **Deprecated**: The following AI provider environment variables are a deprecated fallback. They still work today (the runtime reads the database first and falls back to the environment), but there is no guarantee they keep working in future releases, and new automation should not be built on them. Configure providers via **Settings → API Keys** instead.
+
+Why the UI is the source of truth: credentials in the database are encrypted at rest (via `OPEN_NOTEBOOK_ENCRYPTION_KEY`), can be added or rotated at runtime without restarts, and support multiple credentials per provider — none of which a single env var can express.
+
+**Headless, CI/CD and Docker deployments:** a declarative provisioning contract over the credentials API (a file describing providers and credentials, with `${VAR}`-style references resolved from the environment) is being designed in [Discussion #765](https://github.com/lfnovo/open-notebook/discussions/765). Until it ships, the env fallback is the only unattended path — use it knowing it is deprecated.
 
 If you have these variables configured from a previous installation, click the **Migrate to Database** button in **Settings → API Keys** to import them into the credential system, then remove them from your configuration.
 

docs/5-CONFIGURATION/ollama.md

@@ -45,15 +45,15 @@ ollama pull mxbai-embed-large  # Best embedding model for Ollama
 4. Click **Save**, then **Test Connection**
 5. Click **Discover Models** → **Register Models**
 
-**Legacy (Deprecated) — Environment variables:**
+**Environment variable fallback (Deprecated):**
 ```bash
 # For local installation:
 export OLLAMA_API_BASE=http://localhost:11434
 # For Docker installation:
 export OLLAMA_API_BASE=http://host.docker.internal:11434
 ```
 
-> **Note**: The `OLLAMA_API_BASE` environment variable is deprecated. Configure Ollama via Settings → API Keys instead.
+> **Deprecated**: `OLLAMA_API_BASE` is a deprecated fallback. It still works today, but there is no guarantee it keeps working in future releases, and new automation should not be built on it. Configure Ollama via **Settings → API Keys** instead. For headless/CI/Docker setups, see the [environment reference](environment-reference.md#legacy-ai-provider-environment-variables-deprecated) and the provisioning discussion in [#765](https://github.com/lfnovo/open-notebook/discussions/765).
 
 ## Network Configuration Guide
 
@@ -543,7 +543,7 @@ export OLLAMA_NUM_PARALLEL=4           # Parallel request handling
 export OLLAMA_FLASH_ATTENTION=1        # Enable flash attention (if supported)
 
 # Open Notebook configuration (configure via Settings → API Keys instead)
-# OLLAMA_API_BASE=http://localhost:11434  # Deprecated — use Settings UI
+# OLLAMA_API_BASE=http://localhost:11434  # Deprecated fallback — works today, no guarantee
 ```
 
 ### SSL Configuration (Self-Signed Certificates)