docs(sync): explain merged persistence and save recovery

docs/src/content/docs/faq.md

@@ -94,6 +94,21 @@ See [Transcripts](/transcripts/).
 ## Does playback progress sync between devices?
 
 Saved progress, subscriptions, playlists, templates, and preferences can travel with PodNotes' `data.json` when your sync service includes plugin data.
-PodNotes has no separate sync account or live playback handoff. Two devices can overwrite each other's changes.
+PodNotes merges changes from other devices before saving and updates its library when Obsidian reports a synced file change.
+
+When `data.json` files identify different libraries, PodNotes combines their entries, including podcasts, progress records, and playlists.
+A new device's library combines with the synced library even if PodNotes starts before sync delivers `data.json`.
+PodNotes records which library a file belongs to with a `libraryId` in `data.json`.
+The combined file keeps the `libraryId` of the library that started first.
+If both devices change the same progress record or feed, the device saving keeps its own version of that entry.
+
+Periodic playback checkpoints write at most once every 10 seconds.
+Pausing, hiding the player's window, or closing the player requests a save at once.
+Sync does not switch an episode already loaded in the player or seek to another device's position.
+The loaded episode stays current on this device, and the player saves its own position even after synced progress arrives.
+
+Changes that arrive between the read and write can still be overwritten.
+Keep PodNotes updated on every device and let sync finish before switching.
 API key values and protected private-feed URLs remain local to each device.
-See [Sync and devices](/sync/) before switching between devices.
+If PodNotes stops saving and shows a notice, follow [Restore saving after a notice](/sync/#restore-saving-after-a-notice).
+See [Sync and devices](/sync/) for conflict and download limits.

docs/src/content/docs/sync.md

@@ -11,6 +11,7 @@ Using the same library on several devices depends on the files your vault sync s
 
 PodNotes stores preferences and library state in `.obsidian/plugins/podnotes/data.json`.
 If you use a different Obsidian configuration folder, the path starts with that folder instead of `.obsidian`.
+A `libraryId` in `data.json` records which library the file belongs to.
 
 The file contains the following data:
 
@@ -30,18 +31,50 @@ The **Default Playback Rate** preference is saved. Saved progress provides a res
 
 ## Changes on two devices
 
-PodNotes saves a snapshot of its local state. It does not merge subscriptions, playlists, preferences, or progress changed on another device.
-An open instance does not automatically reload a synced `data.json`.
+Before each save, PodNotes reads `data.json`.
+For files from the same library, it compares the file with the last loaded or saved copy and this device's changes.
+It merges changes to different entries, including subscriptions, progress, playlists, and preferences.
 
 For example, one device can add a podcast while another updates its playback progress.
-The second device's next save can replace the first device's subscription change with its older library snapshot.
-The outcome depends on sync timing and your sync service's conflict handling.
+Once the subscription reaches the second device's `data.json`, its next save keeps both changes.
 
-Using one device at a time reduces this risk. Allow sync to finish before loading PodNotes on the second device.
-If sync is still running when Obsidian starts, PodNotes can load an older snapshot before the synced file arrives.
-This includes sync services that run inside Obsidian. On mobile, data loads even while the player stays closed.
-Keep PodNotes disabled on the second device while sync finishes, then enable it to load the transferred data.
-Syncing a file into an already open session does not update that session's in-memory library.
+When `data.json` files identify different libraries, PodNotes combines their entries, including podcasts, progress records, and playlists.
+A new device's library combines with the synced library even if PodNotes starts before sync delivers `data.json`.
+A setting changed from its default in only one library keeps that library's value.
+The combined file keeps the `libraryId` of the library that started first.
+If a podcast has different names in the two libraries, it appears twice, once under each name.
+
+When Obsidian reports a synced file change, PodNotes updates its library without a restart.
+Sync does not switch an episode already loaded in the player or seek to another device's position.
+The loaded episode stays current on this device.
+The player saves its own position for that episode, even after progress from another device arrives.
+
+For other changes, conflicts favor the device saving when both devices edit the same setting or entry before seeing each other's changes.
+PodNotes takes these entries whole, rather than combining their fields:
+
+- A saved feed, including its URL and private-feed secret reference.
+- An episode's progress record or note mapping.
+- The current episode, including a playlist's current episode.
+- Each episode in the queue, favorites, Local Files, custom playlists, or downloads.
+
+Episodes match by podcast name and title, so equal titles from different podcasts stay separate.
+A download's stream URL, file path, and ownership record stay together.
+
+A change that arrives between the read and write can still be overwritten.
+Sync can also see a partly written file because PodNotes writes `data.json` in place.
+An older PodNotes version on another device can overwrite the whole file.
+Keep PodNotes updated on every device and let sync finish before switching devices.
+
+## When PodNotes saves
+
+User changes request a save at once. Changes made during a save share the next save.
+During playback, periodic position checkpoints write at most once every 10 seconds.
+Pausing, hiding the player's window, or closing the player requests a position save at once, including in a popout.
+Once the Obsidian window starts closing, PodNotes starts no new writes.
+When Obsidian quits, it lets an in-flight write finish.
+
+PodNotes reads the file back after each write to check that the saved data matches.
+A mismatch counts as a failed save.
 
 ## Secrets on each device
 
@@ -99,10 +132,28 @@ Older links can contain the original private URL and are not rewritten by the se
 
 ## Unreadable plugin data
 
-If `data.json` exists but Obsidian cannot read or parse it, PodNotes leaves the file unchanged.
-It starts with default settings and shows a persistent notice that nothing is saved.
-The notice includes the actual file path.
+If a non-empty `data.json` cannot be read or parsed, PodNotes leaves it unchanged and shows a persistent notice that saving has stopped.
+The notice includes the file path. If the file is unreadable at startup, PodNotes starts with default settings.
+After an unreadable startup, a replacement must load without repairs before saving resumes.
+When PodNotes already has a loaded library, entries dropped while reading a synced file do not count as deletions.
+PodNotes keeps their last known values while merging other changes.
+
+If a copy from an older data format arrives during a session, PodNotes stops saving and shows a notice asking you to restart Obsidian.
+Restarting runs the migration, including moving old API keys into secret storage.
+
+An empty file counts as missing. At startup, PodNotes starts a new library.
+After a failed write leaves the file empty, the next save can write the data again, including changes merged from another device.
+PodNotes does not repair a non-empty, partly written file.
+
+### Restore saving after a notice
+
+1. For an unreadable file, let sync finish. Check available disk space and file permissions if the notice remains.
+2. Restore a readable backup of the file named in the notice if needed. PodNotes resumes saving when it reads a usable copy.
+   If the notice remains, restart Obsidian.
+3. For an older-format notice, update PodNotes on every device, let sync finish, and restart Obsidian to migrate the file.
+
+After an unreadable startup, PodNotes adopts the recovered library instead of merging changes made after saving stopped.
+If PodNotes had already loaded a library, it merges those changes with the recovered file.
 
-Saving remains disabled until you restore or delete that file and restart Obsidian.
-Restoring a readable backup preserves the previous library. Deleting the file starts a new library.
-Changes made while saving is disabled do not become a replacement for the unreadable file.
+To start a new library on this device, back up `data.json`, delete it, and restart Obsidian.
+Another device with the old library loaded combines it with the new library when the new file arrives.