wip

docs/guide/limitations.md

@@ -8,14 +8,8 @@ VaultLink works well for most Obsidian vaults, but has some constraints you shou
 
 Only **`.md`** and **`.txt`** files get automatic conflict-free merging.
 
-Other file types (images, PDFs, etc.) use last-write-wins:
-
-```
-User A updates diagram.png → Server stores version 1
-User B updates diagram.png → Server stores version 2 (overwrites A's changes)
-```
-
-**Workaround**: Avoid editing the same non-text file simultaneously.
+For other file types, a one-sided change is retained. Concurrent unmergeable
+changes keep the server's version. The client does not archive displaced bytes.
 
 ### Binary Detection
 
@@ -24,7 +18,7 @@ Files are treated as binary if they:
 - Contain NUL bytes (`0x00`)
 - Fail UTF-8 validation
 
-Binary files within `.md` or `.txt` extensions still get last-write-wins (no merge).
+Binary files within `.md` or `.txt` extensions follow the same unmergeable-content policy.
 
 ## Performance Constraints
 
@@ -61,11 +55,11 @@ Rough estimates (varies by vault size and activity):
 
 - All versions stored indefinitely (no automatic cleanup)
 - Each vault is a separate SQLite database
-- Deleted files marked as deleted (not purged)
+- Deletion removes file-manifest membership; content history remains readable
 
 **Growth**: Version history grows with every change. A 10 MB vault with frequent edits might grow to 100+ MB over months.
 
-**Cleanup**: Manual only (see [Advanced Configuration](/config/advanced#version-history-cleanup)).
+Immutable merge bases and request receipts must not be independently deleted. There is no automatic safe history-pruning protocol.
 
 ### Implications
 
@@ -92,7 +86,7 @@ Result: "The very quick red fox" ← Both changes preserved
 - Simultaneous edits to the same sentence
 - Large structural changes (moving sections around)
 
-**Result**: Merged file might need manual cleanup in ~1-5% of concurrent edits.
+Merged files may require manual review; there is no measured universal conflict-success rate.
 
 ## Scalability
 
@@ -140,6 +134,22 @@ Not currently supported. Running multiple servers requires manual vault partitio
 - Tokens configured in server config file
 - No runtime user management
 
+## Restored backups
+
+Restore server databases while the server is stopped. API v5 clients detect a
+changed history even when version numbers are reused. Clean files reconcile with
+the restored server; unsent edits are preserved as separate local documents.
+Clients and server must be upgraded together. This does not replace independent
+backups or protect against arbitrary physical-media corruption.
+
+## Interrupted sync
+
+The client has no filesystem journal or power-loss durability protocol. Interrupted
+writes may leave missing, partial or moved files. On restart, normal scans reconcile
+the current files, including edits made while the client was stopped. Metadata
+saves must remain complete and readable, so the client can continue syncing; exact
+pre-interruption file contents and identities are not guaranteed.
+
 ## Known Edge Cases
 
 ### Simultaneous Deletes and Edits
@@ -147,10 +157,10 @@ Not currently supported. Running multiple servers requires manual vault partitio
 ```
 User A deletes note.md
 User B edits note.md
-Result: Edit wins (file recreated with B's content)
+Result: Manifest deletion removes the file, including unsent local edits.
 ```
 
-Operational transformation prioritises content preservation.
+Content updates do not restore deleted membership. There is no local recovery archive.
 
 ### Large File Uploads