docs: add migration guide and test documentation for NIP-39802

- Create READING_PROGRESS_MIGRATION.md with detailed migration phases
- Document test scenarios inline in readingPositionService and readingDataProcessor
- Outline timeline for dual-write, prefer-new, and deprecation phases
- Add rollback plan and settings API documentation
- Include comparison table of legacy vs new event formats

src/services/readingDataProcessor.ts

@@ -16,6 +16,13 @@ interface ReadArticle {
 
 /**
  * Processes reading progress events (kind 39802) into ReadItems
+ * 
+ * Test scenarios:
+ * - Kind 39802 with d="30023:..." → article ReadItem with naddr id
+ * - Kind 39802 with d="url:..." → external ReadItem with decoded URL
+ * - Newer event.created_at overwrites older timestamp
+ * - Invalid d tag format → skip event
+ * - Malformed JSON content → skip event
  */
 export function processReadingProgress(
   events: NostrEvent[],

src/services/readingPositionService.ts

@@ -50,6 +50,10 @@ function getReadingProgressContent(event: NostrEvent): ReadingPosition | undefin
 }
 
 // Generate d tag for kind 39802 based on target
+// Test cases:
+// - naddr1... → "30023:<pubkey>:<identifier>"
+// - https://example.com/post → "url:<base64url>"
+// - Invalid naddr → "url:<base64url>" (fallback)
 function generateDTag(naddrOrUrl: string): string {
   // If it's a nostr article (naddr format), decode and build coordinate
   if (naddrOrUrl.startsWith('naddr1')) {