1  # Local Testing Guide: Collaboration Handshake
  2  
  3  ## What We Built Today
  4  
  5  We've implemented the complete collaboration handshake system for DreamNode sharing via Radicle links. Here's what happens when you click a share link:
  6  
  7  ### Single Link Flow
  8  ```
  9  obsidian://interbrain-clone?id=rad:z123...&senderDid=did:key:z6Mk...&senderName=Alice
 10  ```
 11  
 12  **What happens automatically:**
 13  1. ✅ Clone DreamNode from Radicle network
 14  2. ✅ Automatically run `rad follow <SENDER_DID>` (enables update propagation)
 15  3. ✅ Create Dreamer node for "Alice" (if doesn't exist)
 16  4. ✅ Save Alice's DID to Dreamer node's `.udd` file
 17  5. ✅ Link cloned DreamNode to Alice's Dreamer node
 18  6. ✅ Focus on cloned DreamNode in liminal-web layout
 19  7. ✅ Alice appears as related node
 20  
 21  ### Batch Link Flow
 22  ```
 23  obsidian://interbrain-clone-batch?ids=rad:z123,rad:z456&senderDid=did:key:z6Mk...&senderName=Alice
 24  ```
 25  
 26  **What happens automatically:**
 27  1. ✅ Clone all DreamNodes from Radicle network
 28  2. ✅ Automatically follow Alice's DID once
 29  3. ✅ Create Dreamer node for "Alice" (if doesn't exist)
 30  4. ✅ Link ALL cloned DreamNodes to Alice's Dreamer node
 31  5. 🔄 **TODO**: Focus on Alice's Dreamer node (showing all shared nodes around her)
 32  
 33  ### Duplicate Detection
 34  - ✅ If Alice's Dreamer node already exists (detected by DID), reuse it
 35  - ✅ If DreamNode already cloned, skip and just focus it
 36  - ✅ Multiple links from same person → one Dreamer node
 37  
 38  ---
 39  
 40  ## How to Test Locally
 41  
 42  ### Setup (One Time)
 43  
 44  1. **Build the latest code:**
 45     ```bash
 46     cd /Users/davidrug/DreamGarden/InterBrain
 47     git pull origin main
 48     npm install
 49     npm run build
 50     ```
 51  
 52  2. **Reload InterBrain in Obsidian:**
 53     - Use Plugin Reloader hotkey, OR
 54     - Toggle InterBrain off/on in Settings
 55  
 56  3. **Verify Radicle is running:**
 57     ```bash
 58     rad node status
 59     # Should show "Running"
 60  
 61     # If not:
 62     rad node start
 63     ```
 64  
 65  4. **Add Radicle key to ssh-agent (CRITICAL for non-interactive operations):**
 66     ```bash
 67     # Add your Radicle key to ssh-agent
 68     ssh-add ~/.radicle/keys/radicle
 69     # You'll be prompted for passphrase ONCE
 70  
 71     # Verify it's loaded:
 72     ssh-add -l
 73     # Should show your Radicle key
 74     ```
 75  
 76     **Why this is needed**: InterBrain runs `rad init` and other commands non-interactively (from within Obsidian). Without ssh-agent, these commands fail with "please set `RAD_PASSPHRASE`" error.
 77  
 78  5. **Get your Radicle identity:**
 79     ```bash
 80     rad self --did
 81     # Example: did:key:z6MkxyzABC123...
 82  
 83     rad self --alias
 84     # Example: David
 85     ```
 86  
 87  ### Test Scenario 1: Generate Share Link
 88  
 89  1. **Select a DreamNode** in InterBrain
 90  2. **Run Command**: `Copy Share Link for Selected DreamNode`
 91     - Opens command palette (Cmd+P)
 92     - Type "Copy Share Link"
 93     - Press Enter
 94  
 95  3. **Check clipboard:**
 96     - Paste into a text editor
 97     - Should see: `obsidian://interbrain-clone?id=rad:z123...&senderDid=did:key:z6Mk...&senderName=YourName`
 98  
 99  4. **What happened behind the scenes:**
100     - Checked if node has Radicle ID
101     - If not, ran `rad init` automatically
102     - Generated link with your DID and name included
103  
104  ### Test Scenario 2: Single Link Handshake
105  
106  1. **Create a test link manually:**
107     ```
108     obsidian://interbrain-clone?id=rad:z32KcCXgBC7ijWnQA6cHU5Frm9QwW&senderDid=did:key:z6MktestABC&senderName=TestFriend
109     ```
110  
111  2. **Click the link in your browser**
112  
113  3. **Watch Obsidian console** (Cmd+Option+I → Console):
114     ```
115     🔗 [URIHandler] Single clone request
116     🤝 [URIHandler] Starting collaboration handshake for TestFriend
117     👤 [URIHandler] Creating new Dreamer node for TestFriend
118     ✅ [URIHandler] Saved DID to Dreamer node
119     🔗 [URIHandler] Linked "YourDreamNode" to "TestFriend"
120     ✅ [URIHandler] Collaboration handshake complete
121     ```
122  
123  4. **Verify in DreamSpace:**
124     - Cloned DreamNode should be selected
125     - In liminal-web layout, "TestFriend" Dreamer node should appear as related
126     - Select TestFriend node → should show connection to cloned node
127  
128  5. **Verify in file system:**
129     ```bash
130     cd /path/to/vault/TestFriend
131     cat .udd | grep radicleId
132     # Should show: "radicleId": "did:key:z6MktestABC"
133     ```
134  
135  ### Test Scenario 3: Duplicate Detection
136  
137  1. **Click the SAME link again**
138  
139  2. **Expected behavior:**
140     - "DreamNode already cloned" message
141     - Just focuses existing node
142     - Does NOT create duplicate Dreamer node
143     - TestFriend Dreamer node still has same DID
144  
145  3. **Verify:**
146     ```bash
147     # Should be only ONE TestFriend directory:
148     ls /path/to/vault | grep TestFriend
149     ```
150  
151  ### Test Scenario 4: Multiple Nodes from Same Person
152  
153  1. **Share TWO different DreamNodes** (using Copy Share Link command)
154  
155  2. **Send both links** to your test account (or paste in browser)
156  
157  3. **Click first link, then second link**
158  
159  4. **Expected behavior:**
160     - First click: Creates TestFriend Dreamer node
161     - Second click: Reuses SAME TestFriend Dreamer node
162     - Both DreamNodes linked to TestFriend
163  
164  5. **Verify in DreamSpace:**
165     - Select TestFriend → both cloned nodes appear as related
166  
167  ### Test Scenario 5: Batch Link
168  
169  1. **Create a batch link manually:**
170     ```
171     obsidian://interbrain-clone-batch?ids=rad:z123,rad:z456&senderDid=did:key:z6MktestABC&senderName=TestFriend
172     ```
173  
174  2. **Click the batch link**
175  
176  3. **Expected behavior:**
177     - Progress notification shows "Cloning 2 DreamNodes..."
178     - Both nodes clone sequentially
179     - TestFriend Dreamer node created once
180     - Both nodes linked to TestFriend
181     - 🔄 **Currently**: Last cloned node gets focus
182     - ✨ **Goal**: TestFriend Dreamer node gets focus (TODO)
183  
184  ---
185  
186  ## Testing Checklist
187  
188  - [ ] "Copy Share Link" command works
189  - [ ] Generated link includes your DID and name
190  - [ ] Clicking link clones node successfully
191  - [ ] Dreamer node created automatically
192  - [ ] DID saved to Dreamer node's .udd file
193  - [ ] Cloned node linked to Dreamer node
194  - [ ] Duplicate click doesn't recreate Dreamer node
195  - [ ] Multiple nodes from same person use same Dreamer node
196  - [ ] Batch link clones all nodes
197  - [ ] Batch link creates one Dreamer node for all
198  - [ ] Automatic peer following works (check console for "✅ Collaboration handshake complete")
199  
200  ---
201  
202  ## Debugging Tips
203  
204  ### If Dreamer node not created:
205  
206  Check console for errors:
207  ```
208  ❌ [URIHandler] Collaboration handshake failed
209  ```
210  
211  Common causes:
212  - Node creation failed (permissions?)
213  - .udd file couldn't be updated
214  - DreamNodeService not initialized
215  
216  ### If link doesn't include DID:
217  
218  Check console:
219  ```
220  ⚠️ [ShareLink] Could not get Radicle identity
221  ```
222  
223  Fixes:
224  ```bash
225  # Verify Radicle identity exists:
226  rad self --did
227  
228  # If not:
229  rad auth
230  ```
231  
232  ### If nodes not linking:
233  
234  Check console:
235  ```
236  ❌ [URIHandler] Failed to link nodes
237  ```
238  
239  Common causes:
240  - DreamSongRelationshipService error
241  - Git operations failed
242  - Node not found after clone
243  
244  ---
245  
246  ## What's Next
247  
248  ### Remaining Implementation:
249  1. **Batch focus behavior**: Focus on Dreamer node instead of last cloned node
250  2. **Better notifications**: Show Dreamer node name in success message
251  3. **Email export testing**: Test with actual email workflow
252  
253  ### Future Enhancements (Post-Test):
254  1. **Bidirectional handshake**: Receiver sends their DID back to sender
255  2. **Batch optimizations**: Parallel cloning instead of sequential
256  3. **Progress indicators**: Real-time progress for batch operations
257  4. **Conflict resolution**: Handle name collisions gracefully
258  
259  ---
260  
261  ## Success Criteria
262  
263  ✅ **Minimum Success:**
264  - Can generate share link with command
265  - Link includes DID and name
266  - Clicking link clones node
267  - Dreamer node created
268  - Nodes linked properly
269  
270  🎯 **Full Success:**
271  - All above, PLUS:
272  - Duplicate detection works
273  - Batch links work
274  - Focus behavior correct
275  - No console errors
276  
277  🌟 **Excellence:**
278  - All above, PLUS:
279  - Smooth UX, no lag
280  - Proper error handling
281  - Works on remote machine (tomorrow's test)
282  
283  ---
284  
285  ## Quick Reference Commands
286  
287  ```bash
288  # Build and reload
289  npm run build
290  
291  # Check Radicle status
292  rad node status
293  rad self --did
294  rad self --alias
295  
296  # View vault DreamNodes
297  ls /path/to/vault
298  
299  # Check .udd file
300  cat /path/to/vault/NodeName/.udd | jq '.'
301  
302  # Check relationships
303  cat /path/to/vault/NodeName/.udd | jq '.liminalWebRelationships'
304  
305  # Follow a peer manually (if automatic fails)
306  rad follow did:key:z6Mk...
307  ```
308