docs: add configuration reference guide

- Create comprehensive Configuration Reference Guide in docs/guides/configuration-reference.md
- Document all environment variables organized by functional area (runtime, providers, storage, observability, etc.)
- Include configuration loading order, file locations, and best practices
- Add security considerations for secrets management, database, and API keys
- Provide troubleshooting guide for common configuration issues
- Include practical configuration examples for development, production, and Kubernetes deployments
- Update mkdocs.yml to include new Guides section with Configuration Reference link

CHANGELOG.md

@@ -28,6 +28,14 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   correctly in all deployment modes: Docker containers, local pip installs
   (wheel or editable), and development environments.
 - **TDD Non-AssertionError Guard Visibility** (#8294): `apply_tdd_inversion` in
+- **bug-hunt-pool-supervisor Non-Blocking Tracking** (#8835): The automation-tracking-manager
+  call in step 5 was blocking the main loop indefinitely, causing 3+ consecutive initialization
+  failures. Step 5 now explicitly marks tracking as best-effort -- if the call does not complete
+  within a reasonable time or fails, it is skipped and the supervisor continues to the next
+  cycle. A new Rule 9 reinforces that tracking must never block the main loop; core
+  functionality (module mapping, worker dispatch, monitoring) takes priority over status
+  reporting.
+
   `features/environment.py` now emits its non-assertion exception guard warning to
   both the structured logger and `stderr` via a new `_warning_with_stderr` helper.
   This makes the guard firing visible in standard Behave console output and CI log

docs/guides/configuration-reference.md

@@ -0,0 +1,453 @@
+# Configuration Reference Guide
+
+This guide provides a comprehensive reference for configuring CleverAgents. Configuration is primarily managed through environment variables, with sensible defaults for most settings.
+
+## Overview
+
+CleverAgents uses a **Pydantic-based settings system** that reads configuration from environment variables with the `CLEVERAGENTS_` prefix. The configuration system is designed to be:
+
+- **Environment-first**: All configuration comes from environment variables, making it ideal for containerized and cloud-native deployments
+- **Hierarchical**: Settings are organized by functional area (runtime, providers, storage, observability, etc.)
+- **Validated**: All configuration values are validated at startup with clear error messages
+- **Sensible defaults**: Most settings have reasonable defaults suitable for development and production
+
+### Configuration Loading Order
+
+1. **Environment variables** (highest priority) — `CLEVERAGENTS_*` prefixed variables
+2. **Provider-specific environment variables** — Native provider variables (e.g., `OPENAI_API_KEY`)
+3. **Default values** — Hardcoded defaults in the settings schema
+
+When a setting is not explicitly configured, the system falls back to the next level in the order above.
+
+### Configuration File Locations
+
+CleverAgents stores configuration and data in the following locations:
+
+| Purpose | Default Location | Environment Variable |
+|---------|------------------|----------------------|
+| User data (sessions, personas, etc.) | `~/.cleveragents/` | `CLEVERAGENTS_DATA_DIR` |
+| Database | `~/.cleveragents/cleveragents.db` | `CLEVERAGENTS_DATABASE_URL` |
+| Logs | `./logs/` | `CLEVERAGENTS_LOG_DIR` |
+| Storage (plans, resources, etc.) | `./data/` | `CLEVERAGENTS_STORAGE_BASE_PATH` |
+| Vector store | `./.cleveragents/vector_store/` | `CLEVERAGENTS_VECTOR_STORE_PATH` |
+
+## Environment Variables Reference
+
+All environment variables are organized by functional area. Each entry includes:
+
+- **Variable name** — The full `CLEVERAGENTS_*` environment variable name
+- **Type** — The expected data type (string, integer, boolean, etc.)
+- **Default** — The default value if not set
+- **Description** — What the setting controls
+- **Example** — A practical example value
+
+### Runtime & Server Configuration
+
+#### `CLEVERAGENTS_ENV`
+- **Type:** String
+- **Default:** `development`
+- **Valid values:** `development`, `production`, `staging`, `test`
+- **Description:** The runtime environment. Controls logging verbosity, debug features, and validation strictness.
+- **Example:** `export CLEVERAGENTS_ENV=production`
+
+#### `CLEVERAGENTS_DEBUG_ENABLED`
+- **Type:** Boolean
+- **Default:** `false`
+- **Description:** Enable debug mode with verbose logging and additional runtime checks. Should never be enabled in production.
+- **Example:** `export CLEVERAGENTS_DEBUG_ENABLED=true`
+
+#### `CLEVERAGENTS_SERVER_HOST`
+- **Type:** String (IP address)
+- **Default:** `0.0.0.0`
+- **Description:** The host address for the CleverAgents server to bind to.
+- **Example:** `export CLEVERAGENTS_SERVER_HOST=127.0.0.1`
+
+#### `CLEVERAGENTS_SERVER_PORT`
+- **Type:** Integer
+- **Default:** `8080`
+- **Valid range:** 1-65535
+- **Description:** The port for the CleverAgents server to listen on.
+- **Example:** `export CLEVERAGENTS_SERVER_PORT=9000`
+
+#### `CLEVERAGENTS_SERVER_RELOAD`
+- **Type:** Boolean
+- **Default:** `false`
+- **Description:** Enable auto-reload on code changes (development only). Never use in production.
+- **Example:** `export CLEVERAGENTS_SERVER_RELOAD=true`
+
+#### `CLEVERAGENTS_SERVER_URL`
+- **Type:** String (URL)
+- **Default:** `None` (local mode)
+- **Description:** URL of a remote CleverAgents server to connect to. When set, the CLI operates in server mode.
+- **Example:** `export CLEVERAGENTS_SERVER_URL=https://cleveragents.example.com`
+
+#### `CLEVERAGENTS_SERVER_TOKEN`
+- **Type:** String
+- **Default:** `None`
+- **Description:** Authentication token for connecting to a remote CleverAgents server. Required when `CLEVERAGENTS_SERVER_URL` is set.
+- **Example:** `export CLEVERAGENTS_SERVER_TOKEN=sk-1234567890abcdef`
+
+### AI Provider Configuration
+
+#### Provider API Keys
+
+Each AI provider requires its API key to be configured. CleverAgents supports multiple providers simultaneously and automatically selects the best available one.
+
+| Provider | Primary Variable | Fallback Variables | Example |
+|----------|------------------|-------------------|---------|
+| OpenAI | `OPENAI_API_KEY` | `CLEVERAGENTS_OPENAI_API_KEY` | `sk-proj-...` |
+| Anthropic | `ANTHROPIC_API_KEY` | `CLEVERAGENTS_ANTHROPIC_API_KEY` | `sk-ant-...` |
+| Google | `GOOGLE_API_KEY` | `GOOGLE_GENAI_API_KEY`, `CLEVERAGENTS_GOOGLE_API_KEY` | `AIza...` |
+| Azure OpenAI | `AZURE_OPENAI_API_KEY` | `AZURE_API_KEY`, `CLEVERAGENTS_AZURE_API_KEY` | `...` |
+| OpenRouter | `OPENROUTER_API_KEY` | `CLEVERAGENTS_OPENROUTER_API_KEY` | `sk-or-...` |
+| Gemini | `GEMINI_API_KEY` | `GOOGLE_GEMINI_API_KEY`, `CLEVERAGENTS_GEMINI_API_KEY` | `AIza...` |
+| Cohere | `COHERE_API_KEY` | `CLEVERAGENTS_COHERE_API_KEY` | `...` |
+| Groq | `GROQ_API_KEY` | `CLEVERAGENTS_GROQ_API_KEY` | `gsk_...` |
+| Together | `TOGETHER_API_KEY` | `CLEVERAGENTS_TOGETHER_API_KEY` | `...` |
+| HuggingFace | `HF_TOKEN` | `HUGGINGFACEHUB_API_TOKEN`, `HUGGING_FACE_HUB_TOKEN` | `hf_...` |
+| Perplexity | `PERPLEXITY_API_KEY` | `CLEVERAGENTS_PERPLEXITY_API_KEY` | `pplx-...` |
+
+#### `CLEVERAGENTS_DEFAULT_PROVIDER`
+- **Type:** String
+- **Default:** `None` (auto-detect from configured providers)
+- **Valid values:** `openai`, `anthropic`, `google`, `azure`, `openrouter`, `gemini`, `cohere`, `groq`, `together`, `huggingface`, `perplexity`
+- **Description:** Pin the default AI provider. When not set, the system automatically selects the first available configured provider in the fallback order.
+- **Example:** `export CLEVERAGENTS_DEFAULT_PROVIDER=anthropic`
+
+#### `CLEVERAGENTS_DEFAULT_MODEL`
+- **Type:** String
+- **Default:** `None` (provider-specific default)
+- **Description:** Pin the default model for the selected provider. When not set, each provider's published default is used (e.g., `gpt-4o` for OpenAI, `claude-sonnet-4-20250514` for Anthropic).
+- **Example:** `export CLEVERAGENTS_DEFAULT_MODEL=gpt-4-turbo`
+
+#### `CLEVERAGENTS_MOCK_PROVIDERS`
+- **Type:** Boolean
+- **Default:** `false`
+- **Description:** Enable mock AI providers for testing. Must not be used in production. Useful for development and CI/CD pipelines.
+- **Example:** `export CLEVERAGENTS_MOCK_PROVIDERS=true`
+
+#### `CLEVERAGENTS_TESTING_USE_MOCK_AI`
+- **Type:** Boolean
+- **Default:** `false`
+- **Description:** Force the in-repo mock provider for Behave/Robot test suites to prevent external API calls.
+- **Example:** `export CLEVERAGENTS_TESTING_USE_MOCK_AI=true`
+
+### Logging & Paths
+
+#### `CLEVERAGENTS_LOG_LEVEL`
+- **Type:** String
+- **Default:** `INFO`
+- **Valid values:** `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`
+- **Description:** The logging level for standard output and file logs.
+- **Example:** `export CLEVERAGENTS_LOG_LEVEL=DEBUG`
+
+#### `CLEVERAGENTS_LOG_DIR`
+- **Type:** Path
+- **Default:** `./logs/`
+- **Description:** Directory where log files are written.
+- **Example:** `export CLEVERAGENTS_LOG_DIR=/var/log/cleveragents`
+
+#### `CLEVERAGENTS_DATA_DIR`
+- **Type:** Path
+- **Default:** `~/.cleveragents/`
+- **Description:** Directory for user data, sessions, personas, and other persistent state.
+- **Example:** `export CLEVERAGENTS_DATA_DIR=/data/cleveragents`
+
+#### `CLEVERAGENTS_STORAGE_BASE_PATH`
+- **Type:** Path
+- **Default:** `./data/`
+- **Description:** Base directory for plan storage, checkpoints, and other runtime data.
+- **Example:** `export CLEVERAGENTS_STORAGE_BASE_PATH=/storage/cleveragents`
+
+### Database & Persistence
+
+#### `CLEVERAGENTS_DATABASE_URL`
+- **Type:** String (database URL)
+- **Default:** `sqlite:///$HOME/.cleveragents/cleveragents.db`
+- **Supported formats:**
+  - SQLite: `sqlite:///path/to/database.db`
+  - PostgreSQL: `postgresql://user:password@host:port/database`
+  - MySQL: `mysql+pymysql://user:password@host:port/database`
+  - DuckDB: `duckdb:///path/to/database.duckdb`
+- **Description:** The database URL for storing sessions, plans, and other persistent data.
+- **Example:** `export CLEVERAGENTS_DATABASE_URL=postgresql://user:pass@localhost/cleveragents`
+
+### Cost Controls & Budgets
+
+#### `CLEVERAGENTS_SESSION_MAX_COST_USD`
+- **Type:** Float
+- **Default:** `None` (unlimited)
+- **Valid range:** >= 0.0
+- **Description:** Maximum USD spend per session across all plans. `None` means unlimited.
+- **Example:** `export CLEVERAGENTS_SESSION_MAX_COST_USD=100.00`
+
+#### `CLEVERAGENTS_ORG_MAX_COST_USD`
+- **Type:** Float
+- **Default:** `None` (unlimited)
+- **Valid range:** >= 0.0
+- **Description:** Maximum USD spend per organization across all sessions. `None` means unlimited.
+- **Example:** `export CLEVERAGENTS_ORG_MAX_COST_USD=1000.00`
+
+#### `CLEVERAGENTS_BUDGET_PER_PLAN`
+- **Type:** Float
+- **Default:** `None` (unlimited)
+- **Valid range:** >= 0.0
+- **Description:** Maximum USD spend per plan execution. `None` means unlimited.
+- **Example:** `export CLEVERAGENTS_BUDGET_PER_PLAN=50.00`
+
+#### `CLEVERAGENTS_BUDGET_PER_DAY`
+- **Type:** Float
+- **Default:** `None` (unlimited)
+- **Valid range:** >= 0.0
+- **Description:** Maximum USD spend per calendar day across all plans. `None` means unlimited.
+- **Example:** `export CLEVERAGENTS_BUDGET_PER_DAY=500.00`
+
+### Observability & Logging
+
+#### LangSmith Tracing
+
+#### `CLEVERAGENTS_LANGSMITH_ENABLED`
+- **Type:** Boolean
+- **Default:** `false`
+- **Aliases:** `LANGCHAIN_TRACING_V2`, `LANGSMITH_TRACING_V2`
+- **Description:** Enable LangSmith tracing for LangChain/LangGraph agents.
+- **Example:** `export CLEVERAGENTS_LANGSMITH_ENABLED=true`
+
+#### `CLEVERAGENTS_LANGSMITH_API_KEY`
+- **Type:** String
+- **Default:** `None`
+- **Aliases:** `LANGSMITH_API_KEY`, `LANGCHAIN_API_KEY`
+- **Description:** API key for LangSmith. Required when tracing is enabled.
+- **Example:** `export CLEVERAGENTS_LANGSMITH_API_KEY=ls_...`
+
+#### `CLEVERAGENTS_LANGSMITH_PROJECT`
+- **Type:** String
+- **Default:** `None`
+- **Aliases:** `LANGSMITH_PROJECT`, `LANGCHAIN_PROJECT`
+- **Description:** LangSmith project name. Required when tracing is enabled.
+- **Example:** `export CLEVERAGENTS_LANGSMITH_PROJECT=my-project`
+
+### Cleanup & Retention Policies
+
+#### `CLEVERAGENTS_CLEANUP_SANDBOX_MAX_AGE_HOURS`
+- **Type:** Integer
+- **Default:** `48`
+- **Valid range:** >= 1
+- **Description:** Maximum age (in hours) before stale sandboxes are eligible for cleanup.
+- **Example:** `export CLEVERAGENTS_CLEANUP_SANDBOX_MAX_AGE_HOURS=72`
+
+#### `CLEVERAGENTS_CHECKPOINT_MAX`
+- **Type:** Integer
+- **Default:** `50`
+- **Valid range:** >= 2
+- **Description:** Maximum number of checkpoints to keep per plan. Oldest checkpoints are pruned first, but the first and most recent are always preserved.
+- **Example:** `export CLEVERAGENTS_CHECKPOINT_MAX=100`
+
+### Audit Logging
+
+#### `CLEVERAGENTS_AUDIT_RETENTION_DAYS`
+- **Type:** Integer
+- **Default:** `0` (keep indefinitely)
+- **Valid range:** >= 0
+- **Description:** Days to retain audit log entries before pruning. `0` means keep indefinitely (spec default for compliance).
+- **Example:** `export CLEVERAGENTS_AUDIT_RETENTION_DAYS=365`
+
+#### `CLEVERAGENTS_AUDIT_ASYNC`
+- **Type:** Boolean
+- **Default:** `true`
+- **Description:** When true, audit entries are written asynchronously via a write-behind queue on a background thread. Set to false for synchronous behavior (useful for debugging).
+- **Example:** `export CLEVERAGENTS_AUDIT_ASYNC=false`
+
+### Metrics & Observability
+
+#### `CLEVERAGENTS_METRICS_ENABLED`
+- **Type:** Boolean
+- **Default:** `true`
+- **Description:** Enable structured metric collection and emission.
+- **Example:** `export CLEVERAGENTS_METRICS_ENABLED=false`
+
+#### `CLEVERAGENTS_METRICS_EXPORT_PROMETHEUS`
+- **Type:** Boolean
+- **Default:** `false`
+- **Description:** Enable Prometheus metrics export endpoint.
+- **Example:** `export CLEVERAGENTS_METRICS_EXPORT_PROMETHEUS=true`
+
+### Retry & Circuit Breaker Configuration
+
+#### `CLEVERAGENTS_RETRY_MAX_ATTEMPTS`
+- **Type:** Integer
+- **Default:** `3`
+- **Valid range:** 1-50
+- **Description:** Default maximum retry attempts for service operations.
+- **Example:** `export CLEVERAGENTS_RETRY_MAX_ATTEMPTS=5`
+
+#### `CLEVERAGENTS_RETRY_BASE_DELAY`
+- **Type:** Float
+- **Default:** `1.0`
+- **Valid range:** 0.0-300.0
+- **Description:** Default base delay in seconds between retries.
+- **Example:** `export CLEVERAGENTS_RETRY_BASE_DELAY=0.5`
+
+#### `CLEVERAGENTS_RETRY_MAX_DELAY`
+- **Type:** Float
+- **Default:** `60.0`
+- **Valid range:** 0.0-3600.0
+- **Description:** Default maximum delay in seconds between retries.
+- **Example:** `export CLEVERAGENTS_RETRY_MAX_DELAY=120.0`
+
+#### `CLEVERAGENTS_RETRY_BACKOFF_STRATEGY`
+- **Type:** String
+- **Default:** `exponential`
+- **Valid values:** `exponential`, `linear`, `fixed`, `jitter`, `none`
+- **Description:** Default backoff strategy for retries.
+- **Example:** `export CLEVERAGENTS_RETRY_BACKOFF_STRATEGY=linear`
+
+### Security & Secrets
+
+#### `CLEVERAGENTS_SHOW_SECRETS`
+- **Type:** Boolean
+- **Default:** `false`
+- **Description:** When true, secrets are shown in CLI output and logs. Should never be enabled in production.
+- **Example:** `export CLEVERAGENTS_SHOW_SECRETS=true`
+
+### Automation & Output
+
+#### `CLEVERAGENTS_AUTOMATION_PROFILE`
+- **Type:** String
+- **Default:** `` (empty, manual mode)
+- **Valid values:** `manual`, `auto`, `full-auto` (or custom profile names)
+- **Description:** Default automation profile name controlling plan execution behavior.
+- **Example:** `export CLEVERAGENTS_AUTOMATION_PROFILE=auto`
+
+#### `CLEVERAGENTS_FORMAT`
+- **Type:** String
+- **Default:** `None` (uses default format)
+- **Valid values:** `json`, `markdown`, `text`, `yaml`
+- **Description:** Default output format for CLI commands.
+- **Example:** `export CLEVERAGENTS_FORMAT=json`
+
+## Configuration Best Practices
+
+### Development Environment
+
+For local development, create a `.env` file in your project root:
+
+```bash
+# .env
+CLEVERAGENTS_ENV=development
+CLEVERAGENTS_DEBUG_ENABLED=true
+CLEVERAGENTS_LOG_LEVEL=DEBUG
+OPENAI_API_KEY=sk-proj-...
+CLEVERAGENTS_DATABASE_URL=sqlite:///./dev.db
+```
+
+### Production Environment
+
+For production deployments:
+
+```bash
+# Use strong, randomly generated secrets
+export CLEVERAGENTS_ENV=production
+export CLEVERAGENTS_DEBUG_ENABLED=false
+export CLEVERAGENTS_LOG_LEVEL=WARNING
+export CLEVERAGENTS_SHOW_SECRETS=false
+
+# Use a production database
+export CLEVERAGENTS_DATABASE_URL=postgresql://user:password@db.example.com/cleveragents
+
+# Configure cost controls
+export CLEVERAGENTS_SESSION_MAX_COST_USD=100
+export CLEVERAGENTS_ORG_MAX_COST_USD=1000
+
+# Enable observability
+export CLEVERAGENTS_METRICS_ENABLED=true
+export CLEVERAGENTS_LANGSMITH_ENABLED=true
+export CLEVERAGENTS_LANGSMITH_API_KEY=ls_...
+export CLEVERAGENTS_LANGSMITH_PROJECT=production
+```
+
+### Multi-Provider Setup
+
+To support multiple AI providers with automatic fallback:
+
+```bash
+# Configure multiple providers
+export OPENAI_API_KEY=sk-proj-...
+export ANTHROPIC_API_KEY=sk-ant-...
+export GOOGLE_API_KEY=AIza...
+
+# Set primary provider (optional)
+export CLEVERAGENTS_DEFAULT_PROVIDER=anthropic
+```
+
+## Security Considerations
+
+### Secrets Management
+
+1. **Never commit secrets** — Use environment variables or a secrets manager (Vault, AWS Secrets Manager, etc.)
+2. **Use strong API keys** — Ensure all provider API keys are strong and rotated regularly
+3. **Restrict access** — Limit who can view or modify configuration in your deployment
+4. **Audit logging** — Enable audit logging to track configuration changes and API usage
+5. **Redaction** — CleverAgents automatically redacts secrets in logs and output
+
+### Database Security
+
+- **Use encrypted connections** — Always use TLS/SSL for database connections
+- **Strong credentials** — Use strong, randomly generated database passwords
+- **Network isolation** — Restrict database access to authorized services only
+
+### API Key Security
+
+- **Rotate keys regularly** — Implement automated key rotation (e.g., monthly)
+- **Use scoped keys** — If your provider supports it, use keys with minimal required permissions
+- **Monitor usage** — Track API usage and set up alerts for unusual activity
+
+## Troubleshooting Configuration Issues
+
+### No AI Provider Configured
+
+**Error:** `ValueError: No AI providers configured and mock_providers is disabled.`
+
+**Solution:**
+1. Set at least one provider API key: `export OPENAI_API_KEY=sk-proj-...`
+2. Or enable mock providers for testing: `export CLEVERAGENTS_MOCK_PROVIDERS=true`
+3. Verify the key is set: `echo $OPENAI_API_KEY`
+
+### LangSmith Configuration Incomplete
+
+**Error:** `LangSmith API key is required` or `LangSmith project name is required`
+
+**Solution:**
+1. Set both required variables:
+   ```bash
+   export CLEVERAGENTS_LANGSMITH_API_KEY=ls_...
+   export CLEVERAGENTS_LANGSMITH_PROJECT=my-project
+   ```
+2. Or disable LangSmith: `export CLEVERAGENTS_LANGSMITH_ENABLED=false`
+
+### Database Connection Failed
+
+**Error:** `sqlalchemy.exc.OperationalError: (psycopg2.OperationalError) could not connect to server`
+
+**Solution:**
+1. Verify the database URL: `echo $CLEVERAGENTS_DATABASE_URL`
+2. Check database credentials and host
+3. Ensure the database is running and accessible
+
+### Configuration Not Taking Effect
+
+**Problem:** Environment variable changes not reflected
+
+**Solution:**
+1. Verify the variable is set: `env | grep CLEVERAGENTS`
+2. Restart the application (singleton settings are cached)
+3. Check for typos in variable names (case-sensitive)
+4. Ensure the variable is exported: `export CLEVERAGENTS_VAR=value`
+
+## Related Documentation
+
+- [Architecture Guide](../architecture.md) — System design and component overview
+- [API Reference - Configuration](../api/config.md) — Detailed API documentation
+- [Development Guide](../development/quality-automation.md) — Development setup and workflows
+- [Specification](../specification.md) — Authoritative design documentation
+- [FAQ](../faq.md) — Frequently asked questions

docs/guides/installation-setup.md

@@ -1,496 +0,0 @@
-# Installation & Setup Guide
-
-This guide provides step-by-step instructions for installing CleverAgents Core and setting up your development environment.
-
-## Prerequisites
-
-Before you begin, ensure you have the following:
-
-### System Requirements
-
-- **Operating System**: Linux, macOS, or Windows (with WSL2)
-- **Disk Space**: At least 2GB free space for the repository and dependencies
-- **Internet Connection**: Required for downloading dependencies and LLM API calls
-
-### Python Version
-
-CleverAgents Core requires **Python 3.13 or later**.
-
-To check your Python version:
-
-```bash
-python3 --version
-```
-
-If you don't have Python 3.13 installed, visit [python.org](https://www.python.org/downloads/) or use your system's package manager:
-
-**macOS (using Homebrew):**
-```bash
-brew install python@3.13
-```
-
-**Ubuntu/Debian:**
-```bash
-sudo apt-get update
-sudo apt-get install python3.13 python3.13-venv python3.13-dev
-```
-
-**Windows (using Chocolatey):**
-```bash
-choco install python --version=3.13
-```
-
-### Git
-
-You'll need Git to clone the repository:
-
-```bash
-git --version
-```
-
-If not installed, download from [git-scm.com](https://git-scm.com/) or use your package manager.
-
-### Optional: pyenv (Recommended for Python Version Management)
-
-For managing multiple Python versions, install [pyenv](https://github.com/pyenv/pyenv):
-
-**macOS:**
-```bash
-brew install pyenv
-```
-
-**Linux:**
-```bash
-curl https://pyenv.run | bash
-```
-
-Then install Python 3.13:
-```bash
-pyenv install 3.13.9
-pyenv global 3.13.9
-```
-
-## Step 1: Clone the Repository
-
-Clone the CleverAgents Core repository:
-
-```bash
-git clone https://git.cleverthis.com/cleveragents/cleveragents-core.git
-cd cleveragents-core
-```
-
-## Step 2: Create a Virtual Environment
-
-A Python virtual environment isolates project dependencies from your system Python installation.
-
-### Using venv (Built-in)
-
-```bash
-# Create virtual environment
-python3 -m venv .venv
-
-# Activate virtual environment
-# On Linux/macOS:
-source .venv/bin/activate
-
-# On Windows:
-.venv\Scripts\activate
-```
-
-### Using uv (Faster Alternative)
-
-If you prefer a faster package manager, install [uv](https://github.com/astral-sh/uv) and use:
-
-```bash
-uv venv .venv
-source .venv/bin/activate  # Linux/macOS
-# or
-.venv\Scripts\activate  # Windows
-```
-
-## Step 3: Install Dependencies
-
-### Basic Installation (CLI Only)
-
-For using the CleverAgents CLI without TUI or development tools:
-
-```bash
-pip install -e .
-```
-
-### Development Installation (Recommended)
-
-For development, testing, and documentation:
-
-```bash
-pip install -e ".[dev,tests,docs]"
-```
-
-### Full Installation (Including TUI)
-
-For the interactive Terminal User Interface:
-
-```bash
-pip install -e ".[dev,tests,docs,tui]"
-```
-
-### Installation Options Explained
-
-| Extra | Purpose | Includes |
-|-------|---------|----------|
-| `dev` | Development tools | ruff, pyright, pre-commit, bandit, vulture, radon |
-| `tests` | Testing frameworks | behave, pytest, robotframework, coverage tools |
-| `docs` | Documentation | mkdocs, mkdocs-material, mkdocstrings |
-| `tui` | Terminal UI | textual framework for interactive interface |
-
-## Step 4: Set Up Pre-commit Hooks (Development Only)
-
-If you're developing, set up pre-commit hooks to automatically run quality checks:
-
-```bash
-bash scripts/setup-dev.sh
-```
-
-This script will:
-- Verify Python 3.13+ is installed
-- Install all development dependencies
-- Install pre-commit hooks
-- Run initial quality checks (format, lint, type check)
-
-### Manual Pre-commit Setup
-
-If you prefer to set up pre-commit manually:
-
-```bash
-pip install pre-commit
-pre-commit install
-pre-commit install --hook-type commit-msg
-```
-
-## Step 5: Verify Installation
-
-### Verify CLI Installation
-
-Test that the CleverAgents CLI is working:
-
-```bash
-agents --version
-agents --help
-```
-
-You should see the version number and available commands.
-
-### Verify Diagnostics
-
-Check that the system can detect your LLM provider credentials:
-
-```bash
-agents diagnostics
-```
-
-This will show:
-- Available LLM providers (based on API keys you've set)
-- Selected default actor
-- Configuration status
-
-### Verify Development Tools (Optional)
-
-If you installed development extras, verify the tools:
-
-```bash
-# Check code formatter
-ruff --version
-
-# Check type checker
-pyright --version
-
-# Check linter
-ruff check --version
-
-# Check pre-commit
-pre-commit --version
-```
-
-### Verify TUI Installation (Optional)
-
-If you installed the TUI extra, launch the interactive interface:
-
-```bash
-agents tui
-```
-
-Inside the TUI:
-- Type a message and press `Enter` to chat
-- Press `/` for slash commands
-- Press `@` for reference picker
-- Press `F1` for help
-- Press `Ctrl+Q` to quit
-
-## Step 6: Configure LLM Providers
-
-CleverAgents supports multiple LLM providers. Set up at least one by exporting API keys:
-
-### OpenAI
-
-```bash
-export OPENAI_API_KEY="sk-..."
-```
-
-### Anthropic
-
-```bash
-export ANTHROPIC_API_KEY="sk-ant-..."
-```
-
-### Google Generative AI
-
-```bash
-export GOOGLE_API_KEY="..."
-```
-
-### Azure OpenAI
-
-```bash
-export AZURE_OPENAI_API_KEY="..."
-export AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com/"
-export AZURE_OPENAI_DEPLOYMENT="your-deployment-name"
-```
-
-### Other Providers
-
-See [LLM Provider Configuration](../reference/providers.md) for additional providers (Groq, Cohere, Together, OpenRouter, Gemini).
-
-### Set Default Provider (Optional)
-
-```bash
-export CLEVERAGENTS_DEFAULT_PROVIDER=openai
-export CLEVERAGENTS_DEFAULT_MODEL=gpt-4o
-```
-
-## Step 7: Create Your First Session
-
-Test your installation by creating a conversation session:
-
-```bash
-# Create a session with a specific actor
-agents session create --actor openai/gpt-4o
-
-# List your sessions
-agents session list
-
-# Export a session
-agents session export --session-id <SESSION_ID> --output my-session.json
-```
-
-## Common Installation Issues
-
-### Issue: "Python 3.13 not found"
-
-**Solution:** Install Python 3.13 using your package manager or pyenv:
-
-```bash
-# Using pyenv
-pyenv install 3.13.9
-pyenv global 3.13.9
-
-# Or specify full path
-/usr/local/bin/python3.13 -m venv .venv
-```
-
-### Issue: "ModuleNotFoundError: No module named 'cleveragents'"
-
-**Solution:** Ensure you're in the virtual environment and installed with `-e` flag:
-
-```bash
-source .venv/bin/activate  # or .venv\Scripts\activate on Windows
-pip install -e .
-```
-
-### Issue: "agents: command not found"
-
-**Solution:** Activate your virtual environment:
-
-```bash
-source .venv/bin/activate  # Linux/macOS
-.venv\Scripts\activate     # Windows
-```
-
-Or use the full path:
-```bash
-.venv/bin/agents --version
-```
-
-### Issue: "No module named 'textual'" when running TUI
-
-**Solution:** Install the TUI extra:
-
-```bash
-pip install -e ".[tui]"
-```
-
-### Issue: Pre-commit hooks not running
-
-**Solution:** Reinstall pre-commit hooks:
-
-```bash
-pre-commit install
-pre-commit install --hook-type commit-msg
-```
-
-### Issue: "LLM provider not detected" in diagnostics
-
-**Solution:** Set your LLM API key as an environment variable:
-
-```bash
-export OPENAI_API_KEY="your-key-here"
-agents diagnostics
-```
-
-### Issue: Permission denied on scripts/setup-dev.sh
-
-**Solution:** Make the script executable:
-
-```bash
-chmod +x scripts/setup-dev.sh
-bash scripts/setup-dev.sh
-```
-
-### Issue: "pip: command not found"
-
-**Solution:** Use Python's pip module directly:
-
-```bash
-python3 -m pip install -e .
-```
-
-### Issue: Virtual environment activation fails on Windows
-
-**Solution:** If using PowerShell, you may need to enable script execution:
-
-```powershell
-Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
-.venv\Scripts\Activate.ps1
-```
-
-## Next Steps After Installation
-
-### For CLI Users
-
-1. **Set up your LLM provider** (see [Configure LLM Providers](#step-6-configure-llm-providers))
-2. **Create your first session**: `agents session create --actor openai/gpt-4o`
-3. **Explore available commands**: `agents --help`
-4. **Read the [FAQ](../faq.md)** for common questions
-
-### For TUI Users
-
-1. **Launch the TUI**: `agents tui`
-2. **Explore slash commands**: Press `/` inside the TUI
-3. **Create personas**: Use the TUI settings to create custom personas
-4. **Learn keyboard shortcuts**: Press `F1` for help
-
-### For Developers
-
-1. **Run the setup script**: `bash scripts/setup-dev.sh`
-2. **Explore the codebase**: Start with `src/cleveragents/`
-3. **Read the [Quality Automation Guide](../development/quality-automation.md)**
-4. **Run tests**: `nox -s unit_tests`
-5. **Review [Architecture](../architecture.md)** and [ADRs](../adr/index.md)
-
-### For Contributors
-
-1. **Read [CONTRIBUTING.md](../../CONTRIBUTING.md)** in the repository root
-2. **Review the [Review Playbook](../development/review_playbook.md)**
-3. **Check out the [Testing Guide](../development/testing.md)**
-4. **Understand the [CI/CD Pipeline](../development/ci-cd.md)**
-
-## Troubleshooting & Support
-
-### Getting Help
-
-- **Documentation**: https://docs.cleverthis.com/cleveragents
-- **Repository Issues**: https://git.cleverthis.com/cleveragents/cleveragents-core/issues
-- **FAQ**: See [FAQ](../faq.md) for common questions
-
-### Diagnostic Commands
-
-Run these commands to gather information for troubleshooting:
-
-```bash
-# Check Python version
-python3 --version
-
-# Check CleverAgents version
-agents --version
-
-# Check provider detection
-agents diagnostics
-
-# Check pre-commit status
-pre-commit status
-
-# Check development tools (if installed)
-ruff --version
-pyright --version
-```
-
-### Uninstalling
-
-To completely remove CleverAgents:
-
-```bash
-# Deactivate virtual environment
-deactivate
-
-# Remove virtual environment
-rm -rf .venv
-
-# Or if using uv
-uv venv --python 3.13 --remove .venv
-```
-
-## Environment Variables Reference
-
-Common environment variables used by CleverAgents:
-
-| Variable | Purpose | Example |
-|----------|---------|---------|
-| `OPENAI_API_KEY` | OpenAI API key | `sk-...` |
-| `ANTHROPIC_API_KEY` | Anthropic API key | `sk-ant-...` |
-| `GOOGLE_API_KEY` | Google Generative AI key | `...` |
-| `CLEVERAGENTS_DEFAULT_PROVIDER` | Default LLM provider | `openai` |
-| `CLEVERAGENTS_DEFAULT_MODEL` | Default model | `gpt-4o` |
-| `CLEVERAGENTS_LANGSMITH_ENABLED` | Enable LangSmith tracing | `true` |
-| `CLEVERAGENTS_LANGSMITH_API_KEY` | LangSmith API key | `...` |
-| `CLEVERAGENTS_TESTING_USE_MOCK_AI` | Use mock AI for testing | `true` |
-
-See [Observability](../reference/observability.md) for additional observability variables.
-
-## System-Specific Notes
-
-### macOS
-
-- Use Homebrew for package management: `brew install python@3.13`
-- If using Apple Silicon (M1/M2), ensure you're using native Python builds
-- Virtual environment activation: `source .venv/bin/activate`
-
-### Linux
-
-- Most distributions have Python 3.13 in their package repositories
-- Ubuntu/Debian: `sudo apt-get install python3.13 python3.13-venv`
-- Fedora/RHEL: `sudo dnf install python3.13 python3.13-devel`
-- Virtual environment activation: `source .venv/bin/activate`
-
-### Windows
-
-- Use Windows Terminal for better experience
-- PowerShell activation: `.venv\Scripts\Activate.ps1`
-- CMD activation: `.venv\Scripts\activate.bat`
-- WSL2 is recommended for better compatibility
-
-## Additional Resources
-
-- **[Architecture Guide](../architecture.md)** - System design and components
-- **[Quality Automation Guide](../development/quality-automation.md)** - Testing and CI/CD
-- **[Testing Guide](../development/testing.md)** - Writing tests
-- **[API Reference](../api/index.md)** - API documentation
-- **[FAQ](../faq.md)** - Frequently asked questions

mkdocs.yml

@@ -10,8 +10,6 @@ site_dir: build/site
 
 nav:
   - Specification: specification.md
-  - Guides:
-    - Installation & Setup: guides/installation-setup.md
   - Architecture: architecture.md
   - API Reference:
     - Overview: api/index.md
@@ -26,6 +24,8 @@ nav:
     - AI Providers: api/providers.md
     - TUI: api/tui.md
     - ACMS / UKO: api/acms.md
+  - Guides:
+    - Configuration Reference: guides/configuration-reference.md
   - Modules:
     - Shell Safety: modules/shell-safety.md
     - UKO Provenance Tracking: modules/uko-provenance.md