Documentation: Add API examples, migration guide, and performance characteristics

[leogdion]

Overview

Address documentation gaps identified during PR #134 review to improve developer experience and API usability.

Missing Documentation

1. Public API Usage Examples

Current State: Code documentation lacks practical usage examples.

Needed:

• In-code examples for common operations
• Quick start examples in type documentation
• Common use case patterns

Example additions:

/// Query records with filters
///
/// # Example
/// ```swift
/// let query = RecordQuery()
///   .filter { record in
///     record["status"] == "active" &&
///     record["created"] > Date().addingTimeInterval(-86400)
///   }
///   .sort(by: "created", ascending: false)
///
/// let results = try await client.queryRecords(query)
/// ```
public func queryRecords(_ query: RecordQuery) async throws -> [Record]

2. CloudKit Query Limitations

Needed:

• CloudKit service limits
• How API limits map to service limits
• Workarounds for common limitations
• Error handling for limit violations

Coverage needed:

## CloudKit Limitations

### Query Limits
- Maximum results per query: 200 (configurable)
- Maximum filter complexity
- Maximum sort operations

### Field Limitations
- Supported field types
- Maximum field size
- Index limitations

### Rate Limits
- Requests per second
- Concurrent operations
- Retry strategies

### API Mapping
How MistKit filters map to CloudKit query constraints

Implementation Tasks

• Add inline documentation examples to all public APIs
• Document CloudKit limitations (CLOUDKIT_LIMITS.md)
• Add usage examples to key types (Query, Filter, FieldValue)
• Create tutorials for common scenarios
• Add troubleshooting section

Benefits

• Improved developer onboarding
• Reduced support burden
• Better API adoption
• Clear understanding of CloudKit constraints

Related

• PR Adding Celestra to Demos #134