diff --git a/CLAUDE.md b/CLAUDE.md
index cb789c6..e8194d8 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -370,6 +370,75 @@ const onSubmit = form.handleSubmit(async (values) => {
 <Button :disabled="!isFormValid">Submit</Button>
 ```
 
+### **Vue Reactivity Best Practices**
+
+**CRITICAL: Handling Complex Object Reactivity**
+
+When working with complex objects from API responses or services, Vue's reactivity system may not always detect changes properly. This is especially common with nested objects or objects from external sources.
+
+**Common Reactivity Issues:**
+- Input components not updating when object properties change
+- Template not re-rendering after API responses
+- Computed properties not recalculating
+
+**✅ SOLUTIONS:**
+
+**1. Force Object Reactivity with Object.assign:**
+```typescript
+// ❌ DON'T: Direct assignment may not trigger reactivity
+createdObject.value = apiResponse
+
+// ✅ DO: Create new object reference to ensure reactivity
+createdObject.value = Object.assign({}, apiResponse)
+```
+
+**2. Force Component Re-render with Dynamic Keys:**
+```vue
+<!-- ❌ DON'T: Component may not update with new data -->
+<Input :value="object.property" readonly />
+
+<!-- ✅ DO: Force re-render with dynamic key -->
+<Input
+  :key="`field-${object?.id}`"
+  :model-value="object?.property || ''"
+  readonly
+/>
+```
+
+**3. Use Safe Navigation and Fallbacks:**
+```vue
+<!-- ✅ Prevent errors and ensure consistent data types -->
+<Input
+  :model-value="object?.property || ''"
+  :key="`field-${object?.uniqueId}`"
+  readonly
+/>
+```
+
+**When to Apply These Patterns:**
+- ✅ API responses stored in reactive refs
+- ✅ Complex objects from services
+- ✅ Input components showing external data
+- ✅ Any scenario where template doesn't update after data changes
+
+**Example from Wallet Module:**
+```typescript
+// Service returns complex invoice object
+const invoice = await walletService.createInvoice(data)
+
+// Force reactivity for template updates
+createdInvoice.value = Object.assign({}, invoice)
+```
+
+```vue
+<!-- Template with forced reactivity -->
+<Input
+  :key="`bolt11-${createdInvoice?.payment_hash}`"
+  :model-value="createdInvoice?.payment_request || ''"
+  readonly
+/>
+```
+
 ### **Module Development Best Practices**
 
 **Module Structure Requirements:**