@sriinnu/runic 1.0.0

package/docs/sync_files_summary.md

@@ -0,0 +1,391 @@
+# Sync Infrastructure File Summary
+
+## Overview
+
+The sync infrastructure in `/Sources/RunicCore/Sync/` consists of 6 files that work together to provide iCloud CloudKit synchronization for Runic. This document provides a detailed summary of what each file does.
+
+---
+
+## 1. SyncProtocol.swift
+
+**Purpose**: Core protocol definitions and supporting types
+
+### Key Components
+
+#### Protocols
+- **SyncEngine**: Main protocol for sync operations
+  - `sync(options:)` - Full bidirectional sync
+  - `push(records:)` - Push local changes to remote
+  - `fetch(recordTypes:)` - Fetch changes from remote
+  - `delete(recordIDs:)` - Delete records from remote
+  - `resetSync()` - Reset sync state
+
+- **SyncableRecord**: Protocol for syncable objects
+  - Required properties: `recordID`, `recordType`, `version`, `modifiedAt`, `lastModifiedDeviceID`
+  - Required methods: `toCKRecord()`, `fromCKRecord(_:)`
+  - Must conform to `Sendable` and `Codable`
+
+- **SyncConflictResolverProtocol**: Conflict resolution interface
+  - `resolve(local:remote:strategy:)` - Resolves conflicts between versions
+
+- **SyncObserver**: Observer pattern for sync events
+  - `syncDidStart()`, `syncDidProgress(current:total:)`, `syncDidComplete(result:)`, `syncDidFail(error:)`
+
+#### Supporting Types
+- **SyncOptions**: Configuration for sync operations
+  - `forceFullSync`, `batchSize`, `conflictStrategy`, `backgroundMode`, `timeout`, `encryptSensitiveData`
+
+- **SyncResult**: Statistics from sync operation
+  - `pushedCount`, `fetchedCount`, `conflictsResolved`, `deletedCount`, `duration`, `warnings`
+
+- **ConflictResolutionStrategy**: Conflict resolution strategies
+  - `.lastWriteWins`, `.preferLocal`, `.preferRemote`, `.highestVersion`, `.merge`
+
+- **SyncError**: Error types with localized descriptions
+  - `.iCloudAccountUnavailable`, `.networkUnavailable`, `.quotaExceeded`, `.timeout`, etc.
+
+- **SyncPriority**: Priority levels for sync operations
+  - `.low`, `.normal`, `.high`, `.critical`
+
+**Lines of Code**: 289
+
+---
+
+## 2. SyncRecord.swift
+
+**Purpose**: Concrete syncable record types with CloudKit conversion
+
+### Key Components
+
+#### CloudKit Record Type Constants
+```swift
+CloudKitRecordType.usageSnapshot
+CloudKitRecordType.userPreferences
+CloudKitRecordType.alertConfiguration
+CloudKitRecordType.syncMetadata
+```
+
+#### Record Types
+
+1. **UsageSnapshotSyncRecord**
+   - **Purpose**: Syncs usage data across devices
+   - **Fields**: providerID, primaryUsed, primaryLimit, secondaryUsed, secondaryLimit, costUSD, accountEmail (encrypted), updatedAt, deviceName, platform
+   - **Features**: Encrypts sensitive email data
+
+2. **UserPreferencesSyncRecord**
+   - **Purpose**: Syncs user settings and preferences
+   - **Fields**: refreshInterval, enabledProviders, notificationsEnabled, autoRefreshEnabled, theme, displayFormat
+   - **Features**: Single record per user (fixed recordID)
+
+3. **AlertConfigurationSyncRecord**
+   - **Purpose**: Syncs alert thresholds and notification settings
+   - **Fields**: providerID, warningThreshold, criticalThreshold, notificationChannels, enabled
+   - **Features**: One record per provider
+
+#### Encryption Helpers
+- `encryptString(_:)` - AES-GCM encryption for sensitive data
+- `decryptString(_:)` - Decryption with error handling
+- `getOrCreateEncryptionKey()` - Keychain-based key management
+- `saveToKeychain(key:data:)` - Secure key storage
+- `loadFromKeychain(key:)` - Key retrieval
+
+**Lines of Code**: 394
+
+---
+
+## 3. iCloudSyncEngine.swift
+
+**Purpose**: CloudKit-based synchronization engine implementation
+
+### Key Components
+
+#### Architecture
+- **Actor-based**: Thread-safe concurrent access
+- **CloudKit Integration**: Uses CKContainer and CKDatabase
+- **Offline Support**: Queue for pending operations
+- **Retry Logic**: Exponential backoff for network errors
+
+#### Properties
+- `container`: CloudKit container
+- `database`: Private CloudKit database
+- `conflictResolver`: Handles conflicts
+- `pendingQueue`: Offline operation queue
+- `changeToken`: For incremental sync
+- `deviceID`: Unique device identifier
+
+#### Key Methods
+
+1. **sync(options:)**: Full bidirectional sync
+   - Checks iCloud account status
+   - Processes pending queue
+   - Fetches remote changes
+   - Detects and resolves conflicts
+   - Returns sync statistics
+
+2. **push(records:)**: Push local changes
+   - Converts SyncableRecord to CKRecord
+   - Batch saves to CloudKit
+   - Handles CloudKit errors
+   - Returns saved record IDs
+
+3. **fetch(recordTypes:)**: Fetch remote changes
+   - Queries CloudKit for each record type
+   - Parses CKRecords to SyncableRecords
+   - Returns fetched records
+
+4. **delete(recordIDs:)**: Delete remote records
+   - Converts IDs to CKRecord.ID
+   - Batch deletes from CloudKit
+   - Returns deleted IDs
+
+5. **enqueue(_:priority:)**: Queue offline operations
+   - Adds to pending queue
+   - Sorts by priority
+
+#### Error Handling
+- Network errors: Retry with exponential backoff
+- Quota exceeded: Return appropriate error
+- Authentication failures: Return auth error
+- Conflict detection: Use conflict resolver
+
+**Lines of Code**: 309
+
+---
+
+## 4. SyncConflictResolver.swift
+
+**Purpose**: Default conflict resolution implementation
+
+### Key Components
+
+#### Architecture
+- **Actor-based**: Thread-safe conflict resolution
+- **Pluggable**: Custom merge handlers per record type
+- **Statistics Tracking**: Comprehensive conflict metrics
+
+#### Properties
+- `conflictStats`: Tracks resolution statistics
+- `mergeHandlers`: Custom handlers per record type
+
+#### Conflict Resolution Strategies
+
+1. **Last-write-wins**: Keep most recently modified
+   - Uses `modifiedAt` timestamp
+   - Version as tiebreaker
+
+2. **Prefer local**: Always keep local version
+
+3. **Prefer remote**: Always keep remote version
+
+4. **Highest version**: Keep highest version number
+   - Timestamp as tiebreaker
+
+5. **Merge**: Custom merge logic
+   - Uses registered handlers
+   - Falls back to last-write-wins
+
+#### Default Merge Handlers
+
+1. **UsageSnapshot**: Prefer record with most recent data
+2. **UserPreferences**: Merge enabled providers (union)
+3. **AlertConfiguration**: Use most conservative thresholds
+
+#### Statistics
+- Total conflicts resolved
+- Conflicts by record type
+- Conflicts by strategy
+- Local vs remote win rate
+- Last conflict timestamp
+
+**Lines of Code**: 311
+
+---
+
+## 5. BackgroundSyncManager.swift
+
+**Purpose**: Manages automatic background synchronization
+
+### Key Components
+
+#### Architecture
+- **Actor-based**: Thread-safe background sync
+- **Lifecycle-aware**: Responds to app state changes
+- **Timer-based**: Periodic sync intervals
+- **Observer pattern**: Notifies sync status
+
+#### Properties
+- `syncEngine`: Underlying sync engine
+- `config`: Sync configuration
+- `syncTimer`: Periodic sync timer (MainActor)
+- `isEnabled`: Sync state
+- `lastSyncDate`: Last successful sync
+- `syncHistory`: Historical sync records
+- `observers`: Registered observers
+
+#### Configuration
+- `activeSyncInterval`: Sync interval when active (default: 5 min)
+- `backgroundSyncInterval`: Sync interval in background (default: 1 hour)
+- `syncOnForeground`: Sync when app becomes active
+- `syncOnBackground`: Sync when app enters background
+
+#### Key Methods
+
+1. **start()**: Starts automatic sync
+   - Enables sync
+   - Schedules first sync
+
+2. **stop()**: Stops automatic sync
+   - Disables sync
+   - Invalidates timer
+
+3. **syncNow(options:)**: Manual sync
+   - Notifies observers
+   - Performs sync
+   - Records history
+   - Returns result
+
+4. **addObserver(_:)**: Register observer
+5. **removeObserver(_:)**: Unregister observer
+
+#### Lifecycle Integration
+- `didBecomeActiveNotification`: Sync on foreground
+- `didEnterBackgroundNotification`: Sync on background
+- iOS background tasks: Complete sync before suspension
+
+#### Statistics
+- Last sync date
+- Total/successful/failed syncs
+- Success rate percentage
+- Average sync duration
+- Recent sync history (last 10)
+
+**Lines of Code**: 385
+
+---
+
+## 6. SyncUsageExample.swift
+
+**Purpose**: Comprehensive integration examples (DEBUG only)
+
+### Key Components
+
+#### Example Functions
+
+1. **setupSyncExample()**: Basic initialization
+2. **customConfigurationExample()**: Custom config
+3. **syncUsageDataExample()**: Sync usage records
+4. **syncPreferencesExample()**: Sync preferences
+5. **syncAlertConfigExample()**: Sync alerts
+6. **manualSyncExample()**: Manual sync with options
+7. **conflictResolutionExample()**: Custom conflict handlers
+8. **observerExample()**: Observer pattern
+9. **statisticsExample()**: Monitoring and stats
+10. **errorHandlingExample()**: Error handling patterns
+
+#### Example Observer
+- **SyncProgressObserver**: Sample observer implementation
+  - Prints sync start, progress, completion, errors
+  - Demonstrates observer pattern
+
+#### Coverage
+- All record types (usage, preferences, alerts)
+- All sync operations (push, fetch, sync, queue)
+- All conflict strategies
+- Custom merge handlers
+- Statistics and monitoring
+- Error handling patterns
+
+**Lines of Code**: 295
+
+---
+
+## File Dependencies
+
+```
+SyncProtocol.swift
+    ↓
+    ├── SyncRecord.swift
+    ├── iCloudSyncEngine.swift
+    │       ↓
+    │   SyncConflictResolver.swift
+    │       ↓
+    │   BackgroundSyncManager.swift
+    │       ↓
+    └── SyncUsageExample.swift
+```
+
+---
+
+## Total Statistics
+
+- **Total Files**: 6
+- **Total Lines**: ~1,983 lines
+- **Protocols Defined**: 4
+- **Concrete Types**: 12
+- **Enums**: 4
+- **Supporting Functions**: 15+
+- **Example Functions**: 10
+
+---
+
+## Key Features
+
+### ✅ Implemented
+- [x] Full bidirectional sync
+- [x] Offline queue with priorities
+- [x] Conflict resolution (5 strategies)
+- [x] Custom merge handlers
+- [x] AES-GCM encryption
+- [x] Background sync manager
+- [x] Lifecycle integration
+- [x] Observer pattern
+- [x] Retry logic with backoff
+- [x] Statistics and monitoring
+- [x] Error handling
+- [x] Comprehensive examples
+
+### 🔒 Security
+- [x] Private CloudKit database
+- [x] Keychain-based encryption keys
+- [x] AES-GCM for sensitive data
+- [x] User authentication required
+
+### ⚡ Performance
+- [x] Actor-based concurrency
+- [x] Batch operations
+- [x] Incremental sync (change tokens)
+- [x] Configurable intervals
+- [x] Priority-based queue
+
+### 🧪 Testing
+- [x] DEBUG-only examples
+- [x] Comprehensive error scenarios
+- [x] Observer testing
+- [x] Statistics validation
+
+---
+
+## Usage Pattern
+
+```swift
+// 1. Initialize
+let syncEngine = iCloudSyncEngine()
+let syncManager = BackgroundSyncManager(syncEngine: syncEngine)
+
+// 2. Configure observer
+await syncManager.addObserver(myObserver)
+
+// 3. Start automatic sync
+await syncManager.start()
+
+// 4. Create and sync records
+let record = UsageSnapshotSyncRecord(...)
+await syncEngine.push(records: [record])
+
+// 5. Monitor statistics
+let stats = await syncManager.statistics
+```
+
+---
+
+**Note**: All files compile successfully with Swift 6 strict concurrency enabled. The infrastructure is production-ready and fully documented.

package/docs/sync_quick_reference.md

@@ -0,0 +1,225 @@
+# CloudKit Sync Quick Reference
+
+## One-Minute Setup
+
+```swift
+import RunicCore
+
+// 1. Initialize
+let syncEngine = iCloudSyncEngine()
+let syncManager = BackgroundSyncManager(syncEngine: syncEngine)
+
+// 2. Start
+await syncManager.start()
+
+// Done! Sync runs automatically every 5 minutes (active) / 1 hour (background)
+```
+
+---
+
+## Common Operations
+
+### Push Usage Data
+```swift
+let record = UsageSnapshotSyncRecord(
+    providerID: "claude",
+    primaryUsed: 75000,
+    primaryLimit: 100000,
+    deviceName: "MacBook Pro",
+    platform: "macOS"
+)
+await syncEngine.push(records: [record])
+```
+
+### Sync Preferences
+```swift
+let prefs = UserPreferencesSyncRecord(
+    refreshInterval: 300,
+    enabledProviders: ["claude", "openai"],
+    notificationsEnabled: true
+)
+await syncEngine.push(records: [prefs])
+```
+
+### Manual Sync
+```swift
+let result = await syncManager.syncNow()
+```
+
+### Force Full Sync
+```swift
+let options = SyncOptions(forceFullSync: true)
+let result = await syncManager.syncNow(options: options)
+```
+
+---
+
+## Monitoring
+
+### Check Sync Status
+```swift
+let stats = await syncManager.statistics
+print("Success rate: \(stats.successRate)%")
+print("Last sync: \(stats.lastSyncDate)")
+```
+
+### Add Observer
+```swift
+class MySyncObserver: SyncObserver {
+    func syncDidStart() { print("Syncing...") }
+    func syncDidProgress(current: Int, total: Int) { }
+    func syncDidComplete(result: SyncResult) { print("Done!") }
+    func syncDidFail(error: SyncError) { print("Failed: \(error)") }
+}
+
+await syncManager.addObserver(MySyncObserver())
+```
+
+---
+
+## Error Handling
+
+```swift
+switch result {
+case .success(let syncResult):
+    print("Synced \(syncResult.pushedCount + syncResult.fetchedCount) records")
+
+case .failure(let error):
+    switch error {
+    case .iCloudAccountUnavailable:
+        // Show "Sign in to iCloud" message
+    case .networkUnavailable:
+        // Queue for later, show offline indicator
+    case .quotaExceeded:
+        // Show "Storage full" message
+    default:
+        // Generic error handling
+    }
+}
+```
+
+---
+
+## Configuration
+
+### Custom Intervals
+```swift
+let config = SyncConfiguration(
+    activeSyncInterval: 180,      // 3 min
+    backgroundSyncInterval: 1800, // 30 min
+    syncOnForeground: true,
+    syncOnBackground: true
+)
+let syncManager = BackgroundSyncManager(syncEngine: syncEngine, config: config)
+```
+
+### Custom Conflict Strategy
+```swift
+let options = SyncOptions(
+    conflictStrategy: .merge  // or .lastWriteWins, .preferLocal, .preferRemote
+)
+```
+
+---
+
+## CloudKit Record Types
+
+| Record Type | Purpose | Key Fields |
+|------------|---------|------------|
+| **UsageSnapshot** | Usage data | providerID, primaryUsed, primaryLimit, costUSD |
+| **UserPreferences** | Settings | refreshInterval, enabledProviders, theme |
+| **AlertConfiguration** | Alerts | warningThreshold, criticalThreshold, enabled |
+
+---
+
+## Conflict Resolution Strategies
+
+| Strategy | Behavior |
+|----------|----------|
+| **lastWriteWins** | Most recent modification wins (default) |
+| **preferLocal** | Always keep local version |
+| **preferRemote** | Always keep remote version |
+| **highestVersion** | Highest version number wins |
+| **merge** | Custom merge logic (smart defaults included) |
+
+---
+
+## Offline Support
+
+```swift
+// Queue for sync when online (automatic)
+await syncEngine.enqueue(record, priority: .high)
+
+// Check pending operations
+let pending = await syncEngine.pendingOperationCount
+```
+
+---
+
+## Security
+
+- ✅ Private CloudKit database (user-specific)
+- ✅ AES-GCM encryption for sensitive data
+- ✅ Keychain-based key storage
+- ✅ User authentication required
+
+---
+
+## Troubleshooting
+
+### "iCloud account unavailable"
+→ Settings > Apple ID > iCloud > Enable iCloud Drive
+
+### "Network unavailable"
+→ Changes queued automatically, will sync when online
+
+### Records not syncing
+1. Check CloudKit Console for errors
+2. Verify entitlements include CloudKit
+3. Ensure container identifier is correct
+
+---
+
+## Performance Tips
+
+- Default batch size: 100 records (adjust with `SyncOptions.batchSize`)
+- Use priority queue for critical data: `.high` or `.critical`
+- Monitor statistics to track sync performance
+- Sync on foreground disabled if last sync < 5 min ago
+
+---
+
+## Required Setup (One-Time)
+
+1. **Entitlements**: Add CloudKit to `Runic.entitlements`
+2. **Container**: Create iCloud container in Developer Portal
+3. **Schema**: Create 3 record types in CloudKit Console
+4. **Code**: Initialize sync engine at app launch
+
+See `CLOUDKIT_SYNC_GUIDE.md` for detailed setup instructions.
+
+---
+
+## Files
+
+- `SyncProtocol.swift` - Protocols and types
+- `SyncRecord.swift` - Record definitions
+- `iCloudSyncEngine.swift` - CloudKit implementation
+- `SyncConflictResolver.swift` - Conflict resolution
+- `BackgroundSyncManager.swift` - Automatic sync
+- `SyncUsageExample.swift` - Integration examples
+
+---
+
+## Build Status
+
+✅ **Compiles successfully** with Swift 6 strict concurrency
+- Zero errors
+- Only non-critical warnings (Codable, Timer isolation)
+- Production ready
+
+---
+
+**Version**: 1.0
+**Last Updated**: 2026-01-31
+**Status**: Ready for integration

package/docs/todo.md

@@ -0,0 +1,11 @@
+---
+summary: "Pending cleanup items for Runic (e.g., retire Claude Opus fallback)."
+read_when:
+  - Grooming backlog or planning maintenance
+  - Removing legacy Claude Opus handling
+---
+
+## TODO
+
+- December 2025: remove the Claude Opus fallback logic (Claude Code) once users have fully migrated; clean up any UI labels and parsers that reference Opus as a tertiary limit.
+- January 2026: owner-authorized roadmap item to deliver Windows and iOS app support.

package/docs/ui.md

@@ -0,0 +1,29 @@
+---
+summary: "Menu bar UI, icon rendering, and menu layout details."
+read_when:
+  - Changing menu layout, icon rendering, or UI copy
+  - Updating menu card or provider-specific UI
+---
+
+# UI & icon
+
+## Menu bar
+- LSUIElement app: no Dock icon; status item uses custom NSImage.
+- Merge Icons toggle combines providers into one status item with a switcher.
+
+## Icon rendering
+- 18×18 template image.
+- Top bar = 5-hour window; bottom hairline = weekly window.
+- Fill represents percent remaining by default; “Show usage as used” flips to percent used.
+- Dimmed when last refresh failed; status overlays render incident indicators.
+- Advanced: menu bar can show provider branding icons with a percent label instead of critter bars.
+
+## Menu card
+- Session + weekly rows with resets (relative countdown when available).
+- Codex-only: Credits + “Buy Credits…” in-card action.
+- Web-only rows (when OpenAI web enabled): code review remaining, usage breakdown submenu.
+
+## Widgets (high level)
+- Widget entries mirror the menu card; detailed pipeline in `docs/widgets.md`.
+
+See also: `docs/widgets.md`.

package/docs/web-integration.md

@@ -0,0 +1,9 @@
+---
+summary: "Deprecated: OpenAI web dashboard integration is documented in docs/codex.md."
+read_when:
+  - Redirect: see docs/codex.md
+---
+
+# OpenAI web integration (Codex)
+
+Moved to `docs/codex.md`.