diff --git a/.trellis/spec/frontend/component-guidelines.md b/.trellis/spec/frontend/component-guidelines.md
index c9daf77..afec38f 100644
--- a/.trellis/spec/frontend/component-guidelines.md
+++ b/.trellis/spec/frontend/component-guidelines.md
@@ -157,6 +157,45 @@ Element Plus `el-table` (v1) and `el-table-v2` (virtualized) have completely dif
 
 When using new Element Plus components, verify required props - they will cause runtime errors if omitted.
 
+### 4. Vue 3 Template Ref Auto-Unwrap Gotchas
+
+Vue 3 `<script setup>` auto-unwraps refs in templates, but with important limitations:
+
+**Works - Top-level refs:**
+```typescript
+const count = ref(0);
+// Template: {{ count }} ✓ (auto-unwrapped)
+```
+
+**Broken - Refs nested in objects:**
+```typescript
+const virtualizer = useVirtualRows(...);
+// Template: {{ virtualizer.visibleRows }} ✗ (NOT auto-unwrapped)
+```
+
+**Fixed - Destructure refs for template use:**
+```typescript
+const virtualizer = useVirtualRows(...);
+const { visibleRows, totalHeight } = virtualizer;
+// Template: {{ visibleRows }} ✓ (auto-unwrapped top-level ref)
+```
+
+**TypeScript also fails** when refs are nested in objects - TypeScript sees `virtualizer.visibleRows` as type `ComputedRef | true | VirtualRow[]` instead of `VirtualRow[]`.
+
+**Rule**: Always destructure refs from composable return objects when they will be used directly in templates.
+
+### 5. Virtual Scrolling Overscan with Small Datasets
+
+Virtual scrolling with `overscan` may render ALL rows even when scrolled if:
+- Total row heights < viewport height + (overscan × average row height)
+- Dataset is small (e.g., 10 rows with 60px each = 600px total)
+
+With overscan=5 and 10 rows (600px total) and viewport 300px:
+- Overscan renders rows -5 to +5 from viewport edge
+- This covers all 10 rows regardless of scroll position
+
+This is NOT a bug - it's expected behavior. Virtual scrolling only culls rows when the dataset exceeds viewport + overscan capacity.
+
 ---
 
 ## Accessibility