docs: update LLM configuration documentation to emphasize environment-driven setup and clarify provider priority management

Author: veithly

docs/api-reference/graph/index.md

@@ -15,7 +15,7 @@ SpoonOS's graph system enables:
 ## Core Components
 
 ### [StateGraph](state-graph.md)
-The main graph execution engine providing LangGraph-style workflow orchestration.
+The main graph execution engine providing workflow orchestration.
 
 **Key Features:**
 - Node and edge management

docs/api-reference/llm/config-manager.md

@@ -2,6 +2,8 @@
 
 The `ConfigurationManager` handles loading, validation, and management of LLM provider configurations from various sources including environment variables, configuration files, and runtime settings.
 
+> **Note (Nov 2025):** The core SDK now defaults to environment-driven configuration. Use the `spoon-cli` configuration manager (or set environment variables manually) to sync `config.json` values before instantiating `ConfigurationManager()`.
+
 ## Class Definition
 
 ```python
@@ -57,8 +59,13 @@ Load configuration from a JSON or TOML file.
 
 **Example:**
 ```python
+import os
+from spoon_ai.llm import ConfigurationManager
+
+# Populate required environment variables before instantiating the manager
+os.environ["OPENAI_API_KEY"] = "sk-..."
+
 config_manager = ConfigurationManager()
-config = config_manager.load_from_file("config.json")
 ```
 
 ### `load_from_env() -> Dict[str, Any]`
@@ -78,6 +85,13 @@ Load configuration from environment variables.
 config = config_manager.load_from_env()
 ```
 
+Environment overrides also control provider priority:
+
+- `DEFAULT_LLM_PROVIDER` selects the preferred provider (e.g. `anthropic`).
+- `LLM_FALLBACK_CHAIN` lists comma-separated providers for cascading retries (e.g. `anthropic,openai,gemini`).
+
+When using `spoon-cli`, these variables are exported automatically after `config.json` loads. If you instantiate the SDK directly, set them yourself before calling `ConfigurationManager()`.
+
 ### `merge_configs(base_config: Dict, override_config: Dict) -> Dict[str, Any]`
 
 Merge two configurations with override priority.
@@ -394,7 +408,7 @@ decrypted = config_manager.decrypt_config(encrypted_config)
 import os
 from spoon_ai.llm import ConfigurationManager
 
-config_manager = ConfigurationManager()
+config_manager = ConfigurationManager()  # environment-first configuration
 
 # Secure: Load from environment
 config_manager.set_provider_config("openai", {
@@ -432,27 +446,12 @@ llm_manager = LLMManager(config_manager=config_manager)
 
 ## Integration Examples
 
-### With LLMManager
-
-```python
-from spoon_ai.llm import ConfigurationManager, LLMManager
-
-# Initialize configuration
-config_manager = ConfigurationManager("config.json")
-
-# Create LLM manager with configuration
-llm_manager = LLMManager(config_manager=config_manager)
-
-# Configuration changes are automatically picked up
-response = await llm_manager.chat(messages)
-```
-
 ### Programmatic Configuration
 
 ```python
 from spoon_ai.llm import ConfigurationManager
 
-config_manager = ConfigurationManager()
+config_manager = ConfigurationManager()  # defaults to environment variables
 
 # Configure providers programmatically
 providers = {

docs/api-reference/llm/index.md

@@ -6,6 +6,8 @@ The LLM (Large Language Model) system in SpoonOS provides a unified, provider-ag
 
 SpoonOS's LLM system offers:
 
+- > **Note (Nov 2025):** The core Python SDK reads provider settings from environment variables. The `spoon-cli` toolchain loads `config.json` and exports those values into the environment automatically. When using the SDK directly, set the relevant `*_API_KEY`, `*_BASE_URL`, and related environment variables before creating `ConfigurationManager()`.
+
 - **Provider Agnosticism**: Unified API across all providers
 - **Automatic Fallback**: Intelligent provider switching on failures
 - **Load Balancing**: Distribute requests across multiple providers
@@ -59,10 +61,14 @@ Handles configuration loading, validation, and management from multiple sources.
 - Configuration templates and merging
 
 ```python
+import os
 from spoon_ai.llm import ConfigurationManager
 
-config_manager = ConfigurationManager("config.json")
-config_manager.set_provider_config("openai", {...})
+# Export provider settings into environment variables
+os.environ["OPENAI_API_KEY"] = "sk-..."
+os.environ["DEFAULT_LLM_PROVIDER"] = "openai"
+
+config_manager = ConfigurationManager()
 ```
 
 ## Quick Start
@@ -82,19 +88,28 @@ response = await llm_manager.chat(messages)
 print(response.content)
 ```
 
-### With Configuration
 
-```python
-from spoon_ai.llm import ConfigurationManager, LLMManager
+### Controlling Provider Priority
+
+You can steer which provider is used first—and how the system falls back—purely via environment variables:
+
+```bash
+# Prefer Anthropic by default
+export DEFAULT_LLM_PROVIDER=anthropic
+
+# Allow fallback to OpenAI, then Gemini
+export LLM_FALLBACK_CHAIN="anthropic,openai,gemini"
+```
 
-# Load configuration
-config_manager = ConfigurationManager("config.json")
-llm_manager = LLMManager(config_manager=config_manager)
+On Windows PowerShell:
 
-# Chat with specific provider
-response = await llm_manager.chat(messages, provider="openai")
+```powershell
+$env:DEFAULT_LLM_PROVIDER = "anthropic"
+$env:LLM_FALLBACK_CHAIN = "anthropic,openai,gemini"
 ```
 
+After setting the variables, simply instantiate `ConfigurationManager()` as usual; no code changes are needed. The `spoon-cli` configuration workflow writes these variables for you whenever it loads `config.json`.
+
 ### Streaming Responses
 
 ```python
@@ -240,7 +255,7 @@ LLM_RETRY_ATTEMPTS=3
 ```python
 from spoon_ai.llm import ConfigurationManager
 
-config_manager = ConfigurationManager()
+config_manager = ConfigurationManager()  # uses environment variables by default
 
 # Configure providers
 config_manager.set_provider_config("openai", {
@@ -515,7 +530,7 @@ llm_manager.set_primary_provider("gemini")  # Generally faster
 ```python
 from spoon_ai.llm import ConfigurationManager
 
-config_manager = ConfigurationManager()
+config_manager = ConfigurationManager()  # refreshes from environment variables
 errors = config_manager.validate_config(your_config)
 for error in errors:
     print(f"Config error: {error}")