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/showcase/cli-tools/cli-version-info-diagnostics.md

@@ -1,435 +0,0 @@
-# Understanding CleverAgents CLI Version, Info, and Diagnostics Commands
-
-## Overview
-This guide demonstrates the three essential system information commands in the CleverAgents CLI: `version`, `info`, and `diagnostics`. These commands provide quick access to system metadata, configuration details, and diagnostic information. You'll learn the difference between fast-path and regular command behavior, and how to use these commands for troubleshooting and system verification.
-
-## Prerequisites
-- CleverAgents installed (`pip install cleveragents`)
-- Python 3.12 or higher
-- Access to a terminal or command-line interface
-
-## What You'll Learn
-This example covers:
-- **Version command**: Display the installed CleverAgents version and build information
-- **Info command**: Get comprehensive system and configuration information
-- **Diagnostics command**: Run diagnostic checks and generate detailed system reports
-- **Output formats**: Using JSON, YAML, and plain text output formats
-- **Fast-path behavior**: Understanding when commands use optimized execution paths
-
-## Step-by-Step Walkthrough
-
-### Step 1: Check the CleverAgents Version
-
-The `version` command is the fastest way to verify your CleverAgents installation.
-
-```bash
-$ agents version
-```
-
-**Expected Output:**
-```
-CleverAgents v3.6.0
-Build: 2026-04-19
-Python: 3.13.0
-```
-
-**What's Happening:**
-The `version` command uses a fast-path execution that bypasses full application initialization. It directly reads version metadata from the package and displays it immediately. This is useful for quick verification without waiting for the full CLI to load.
-
-### Step 2: Get Detailed System Information
-
-The `info` command provides comprehensive system and configuration details.
-
-```bash
-$ agents info
-```
-
-**Expected Output:**
-```
-CleverAgents System Information
-================================
-
-Version Information:
-  Version: 3.6.0
-  Build Date: 2026-04-19
-  Python Version: 3.13.0
-  Platform: linux
-
-Installation Details:
-  Installation Path: /usr/local/lib/python3.13/site-packages/cleveragents
-  Configuration Directory: ~/.cleveragents
-  Database Location: ~/.cleveragents/cleveragents.db
-
-System Configuration:
-  Default Actor: anthropic/claude-sonnet-4-20250514
-  Default Project: None
-  Execution Environment: development
-  Log Level: INFO
-
-Feature Flags:
-  A2A Protocol: enabled
-  Container Execution: enabled
-  Cost Budgets: enabled
-  Safety Profiles: enabled
-```
-
-**What's Happening:**
-The `info` command performs a regular initialization of the application to gather comprehensive system information. It reads configuration files, checks the database, and verifies feature availability. This command takes slightly longer than `version` but provides much more detailed information about your system setup.
-
-### Step 3: Get Machine-Readable Version Information (JSON)
-
-For automation and scripting, use the JSON output format with the `version` command.
-
-```bash
-$ agents --format json version
-```
-
-**Expected Output:**
-```json
-{
-  "status": "success",
-  "data": {
-    "version": "3.6.0",
-    "build_date": "2026-04-19",
-    "python_version": "3.13.0",
-    "platform": "linux",
-    "git_commit": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
-    "git_branch": "main"
-  }
-}
-```
-
-**What's Happening:**
-The `--format json` flag tells CleverAgents to output the response as JSON. This is useful for parsing the output in scripts or integrating with other tools. The JSON envelope includes a status field and a data field containing the actual information.
-
-### Step 4: Get Machine-Readable System Information (JSON)
-
-Get comprehensive system information in JSON format for programmatic access.
-
-```bash
-$ agents --format json info
-```
-
-**Expected Output:**
-```json
-{
-  "status": "success",
-  "data": {
-    "version": {
-      "version": "3.6.0",
-      "build_date": "2026-04-19",
-      "python_version": "3.13.0",
-      "platform": "linux"
-    },
-    "installation": {
-      "installation_path": "/usr/local/lib/python3.13/site-packages/cleveragents",
-      "config_directory": "/home/user/.cleveragents",
-      "database_location": "/home/user/.cleveragents/cleveragents.db"
-    },
-    "configuration": {
-      "default_actor": "anthropic/claude-sonnet-4-20250514",
-      "default_project": null,
-      "execution_environment": "development",
-      "log_level": "INFO"
-    },
-    "features": {
-      "a2a_protocol": true,
-      "container_execution": true,
-      "cost_budgets": true,
-      "safety_profiles": true
-    }
-  }
-}
-```
-
-**What's Happening:**
-The JSON output is structured hierarchically, making it easy to parse and extract specific information. Each section corresponds to a category of system information.
-
-### Step 5: Run System Diagnostics
-
-The `diagnostics` command performs comprehensive system checks and generates a detailed report.
-
-```bash
-$ agents diagnostics
-```
-
-**Expected Output:**
-```
-CleverAgents System Diagnostics Report
-======================================
-
-Timestamp: 2026-04-19T10:30:45Z
-System: linux (x86_64)
-Python: 3.13.0
-
-✓ Installation Check
-  - Package installed: YES
-  - Installation path: /usr/local/lib/python3.13/site-packages/cleveragents
-  - Version: 3.6.0
-
-✓ Configuration Check
-  - Config directory exists: YES
-  - Config file readable: YES
-  - Database accessible: YES
-
-✓ Database Check
-  - Database file exists: YES
-  - Database version: 3.6.0
-  - Tables initialized: YES
-  - Connection pool: healthy
-
-✓ Actor Registry Check
-  - Actors available: 12
-  - Default actor configured: YES
-  - Actor connectivity: OK
-
-✓ Resource System Check
-  - Resource types registered: 45
-  - Resource handlers loaded: 45
-  - Resource validation: OK
-
-✓ Skill System Check
-  - Skills available: 156
-  - Skill registry: healthy
-  - Skill validation: OK
-
-✓ Tool System Check
-  - Tools available: 89
-  - Tool registry: healthy
-  - Tool validation: OK
-
-✓ Network Connectivity Check
-  - DNS resolution: OK
-  - API connectivity: OK
-  - Server connectivity: OK
-
-Summary:
-  Total checks: 8
-  Passed: 8
-  Failed: 0
-  Warnings: 0
-  Status: HEALTHY
-```
-
-**What's Happening:**
-The `diagnostics` command performs a comprehensive system health check. It verifies installation integrity, configuration validity, database connectivity, and the availability of all major subsystems. This is useful for troubleshooting issues or verifying that your CleverAgents installation is properly configured.
-
-### Step 6: Get Machine-Readable Diagnostics (JSON)
-
-For automated monitoring and alerting, use JSON format with the diagnostics command.
-
-```bash
-$ agents --format json diagnostics
-```
-
-**Expected Output:**
-```json
-{
-  "status": "success",
-  "data": {
-    "timestamp": "2026-04-19T10:30:45Z",
-    "system": {
-      "platform": "linux",
-      "architecture": "x86_64",
-      "python_version": "3.13.0"
-    },
-    "checks": [
-      {
-        "name": "Installation Check",
-        "status": "passed",
-        "details": {
-          "package_installed": true,
-          "installation_path": "/usr/local/lib/python3.13/site-packages/cleveragents",
-          "version": "3.6.0"
-        }
-      },
-      {
-        "name": "Configuration Check",
-        "status": "passed",
-        "details": {
-          "config_directory_exists": true,
-          "config_file_readable": true,
-          "database_accessible": true
-        }
-      },
-      {
-        "name": "Database Check",
-        "status": "passed",
-        "details": {
-          "database_file_exists": true,
-          "database_version": "3.6.0",
-          "tables_initialized": true,
-          "connection_pool": "healthy"
-        }
-      },
-      {
-        "name": "Actor Registry Check",
-        "status": "passed",
-        "details": {
-          "actors_available": 12,
-          "default_actor_configured": true,
-          "actor_connectivity": "OK"
-        }
-      },
-      {
-        "name": "Resource System Check",
-        "status": "passed",
-        "details": {
-          "resource_types_registered": 45,
-          "resource_handlers_loaded": 45,
-          "resource_validation": "OK"
-        }
-      },
-      {
-        "name": "Skill System Check",
-        "status": "passed",
-        "details": {
-          "skills_available": 156,
-          "skill_registry": "healthy",
-          "skill_validation": "OK"
-        }
-      },
-      {
-        "name": "Tool System Check",
-        "status": "passed",
-        "details": {
-          "tools_available": 89,
-          "tool_registry": "healthy",
-          "tool_validation": "OK"
-        }
-      },
-      {
-        "name": "Network Connectivity Check",
-        "status": "passed",
-        "details": {
-          "dns_resolution": "OK",
-          "api_connectivity": "OK",
-          "server_connectivity": "OK"
-        }
-      }
-    ],
-    "summary": {
-      "total_checks": 8,
-      "passed": 8,
-      "failed": 0,
-      "warnings": 0,
-      "status": "HEALTHY"
-    }
-  }
-}
-```
-
-**What's Happening:**
-The JSON format provides structured diagnostic data that can be easily parsed by monitoring systems, dashboards, or automated alerting tools. Each check includes its status and detailed information about what was verified.
-
-### Step 7: Compare Output Formats
-
-You can also use YAML format for human-readable structured output.
-
-```bash
-$ agents --format yaml version
-```
-
-**Expected Output:**
-```yaml
-status: success
-data:
-  version: 3.6.0
-  build_date: '2026-04-19'
-  python_version: 3.13.0
-  platform: linux
-  git_commit: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
-  git_branch: main
-```
-
-**What's Happening:**
-YAML format provides a middle ground between plain text and JSON - it's human-readable but also machine-parseable. This is useful when you want structured output but prefer YAML over JSON.
-
-## Understanding Fast-Path vs Regular Command Behavior
-
-### Fast-Path Commands
-The `version` command uses a fast-path execution:
-- **Execution time**: ~50-100ms
-- **Initialization**: Minimal (no database, no configuration loading)
-- **Use case**: Quick version checks, CI/CD pipelines, automated scripts
-- **Reliability**: Very high (no external dependencies)
-
-### Regular Commands
-The `info` and `diagnostics` commands use regular initialization:
-- **Execution time**: ~500-2000ms (depending on system complexity)
-- **Initialization**: Full application startup (database, configuration, registries)
-- **Use case**: Detailed system information, troubleshooting, verification
-- **Reliability**: High (requires working installation)
-
-## Complete Interaction Log
-<details>
-<summary>Click to see the full CleverAgents session log</summary>
-
-```
-[2026-04-19T10:30:00Z] Starting CleverAgents CLI session...
-[2026-04-19T10:30:00Z] User: agents version
-[2026-04-19T10:30:00Z] CleverAgents: CleverAgents v3.6.0
-[2026-04-19T10:30:00Z] CleverAgents: Build: 2026-04-19
-[2026-04-19T10:30:00Z] CleverAgents: Python: 3.13.0
-[2026-04-19T10:30:02Z] User: agents info
-[2026-04-19T10:30:02Z] CleverAgents: CleverAgents System Information
-[2026-04-19T10:30:02Z] CleverAgents: ================================
-[2026-04-19T10:30:02Z] CleverAgents: Version Information:
-[2026-04-19T10:30:02Z] CleverAgents:   Version: 3.6.0
-[2026-04-19T10:30:02Z] CleverAgents:   Build Date: 2026-04-19
-[2026-04-19T10:30:02Z] CleverAgents:   Python Version: 3.13.0
-[2026-04-19T10:30:02Z] CleverAgents:   Platform: linux
-[2026-04-19T10:30:02Z] CleverAgents: Installation Details:
-[2026-04-19T10:30:02Z] CleverAgents:   Installation Path: /usr/local/lib/python3.13/site-packages/cleveragents
-[2026-04-19T10:30:02Z] CleverAgents:   Configuration Directory: ~/.cleveragents
-[2026-04-19T10:30:02Z] CleverAgents:   Database Location: ~/.cleveragents/cleveragents.db
-[2026-04-19T10:30:02Z] CleverAgents: System Configuration:
-[2026-04-19T10:30:02Z] CleverAgents:   Default Actor: anthropic/claude-sonnet-4-20250514
-[2026-04-19T10:30:02Z] CleverAgents: Default Project: None
-[2026-04-19T10:30:02Z] CleverAgents:   Execution Environment: development
-[2026-04-19T10:30:02Z] CleverAgents:   Log Level: INFO
-[2026-04-19T10:30:02Z] CleverAgents: Feature Flags:
-[2026-04-19T10:30:02Z] CleverAgents:   A2A Protocol: enabled
-[2026-04-19T10:30:02Z] CleverAgents:   Container Execution: enabled
-[2026-04-19T10:30:02Z] CleverAgents:   Cost Budgets: enabled
-[2026-04-19T10:30:02Z] CleverAgents:   Safety Profiles: enabled
-[2026-04-19T10:30:03Z] User: agents --format json version
-[2026-04-19T10:30:03Z] CleverAgents: {"status": "success", "data": {"version": "3.6.0", ...}}
-[2026-04-19T10:30:05Z] User: agents --format json info
-[2026-04-19T10:30:05Z] CleverAgents: {"status": "success", "data": {...}}
-[2026-04-19T10:30:07Z] User: agents diagnostics
-[2026-04-19T10:30:07Z] CleverAgents: CleverAgents System Diagnostics Report
-[2026-04-19T10:30:07Z] CleverAgents: ======================================
-[2026-04-19T10:30:07Z] CleverAgents: [Diagnostic checks output...]
-[2026-04-19T10:30:10Z] User: agents --format json diagnostics
-[2026-04-19T10:30:10Z] CleverAgents: {"status": "success", "data": {...}}
-[2026-04-19T10:30:12Z] Session completed successfully.
-```
-</details>
-
-## Key Takeaways
-- **Version command** is the fastest way to check your CleverAgents installation - use it for quick verification
-- **Info command** provides comprehensive system configuration and feature information - use it for setup verification
-- **Diagnostics command** performs health checks on all major subsystems - use it for troubleshooting
-- **Output formats** (JSON, YAML, plain text) allow you to choose the best format for your use case
-- **Fast-path execution** in the version command makes it ideal for CI/CD pipelines and automated scripts
-- **Regular initialization** in info and diagnostics commands ensures accurate system state reporting
-
-## Try It Yourself
-Now that you understand these commands, try these variations:
-
-- Run `agents version --help` to see all available options
-- Run `agents info --help` to see configuration options
-- Run `agents diagnostics --help` to see diagnostic options
-- Combine with other flags: `agents --format yaml info`
-- Use in scripts: `VERSION=$(agents --format json version | jq -r '.data.version')`
-- Monitor system health: `agents --format json diagnostics | jq '.data.summary.status'`
-
-## Related Examples
-- [Mastering Output Format Flags in CleverAgents CLI](output-format-flags.md) — Learn more about output formatting options
-- [CleverAgents CLI Basics](cleveragents-cli-basics.md) — Get started with the CLI
-- [Server Connection and A2A Protocol Integration](server-and-a2a-integration.md) — Learn about server connectivity
-
----
-*This example was automatically generated and verified by the CleverAgents UAT system.*
-*Feature area: CLI System Commands | Test cycle: 1 | Generated: 2026-04-19*

docs/showcase/examples.json

@@ -1,26 +1,5 @@
 {
   "examples": [
-    {
-      "title": "Understanding CleverAgents CLI Version, Info, and Diagnostics Commands",
-      "category": "cli-tools",
-      "path": "cli-tools/cli-version-info-diagnostics.md",
-      "feature": "Version info diagnostics fast-path regular initialization",
-      "commands": [
-        "agents version",
-        "agents info",
-        "agents diagnostics",
-        "agents --format json version",
-        "agents --format json info",
-        "agents --format json diagnostics",
-        "agents --format yaml version",
-        "agents --format yaml info",
-        "agents --format yaml diagnostics"
-      ],
-      "complexity": "beginner",
-      "educational_value": "high",
-      "generated_by": "uat-tester",
-      "generated_at": "2026-04-19"
-    },
     {
       "title": "Mastering Output Format Flags in CleverAgents CLI",
       "category": "cli-tools",
@@ -113,5 +92,5 @@
       "keywords": ["test", "pytest", "behave", "unittest", "automation", "QA"]
     }
   },
-  "last_updated": "2026-04-19T10:30:00Z"
+  "last_updated": null
 }

features/cli_version_info_diagnostics_showcase.feature

@@ -1,98 +0,0 @@
-Feature: CLI Version, Info, and Diagnostics Commands Showcase
-  As a CleverAgents user
-  I want to understand the version, info, and diagnostics commands
-  So that I can verify my installation and troubleshoot issues
-
-  Background:
-    Given the CleverAgents CLI is installed and available
-
-  Scenario: Display version information using fast-path execution
-    When I run the command "agents version"
-    Then the output should contain "CleverAgents"
-    And the output should contain a version number
-    And the command should complete quickly (within 200ms)
-
-  Scenario: Display version information in JSON format
-    When I run the command "agents --format json version"
-    Then the output should be valid JSON
-    And the JSON should have a "status" field with value "success"
-    And the JSON should have a "data" field containing version information
-    And the JSON data should contain "version" field
-    And the JSON data should contain "python_version" field
-
-  Scenario: Display version information in YAML format
-    When I run the command "agents --format yaml version"
-    Then the output should be valid YAML
-    And the YAML should have a "status" field with value "success"
-    And the YAML should have a "data" field containing version information
-
-  Scenario: Display comprehensive system information
-    When I run the command "agents info"
-    Then the output should contain "CleverAgents System Information"
-    And the output should contain "Version Information"
-    And the output should contain "Installation Details"
-    And the output should contain "System Configuration"
-    And the output should contain "Feature Flags"
-
-  Scenario: Display system information in JSON format
-    When I run the command "agents --format json info"
-    Then the output should be valid JSON
-    And the JSON should have a "status" field with value "success"
-    And the JSON data should contain "version" field
-    And the JSON data should contain "installation" field
-    And the JSON data should contain "configuration" field
-    And the JSON data should contain "features" field
-
-  Scenario: Run system diagnostics
-    When I run the command "agents diagnostics"
-    Then the output should contain "CleverAgents System Diagnostics Report"
-    And the output should contain "Installation Check"
-    And the output should contain "Configuration Check"
-    And the output should contain "Database Check"
-    And the output should contain "Summary"
-    And the output should contain "Status"
-
-  Scenario: Run diagnostics in JSON format
-    When I run the command "agents --format json diagnostics"
-    Then the output should be valid JSON
-    And the JSON should have a "status" field with value "success"
-    And the JSON data should contain "timestamp" field
-    And the JSON data should contain "system" field
-    And the JSON data should contain "checks" field
-    And the JSON data should contain "summary" field
-
-  Scenario: Verify fast-path vs regular command behavior
-    When I run the command "agents version"
-    Then the command should complete quickly (within 200ms)
-    When I run the command "agents info"
-    Then the command should take longer than version command
-    When I run the command "agents diagnostics"
-    Then the command should take longer than version command
-
-  Scenario: Verify output format consistency
-    When I run the command "agents --format json version"
-    And I run the command "agents --format json info"
-    And I run the command "agents --format json diagnostics"
-    Then all JSON outputs should have a "status" field
-    And all JSON outputs should have a "data" field
-
-  Scenario: Verify showcase documentation exists
-    Given the showcase documentation file exists at "docs/showcase/cli-tools/cli-version-info-diagnostics.md"
-    When I read the documentation file
-    Then it should contain "Understanding CleverAgents CLI Version, Info, and Diagnostics Commands"
-    And it should contain "version" command explanation
-    And it should contain "info" command explanation
-    And it should contain "diagnostics" command explanation
-    And it should contain "Fast-Path vs Regular Command Behavior" section
-    And it should contain JSON output examples
-    And it should contain YAML output examples
-
-  Scenario: Verify showcase is registered in examples.json
-    Given the showcase examples registry exists at "docs/showcase/examples.json"
-    When I read the examples registry
-    Then it should contain an entry for "Understanding CleverAgents CLI Version, Info, and Diagnostics Commands"
-    And the entry should have category "cli-tools"
-    And the entry should have path "cli-tools/cli-version-info-diagnostics.md"
-    And the entry should list version, info, and diagnostics commands
-    And the entry should have complexity "beginner"
-    And the entry should have educational_value "high"

features/steps/cli_version_info_diagnostics_showcase_steps.py

@@ -1,291 +0,0 @@
-"""Step definitions for CLI Version, Info, and Diagnostics Commands Showcase."""
-
-import json
-import os
-import re
-import subprocess
-import time
-from pathlib import Path
-from typing import Any
-
-import yaml
-from behave import given, then, when
-
-
-@given("the CleverAgents CLI is installed and available")
-def step_cli_is_installed(context: Any) -> None:
-    """Verify that the CleverAgents CLI is installed and available."""
-    try:
-        result = subprocess.run(
-            ["agents", "--version"],
-            capture_output=True,
-            text=True,
-            timeout=5,
-        )
-        assert result.returncode == 0, f"CLI not available: {result.stderr}"
-        context.cli_available = True
-    except FileNotFoundError:
-        raise AssertionError("agents CLI not found in PATH")
-
-
-@when('I run the command "{command}"')
-def step_run_command(context: Any, command: str) -> None:
-    """Run a CLI command and capture the output."""
-    start_time = time.time()
-    try:
-        result = subprocess.run(
-            command.split(),
-            capture_output=True,
-            text=True,
-            timeout=10,
-        )
-        elapsed_time = time.time() - start_time
-        
-        context.last_command = command
-        context.last_output = result.stdout
-        context.last_stderr = result.stderr
-        context.last_returncode = result.returncode
-        context.last_elapsed_time = elapsed_time
-    except subprocess.TimeoutExpired:
-        raise AssertionError(f"Command timed out: {command}")
-    except Exception as e:
-        raise AssertionError(f"Failed to run command '{command}': {e}")
-
-
-@then('the output should contain "{text}"')
-def step_output_contains(context: Any, text: str) -> None:
-    """Verify that the output contains the specified text."""
-    assert hasattr(context, "last_output"), "No command has been run yet"
-    assert text in context.last_output, (
-        f"Expected '{text}' in output, but got:\n{context.last_output}"
-    )
-
-
-@then("the output should contain a version number")
-def step_output_contains_version(context: Any) -> None:
-    """Verify that the output contains a version number."""
-    assert hasattr(context, "last_output"), "No command has been run yet"
-    # Match version patterns like 3.6.0, v3.6.0, etc.
-    version_pattern = r"\d+\.\d+\.\d+"
-    assert re.search(version_pattern, context.last_output), (
-        f"Expected version number in output, but got:\n{context.last_output}"
-    )
-
-
-@then("the command should complete quickly (within {milliseconds:d}ms)")
-def step_command_completes_quickly(context: Any, milliseconds: int) -> None:
-    """Verify that the command completes within the specified time."""
-    assert hasattr(context, "last_elapsed_time"), "No command has been run yet"
-    elapsed_ms = context.last_elapsed_time * 1000
-    assert elapsed_ms < milliseconds, (
-        f"Command took {elapsed_ms:.0f}ms, expected < {milliseconds}ms"
-    )
-
-
-@then("the output should be valid JSON")
-def step_output_is_valid_json(context: Any) -> None:
-    """Verify that the output is valid JSON."""
-    assert hasattr(context, "last_output"), "No command has been run yet"
-    try:
-        context.last_json = json.loads(context.last_output)
-    except json.JSONDecodeError as e:
-        raise AssertionError(f"Output is not valid JSON: {e}\nOutput: {context.last_output}")
-
-
-@then('the JSON should have a "{field}" field with value "{value}"')
-def step_json_field_equals(context: Any, field: str, value: str) -> None:
-    """Verify that a JSON field has a specific value."""
-    assert hasattr(context, "last_json"), "Output is not valid JSON"
-    assert field in context.last_json, (
-        f"Field '{field}' not found in JSON. Keys: {list(context.last_json.keys())}"
-    )
-    assert context.last_json[field] == value, (
-        f"Expected {field}='{value}', got '{context.last_json[field]}'"
-    )
-
-
-@then('the JSON should have a "{field}" field containing {nested_field}')
-def step_json_has_nested_field(context: Any, field: str, nested_field: str) -> None:
-    """Verify that a JSON field contains nested data."""
-    assert hasattr(context, "last_json"), "Output is not valid JSON"
-    assert field in context.last_json, (
-        f"Field '{field}' not found in JSON. Keys: {list(context.last_json.keys())}"
-    )
-    # Store the nested data for further assertions
-    context.last_json_data = context.last_json[field]
-
-
-@then('the JSON data should contain "{field}" field')
-def step_json_data_contains_field(context: Any, field: str) -> None:
-    """Verify that the JSON data contains a specific field."""
-    assert hasattr(context, "last_json_data"), "No JSON data field has been accessed"
-    assert isinstance(context.last_json_data, dict), "JSON data is not a dictionary"
-    assert field in context.last_json_data, (
-        f"Field '{field}' not found in JSON data. Keys: {list(context.last_json_data.keys())}"
-    )
-
-
-@then("the output should be valid YAML")
-def step_output_is_valid_yaml(context: Any) -> None:
-    """Verify that the output is valid YAML."""
-    assert hasattr(context, "last_output"), "No command has been run yet"
-    try:
-        context.last_yaml = yaml.safe_load(context.last_output)
-    except yaml.YAMLError as e:
-        raise AssertionError(f"Output is not valid YAML: {e}\nOutput: {context.last_output}")
-
-
-@then('the YAML should have a "{field}" field with value "{value}"')
-def step_yaml_field_equals(context: Any, field: str, value: str) -> None:
-    """Verify that a YAML field has a specific value."""
-    assert hasattr(context, "last_yaml"), "Output is not valid YAML"
-    assert field in context.last_yaml, (
-        f"Field '{field}' not found in YAML. Keys: {list(context.last_yaml.keys())}"
-    )
-    assert context.last_yaml[field] == value, (
-        f"Expected {field}='{value}', got '{context.last_yaml[field]}'"
-    )
-
-
-@then('the YAML should have a "{field}" field containing {nested_field}')
-def step_yaml_has_nested_field(context: Any, field: str, nested_field: str) -> None:
-    """Verify that a YAML field contains nested data."""
-    assert hasattr(context, "last_yaml"), "Output is not valid YAML"
-    assert field in context.last_yaml, (
-        f"Field '{field}' not found in YAML. Keys: {list(context.last_yaml.keys())}"
-    )
-    # Store the nested data for further assertions
-    context.last_yaml_data = context.last_yaml[field]
-
-
-@then("the command should take longer than version command")
-def step_command_slower_than_version(context: Any) -> None:
-    """Verify that the current command is slower than the version command."""
-    assert hasattr(context, "last_elapsed_time"), "No command has been run yet"
-    assert hasattr(context, "version_command_time"), "Version command time not recorded"
-    assert context.last_elapsed_time > context.version_command_time, (
-        f"Expected current command ({context.last_elapsed_time:.3f}s) to be slower than "
-        f"version command ({context.version_command_time:.3f}s)"
-    )
-
-
-@given('the showcase documentation file exists at "{path}"')
-def step_documentation_file_exists(context: Any, path: str) -> None:
-    """Verify that the documentation file exists."""
-    full_path = Path(path)
-    assert full_path.exists(), f"Documentation file not found: {path}"
-    context.doc_file_path = full_path
-
-
-@when("I read the documentation file")
-def step_read_documentation_file(context: Any) -> None:
-    """Read the documentation file."""
-    assert hasattr(context, "doc_file_path"), "Documentation file path not set"
-    with open(context.doc_file_path, "r") as f:
-        context.doc_content = f.read()
-
-
-@then('it should contain "{text}"')
-def step_doc_contains(context: Any, text: str) -> None:
-    """Verify that the documentation contains the specified text."""
-    assert hasattr(context, "doc_content"), "Documentation content not loaded"
-    assert text in context.doc_content, (
-        f"Expected '{text}' in documentation, but it was not found"
-    )
-
-
-@given('the showcase examples registry exists at "{path}"')
-def step_examples_registry_exists(context: Any, path: str) -> None:
-    """Verify that the examples registry file exists."""
-    full_path = Path(path)
-    assert full_path.exists(), f"Examples registry file not found: {path}"
-    context.examples_file_path = full_path
-
-
-@when("I read the examples registry")
-def step_read_examples_registry(context: Any) -> None:
-    """Read the examples registry file."""
-    assert hasattr(context, "examples_file_path"), "Examples file path not set"
-    with open(context.examples_file_path, "r") as f:
-        context.examples_data = json.load(f)
-
-
-@then('it should contain an entry for "{title}"')
-def step_examples_contains_entry(context: Any, title: str) -> None:
-    """Verify that the examples registry contains an entry for the specified title."""
-    assert hasattr(context, "examples_data"), "Examples data not loaded"
-    examples = context.examples_data.get("examples", [])
-    matching_entries = [e for e in examples if e.get("title") == title]
-    assert matching_entries, (
-        f"No entry found for '{title}' in examples registry. "
-        f"Available titles: {[e.get('title') for e in examples]}"
-    )
-    context.current_example = matching_entries[0]
-
-
-@then('the entry should have category "{category}"')
-def step_example_has_category(context: Any, category: str) -> None:
-    """Verify that the example entry has the specified category."""
-    assert hasattr(context, "current_example"), "No example entry selected"
-    assert context.current_example.get("category") == category, (
-        f"Expected category '{category}', got '{context.current_example.get('category')}'"
-    )
-
-
-@then('the entry should have path "{path}"')
-def step_example_has_path(context: Any, path: str) -> None:
-    """Verify that the example entry has the specified path."""
-    assert hasattr(context, "current_example"), "No example entry selected"
-    assert context.current_example.get("path") == path, (
-        f"Expected path '{path}', got '{context.current_example.get('path')}'"
-    )
-
-
-@then("the entry should list {commands_str} commands")
-def step_example_lists_commands(context: Any, commands_str: str) -> None:
-    """Verify that the example entry lists the specified commands."""
-    assert hasattr(context, "current_example"), "No example entry selected"
-    commands = context.current_example.get("commands", [])
-    # Parse the commands_str (e.g., "version, info, and diagnostics")
-    expected_commands = [
-        cmd.strip() for cmd in commands_str.replace(" and ", ", ").split(", ")
-    ]
-    for cmd in expected_commands:
-        assert any(cmd in c for c in commands), (
-            f"Expected command containing '{cmd}' in {commands}"
-        )
-
-
-@then('the entry should have complexity "{complexity}"')
-def step_example_has_complexity(context: Any, complexity: str) -> None:
-    """Verify that the example entry has the specified complexity."""
-    assert hasattr(context, "current_example"), "No example entry selected"
-    assert context.current_example.get("complexity") == complexity, (
-        f"Expected complexity '{complexity}', got '{context.current_example.get('complexity')}'"
-    )
-
-
-@then('the entry should have educational_value "{value}"')
-def step_example_has_educational_value(context: Any, value: str) -> None:
-    """Verify that the example entry has the specified educational value."""
-    assert hasattr(context, "current_example"), "No example entry selected"
-    assert context.current_example.get("educational_value") == value, (
-        f"Expected educational_value '{value}', got '{context.current_example.get('educational_value')}'"
-    )
-
-
-@then("all JSON outputs should have a \"status\" field")
-def step_all_json_have_status(context: Any) -> None:
-    """Verify that all JSON outputs have a status field."""
-    # This is a summary step that checks previous JSON outputs
-    # In a real scenario, we'd track all JSON outputs
-    assert hasattr(context, "last_json"), "No JSON output to verify"
-    assert "status" in context.last_json, "JSON output missing 'status' field"
-
-
-@then("all JSON outputs should have a \"data\" field")
-def step_all_json_have_data(context: Any) -> None:
-    """Verify that all JSON outputs have a data field."""
-    # This is a summary step that checks previous JSON outputs
-    assert hasattr(context, "last_json"), "No JSON output to verify"
-    assert "data" in context.last_json, "JSON output missing 'data' field"

mkdocs.yml

@@ -11,6 +11,8 @@ site_dir: build/site
 nav:
   - Specification: specification.md
   - Architecture: architecture.md
+  - Guides:
+    - Getting Started: guides/getting-started.md
   - API Reference:
     - Overview: api/index.md
     - Core Utilities: api/core.md