docs: rewrite README with accurate copy, fix broken links, remove phantom Discord

- Rewrote from scratch aligned with business plan v13.6.21 positioning
- Removed all broken links (api.validkit.com/docs 404, Discord doesn't exist)
- Removed references to nonexistent example files
- Removed duplicate Error Handling and License sections
- Fixed CompactResult.d type: bool → bool | None (matches Optional[bool] model)
- Fixed error handling example: added ValidKitError catch-all (TimeoutError/ConnectionError
  inherit from ValidKitError, not ValidKitAPIError)
- Fixed format parameter: use ResponseFormat.FULL enum instead of string literal
- Added None guard for optional MX records access

Reviewed by developer-docs-writer (technical accuracy) and code-reviewer (code examples).

Closes #2340

Author: jesse-validkit

README.md

@@ -1,249 +1,184 @@
 # ValidKit Python SDK
 
-[![PyPI version](https://badge.fury.io/py/validkit.svg)](https://badge.fury.io/py/validkit)
+[![PyPI version](https://badge.fury.io/py/validkit.svg)](https://pypi.org/project/validkit/)
 [![Python Versions](https://img.shields.io/pypi/pyversions/validkit.svg)](https://pypi.org/project/validkit/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Documentation](https://img.shields.io/badge/docs-available-brightgreen.svg)](https://docs.validkit.com)
 
-Async Python SDK for ValidKit Email Verification API - Built for AI Agents and high-volume applications.
-
-## Features
-
-- 🚀 **Fully Async**: Built on aiohttp for maximum performance
-- 🤖 **AI-Agent Optimized**: Token-efficient responses and agent-friendly formats
-- 📦 **Batch Processing**: Verify up to 10,000 emails in a single request
-- 🔄 **Smart Retries**: Automatic retry logic with exponential backoff
-- 🌊 **Connection Pooling**: Efficient connection reuse for high throughput
-- 📊 **Progress Tracking**: Real-time progress updates for large batches
-- 🪝 **Webhook Support**: Async webhook handling for batch results
-- 🔍 **Type Safety**: Full type hints and Pydantic models
-
-**Full API Documentation**: https://api.validkit.com/docs/openapi.json
+Email validation for signup flows -- block junk without blocking `test+staging@example.com`. Async Python client with batch support up to 10K emails, automatic retries, and Pydantic models.
 
 ## Installation
 
 ```bash
 pip install validkit
 ```
 
+Requires Python 3.8+.
+
 ## Quick Start
 
 ```python
 import asyncio
 from validkit import AsyncValidKit
 
 async def main():
-    # Initialize the client
     async with AsyncValidKit(api_key="your_api_key") as client:
-        # Single email verification
+        # Single email
         result = await client.verify_email("user@example.com")
-        print(f"Valid: {result.valid}")
-        
-        # Batch verification
-        emails = ["user1@example.com", "user2@example.com", "user3@example.com"]
-        results = await client.verify_batch(emails)
-        
-        for email, result in results.items():
-            print(f"{email}: {result.valid}")
+        print(result.valid)  # True
 
-asyncio.run(main())
-```
+        # Batch -- compact format by default
+        results = await client.verify_batch([
+            "alice@company.com",
+            "bob@tempmail.com",
+            "not-an-email",
+        ])
+        for email, r in results.items():
+            print(f"{email}: valid={r.v}, disposable={r.d}")
 
-## Advanced Usage
-
-### Batch Processing with Progress
-
-```python
-async def verify_large_batch():
-    async with AsyncValidKit(api_key="your_api_key") as client:
-        emails = ["email{}@example.com".format(i) for i in range(10000)]
-        
-        # Process with progress callback
-        async def progress_callback(processed, total):
-            print(f"Progress: {processed}/{total} ({processed/total*100:.1f}%)")
-        
-        results = await client.verify_batch(
-            emails,
-            chunk_size=1000,
-            progress_callback=progress_callback
-        )
-        
-        valid_count = sum(1 for r in results.values() if r.valid)
-        print(f"Valid emails: {valid_count}/{len(emails)}")
+asyncio.run(main())
 ```
 
-### Webhook Support
+## Features
 
-```python
-# Start async batch job with webhook
-job = await client.verify_batch_async(
-    emails=large_email_list,
-    webhook_url="https://your-app.com/webhook/validkit",
-    webhook_headers={"Authorization": "Bearer your_token"}
-)
+- **Async-native** -- aiohttp with connection pooling (100 connections default)
+- **Batch verification** -- up to 10,000 emails per call, chunked automatically
+- **Developer Pattern Intelligence** -- understands `test@`, `+addressing`, disposable domains
+- **Compact format** -- token-efficient responses (`v`, `d`, `r` fields) enabled by default
+- **Streaming** -- `async for` results as they complete
+- **Webhook delivery** -- fire-and-forget async batch jobs with callback
+- **Automatic retries** -- exponential backoff, 3 retries default
+- **Type-safe** -- Pydantic v2 models with full type hints
 
-print(f"Batch job started: {job.id}")
-print(f"Check status at: {job.status_url}")
-```
+## Advanced Usage
 
-### Custom Configuration
+### Custom configuration
 
 ```python
 from validkit import AsyncValidKit, ValidKitConfig
 
 config = ValidKitConfig(
     api_key="your_api_key",
-    base_url="https://api.validkit.com",
-    timeout=30,
-    max_retries=3,
-    max_connections=100,
-    rate_limit=10000  # requests per minute
+    timeout=30,           # seconds
+    max_retries=3,        # retry count
+    max_connections=100,   # connection pool size
+    rate_limit=10000,     # requests/min (None = unlimited)
+    compact_format=True,  # smaller payloads
 )
 
 async with AsyncValidKit(config=config) as client:
-    # Your code here
-    pass
+    result = await client.verify_email("user@example.com")
 ```
 
-## Response Format
-
-### Single Email Response
+### Batch with progress tracking
 
 ```python
-{
-    "valid": true,
-    "email": "user@example.com",
-    "format": {"valid": true},
-    "disposable": {"valid": true, "value": false},
-    "mx": {"valid": true, "records": ["mx1.example.com"]},
-    "smtp": {"valid": true}
-}
+def on_progress(processed, total):
+    print(f"{processed}/{total} ({processed / total * 100:.1f}%)")
+
+results = await client.verify_batch(
+    emails,
+    chunk_size=1000,
+    progress_callback=on_progress,
+)
 ```
 
-### Batch Response (Compact Format)
+### Async batch with webhook
 
 ```python
-{
-    "user1@example.com": {"v": true, "d": false},
-    "user2@example.com": {"v": false, "r": "invalid_format"},
-    "user3@example.com": {"v": true, "d": true}
-}
-```
+job = await client.verify_batch_async(
+    emails=large_list,
+    webhook_url="https://your-app.com/webhooks/validkit",
+    webhook_headers={"Authorization": "Bearer token"},
+)
 
-Where:
-- `v`: valid (boolean)
-- `d`: disposable (boolean)
-- `r`: reason (string, only if invalid)
+# Poll until complete, or wait for webhook
+job = await client.get_batch_status(job.id)
+results = await client.get_batch_results(job.id)
 
-## Agent-Optimized Features
+# Cancel if needed
+await client.cancel_batch(job.id)
+```
 
-### Token-Efficient Mode
+### Streaming
 
 ```python
-# Get compact responses (80% smaller)
-result = await client.verify_email(
-    "user@example.com",
-    format="compact"
-)
+async for email, result in client.stream_verify(emails, batch_size=100):
+    print(f"{email}: valid={result.v}")
 ```
 
-### Multi-Agent Tracing
+### Trace IDs
+
+Attach a trace ID for cross-service debugging:
 
 ```python
-# Include trace headers for multi-agent debugging
-result = await client.verify_email(
-    "user@example.com",
-    trace_id="agent_123_task_456"
-)
+result = await client.verify_email("user@example.com", trace_id="req_abc123")
 ```
 
 ## Error Handling
 
 ```python
 from validkit.exceptions import (
-    ValidKitAPIError,
-    RateLimitError,
-    InvalidAPIKeyError,
-    BatchSizeError
+    ValidKitError,       # base -- catches everything
+    ValidKitAPIError,    # API errors (4xx, 5xx)
+    InvalidAPIKeyError,  # 401
+    RateLimitError,      # 429, includes retry_after
+    BatchSizeError,      # batch exceeds 10K
+    TimeoutError,        # request timeout (inherits ValidKitError, not API)
+    ConnectionError,     # network failure (inherits ValidKitError, not API)
 )
 
 try:
-    result = await client.verify_email("invalid-email")
+    result = await client.verify_email("user@example.com")
+except RateLimitError as e:
+    print(e.retry_after)  # seconds until retry
+except InvalidAPIKeyError:
+    print("Check your API key")
 except ValidKitAPIError as e:
-    print(f"API Error: {e.message}")
-    print(f"Error Code: {e.code}")
-    print(f"Status Code: {e.status_code}")
+    print(e.message, e.status_code, e.code)
+except ValidKitError as e:
+    # Catches TimeoutError, ConnectionError, and any other non-API errors
+    print(f"SDK error: {e}")
 ```
 
-## Rate Limiting
+The SDK retries automatically on rate limits and transient errors (up to `max_retries`). Catch exceptions only if you need custom handling.
+
+## Compact Response Format
 
-The SDK automatically handles rate limiting with smart backoff:
+Default format. Smaller payloads, same information:
+
+| Field | Type | Meaning |
+|-------|------|---------|
+| `v` | `bool` | Email is valid |
+| `d` | `bool \| None` | Domain is disposable (None if not checked) |
+| `r` | `str \| None` | Reason (present only when invalid) |
 
 ```python
-# SDK will automatically retry with exponential backoff
-results = await client.verify_batch(
-    large_email_list,
-    auto_retry=True  # Default: True
-)
+# Compact (default)
+r = await client.verify_email("bad@example.com")
+print(r.v, r.d, r.r)  # False, False, "invalid_format"
+
+# Full format -- use when you need MX records, SMTP details
+from validkit.models import ResponseFormat
+full = await client.verify_email("user@example.com", format=ResponseFormat.FULL)
+if full.mx:
+    print(full.mx.records)  # ["mx1.example.com"]
 ```
 
 ## Examples
 
-Check the `examples/` directory for more detailed examples:
-
-- `basic_usage.py` - Simple verification examples
-- `batch_processing.py` - Large batch processing patterns
-- `webhook_handler.py` - Webhook endpoint implementation
-- `agent_integration.py` - AI agent integration patterns
-- `error_handling.py` - Comprehensive error handling
-
-## Requirements
-
-- Python 3.8+
-- aiohttp
-- pydantic
+See [`examples/`](examples/):
 
-## License
-
-MIT License - see LICENSE file for details.
-
-## Performance Tips
-
-1. **Use batch verification** for multiple emails (up to 10,000 per request)
-2. **Enable connection pooling** (default) for high-throughput applications  
-3. **Set appropriate timeouts** based on your batch size
-4. **Use webhooks** for large async batches to avoid long-running requests
+- [`basic_usage.py`](examples/basic_usage.py) -- single verification, batch, streaming, configuration
+- [`batch_processing.py`](examples/batch_processing.py) -- large batches, CSV processing, webhook jobs, domain analysis
 
 ## Contributing
 
-We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
-
-### Development Setup
-
-```bash
-# Clone the repository
-git clone https://github.com/ValidKit/validkit-python-sdk.git
-cd validkit-python-sdk
-
-# Create virtual environment
-python -m venv venv
-source venv/bin/activate  # On Windows: venv\Scripts\activate
-
-# Install dependencies
-pip install -e ".[dev]"
-
-# Run tests
-pytest
-```
+See [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ## Support
 
-- 📖 **Documentation**: https://docs.validkit.com
-- 🔧 **API Reference**: https://api.validkit.com/docs/openapi.json
-- 🐛 **Issues**: https://github.com/ValidKit/validkit-python-sdk/issues
-- 📧 **Email**: support@validkit.com
-- 💬 **Discord**: [Join our community](https://discord.gg/validkit)
+[Docs](https://docs.validkit.com) -- [GitHub Issues](https://github.com/ValidKit/validkit-python-sdk/issues) -- support@validkit.com
 
----
+## License
 
-Built with ❤️ for AI agents by [ValidKit](https://validkit.com)
+MIT -- see [LICENSE](LICENSE).