feat: Add wishful.explore() for multi-variant generation + documentation overhaul

[pyros-projects]

✨ Overview

This PR introduces wishful.explore() - a powerful new feature that generates multiple implementation variants, tests them, and caches the winner. Plus a comprehensive documentation overhaul.

🔍 New Feature: wishful.explore()

Generate multiple variants of a function and automatically select the best one:

import wishful

# Generate 5 implementations, keep the first one that passes
parser = wishful.explore(
    "wishful.static.text.extract_emails",
    variants=5,
    test=lambda fn: fn("test@example.com") == ["test@example.com"]
)

# The winner is cached! Future imports use the proven implementation.
from wishful.static.text import extract_emails  # ← Uses the battle-tested winner

Key Features

• Test-based selection: Filter variants with pass/fail tests (test=)
• Benchmark scoring: Score variants and pick the best (benchmark=, optimize="fastest")
• Winner caching: The selected variant is automatically cached to .wishful/
• Beautiful Rich progress display: Real-time progress with variant status table
• CSV logging: Results saved to {cache_dir}/_explore/ for analysis
• Metadata on functions: Access __wishful_metadata__ and __wishful_source__

Selection Strategies

• first_passing (default): Return first variant that passes the test
• fastest / best_score: Benchmark all variants, return highest scorer

📚 Documentation Overhaul

• AGENTS.md: Comprehensive guide for AI agents working on the codebase
• README.md: Major updates including explore docs, better configuration table
• docs-site/explore.mdx: Full documentation for the explore feature
• New examples:
  • examples/12_explore.py: Basic explore usage
  • examples/13_explore_advanced.py: Advanced patterns (LLM-as-judge, code golf, self-improving loops)
• Updated examples: 00_quick_start, 05_api_client, 07_typed_outputs, 08_dynamic_vs_static

🔧 Technical Changes

New Module: src/wishful/explore/

src/wishful/explore/
├── __init__.py      # Public API: explore, ExplorationError
├── explorer.py      # Core explore() - async internally, sync API
├── strategies.py    # Selection strategies (first_passing, best_score)
├── variant.py       # VariantMetadata and wrapper
├── progress.py      # Rich Live progress display and CSV logging
└── exceptions.py    # ExplorationError

Other Changes

• LLM client: Added async generation support (agenerate_module_code)
• Tests: 22+ new tests in test_explore.py
• Version: Bumped to 0.2.4
• Test badge: Updated from 83 → 112 passing tests

🗑️ Removed

• docs/CHANGELOG.md (outdated)
• docs/ideas/advanced_context_discovery.md (moved to internal docs)

📊 Stats

28 files changed, 2875 insertions(+), 642 deletions(-)