Define Python ⇆ Swift boundary

[banagale]

Document what stays in Python vs what will migrate to Swift.
Capture JSON payload shape (PromptSession).

✅ Work Completed

1. Data Models & Schema Definition

• Created src/filekitty/models.py - Complete PromptSession data model with JSON serialization
• FileMetadata, TreeSnapshot, SelectionState - Supporting data structures
• UTC timestamp handling - Swift ISO8601DateFormatter compatible
• JSON round-trip validation - Ensures schema stability

2. API Specification

• Created swift_integration_spec.md - Complete JSON API contract
• 5 core actions defined: process_files, get_python_symbols, update_selection, save_session, load_session
• CLI interface specified with filekitty binary, --json and --debug flags
• Error handling with optional debug tracebacks

3. Architecture Documentation

• Created architecture_boundaries.md - Clear Python vs Swift responsibility separation
• Migration strategy with 5 phases including packaging & release
• Security considerations and validation requirements

4. Testing & Examples

• Created src/tests/test_models.py - JSON schema stability tests
• Created example_payloads.json - Real-world test data examples
• All tests pass with poetry run pytest

5. Implementation Ready

• Foundation for issues Build minimal SwiftUI shell (file tree + prompt display) #71 (SwiftUI shell) and Bridge SwiftUI to Python via CLI or PythonKit #72 (Python bridge)
• Phase 5 packaging strategy for Publish SwiftUI alpha release (.app / .dmg) #74 (alpha release)
• Comprehensive documentation for Swift developers

Files Added

• src/filekitty/models.py - Core data models
• swift_integration_spec.md - API specification
• architecture_boundaries.md - Architecture documentation
• example_payloads.json - Test data examples
• src/tests/test_models.py - Schema validation tests

Ready for SwiftUI implementation phase 🚀

[banagale]

Closed with #75