docs: add installation and setup guide

docs/guides/installation-setup.md

@@ -0,0 +1,496 @@
+# 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,6 +10,8 @@ site_dir: build/site
 
 nav:
   - Specification: specification.md
+  - Guides:
+    - Installation & Setup: guides/installation-setup.md
   - Architecture: architecture.md
   - API Reference:
     - Overview: api/index.md