docs/api/config.md

@@ -98,3 +98,264 @@ from cleveragents.config.security_scanner import scan_for_secrets
 issues = scan_for_secrets({"db_url": "postgresql://user:password@host/db"})
 # → [SecretIssue(field="db_url", pattern="password_in_url")]
 ```
+
+---
+
+## Complete Environment Variable Reference
+
+All `CLEVERAGENTS_*` environment variables recognised by the settings system.
+Variables marked **secret** are redacted from logs and CLI output.
+
+### Provider and Model Selection
+
+| Environment Variable | Type | Default | Description |
+|---------------------|------|---------|-------------|
+| `CLEVERAGENTS_DEFAULT_PROVIDER` | `str` | auto-detected | Pin the global LLM provider (`openai`, `anthropic`, `google`, `azure`, `openrouter`, `groq`, `together`, `cohere`, `gemini`) |
+| `CLEVERAGENTS_DEFAULT_MODEL` | `str` | provider default | Pin the global model ID |
+| `CLEVERAGENTS_FALLBACK_PROVIDERS` | `str` | `""` | Comma-separated ordered list of fallback providers (e.g. `anthropic,openrouter`) |
+
+### Provider API Keys
+
+| Environment Variable | Provider | Secret |
+|---------------------|----------|--------|
+| `OPENAI_API_KEY` | OpenAI | ✓ |
+| `ANTHROPIC_API_KEY` | Anthropic | ✓ |
+| `GOOGLE_API_KEY` | Google | ✓ |
+| `GOOGLE_GENAI_API_KEY` | Google (alias) | ✓ |
+| `GEMINI_API_KEY` | Gemini | ✓ |
+| `GOOGLE_GEMINI_API_KEY` | Gemini (alias) | ✓ |
+| `AZURE_OPENAI_API_KEY` | Azure OpenAI | ✓ |
+| `AZURE_OPENAI_ENDPOINT` | Azure OpenAI | — |
+| `AZURE_OPENAI_DEPLOYMENT` | Azure OpenAI | — |
+| `OPENROUTER_API_KEY` | OpenRouter | ✓ |
+| `CLEVERAGENTS_OPENROUTER_ORGANIZATION` | OpenRouter | — |
+| `GROQ_API_KEY` | Groq | ✓ |
+| `TOGETHER_API_KEY` | Together | ✓ |
+| `COHERE_API_KEY` | Cohere | ✓ |
+| `HF_TOKEN` | Hugging Face | ✓ |
+
+### Paths and Storage
+
+| Environment Variable | Type | Default | Description |
+|---------------------|------|---------|-------------|
+| `CLEVERAGENTS_DATA_DIR` | `path` | `~/.local/share/cleveragents` | Root directory for database, logs, and runtime data |
+| `CLEVERAGENTS_CONFIG_PATH` | `path` | `~/.config/cleveragents/config.toml` | Path to the TOML configuration file |
+| `CLEVERAGENTS_ACTOR_PATH` | `path` | `~/.config/cleveragents/actors` | Directory scanned for custom actor YAML files |
+| `CLEVERAGENTS_DB_URL` | `str` | SQLite in `CLEVERAGENTS_DATA_DIR` | Database URL (SQLite, PostgreSQL, MySQL, or DuckDB) |
+
+### Budget and Cost Controls
+
+| Environment Variable | Type | Default | Description |
+|---------------------|------|---------|-------------|
+| `CLEVERAGENTS_BUDGET_PER_PLAN` | `int` | unlimited | Maximum tokens consumed per plan execution |
+| `CLEVERAGENTS_BUDGET_PER_DAY` | `int` | unlimited | Maximum tokens consumed per calendar day |
+
+### Actor Defaults
+
+| Environment Variable | Type | Default | Description |
+|---------------------|------|---------|-------------|
+| `CLEVERAGENTS_ACTOR__DEFAULT__ESTIMATION` | `str` | `""` | Name of the actor used for cost/effort estimation |
+| `CLEVERAGENTS_ACTOR__DEFAULT__INVARIANT` | `str` | `""` | Name of the actor used for invariant reconciliation |
+
+### Logging and Observability
+
+| Environment Variable | Type | Default | Description |
+|---------------------|------|---------|-------------|
+| `CLEVERAGENTS_LOG_LEVEL` | `str` | `WARNING` | Log level: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL` |
+| `CLEVERAGENTS_LOG_FORMAT` | `str` | `text` | Log format: `text` or `json` |
+| `CLEVERAGENTS_LANGSMITH_ENABLED` | `bool` | `false` | Enable LangSmith tracing |
+| `CLEVERAGENTS_LANGSMITH_PROJECT` | `str` | `""` | LangSmith project name |
+| `CLEVERAGENTS_LANGSMITH_API_KEY` | `str` | `""` | LangSmith API key (secret) |
+| `CLEVERAGENTS_LANGSMITH_ENDPOINT` | `str` | LangSmith default | LangSmith endpoint URL |
+| `CLEVERAGENTS_LANGSMITH_USER_ID` | `str` | `""` | LangSmith user ID for trace attribution |
+| `CLEVERAGENTS_LANGSMITH_TAGS` | `str` | `""` | Comma-separated tags added to all LangSmith traces |
+
+### Testing
+
+| Environment Variable | Type | Default | Description |
+|---------------------|------|---------|-------------|
+| `CLEVERAGENTS_TESTING_USE_MOCK_AI` | `bool` | `false` | Force the in-repo mock provider; disables all real API calls |
+
+### TUI
+
+| Environment Variable | Type | Default | Description |
+|---------------------|------|---------|-------------|
+| `CLEVERAGENTS_TUI_ANIMATIONS` | `bool` | `true` | Enable/disable TUI animations |
+
+---
+
+## Configuration File
+
+CleverAgents reads a TOML configuration file from `~/.config/cleveragents/config.toml`
+(or the path set by `CLEVERAGENTS_CONFIG_PATH`). Environment variables always take
+precedence over file values.
+
+```toml
+# ~/.config/cleveragents/config.toml
+
+[defaults]
+provider = "anthropic"
+model = "claude-sonnet-4-20250514"
+fallback_providers = ["openrouter", "openai"]
+
+[budget]
+per_plan = 100000
+per_day = 1000000
+
+[actor.default]
+estimation = "local/my-estimator"
+invariant = "local/my-invariant-checker"
+
+[logging]
+level = "INFO"
+format = "json"
+
+[langsmith]
+enabled = true
+project = "my-project"
+```
+
+---
+
+## Actor Configuration YAML Format
+
+Custom actors are defined as YAML files placed in `~/.config/cleveragents/actors/`
+(or the path set by `CLEVERAGENTS_ACTOR_PATH`).
+
+### Minimal LLM Actor
+
+```yaml
+name: local/my-assistant   # Required — must be namespace/identifier
+type: llm                  # Required — llm | tool | graph
+description: My assistant  # Required
+model: gpt-4o              # Required for llm and graph types
+version: "1.0"             # Optional
+```
+
+### LLM Actor with Skills
+
+```yaml
+name: local/code-assistant
+type: llm
+description: Code-focused assistant with file and git tools
+model: claude-sonnet-4-20250514
+version: "1.0"
+
+skills:
+  - local/file-ops
+  - local/git-ops
+```
+
+### Graph Actor (Multi-Node Workflow)
+
+```yaml
+name: local/dev-pipeline
+type: graph
+description: Multi-step development pipeline
+model: gpt-4o
+version: "1.0"
+
+skills:
+  - local/file-ops
+
+route:
+  entry_node: planner
+  exit_nodes:
+    - reviewer
+
+  nodes:
+    - id: planner
+      type: agent
+      name: Planner
+      description: Plans the implementation
+      config:
+        model: gpt-4o
+        prompt: "Analyze requirements and create a plan."
+
+    - id: implementer
+      type: agent
+      name: Implementer
+      description: Implements the plan
+      config:
+        model: gpt-4o
+        prompt: "Implement the changes per the plan."
+
+    - id: gate
+      type: conditional
+      name: Quality Gate
+      description: Routes based on lint result
+      config:
+        conditions:
+          - check: "state.get('lint_ok') == True"
+            route_to: reviewer
+          - check: "state.get('lint_ok') == False"
+            route_to: planner
+
+    - id: reviewer
+      type: agent
+      name: Reviewer
+      description: Reviews the implementation
+      config:
+        model: gpt-4o
+        prompt: "Review the implementation for correctness."
+
+  edges:
+    - from_node: planner
+      to_node: implementer
+    - from_node: implementer
+      to_node: gate
+    - from_node: gate
+      to_node: planner
+    - from_node: gate
+      to_node: reviewer
+```
+
+See [Actor Configuration Reference](../reference/actor_config.md) for the full field listing and validation rules.
+
+---
+
+## Action Configuration YAML Format
+
+Actions define high-level tasks. They are typically created via the CLI
+(`agents action create`) but can also be written as YAML files.
+
+```yaml
+name: local/refactor-auth
+description: Refactor the authentication module to use async patterns
+version: "1.0"
+
+# Actor to use for this action
+actor: local/dev-pipeline
+
+# Automation profile (manual | review | supervised | cautious | trusted | autonomous | ci | full-auto)
+automation_profile: trusted
+
+# Resources this action operates on
+resources:
+  - type: git-checkout
+    path: /path/to/repo
+    name: main-repo
+
+# Invariants enforced for every plan spawned from this action
+invariants:
+  - "All API changes must maintain backward compatibility"
+  - "Test coverage must not decrease"
+
+# Definition of Done
+definition_of_done:
+  must:
+    - "All existing tests pass"
+    - "New tests cover the changed code"
+  should:
+    - "Cyclomatic complexity does not increase"
+```
+
+---
+
+## Related Documentation
+
+- [ADR-024 Configuration System](../adr/ADR-024-configuration-system.md) — design rationale
+- [ADR-025 Observability & Logging](../adr/ADR-025-observability-and-logging.md) — LangSmith integration details
+- [Actor Configuration Reference](../reference/actor_config.md) — full actor YAML schema
+- [Diagnostics Check List](../reference/diagnostics_checks.md) — `agents diagnostics` checks
+- [Troubleshooting Guide](../guides/troubleshooting.md) — common configuration problems and fixes

docs/guides/faq.md

@@ -0,0 +1,326 @@
+# Frequently Asked Questions
+
+Quick answers to common questions about CleverAgents. For deeper dives, follow the links to the relevant documentation.
+
+> **Note:** The existing [Architecture FAQ](../faq.md) covers advanced architectural questions about ACMS, dependency closures, parallel execution, and automation profiles. This guide focuses on practical day-to-day usage questions.
+
+---
+
+## General
+
+### What is CleverAgents?
+
+CleverAgents is a Python-first automation platform that lets you build, run, and manage AI agents for software development tasks. It provides:
+
+- A unified `agents` CLI and interactive Textual TUI
+- A structured plan lifecycle (Strategize → Execute → Apply) with a full decision tree
+- Multi-provider LLM support (OpenAI, Anthropic, Google, Azure, Groq, and more)
+- A git worktree sandbox for safe, isolated plan execution
+- SQLite-backed local persistence for sessions, plans, and decisions
+- An Actor system for composing reusable agent workflows
+
+See the [README](../../README.md) for a full feature overview.
+
+### How does CleverAgents differ from using LangChain/LangGraph directly?
+
+CleverAgents is built *on top of* LangChain/LangGraph and adds:
+
+| Feature | LangChain/LangGraph | CleverAgents |
+|---------|--------------------|----|
+| Provider switching | Manual wiring | Auto-detected from env vars |
+| Plan lifecycle | Custom | Built-in Strategize/Execute/Apply |
+| Decision tracking | None | Full decision tree with correction |
+| Sandbox isolation | None | Git worktree + filesystem overlays |
+| Invariant enforcement | None | Multi-scope invariant system |
+| CLI/TUI | None | Unified `agents` CLI + Textual TUI |
+| Persistence | Custom | SQLite with Alembic migrations |
+| Actor system | Chains/Graphs | Named, versioned, YAML-configured actors |
+
+If you want full control over every LangGraph node and edge, use LangGraph directly. If you want a structured, production-ready agent platform with batteries included, use CleverAgents.
+
+### Is CleverAgents open source?
+
+Yes. CleverAgents Core is licensed under the Apache 2.0 License. See [LICENSE](../../LICENSE) and [ATTRIBUTIONS.md](../../ATTRIBUTIONS.md).
+
+---
+
+## Setup and Configuration
+
+### Can I use CleverAgents without an LLM API key?
+
+Yes, for **testing and development** purposes. Set the mock provider environment variable:
+
+```bash
+export CLEVERAGENTS_TESTING_USE_MOCK_AI=true
+agents tell --actor mock/default "Hello"
+```
+
+The mock provider returns deterministic responses without hitting any external API. It is used by the full test suite to avoid API costs.
+
+For production use, you need at least one real provider API key. See [LLM provider configuration](../../README.md#llm-provider-configuration) for the list of supported providers.
+
+### Where does CleverAgents store its data?
+
+| Data type | Default location |
+|-----------|-----------------|
+| Database | `~/.local/share/cleveragents/cleveragents.db` |
+| Config file | `~/.config/cleveragents/config.toml` |
+| Actors | `~/.config/cleveragents/actors/` |
+| Personas | `~/.config/cleveragents/personas/` |
+| Logs | `~/.local/share/cleveragents/logs/` |
+
+Override the data directory:
+
+```bash
+export CLEVERAGENTS_DATA_DIR=/custom/path
+```
+
+Override the config file:
+
+```bash
+export CLEVERAGENTS_CONFIG_PATH=/custom/config.toml
+```
+
+### How do I pin a specific LLM provider and model?
+
+```bash
+# Via environment variables
+export CLEVERAGENTS_DEFAULT_PROVIDER=anthropic
+export CLEVERAGENTS_DEFAULT_MODEL=claude-sonnet-4-20250514
+
+# Via config file (~/.config/cleveragents/config.toml)
+[defaults]
+provider = "anthropic"
+model = "claude-sonnet-4-20250514"
+
+# Via actor configuration (most specific)
+agents actor set-default anthropic/claude-sonnet-4-20250514
+```
+
+### How do I check which provider is being used?
+
+```bash
+agents diagnostics
+```
+
+This prints the detected provider, model, and API key status for every supported provider.
+
+---
+
+## Actors
+
+### How do I add a custom actor?
+
+1. Create a YAML file in `~/.config/cleveragents/actors/`:
+
+```yaml
+# ~/.config/cleveragents/actors/my-assistant.yaml
+name: local/my-assistant
+type: llm
+description: My custom assistant
+model: gpt-4o
+```
+
+2. Verify it is registered:
+
+```bash
+agents actor list
+```
+
+3. Use it:
+
+```bash
+agents tell --actor local/my-assistant "Hello"
+```
+
+For graph actors with multiple nodes, see [Actor Configuration Reference](../reference/actor_config.md).
+
+### What is the difference between built-in and custom actors?
+
+- **Built-in actors** (`<provider>/<model>`, e.g., `openai/gpt-4o`) are immutable and auto-generated from the provider registry. You cannot modify or delete them.
+- **Custom actors** must be named `local/<id>` (or another custom namespace). They are stored in YAML files and fully configurable.
+
+The default actor cannot be removed. Use `--unsafe` when adding or updating actors marked as unsafe.
+
+### How do I set a default actor?
+
+```bash
+agents actor set-default openai/gpt-4o
+```
+
+Once set, commands like `agents tell` and `agents build` do not require `--actor`.
+
+### Can I use an actor with a local LLM (Ollama)?
+
+Yes. Configure an actor pointing to an OpenAI-compatible endpoint:
+
+```yaml
+name: local/ollama-llama3
+type: llm
+description: Local Llama 3 via Ollama
+model: llama3
+```
+
+Set the base URL to your Ollama instance:
+
+```bash
+export OPENAI_API_BASE=http://localhost:11434/v1
+export OPENAI_API_KEY=ollama   # Ollama accepts any non-empty key
+```
+
+Then use the actor:
+
+```bash
+agents tell --actor local/ollama-llama3 "Hello"
+```
+
+---
+
+## Tools and Skills
+
+### How do I create a custom tool?
+
+Tools are Python functions registered with the tool registry. Create a tool definition:
+
+```python
+# my_tools/search.py
+from cleveragents.tool import tool
+
+@tool(name="local/web-search", description="Search the web")
+def web_search(query: str) -> str:
+    """Search the web for the given query."""
+    # implementation
+    return results
+```
+
+Register it:
+
+```bash
+agents tool add local/web-search --path my_tools/search.py
+```
+
+See [Tool API Reference](../api/tool.md) for the full tool lifecycle and registry API.
+
+### What is the difference between a Tool and a Skill?
+
+- **Tools** are individual callable functions that actors can invoke (like LangChain tools). They perform a single operation.
+- **Skills** are collections of related tools bundled together as a reusable unit. An actor declares which skills it uses, and the skill's tools become available to it.
+
+Example: a `local/git-ops` skill might bundle `git_commit`, `git_push`, `git_diff`, and `git_log` tools.
+
+---
+
+## Plans and Actions
+
+### What is the difference between an Action and a Plan?
+
+- An **Action** is a high-level task definition — it describes *what* you want to accomplish, the resources involved, invariants to enforce, and the automation profile to use.
+- A **Plan** is a concrete execution instance of an Action. When you run an action, CleverAgents creates a Plan and runs it through the Strategize → Execute → Apply lifecycle.
+
+Think of Actions as templates and Plans as runs.
+
+### How does the git worktree sandbox work?
+
+When a plan executes against a git repository resource, CleverAgents:
+
+1. Creates a new branch `cleveragents/plan-<plan-id>` from the current HEAD.
+2. Creates a temporary git worktree in a system temp directory.
+3. The actor writes all changes inside the worktree (not the original repo).
+4. On **Apply**: stages and commits all changes in the worktree, then merges the sandbox branch back into the original branch.
+5. On **Rollback**: discards the worktree entirely — the original branch is untouched.
+
+This means you can always safely reject a plan's changes without any manual cleanup.
+
+See [Git Worktree Sandbox](../modules/git-worktree-sandbox.md) for the full technical reference.
+
+### What is the A2A protocol?
+
+A2A (Agent-to-Agent) is a JSON-RPC 2.0 protocol that CleverAgents uses internally to wire the CLI and TUI to live application services (session, plan, registry, event). It follows the standard JSON-RPC 2.0 wire format with `method`, `id`, `result`, and `error` fields.
+
+See [A2A Protocol Reference](../api/a2a.md) for details.
+
+### How do I correct a bad decision in a plan?
+
+Use `agents plan correct`:
+
+```bash
+# View the decision tree
+agents plan tree <plan-id>
+
+# Correct a specific decision
+agents plan correct <decision-id> \
+  --mode revert \
+  --guidance "Use gRPC instead of REST for this service"
+```
+
+The system marks the original decision as superseded, creates a new decision with your guidance, and recomputes only the affected downstream decisions — preserving all unrelated work.
+
+---
+
+## Testing
+
+### How do I run tests without hitting real APIs?
+
+Set the mock AI environment variable:
+
+```bash
+export CLEVERAGENTS_TESTING_USE_MOCK_AI=true
+
+# Run all tests
+nox -s unit_tests
+nox -s integration_tests
+
+# Run a specific feature
+nox -s unit_tests -- features/plan_model.feature
+```
+
+The mock provider is used by the full CI test suite and never hits external APIs.
+
+### What testing frameworks does CleverAgents use?
+
+- **Behave** (BDD/Gherkin) for unit-level and scenario tests — feature files live under `features/`
+- **Robot Framework** for integration and end-to-end tests — suites live under `robot/`
+- **ASV** (airspeed velocity) for performance benchmarks — under `benchmarks/`
+- **Coverage**: `coverage.py` with branch coverage, enforced at **≥97%**
+
+Always run tests through `nox` sessions, never invoke `behave` or `robot` directly.
+
+See [Testing Guide](../development/testing.md) for full details.
+
+---
+
+## Contributing
+
+### How do I contribute to CleverAgents?
+
+1. Read [CONTRIBUTING.md](../../CONTRIBUTING.md) — it covers the full development workflow, coding standards, and review process.
+2. Set up your development environment:
+   ```bash
+   git clone https://git.cleverthis.com/cleveragents/cleveragents-core.git
+   cd cleveragents-core
+   python -m venv .venv && source .venv/bin/activate
+   pip install -e ".[dev,tests,docs,tui]"
+   bash scripts/setup-dev.sh
+   ```
+3. Create a feature branch and make your changes.
+4. Ensure all checks pass:
+   ```bash
+   nox -s format lint typecheck unit_tests integration_tests coverage_report
+   ```
+5. Open a pull request against `master`.
+
+### Where do I report bugs?
+
+File issues at: [https://git.cleverthis.com/cleveragents/cleveragents-core/issues](https://git.cleverthis.com/cleveragents/cleveragents-core/issues)
+
+Include:
+- Output of `agents diagnostics`
+- Output of `agents --version`
+- Your Python version (`python --version`)
+- Debug logs (`CLEVERAGENTS_LOG_LEVEL=DEBUG agents <command> 2>debug.log`)
+
+---
+
+## Troubleshooting
+
+For detailed troubleshooting steps, see the [Troubleshooting Guide](troubleshooting.md).

docs/guides/index.md

@@ -0,0 +1,20 @@
+# Guides
+
+Practical how-to guides for working with CleverAgents.
+
+## Available Guides
+
+| Guide | Description |
+|-------|-------------|
+| [Troubleshooting](troubleshooting.md) | Step-by-step fixes for installation, provider, database, plan execution, TUI, and test suite issues |
+| [FAQ](faq.md) | Frequently asked questions about CleverAgents — setup, actors, plans, testing, and contributing |
+
+## Other Documentation
+
+- **[API Reference](../api/index.md)** — Python API for `cleveragents` modules
+- **[Configuration Reference](../api/config.md)** — All `CLEVERAGENTS_*` environment variables, config file format, actor YAML schema
+- **[Reference](../reference/)** — Detailed reference pages for CLI commands, schemas, and subsystems
+- **[Modules](../modules/)** — Deep-dive documentation for specific subsystems (git worktree sandbox, UKO, invariant reconciliation, etc.)
+- **[Development](../development/)** — Contributor guides: testing, CI/CD, quality automation, ops runbook
+- **[Architecture FAQ](../faq.md)** — Advanced architectural questions about ACMS, parallel execution, and automation profiles
+- **[ADRs](../adr/index.md)** — Architecture Decision Records explaining *why* key design choices were made

docs/guides/troubleshooting.md

@@ -0,0 +1,776 @@
+# Troubleshooting Guide
+
+This guide covers the most common issues encountered when installing, configuring, and running CleverAgents, along with step-by-step remediation instructions.
+
+---
+
+## Table of Contents
+
+- [Installation Issues](#installation-issues)
+- [LLM Provider Issues](#llm-provider-issues)
+- [Database Issues](#database-issues)
+- [Plan Execution Issues](#plan-execution-issues)
+- [TUI Issues](#tui-issues)
+- [Test Suite Issues](#test-suite-issues)
+- [Common Error Messages](#common-error-messages)
+- [Diagnostic Commands](#diagnostic-commands)
+- [Getting Help](#getting-help)
+
+---
+
+## Installation Issues
+
+### Python version mismatch
+
+CleverAgents requires **Python 3.11 or later**. Check your version:
+
+```bash
+python --version
+# or
+python3 --version
+```
+
+If you see `Python 3.10.x` or earlier, install a supported version. The project ships a `.python-version` file for [pyenv](https://github.com/pyenv/pyenv) users:
+
+```bash
+# Install pyenv (if not already installed)
+curl https://pyenv.run | bash
+
+# Install the required Python version
+pyenv install $(cat .python-version)
+pyenv local $(cat .python-version)
+```
+
+### Virtual environment not activated
+
+Symptoms: `agents: command not found` or `ModuleNotFoundError: No module named 'cleveragents'`.
+
+```bash
+# Create and activate a virtual environment
+python -m venv .venv
+source .venv/bin/activate   # Linux/macOS
+.venv\Scripts\activate      # Windows
+
+# Verify activation
+which python   # should point to .venv/bin/python
+```
+
+### `pip install` failures
+
+**Dependency resolution errors:**
+
+```bash
+# Upgrade pip first
+pip install --upgrade pip
+
+# Install with all extras
+pip install -e ".[dev,tests,docs,tui]"
+```
+
+**Build errors for compiled extensions:**
+
+```bash
+# Install build tools (Debian/Ubuntu)
+sudo apt-get install build-essential python3-dev
+
+# Install build tools (macOS)
+xcode-select --install
+```
+
+**Lock file conflicts (uv users):**
+
+```bash
+# Sync from the lock file
+uv sync
+
+# Or regenerate the lock file
+uv lock --upgrade
+```
+
+### Pre-commit hooks failing on first setup
+
+```bash
+# Run the setup script
+bash scripts/setup-dev.sh
+
+# Or install hooks manually
+pre-commit install
+pre-commit run --all-files
+```
+
+---
+
+## LLM Provider Issues
+
+### Missing API key
+
+**Symptom:** `Error [525] CONFIGURATION_ERROR: No LLM provider is configured`
+
+CleverAgents requires at least one provider API key. Run diagnostics to see which keys are detected:
+
+```bash
+agents diagnostics
+```
+
+Set the appropriate key for your provider:
+
+```bash
+# OpenAI
+export OPENAI_API_KEY="sk-..."
+
+# Anthropic
+export ANTHROPIC_API_KEY="sk-ant-..."
+
+# Google
+export GOOGLE_API_KEY="AIza..."
+
+# Groq
+export GROQ_API_KEY="gsk_..."
+```
+
+Add the export to your shell profile (`~/.bashrc`, `~/.zshrc`, etc.) to persist it across sessions.
+
+### Wrong provider selected
+
+**Symptom:** The system uses a different provider than expected.
+
+The provider auto-detection order is:
+
+```
+openai → anthropic → google → azure → openrouter → groq → together → cohere → gemini
+```
+
+To pin a specific provider:
+
+```bash
+export CLEVERAGENTS_DEFAULT_PROVIDER=anthropic
+export CLEVERAGENTS_DEFAULT_MODEL=claude-sonnet-4-20250514
+```
+
+Or set it in your config file (`~/.config/cleveragents/config.toml`):
+
+```toml
+[defaults]
+provider = "anthropic"
+model = "claude-sonnet-4-20250514"
+```
+
+### Model not found
+
+**Symptom:** `Error [527] MODEL_UNAVAILABLE: Model 'gpt-5' not found`
+
+Verify the model name is correct for your provider. Check the capability matrix:
+
+```bash
+# List available actors (which embed provider/model choices)
+agents actor list
+
+# Check provider documentation
+# See: docs/reference/providers.md
+```
+
+Common model identifiers:
+
+| Provider | Example model IDs |
+|----------|------------------|
+| OpenAI | `gpt-4o`, `gpt-4o-mini`, `o1-preview` |
+| Anthropic | `claude-sonnet-4-20250514`, `claude-3-5-haiku-20241022` |
+| Google | `gemini-2.0-flash`, `gemini-1.5-pro` |
+| Groq | `llama-3.3-70b-versatile`, `mixtral-8x7b-32768` |
+
+### Rate limit errors
+
+**Symptom:** `Error [429] RATE_LIMITED: Too many requests`
+
+CleverAgents has built-in retry logic with exponential backoff. If you hit persistent rate limits:
+
+1. **Reduce concurrency** — avoid running multiple parallel plans simultaneously.
+2. **Switch to a fallback provider:**
+
+```bash
+export CLEVERAGENTS_FALLBACK_PROVIDERS="anthropic,openrouter"
+```
+
+3. **Set a budget limit** to prevent runaway token usage:
+
+```bash
+export CLEVERAGENTS_BUDGET_PER_PLAN=50000   # tokens per plan
+export CLEVERAGENTS_BUDGET_PER_DAY=500000   # tokens per day
+```
+
+### Azure OpenAI configuration
+
+Azure requires additional environment variables beyond the API key:
+
+```bash
+export AZURE_OPENAI_API_KEY="your-key"
+export AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com"
+export AZURE_OPENAI_DEPLOYMENT="your-deployment-name"
+export CLEVERAGENTS_DEFAULT_PROVIDER=azure
+```
+
+### Token limit exceeded
+
+**Symptom:** `Error [526] TOKEN_LIMIT: Context window exceeded`
+
+- Switch to a model with a larger context window (e.g., `gpt-4o` supports 128K tokens).
+- Break the task into smaller sub-plans.
+- Reduce the number of resources included in the plan scope.
+
+---
+
+## Database Issues
+
+### Migration failures
+
+**Symptom:** `Error [522] DATABASE_ERROR: alembic migration failed`
+
+Run migrations manually:
+
+```bash
+# Check current migration state
+alembic current
+
+# Apply pending migrations
+alembic upgrade head
+
+# If migrations are out of sync, check history
+alembic history --verbose
+```
+
+If the database is corrupted, you can reset it (this deletes all local data):
+
+```bash
+# Backup first
+cp ~/.local/share/cleveragents/cleveragents.db ~/.local/share/cleveragents/cleveragents.db.bak
+
+# Remove and let CleverAgents recreate on next run
+rm ~/.local/share/cleveragents/cleveragents.db
+agents diagnostics
+```
+
+### Database locked
+
+**Symptom:** `Error [522] DATABASE_ERROR: database is locked`
+
+Another process is holding an exclusive lock on the SQLite database. Find and stop it:
+
+```bash
+# Find processes using the database file
+lsof ~/.local/share/cleveragents/cleveragents.db
+
+# Or check for stale lock files
+ls ~/.local/share/cleveragents/*.db-wal
+ls ~/.local/share/cleveragents/*.db-shm
+```
+
+If no other process is running, the lock files may be stale:
+
+```bash
+rm -f ~/.local/share/cleveragents/cleveragents.db-wal
+rm -f ~/.local/share/cleveragents/cleveragents.db-shm
+```
+
+### Schema mismatch
+
+**Symptom:** `Error [522] DATABASE_ERROR: no such column: ...` or `table ... has no column named ...`
+
+Your database schema is out of date. Run:
+
+```bash
+alembic upgrade head
+```
+
+If you have a very old database, you may need to stamp it at the base revision first:
+
+```bash
+alembic stamp base
+alembic upgrade head
+```
+
+### Data directory not writable
+
+**Symptom:** `Error [523] FILESYSTEM_ERROR: Permission denied: '/home/user/.local/share/cleveragents'`
+
+```bash
+# Fix permissions
+chmod 755 ~/.local/share/cleveragents
+chmod 644 ~/.local/share/cleveragents/cleveragents.db
+
+# Or use a custom data directory
+export CLEVERAGENTS_DATA_DIR=/path/to/writable/dir
+```
+
+---
+
+## Plan Execution Issues
+
+### Actor not found
+
+**Symptom:** `Error [404] NOT_FOUND: Actor 'local/my-actor' not found`
+
+```bash
+# List all registered actors
+agents actor list
+
+# Check actor YAML files are in the search path
+agents actor list --verbose
+
+# Verify actor name format (must be namespace/identifier)
+# Correct:   local/my-actor
+# Incorrect: my-actor
+```
+
+Custom actors must be placed in `~/.config/cleveragents/actors/` or a path configured via `CLEVERAGENTS_ACTOR_PATH`.
+
+### Actor configuration errors
+
+**Symptom:** `Schema validation failed for actor.yaml`
+
+Common actor YAML mistakes and fixes:
+
+```yaml
+# WRONG — missing namespace
+name: my-actor
+
+# CORRECT
+name: local/my-actor
+```
+
+```yaml
+# WRONG — llm type without model
+name: local/my-actor
+type: llm
+description: My actor
+
+# CORRECT
+name: local/my-actor
+type: llm
+description: My actor
+model: gpt-4o
+```
+
+See [Actor Configuration Reference](../reference/actor_config.md) for the full schema.
+
+### Sandbox creation failure
+
+**Symptom:** `Error [521] EXECUTION_ERROR: SandboxCreationError: git worktree add failed`
+
+The git worktree sandbox requires the resource path to be a valid git repository root:
+
+```bash
+# Verify the path is a git repository
+git -C /path/to/resource rev-parse --git-dir
+
+# Ensure git is installed
+git --version
+
+# Check disk space (worktrees need space)
+df -h /tmp
+```
+
+If the repository has an existing worktree with the same name (from a crashed plan):
+
+```bash
+# List existing worktrees
+git worktree list
+
+# Remove stale worktrees
+git worktree prune
+git worktree remove /tmp/ca-sandbox-plan-<id> --force
+```
+
+### Git worktree errors
+
+**Symptom:** `fatal: 'cleveragents/plan-...' is already checked out`
+
+A previous plan left a stale worktree. Clean it up:
+
+```bash
+# In the repository directory
+git worktree prune
+
+# List and remove specific stale worktrees
+git worktree list
+git worktree remove <path> --force
+
+# Delete the stale branch
+git branch -D cleveragents/plan-<plan-id>
+```
+
+### ChangeSet empty
+
+**Symptom:** Plan completes but no files are changed; `CommitResult` shows empty file lists.
+
+This usually means the actor did not write any changes to the sandbox path. Possible causes:
+
+1. **Actor wrote to the wrong path** — ensure the actor uses the sandbox path returned by `get_path()`, not the original resource path.
+2. **All changes were identical to existing content** — git does not stage unchanged files.
+3. **Actor exited early** — check plan logs for warnings or early termination.
+
+Debug by inspecting the plan's decision tree:
+
+```bash
+agents plan tree <plan-id>
+agents plan errors <plan-id>
+```
+
+### Plan stuck in Strategize phase
+
+**Symptom:** Plan does not progress past the Strategize phase.
+
+```bash
+# Check plan status
+agents plan status <plan-id>
+
+# View the decision tree
+agents plan tree <plan-id>
+
+# Check for invariant violations blocking the transition
+agents plan errors <plan-id>
+```
+
+If the automation profile requires human input at phase transitions, you may need to approve the transition:
+
+```bash
+agents plan approve <plan-id>
+```
+
+### Invariant violation blocking plan
+
+**Symptom:** `INVARIANT_VIOLATED` event emitted; plan blocked at phase transition.
+
+```bash
+# View active invariants
+agents invariant list
+
+# View the specific violation
+agents plan errors <plan-id>
+
+# Correct the decision that caused the violation
+agents plan correct <decision-id> --guidance "..."
+```
+
+---
+
+## TUI Issues
+
+### TUI fails to launch
+
+**Symptom:** `Error: No module named 'textual'` or blank screen on launch.
+
+```bash
+# Install the TUI extra
+pip install -e ".[tui]"
+
+# Verify Textual is installed
+python -c "import textual; print(textual.__version__)"
+```
+
+### Terminal compatibility issues
+
+**Symptom:** Garbled output, missing colors, or broken layout.
+
+CleverAgents TUI requires a terminal with:
+- 256-color or true-color support
+- Unicode/UTF-8 support
+- Minimum 80×24 terminal size
+
+```bash
+# Check terminal color support
+echo $TERM
+echo $COLORTERM
+
+# Force true-color mode
+export COLORTERM=truecolor
+
+# Increase terminal size or use a larger window
+```
+
+Recommended terminals: iTerm2, Alacritty, kitty, Windows Terminal, GNOME Terminal.
+
+### Display glitches or rendering artifacts
+
+```bash
+# Force a terminal reset
+reset
+
+# Try disabling animations
+export CLEVERAGENTS_TUI_ANIMATIONS=false
+
+# Run with a specific color depth
+TERM=xterm-256color agents tui
+```
+
+### TUI crashes on startup
+
+```bash
+# Run with verbose logging to diagnose
+CLEVERAGENTS_LOG_LEVEL=DEBUG agents tui 2>tui-debug.log
+cat tui-debug.log
+```
+
+### Slash commands not working
+
+Ensure you are pressing `/` at the beginning of the input field. The slash command overlay lists all 67 available commands across 14 groups. Press `Escape` to dismiss it.
+
+---
+
+## Test Suite Issues
+
+### Mock AI not working
+
+**Symptom:** Tests hit real APIs or fail with `No LLM provider configured`.
+
+Set the mock AI environment variable before running tests:
+
+```bash
+export CLEVERAGENTS_TESTING_USE_MOCK_AI=true
+nox -s unit_tests
+```
+
+Verify the mock is active:
+
+```bash
+python -c "
+import os
+os.environ['CLEVERAGENTS_TESTING_USE_MOCK_AI'] = 'true'
+from cleveragents.config.settings import Settings
+s = Settings()
+print('Provider:', s.provider)  # should show 'mock'
+"
+```
+
+### Coverage below 97%
+
+**Symptom:** `COVERAGE FAILED: 95.3% < 97% threshold`
+
+1. **Identify uncovered lines:**
+
+```bash
+nox -s coverage_report -- --show-missing
+```
+
+2. **Add missing Behave scenarios** for the uncovered code paths.
+
+3. **Check for excluded files** — some files may be incorrectly excluded from coverage measurement in `pyproject.toml`.
+
+4. **Run coverage locally before pushing:**
+
+```bash
+nox -s unit_tests
+nox -s coverage_report
+```
+
+### Robot Framework errors
+
+**Symptom:** `robot: command not found` or `ImportError` in Robot suites.
+
+```bash
+# Install test dependencies
+pip install -e ".[tests]"
+
+# Run Robot tests via nox (never directly)
+nox -s integration_tests
+
+# Run a specific Robot suite
+nox -s integration_tests -- robot/suites/actor_cli.robot
+```
+
+**Symptom:** `FAIL: Setup failed: ...`
+
+Check that the test environment is clean:
+
+```bash
+# Reset the test database
+CLEVERAGENTS_DATA_DIR=/tmp/cleveragents-test agents diagnostics
+
+# Ensure mock AI is enabled for tests
+export CLEVERAGENTS_TESTING_USE_MOCK_AI=true
+```
+
+### Behave step not found
+
+**Symptom:** `NotImplementedError: STEP NOT IMPLEMENTED`
+
+The Behave step definition is missing. Check `features/steps/` for the relevant step file and add the missing step implementation.
+
+### Pre-commit hook failures
+
+```bash
+# Run all hooks manually
+pre-commit run --all-files
+
+# Run a specific hook
+pre-commit run ruff --all-files
+pre-commit run pyright --all-files
+
+# Skip hooks temporarily (not recommended for CI)
+git commit --no-verify -m "wip: ..."
+```
+
+---
+
+## Common Error Messages
+
+### `Error [400] BAD_REQUEST: name must be in 'namespace/name' format`
+
+Actor, tool, or skill names must include a namespace prefix separated by `/`.
+
+- ❌ `my-actor`
+- ✅ `local/my-actor`
+
+### `Error [401] UNAUTHORIZED: Invalid API key`
+
+The API key for the selected provider is invalid or expired. Regenerate it from the provider's dashboard and update your environment variable.
+
+### `Error [404] NOT_FOUND: Resource '...' not found`
+
+The referenced resource, actor, skill, or tool does not exist in the registry. Use `agents actor list`, `agents resource list`, or `agents tool list` to see what is registered.
+
+### `Error [409] CONFLICT: Actor '...' already exists`
+
+You are trying to register an actor with a name that is already taken. Use `agents actor update` to modify an existing actor, or choose a different name.
+
+### `Error [422] VALIDATION_FAILED: ...`
+
+A configuration value or input failed schema validation. The error message includes the field path and the validation rule that failed. See the relevant schema reference for the correct format.
+
+### `Error [500] INTERNAL: Unexpected error`
+
+An unhandled exception occurred. Enable debug logging to get the full traceback:
+
+```bash
+CLEVERAGENTS_LOG_LEVEL=DEBUG agents <command> 2>debug.log
+cat debug.log
+```
+
+Report the issue with the log output at the [issue tracker](https://git.cleverthis.com/cleveragents/cleveragents-core/issues).
+
+### `Error [520] PROVIDER_ERROR: ...`
+
+The LLM provider returned an error. Common causes:
+
+- Invalid API key → check `agents diagnostics`
+- Model not available in your region → try a different model
+- Provider outage → check the provider's status page
+
+### `Error [521] EXECUTION_ERROR: SandboxCreationError`
+
+See [Sandbox creation failure](#sandbox-creation-failure) above.
+
+### `Error [522] DATABASE_ERROR: database is locked`
+
+See [Database locked](#database-locked) above.
+
+### `Error [525] CONFIGURATION_ERROR: No LLM provider is configured`
+
+No API key is set for any supported provider. See [Missing API key](#missing-api-key) above.
+
+### `Error [527] MODEL_UNAVAILABLE: ...`
+
+The requested model does not exist or is not accessible with your API key. See [Model not found](#model-not-found) above.
+
+---
+
+## Diagnostic Commands
+
+### `agents diagnostics`
+
+Runs a comprehensive health check covering configuration, database, provider API keys, disk space, file permissions, and git availability.
+
+```bash
+# Basic diagnostics (human-readable)
+agents diagnostics
+
+# JSON output (useful for scripting)
+agents diagnostics --format json
+
+# Fail with exit code 1 if any check errors (useful in CI)
+agents diagnostics --check
+```
+
+See [Diagnostics Check List](../reference/diagnostics_checks.md) for the full list of checks and their remediation steps.
+
+### `agents actor list`
+
+Lists all registered actors, including built-in and custom actors.
+
+```bash
+agents actor list
+agents actor list --verbose   # show full configuration
+```
+
+### `agents resource list`
+
+Lists all registered resources.
+
+```bash
+agents resource list
+agents resource list --type git-checkout
+```
+
+### `agents plan status <plan-id>`
+
+Shows the current status and phase of a plan.
+
+```bash
+agents plan status 01HZ...
+```
+
+### `agents plan tree <plan-id>`
+
+Displays the full decision tree for a plan, showing every decision made during Strategize and Execute phases.
+
+```bash
+agents plan tree 01HZ...
+```
+
+### `agents plan errors <plan-id>`
+
+Lists errors and invariant violations associated with a plan.
+
+```bash
+agents plan errors 01HZ...
+```
+
+### `agents config list`
+
+Shows the current effective configuration, including all `CLEVERAGENTS_*` environment variables and config file values.
+
+```bash
+agents config list
+agents config list --format json
+```
+
+---
+
+## Getting Help
+
+### Documentation
+
+- **Full documentation:** [https://docs.cleverthis.com/cleveragents](https://docs.cleverthis.com/cleveragents)
+- **API Reference:** [docs/api/](../api/index.md)
+- **Configuration Reference:** [docs/api/config.md](../api/config.md)
+- **Actor Configuration:** [docs/reference/actor_config.md](../reference/actor_config.md)
+- **Provider Capability Matrix:** [docs/reference/providers.md](../reference/providers.md)
+- **Diagnostics Check List:** [docs/reference/diagnostics_checks.md](../reference/diagnostics_checks.md)
+- **FAQ:** [docs/guides/faq.md](faq.md)
+
+### Reporting Issues
+
+Before filing an issue, please:
+
+1. Run `agents diagnostics` and include the output.
+2. Enable debug logging and include the relevant log lines:
+   ```bash
+   CLEVERAGENTS_LOG_LEVEL=DEBUG agents <command> 2>debug.log
+   ```
+3. Include your Python version (`python --version`) and CleverAgents version (`agents --version`).
+
+File issues at: [https://git.cleverthis.com/cleveragents/cleveragents-core/issues](https://git.cleverthis.com/cleveragents/cleveragents-core/issues)
+
+### Community
+
+- Check existing issues and discussions before opening a new one.
+- See [CONTRIBUTING.md](../../CONTRIBUTING.md) for contribution guidelines.

mkdocs.yml

@@ -41,6 +41,10 @@ nav:
     - Automation Tracking: development/automation-tracking.md
     - Custom Sandbox Strategy: development/custom_sandbox_strategy.md
     - Documentation Writer: development/docs-writer.md
+  - Guides:
+    - Overview: guides/index.md
+    - Troubleshooting: guides/troubleshooting.md
+    - FAQ: guides/faq.md
   - Implementation Timeline: timeline.md
   - FAQ: faq.md
   - Reference: reference/