Signed-off-by: Matt Bruce <mbrucedogs@gmail.com>

Proposal.md

@@ -18,6 +18,7 @@ Create a single, typed, discoverable namespace for persisted app data with consi
 
 ### Core Components
 - **StorageKey** protocol - Defines storage configuration for each data type
+- **StorageKey.migration** - Optional protocol-based migration attached to a key
 - **StorageRouter** actor - Main entry point coordinating all storage operations
 - **StorageProviding** protocol - Abstraction for storage operations
 - **StorageKeyCatalog** protocol - Catalog of keys for auditing/validation
@@ -47,6 +48,10 @@ Each helper is a dedicated actor providing thread-safe access to a specific stor
 - **AnyStorageKey** - Type-erased storage key for catalogs
 - **AnyStorageMigration** - Type-erased migration for protocol-based workflows
 - **AnyCodable** - Type-erased Codable for mixed-type payloads
+- **MigrationContext** - Context for conditional migrations (app version, device, system info)
+- **MigrationResult** - Migration outcome with errors and metadata
+- **MigrationError** - Error types for migration failures
+- **DeviceInfo / SystemInfo** - Device and system metrics used by migrations
 
 ## Usage Pattern
 Apps extend StorageKeys with their own key types and use StorageRouter.shared. This follows the Notification.Name pattern for discoverable keys.
@@ -62,6 +67,14 @@ The `StorageRouter` provides discovery APIs to retrieve all registered keys for
 ## Sync Behavior
 StorageRouter can call WCSession.updateApplicationContext for manual or automaticSmall sync policies when availability allows it. Session activation and receiving data are owned by the app.
 
+### Bootstrapping and Watch Requests
+LocalData exposes helper APIs to make watch sync reliable after relaunch or reconnection:
+
+- `StorageRouter.syncRegisteredKeysIfNeeded()` re-sends stored values for eligible keys.
+- `StorageRouter.syncSnapshot()` returns a payload snapshot for replying to watch requests.
+
+Apps should call `syncRegisteredKeysIfNeeded()` on launch and on WatchConnectivity reachability changes, and reply to watch-initiated requests with `syncSnapshot()` to avoid launch-order issues.
+
 ## Platforms
 - iOS 17+
 - watchOS 10+
@@ -69,5 +82,6 @@ StorageRouter can call WCSession.updateApplicationContext for manual or automati
 ## Future Ideas (Not Implemented)
 - Key rotation strategies for encrypted data
 - Watch-optimized data representations
+- Persistent storage for sync policy overrides
 
 Any future changes should keep LocalData documentation in sync with code changes.