Update Documentation for Exploration Agent Features

🔗 Parent Epic: #449

Epic: Exploration Agent: Complete Integration & Rollout
Position: Phase 4 (Documentation)
Status: Blocked by #430

---

Context

After CLI integration (#430) and enhancements (#434, #436), users need comprehensive documentation to understand and use the exploration features.

Branch: feature/agentic-context-loop
Current Docs: Technical specs in specs/, developer docs in EXPLORATION_SUMMARY.md
Missing: User-facing documentation, examples, tutorials

Scope

Update all user-facing documentation to cover:

1. Exploration agent features and benefits
2. CLI flag usage and examples
3. Common use cases and workflows
4. Troubleshooting and FAQ
5. Performance characteristics

Implementation Plan

1. Update README.md

Add exploration section:

## Exploration Mode

cmdai includes an intelligent exploration agent that:
- **Discovers relevant tools** for your query
- **Enriches context** from man pages, help text, and tldr
- **Generates ranked alternatives** with confidence scores
- **Provides platform-aware** suggestions (BSD vs GNU)

### Quick Start

```bash
# Enable exploration mode
cmdai "show top CPU processes" --explore

# See all alternatives
cmdai "find large files" --explore --explore-show

# Interactive selection from alternatives
cmdai --alternatives

How It Works

1. Complexity Assessment: Determines if query needs exploration
2. Tool Discovery: Finds 2-3 relevant command-line tools
3. Context Enrichment: Fetches man pages, help text, tldr (parallel)
4. Multi-Command Generation: Generates ranked alternatives with pros/cons

Performance: ~6s for full pipeline, <2s for quick result in async mode

Exploration Flags

Flag	Description	Default
--explore	Enable exploration mode	false
--explore-depth N	Number of alternatives to generate	3
--explore-wait	Wait for full exploration before output	false
--explore-show	Show alternatives (waits for background)	false
--explore-files MODE	File context: auto/always/never	auto
--alternatives	Show alternatives from last exploration	-
--last	Re-run last exploration prompt	-

Examples

Basic Exploration

$ cmdai "compress all .log files older than 30 days" --explore
find . -name "*.log" -mtime +30 -exec gzip {} +

[Exploring alternatives in background...]

See All Alternatives

$ cmdai "monitor network traffic on port 80" --explore --explore-show
tcpdump port 80

[Exploring alternatives...]

Alternatives:
1. tcpdump port 80 (confidence: 0.90)
   Tools: tcpdump
   ✅ Most direct, captures packets
   ⚠️  Requires sudo on most systems

2. lsof -i :80 (confidence: 0.85)
   Tools: lsof
   ✅ No sudo needed, shows processes
   ⚠️  Doesn't capture packets

3. netstat -an | grep :80 (confidence: 0.75)
   Tools: netstat, grep
   ✅ Lightweight, shows connections
   ⚠️  Less detailed than lsof

Interactive Selection

# Try generated command
$ sudo tcpdump port 80
[permission error]

# Select alternative
$ cmdai --alternatives
Found 3 alternatives from last exploration:

1. tcpdump port 80 (confidence: 0.90) [CURRENT]
2. lsof -i :80 (confidence: 0.85)
3. netstat -an | grep :80 (confidence: 0.75)

Select alternative (1-3, or 'q' to quit): 2
lsof -i :80

When to Use Exploration

✅ Use exploration when:

• Working with unfamiliar tools or domains
• Need multiple approaches to a problem
• Want to learn platform-specific differences
• Dealing with complex multi-tool pipelines

❌ Skip exploration when:

• Running simple, common commands
• Time-sensitive operations
• Already know the exact command needed
• Working in scripts/automation

Performance

Mode	Time to First Output	Total Time
Default (async)	<2s	2s (background continues)
With --explore-show	<2s	~6s
With --explore-wait	~6s	~6s

Troubleshooting

Q: Exploration is slow

• Check network connectivity (tldr fetching)
• Use --explore-wait to see progress
• Disable file context: --explore-files never

Q: No alternatives shown

• Use --explore-show to wait for alternatives
• Check ~/.cache/cmdai/last_exploration.json exists
• Run with RUST_LOG=debug to see what's happening

Q: Suggestions don't work on my platform

• Exploration tries to be platform-aware (BSD vs GNU)
• Some tools may not be installed (check with which)
• File an issue with your OS/distro details

### 2. Create USER_GUIDE.md

Comprehensive user guide:
```markdown
# cmdai User Guide: Exploration Mode

## Table of Contents
1. [Introduction](#introduction)
2. [Getting Started](#getting-started)
3. [Understanding the Pipeline](#understanding-the-pipeline)
4. [Advanced Usage](#advanced-usage)
5. [Use Cases & Patterns](#use-cases--patterns)
6. [Troubleshooting](#troubleshooting)

## Introduction

The exploration agent transforms cmdai from a simple command generator into an intelligent assistant that:
- Understands your intent beyond keywords
- Discovers tools you might not know about
- Provides multiple approaches to solve problems
- Teaches you platform-specific differences

### What Makes It Different?

**Traditional approach** (single command):

User: "find large files" AI: find . -size +100M

**Exploration approach** (context-aware alternatives):

User: "find large files" AI:

1. find . -type f -size +100M -exec ls -lh {} ; (confidence: 0.90) Most precise, shows file sizes

2. du -h . | sort -rh | head -20 (confidence: 0.85) Sorted by size, includes directories

3. ncdu (confidence: 0.75) Interactive TUI, easiest to use Requires: brew install ncdu

## Getting Started

[... comprehensive tutorial ...]

## Understanding the Pipeline

### Phase 0: Complexity Assessment (~1-2s)
[Explain how complexity is determined]

### Phase 1: Tool Discovery (~1s)
[Explain tool discovery process]

### Phase 2: Context Enrichment (~0.3s)
[Explain parallel fetching of man/help/tldr]

### Phase 3: Multi-Command Generation (~0.8s)
[Explain alternative generation and ranking]

## Advanced Usage

### Async vs Sync Modes
[Explain --explore-wait and --explore-show]

### File Context Detection
[Explain --explore-files modes]

### Interactive Selection
[Explain --alternatives workflow]

## Use Cases & Patterns

### 1. Learning New Tools
[Example: Discovering alternatives to familiar tools]

### 2. Platform Migration
[Example: Moving from Linux to macOS]

### 3. Complex Pipelines
[Example: Building multi-tool commands]

### 4. Security-Conscious Commands
[Example: Avoiding destructive operations]

## Troubleshooting

[Comprehensive FAQ and solutions]

3. Update EXAMPLES.md

Add exploration examples:

## Exploration Mode Examples

### Example 1: Process Management
[Before/after with exploration]

### Example 2: File Operations
[Complex find + compress example]

### Example 3: Network Monitoring
[Multiple tool alternatives]

### Example 4: System Analysis
[Performance debugging scenario]

### Example 5: Interactive Recovery
[Failure → alternative selection workflow]

4. Update CHANGELOG.md

Document the feature:

## [Unreleased]

### Added
- **Exploration Agent**: Intelligent tool discovery and context enrichment
  - Discovers 2-3 relevant tools for complex queries
  - Enriches context from man pages, help text, and tldr (parallel execution)
  - Generates ranked alternatives with confidence scores, pros/cons
  - Platform-aware reasoning (BSD vs GNU command differences)
  - Performance: <2s quick result, ~6s full pipeline
  - CLI flags: `--explore`, `--explore-wait`, `--explore-show`, `--explore-depth`
- **Async Exploration**: Progressive enhancement (quick result + background exploration)
  - Quick command in <2s, alternatives explored in background
  - `--explore-show` waits and displays alternatives
  - `--explore-wait` preserves synchronous behavior
- **Interactive Selection**: Alternative selection from cached results
  - `--alternatives` shows interactive menu of last exploration
  - `--last` re-runs last exploration prompt
  - State persists in `~/.cache/cmdai/last_exploration.json`

### Changed
- Default behavior unchanged (backward compatible)
- Exploration opt-in with `--explore` flag

### Performance
- Tool discovery: ~1s (50% faster than target)
- Context enrichment: ~0.3s (9x speedup via parallel execution)
- Full pipeline: ~6.2s (38% faster than target)

5. Create docs/EXPLORATION.md

Technical deep-dive for contributors:

# Exploration Agent: Technical Overview

## Architecture

[Detailed architecture diagrams and explanations]

## Implementation Details

[Code structure, key types, algorithms]

## Performance Optimization

[Parallel execution, caching, optimizations]

## Testing Strategy

[Test coverage, key scenarios, benchmarks]

## Future Enhancements

[Roadmap for exploration features]

Deliverables

• README.md updated with exploration section
• USER_GUIDE.md created with comprehensive tutorial
• EXAMPLES.md updated with exploration examples
• CHANGELOG.md updated with feature description
• docs/EXPLORATION.md created for contributors
• All examples tested and validated
• Screenshots/GIFs for key workflows (optional)

Documentation Quality Standards

All documentation must:

• ✅ Be tested with actual commands (no fake examples)
• ✅ Include expected output
• ✅ Cover error cases and troubleshooting
• ✅ Be platform-aware (note macOS vs Linux differences)
• ✅ Have clear learning progression (beginner → advanced)
• ✅ Link to related docs and specs

Acceptance Criteria

• README.md includes exploration section with examples
• USER_GUIDE.md provides comprehensive tutorial
• EXAMPLES.md has 5+ exploration scenarios
• CHANGELOG.md documents all exploration features
• docs/EXPLORATION.md provides technical deep-dive
• All examples tested on macOS and Linux
• No broken links or references
• Clear, concise writing (no jargon without explanation)

---

🔄 Dependencies

Depends on:

• #430 - CLI Integration (MUST BE COMPLETE)

Can proceed in parallel with:

• #431 - Vancouver Validation (results inform examples)
• #434 - Async Exploration (document async features)
• #436 - Interactive Selection (document interactive features)

Blocks: None (but should be complete before release)

---

Estimated Time

1-2 hours (can be split across incremental updates)

Writing Guidelines

Tone

• Conversational but professional
• Assume user knows basic CLI but not advanced shell scripting
• Encourage exploration and learning

Structure

• Start with simplest use case
• Build complexity gradually
• Always show expected output
• Highlight common pitfalls

Examples

• Use realistic scenarios (not "foo bar baz")
• Show both success and failure cases
• Include platform-specific notes where relevant
• Test all examples before committing

Review Checklist

Before marking complete:

• All examples tested on macOS
• All examples tested on Linux (if applicable)
• No typos or grammar errors
• Links work and point to correct locations
• Code blocks have correct syntax highlighting
• Screenshots/GIFs are clear and helpful (if included)
• Troubleshooting section answers common questions
• Contributing guide updated (if architecture changed)