docs: clarify peer id reuse safeguards (#27)

Author: zxch3n

pages/docs/concepts/peerid_management.mdx

@@ -41,6 +41,8 @@ doc.setPeerId("123123123");  // You can only set 64 bit integers as peer IDs
 
 ⚠️ **Warning**: Manual assignment requires careful conflict avoidance.
 
+If you intentionally reuse a Peer ID, persist the document's local data (snapshot, updates, or durable cache) alongside that ID and load it before fetching or applying any remote updates. This ensures the `(peerId, counter)` pairs continue to reference the same operations. Skipping this step risks generating a new operation that reuses an existing operation ID, which leads to inconsistent replicas.
+
 ## Counter System
 
 Each peer maintains a monotonic counter starting at 0:
@@ -65,6 +67,7 @@ console.log(doc.version()); // { "1": 2 }
 - Use user IDs as peer IDs, because an user can have multiple devices
 - Use fixed IDs
 - Reuse IDs without proper management
+- Allow multiple browser tabs or processes to operate on the same reused Peer ID in parallel—coordinate access with locks so that only one session emits operations for that ID at a time
 
 ## Related Documentation
 

pages/docs/tutorial/tips.mdx

@@ -20,6 +20,8 @@ from an identical baseline without generating unnecessary operations.
 
 When using `setPeerId`, you must avoid having two parallel peers use the same PeerId. This can cause serious consistency problems in your application.
 
+If you plan to reuse a PeerId across sessions, make sure that you persist the document's local state together with that PeerId and load it before applying any remote updates. Otherwise, the same `peerId + counter` combination could end up referring to two different operations, producing divergence that cannot be resolved automatically.
+
 <details>
 <summary>Why</summary>
 
@@ -34,6 +36,8 @@ Be careful when reusing PeerIds (this optimization is often unnecessary). You sh
 
 If you must reuse PeerIds, you need to carefully manage your local PeerId cache with proper locking mechanisms. This would allow only one tab to "take" a specific PeerId, while other tabs use random IDs. The PeerId should be returned to the cache when no longer in use.
 
+In addition to locking, avoid having multiple browser tabs (or apps on different processes) use the same PeerId concurrently. Coordinating access in this way ensures that a reused PeerId never emits two different operations with the same operation ID.
+
 </details>
 
 ---