docs: add Phase 1 plans and codebase documentation

- 01-01-PLAN.md: core.py + mlb.py (executed)
- 01-02-PLAN.md: nba.py + nhl.py
- 01-03-PLAN.md: nfl.py + orchestrator refactor
- Codebase documentation for planning context

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

.planning/codebase/CONVENTIONS.md

@@ -0,0 +1,150 @@
+# Coding Conventions
+
+**Analysis Date:** 2026-01-09
+
+## Naming Patterns
+
+**Files:**
+- PascalCase for all Swift files: `TripDetailView.swift`, `DataProvider.swift`
+- Views: `*View.swift` (e.g., `HomeView.swift`, `TripCreationView.swift`)
+- ViewModels: `*ViewModel.swift` (e.g., `TripCreationViewModel.swift`)
+- Services: `*Service.swift` (e.g., `LocationService.swift`)
+- Tests: `*Tests.swift` (e.g., `TravelEstimatorTests.swift`)
+
+**Functions:**
+- camelCase for all functions: `loadInitialData()`, `planItineraries()`
+- No special prefix for async functions
+- Handlers: `handle*` pattern not heavily used; actions named directly
+
+**Variables:**
+- camelCase: `selectedSports`, `startDate`, `gamesOnThisDay`
+- No underscore prefix for private (Swift convention)
+- Constants: camelCase (no UPPER_SNAKE_CASE)
+
+**Types:**
+- PascalCase for all types: `Stadium`, `TripPreferences`, `PlanningRequest`
+- No I prefix for protocols: `ScenarioPlanner` (not `IScenarioPlanner`)
+- Enums: PascalCase name, camelCase cases: `Sport.mlb`, `FailureReason.noGamesFound`
+
+## Code Style
+
+**Formatting:**
+- 4-space indentation (inferred from code)
+- No SwiftLint or SwiftFormat configuration
+- Follows standard Swift conventions organically
+
+**Section Organization:**
+- `// MARK: -` for major sections (560 occurrences across codebase)
+- Pattern: `// MARK: - Section Name`
+- Example sections: `// MARK: - Properties`, `// MARK: - Public API`, `// MARK: - Private`
+
+**File Headers:**
+```swift
+//
+//  FileName.swift
+//  SportsTime
+//
+//  Optional description line.
+//
+```
+
+## Import Organization
+
+**Order:**
+1. Foundation/Swift standard library
+2. Apple frameworks (SwiftUI, SwiftData, MapKit)
+3. Project imports (`@testable import SportsTime` in tests)
+
+**Grouping:**
+- No blank lines between import groups
+- Alphabetical not enforced
+
+**Path Aliases:**
+- None used (no module aliasing)
+
+## Error Handling
+
+**Patterns:**
+- Explicit result types: `ItineraryResult` enum with `.success` / `.failure`
+- `throws` for recoverable service errors
+- Async functions use `async throws`
+
+**Error Types:**
+- `PlanningFailure` with `FailureReason` enum and user message
+- `ConstraintViolation` for planning constraint issues
+- SwiftData errors propagated via `try`
+
+**Async:**
+- `async/await` throughout (no completion handlers)
+- `try await` pattern for async throwing functions
+
+## Logging
+
+**Framework:**
+- `print()` with emoji prefixes for debugging
+- No production logging framework (Sentry, etc.)
+
+**Patterns:**
+- Warning: `print("⚠️ Warning message")`
+- Info: `print("ℹ️ Info message")`
+- Error: `print("❌ Error: \(error)")`
+- Debug only; no structured logging
+
+## Comments
+
+**When to Comment:**
+- Explain why, not what
+- Document business logic and edge cases
+- Complex algorithms get explanatory comments
+
+**Documentation Comments:**
+- Triple-slash `///` for public APIs (487 occurrences)
+- Example:
+  ```swift
+  /// Main entry point for trip planning.
+  /// - Parameter request: The planning request containing all inputs
+  /// - Returns: Ranked itineraries on success, or explicit failure
+  func planItineraries(request: PlanningRequest) -> ItineraryResult
+  ```
+
+**TODO Comments:**
+- Format: `// TODO: description`
+- Currently only 1 TODO in codebase: `RouteDescriptionGenerator.swift:30`
+
+## Function Design
+
+**Size:**
+- No strict line limit enforced
+- Large files exist (800+ lines in some services)
+- Complex logic extracted to private helpers
+
+**Parameters:**
+- Default parameters used extensively
+- Options objects for complex configuration: `PlanningRequest`, `TripPreferences`
+
+**Return Values:**
+- Explicit returns
+- Result types for operations that can fail
+- Optional for lookups that may not find data
+
+## Module Design
+
+**Exports:**
+- No barrel files (Swift doesn't use this pattern)
+- Public API via `public`/`internal` access control
+
+**Access Control:**
+- `private` for implementation details
+- `internal` (default) for module-internal
+- `public` for Codable conformances and cross-module APIs
+
+**Property Wrappers:**
+- `@Observable` for ViewModels (modern pattern)
+- `@Model` for SwiftData entities
+- `@MainActor` for UI-bound services
+- `@Query` for SwiftData queries in views
+
+---
+
+*Convention analysis: 2026-01-09*
+*Update when patterns change*