docs: add getting started tutorial

The automation-tracking-manager call in step 5 was blocking the main loop
indefinitely, causing 3+ consecutive initialization failures. This commit
documents the fix in CHANGELOG.md with the proper issue reference.

ISSUES CLOSED: #8835

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/getting-started.md

@@ -0,0 +1,411 @@
+# Getting Started with CleverAgents
+
+Welcome to CleverAgents! This guide will help you get up and running in about 5 minutes, walk you through your first project, and point you toward deeper learning resources.
+
+## What is CleverAgents?
+
+CleverAgents is a Python-first AI agent orchestration platform that lets you build, configure, and run intelligent automation workflows. It provides:
+
+- **Unified CLI** (`agents` command) for all interactions
+- **Interactive TUI** (Terminal User Interface) for hands-on agent management
+- **Actor System** — composable AI agents with tools and skills
+- **Plan Lifecycle** — structured workflow from strategy to execution to application
+- **Resource Management** — handle files, databases, containers, and more
+- **Multi-Provider Support** — OpenAI, Anthropic, Google, Azure, and others
+
+## Quick Start (5 Minutes)
+
+### 1. Clone the Repository
+
+```bash
+git clone https://git.cleverthis.com/cleveragents/cleveragents-core.git
+cd cleveragents-core
+```
+
+### 2. Set Up Your Environment
+
+```bash
+# Create a virtual environment
+python -m venv .venv
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+
+# Install CleverAgents with development dependencies
+pip install -e ".[dev,tests,docs]"
+
+# Set up pre-commit hooks and verify tooling
+bash scripts/setup-dev.sh
+```
+
+### 3. Verify Installation
+
+```bash
+# Check the CLI is working
+agents --version
+agents --help
+
+# Run diagnostics to check LLM provider configuration
+agents diagnostics
+```
+
+### 4. Configure an LLM Provider
+
+CleverAgents works with multiple LLM providers. Set up at least one:
+
+**OpenAI:**
+```bash
+export OPENAI_API_KEY="sk-..."
+```
+
+**Anthropic:**
+```bash
+export ANTHROPIC_API_KEY="sk-ant-..."
+```
+
+**Google:**
+```bash
+export GOOGLE_API_KEY="..."
+```
+
+See [LLM Provider Configuration](#llm-provider-configuration) below for all supported providers.
+
+### 5. Launch the Interactive TUI
+
+```bash
+# Install the TUI extra if not already installed
+pip install -e ".[tui]"
+
+# Launch the interactive terminal UI
+agents tui
+```
+
+Inside the TUI, you can:
+- Type messages and press `Enter` to chat with the active actor
+- Press `/` to open the slash command overlay
+- Press `@` to insert file/resource references
+- Press `!` to enter shell mode
+- Press `F1` for context-sensitive help
+- Press `Ctrl+Q` to quit
+
+## Your First Project: Hello World Agent
+
+Let's create a simple agent that greets you and answers questions.
+
+### Step 1: Create a Basic Actor Configuration
+
+Create a file `my-first-actor.yaml`:
+
+```yaml
+# Simple greeting actor
+name: local/hello-world
+entry_node: greeter
+nodes:
+  greeter:
+    model: gpt-4o  # or your preferred model
+    tool_sources: [builtin]
+    system_prompt: |
+      You are a friendly greeting agent. 
+      Respond warmly and helpfully to user messages.
+      Keep responses concise and friendly.
+```
+
+### Step 2: Use the Actor in the CLI
+
+```bash
+# Tell the agent to do something
+agents tell --actor local/hello-world "Say hello and tell me what you can do"
+
+# Or use the v3 plan workflow
+agents plan use local/hello-world my-project
+agents plan execute <PLAN_ID>
+agents plan apply <PLAN_ID>
+```
+
+### Step 3: Use the Actor in the TUI
+
+```bash
+# Launch the TUI
+agents tui
+
+# Inside the TUI:
+# 1. Press Ctrl+T to cycle through available actors
+# 2. Select "local/hello-world"
+# 3. Type a message and press Enter
+```
+
+## Basic Concepts
+
+### Actors
+
+**Actors** are the execution units of CleverAgents. Each actor:
+- Is defined in YAML with a name, entry node, and node graph
+- Binds an LLM, tools, and optional integrations (LSP, MCP)
+- Can be built-in (e.g., `openai/gpt-4o`) or custom (e.g., `local/my-actor`)
+
+Example actor structure:
+```yaml
+name: local/my-actor
+entry_node: main
+nodes:
+  main:
+    model: gpt-4o
+    tool_sources: [builtin, mcp://bash-tools]
+```
+
+See [Actor System](../architecture.md#actor-system) for details.
+
+### Tools
+
+**Tools** are atomic capabilities available to actors. They include:
+- Built-in tools (file operations, shell commands)
+- MCP (Model Context Protocol) tools from external servers
+- LSP (Language Server Protocol) tools for code intelligence
+- Custom tools defined in your project
+
+Tools are registered in the `ToolRegistry` and invoked by actors during execution.
+
+### Skills
+
+**Skills** are composable capability bundles that expose one or more tools. They:
+- Load from YAML or AgentSkills.io-compatible directories
+- Support progressive disclosure (discover → activate → deactivate)
+- Are tracked by the `SkillRegistry`
+
+### Resources
+
+**Resources** are managed external entities like files, databases, and containers. They:
+- Organize into a DAG (Directed Acyclic Graph) with dependency tracking
+- Support multiple types: `file`, `directory`, `sqlite`, `postgresql`, `container.docker`, etc.
+- Each type has a handler implementing CRUD, checkpoint, and rollback
+
+### Plan Lifecycle
+
+The **Plan Lifecycle** is the central workflow abstraction:
+
+```
+Action → Strategize → Execute → Apply
+  ↑                      ↓
+  └──────────────────────┘
+       (correction/rollback)
+```
+
+| Phase | Description |
+|-------|-------------|
+| **Action** | User intent captured as a plan request |
+| **Strategize** | LLM generates a structured plan with operations |
+| **Execute** | Operations executed against resources via tools |
+| **Apply** | Validated changes committed; diff reviewed and approved |
+
+See [Plan Lifecycle](../architecture.md#plan-lifecycle) for details.
+
+### Personas
+
+**Personas** are named identities that bind:
+- An actor (which LLM and tools to use)
+- Argument presets (default parameters)
+- Scope references (which resources are available)
+
+Personas are persisted in `~/.config/cleveragents/personas/` and can be switched in the TUI with `Ctrl+T`.
+
+### Sessions
+
+**Sessions** are conversation histories. You can:
+- Create new sessions: `agents session create --actor openai/gpt-4o`
+- List sessions: `agents session list`
+- Export sessions: `agents session export --session-id <ID> --output session.json`
+- Import sessions: `agents session import --input session.json`
+
+## LLM Provider Configuration
+
+CleverAgents automatically discovers and uses configured LLM providers. Set environment variables for the providers you want to use:
+
+| Provider | Environment Variable | Example |
+|----------|----------------------|---------|
+| OpenAI | `OPENAI_API_KEY` | `sk-...` |
+| Anthropic | `ANTHROPIC_API_KEY` | `sk-ant-...` |
+| Google | `GOOGLE_API_KEY` or `GOOGLE_GENAI_API_KEY` | `AIza...` |
+| Azure OpenAI | `AZURE_OPENAI_API_KEY`, `AZURE_OPENAI_ENDPOINT`, `AZURE_OPENAI_DEPLOYMENT` | See Azure docs |
+| OpenRouter | `OPENROUTER_API_KEY` | `sk-or-...` |
+| Groq | `GROQ_API_KEY` | `gsk_...` |
+| Together | `TOGETHER_API_KEY` | `...` |
+| Cohere | `COHERE_API_KEY` | `...` |
+
+### Setting a Default Provider
+
+```bash
+# Pin the global provider
+export CLEVERAGENTS_DEFAULT_PROVIDER=openai
+
+# Pin a specific model
+export CLEVERAGENTS_DEFAULT_MODEL=gpt-4o
+```
+
+### Checking Your Configuration
+
+```bash
+# See which providers are configured and which actor is selected
+agents diagnostics
+```
+
+## Common First-Time Issues and Solutions
+
+### Issue: "No LLM provider configured"
+
+**Symptom:** Error message says no API keys found.
+
+**Solution:**
+1. Verify you've set an environment variable: `echo $OPENAI_API_KEY`
+2. If empty, set it: `export OPENAI_API_KEY="sk-..."`
+3. Run `agents diagnostics` to verify the provider is detected
+4. Restart your terminal or shell session if you just set the variable
+
+### Issue: "Actor not found"
+
+**Symptom:** Error says `local/my-actor` doesn't exist.
+
+**Solution:**
+1. Check the actor file exists: `ls my-first-actor.yaml`
+2. Verify the file is valid YAML (check indentation)
+3. Use the full path if the file is not in the current directory
+4. Built-in actors use the format `<provider>/<model>` (e.g., `openai/gpt-4o`)
+
+### Issue: "TUI won't start"
+
+**Symptom:** `agents tui` fails or shows a blank screen.
+
+**Solution:**
+1. Ensure the TUI extra is installed: `pip install -e ".[tui]"`
+2. Check your terminal supports 256 colors: `echo $TERM`
+3. Try running with explicit terminal: `TERM=xterm-256color agents tui`
+4. Check for conflicting environment variables: `env | grep -i textual`
+
+### Issue: "Tool execution fails"
+
+**Symptom:** Actor tries to use a tool but gets an error.
+
+**Solution:**
+1. Check the tool is available: `agents tools list` (if implemented)
+2. Verify tool permissions are granted (TUI shows permission overlay)
+3. Check tool configuration in the actor YAML
+4. Review tool documentation: see [Tool System](../architecture.md#tool-system)
+
+### Issue: "Session not found"
+
+**Symptom:** Error when trying to export or import a session.
+
+**Solution:**
+1. List available sessions: `agents session list`
+2. Use the correct session ID from the list
+3. Check the session file exists (for import): `ls session.json`
+4. Verify the JSON is valid: `python -m json.tool session.json`
+
+### Issue: "Permission denied" errors
+
+**Symptom:** Actor can't read/write files or access resources.
+
+**Solution:**
+1. Check file permissions: `ls -la <file>`
+2. Ensure the file is readable/writable by your user
+3. In the TUI, approve permission requests when prompted (press `y`)
+4. Check resource configuration in your project
+
+## Next Learning Steps
+
+Now that you're up and running, here's what to explore next:
+
+### 1. **Understand the Architecture** (30 minutes)
+   - Read [Architecture Overview](../architecture.md)
+   - Learn about the layered design and key components
+   - Understand the Plan Lifecycle in detail
+
+### 2. **Build Your First Custom Actor** (1 hour)
+   - Create a YAML actor configuration
+   - Add tools and integrations
+   - Test in the TUI and CLI
+   - See [Actor System](../architecture.md#actor-system) for details
+
+### 3. **Work with Resources** (1 hour)
+   - Create file and database resources
+   - Use resources in your actor
+   - Understand the Resource DAG
+   - See [Resource System](../architecture.md#resource-system)
+
+### 4. **Explore Tools and Skills** (1 hour)
+   - Discover available tools
+   - Create custom tools
+   - Load and manage skills
+   - See [Tool System](../architecture.md#tool-system) and [Skill System](../architecture.md#skill-system)
+
+### 5. **Master the Plan Lifecycle** (2 hours)
+   - Create and execute plans
+   - Understand phase transitions
+   - Use correction and rollback
+   - See [Plan Lifecycle](../architecture.md#plan-lifecycle)
+
+### 6. **Integrate with External Services** (2 hours)
+   - Set up MCP (Model Context Protocol) servers
+   - Configure LSP (Language Server Protocol) integration
+   - Use ACMS (Advanced Context Management System)
+   - See [MCP Integration](../architecture.md#mcp-integration) and [LSP Integration](../architecture.md#lsp-integration)
+
+### 7. **Deploy to Production** (2 hours)
+   - Use server mode: `agents server connect`
+   - Deploy with Kubernetes (see `k8s/`)
+   - Configure observability and logging
+   - See [Server Architecture](../development/agent-system-specification.md)
+
+## Key Documentation References
+
+| Topic | Document |
+|-------|----------|
+| **Architecture** | [Architecture Overview](../architecture.md) |
+| **Specification** | [Full Specification](../specification.md) |
+| **API Reference** | [API Docs](../api/index.md) |
+| **Development** | [Development Guide](../development/agent-system-specification.md) |
+| **Testing** | [Testing Guide](../development/testing.md) |
+| **FAQ** | [Frequently Asked Questions](../faq.md) |
+| **Design Decisions** | [Architecture Decision Records (ADRs)](../adr/index.md) |
+
+## Tips for Success
+
+1. **Start Small** — Create simple actors before complex ones
+2. **Use the TUI** — The interactive interface is great for learning and debugging
+3. **Read the Specification** — `docs/specification.md` is the authoritative source
+4. **Check the Examples** — See `examples/` for real-world configurations
+5. **Run Tests** — Use `nox -s unit_tests` to verify your changes
+6. **Ask for Help** — Check the FAQ and ADRs for common questions
+
+## Troubleshooting Commands
+
+```bash
+# Check your setup
+agents diagnostics
+
+# List available actors
+agents actor list
+
+# List available tools
+agents tools list  # if implemented
+
+# List sessions
+agents session list
+
+# View help for any command
+agents <command> --help
+
+# Run tests to verify everything works
+nox -s unit_tests
+
+# Check code quality
+nox -s lint
+nox -s typecheck
+```
+
+## What's Next?
+
+- **Build an actor** — Create a custom actor for your use case
+- **Explore the TUI** — Spend time in the interactive interface
+- **Read the architecture** — Understand the design decisions
+- **Join the community** — Check out discussions and issues
+- **Contribute** — See [CONTRIBUTING.md](../../CONTRIBUTING.md) for guidelines
+
+Happy automating! 🚀

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,9 +10,9 @@ site_dir: build/site
 
 nav:
   - Specification: specification.md
-  - Guides:
-    - Installation & Setup: guides/installation-setup.md
   - Architecture: architecture.md
+  - Guides:
+    - Getting Started: guides/getting-started.md
   - API Reference:
     - Overview: api/index.md
     - Core Utilities: api/core.md