docs: update documentation for resolved issues (#25)

Updated documentation to reflect completed fixes:

1. FUTURE-WORK.md:
   - Moved conversation sorting & title fixes to "Recently Completed"
   - Added technical details and PR references
   - Updated coverage stats (63.29%)

2. conversation-sorting-rearranges-on-selection.md:
   - Added complete resolution section documenting PR #24
   - Explained the three-location bug (saveConversation, handleLoadConversation, auto-save effect)
   - Documented the root cause: auto-save effect dependency on currentConversationId
   - Added solution with code examples

3. conversation-title-not-updating-in-ui.md:
   - Updated status to RESOLVED with PR #22 reference
   - Clarified root cause: component display logic, not state management
   - Added test count (511 tests passing)

4. conversation-title.test.tsx:
   - Changed BUG comment to "Fixed" since issue is resolved

All issues documented as resolved with proper cross-references.

Author: flegaspi700

FUTURE-WORK.md

@@ -1,8 +1,36 @@
 # Future Work & Known Issues
 
-## ✅ Recently Completed (Oct 20, 2025)
+## ✅ Recently Completed (November 4, 2025)
 
-### CI/CD Pipeline & Code Quality
+### Conversation Sorting & Management Fixes
+**Status**: ✅ COMPLETE  
+**What We Fixed**:
+- ✅ Conversation sorting stability - lists no longer rearrange when selecting conversations
+- ✅ Pin/Star feature - keep important conversations at the top
+- ✅ Conversation title UI bug - titles update immediately without page refresh
+- ✅ Empty conversation saving - create and name conversations before adding content
+
+**Technical Details**:
+- **Root Cause**: Three locations where `saveConversation()` was updating timestamps during loads:
+  1. `saveConversation()` function itself - added `updateTimestamp` parameter (PR #23)
+  2. `handleLoadConversation()` - now uses `updateTimestamp: false`
+  3. Auto-save effect - removed `currentConversationId` from dependencies
+- **Pin Feature**: Added `isPinned` field with visual distinction and toggle functionality
+- **Tests**: 8 new TDD tests for sorting/pinning, all 532 tests passing ✅
+- **Coverage**: Improved to 63.29% (statements)
+
+**Related PRs**:
+- PR #23 - `feat/conversation-sorting-and-pinning`
+- PR #24 - `fix/auto-save-timestamp-complete`
+- PR #22 - `fix/conversation-title-ui-update`
+
+**Documentation**:
+- `docs/04-development/issues/conversation-sorting-rearranges-on-selection.md`
+- `docs/04-development/issues/conversation-title-not-updating-in-ui.md`
+
+---
+
+### CI/CD Pipeline & Code Quality (Oct 20, 2025)
 **Status**: ✅ COMPLETE  
 **What We Fixed**:
 - ✅ CI/CD pipeline with automated checks (ESLint, Jest, builds)
@@ -13,12 +41,6 @@
 - ✅ Adjusted coverage thresholds to match actual coverage (51%/51%/44%)
 - ✅ Resolved merge conflicts with main branch
 
-**Coverage Thresholds**:
-- Statements: 51% (actual: 51.2%)
-- Lines: 51% (actual: 51.2%)
-- Branches: 65% (actual: 65.6%)
-- Functions: 44% (actual: 44.9%)
-
 **Related Commits**:
 - `4f49ecd` - ESLint fixes and font optimization
 - `efe1acd` - Coverage threshold adjustment

docs/04-development/issues/conversation-sorting-rearranges-on-selection.md

@@ -1,29 +1,41 @@
 # Issue: Conversation Sorting Rearranges When Selected
 
-**Status:** ✅ RESOLVED  
+**Status:** ✅ RESOLVED (November 4, 2025)  
 **Priority:** Medium  
 **Date Reported:** November 4, 2025  
 **Date Resolved:** November 4, 2025  
-**Branch:** feat/conversation-sorting-and-pinning  
-**Tests:** 8 new tests, all 519 tests passing ✅
+**Related PRs:**
+- PR #23 - `feat/conversation-sorting-and-pinning` (Initial fix)
+- PR #24 - `fix/auto-save-timestamp-complete` (Complete fix)
+**Tests:** 8 new TDD tests, all 532 tests passing ✅
 
 ## Problem Description
 
 The conversation history list constantly rearranges when a conversation is selected. This makes it difficult to find and navigate between conversations because the list order keeps changing based on which conversation was last accessed.
 
-## Current Behavior
+## Current Behavior (FIXED)
 
-When you click on a conversation in the sidebar:
+**Before Fix:**
+When you clicked on a conversation in the sidebar:
 1. The conversation loads correctly
 2. The `updatedAt` timestamp is updated to current time
 3. `loadConversations()` sorts by `updatedAt` descending
 4. The selected conversation jumps to the top of the list
 5. All other conversations shift down
 
-**Result:** The list constantly reshuffles, making navigation confusing.
+**After Fix:**
+When you click on a conversation:
+1. The conversation loads correctly
+2. The `updatedAt` timestamp is **NOT** updated
+3. The list order remains stable
+4. The selected conversation stays in its position ✅
+
+Timestamps are now only updated when you send a new message.
 
 ## Root Cause
 
+Found **THREE** locations where `saveConversation()` was incorrectly updating timestamps:
+
 **File:** `src/lib/storage.ts`
 
 ### saveConversation() - Lines 207-225
@@ -371,6 +383,71 @@ className={`
 2. **Loading vs Saving:** Loading an existing conversation shouldn't update its timestamp
 3. **TDD Success:** Writing tests first helped design the API correctly (`updateTimestamp` parameter)
 4. **Migration-Friendly:** `isPinned ?? false` ensures backwards compatibility with existing conversations
+5. **Three-Location Bug:** Issue persisted because fixes were applied piecemeal - needed to fix all three:
+   - ✅ `saveConversation()` function itself
+   - ✅ `handleLoadConversation()` call site
+   - ✅ Auto-save effect dependencies (the main culprit)
+
+---
+
+## Complete Resolution (November 4, 2025)
+
+### The Final Fix - PR #24: `fix/auto-save-timestamp-complete`
+
+After PR #23 was merged, the issue **still persisted**. Investigation revealed the auto-save effect was the main culprit:
+
+**Problem:** Auto-save effect depended on `currentConversationId`
+```typescript
+// BEFORE (BUGGY):
+useEffect(() => {
+  // ... save conversation ...
+}, [messages, files, aiTheme, currentConversationId, isLoaded]); // ❌ currentConversationId triggers effect
+```
+
+**What happened:**
+1. User clicks conversation → `handleLoadConversation()` called
+2. `setCurrentConversationId(conversation.id)` → **triggers effect**
+3. Effect runs and calls `saveConversation()` without `false`
+4. Timestamp updates, conversation jumps to top
+
+**Solution:** Remove `currentConversationId` from dependencies
+```typescript
+// AFTER (FIXED):
+useEffect(() => {
+  if (isLoaded && !isLoadingConversationRef.current) {
+    if (messages.length > 0) { // Only save when there's content
+      if (!currentConversationId) {
+        // New conversation
+        saveConversation(conversation);
+      } else {
+        // Existing conversation - don't update timestamp
+        saveConversation(conversation, false);
+      }
+    }
+  }
+}, [messages, files, aiTheme, isLoaded]); // ✅ No currentConversationId
+```
+
+**Explicit timestamp update** added when user sends messages:
+```typescript
+onComplete: (fullText) => {
+  const aiMessage: Message = { id: aiMessageId, role: 'ai', content: fullText };
+  setMessages((prev) => [...prev, aiMessage]);
+  
+  // Update timestamp when conversation actually changes
+  if (currentConversationId) {
+    const conversation = createConversation([...messages, userMessage, aiMessage], files, aiTheme, conversationTitleRef.current);
+    conversation.id = currentConversationId;
+    saveConversation(conversation, true); // ✅ Explicitly update timestamp
+  }
+}
+```
+
+**Test Results:**
+- All 532 tests passing ✅
+- Manual testing: Conversations stay in place when selected ✅
+- Manual testing: Conversations move to top when new message sent ✅
+- Browser localStorage cache needed to be cleared for existing users
 
 ---
 

docs/04-development/issues/conversation-title-not-updating-in-ui.md

@@ -1,36 +1,38 @@
 # Issue: Conversation Title Not Updating in UI
 
-**Status:** ✅ RESOLVED  
+**Status:** ✅ RESOLVED (November 4, 2025)  
 **Priority:** High  
 **Date Reported:** November 2, 2025  
 **Date Resolved:** November 4, 2025  
 **Original Branch:** feat/save-empty-conversations  
 **Fix Branch:** fix/conversation-title-ui-update  
-**Commit:** a1dd36c
+**PR:** #22
+**Commit:** a1dd36c  
+**Tests:** 3 new TDD tests added, all 511 tests passing ✅
 
 ## Problem Description
 
 When updating a conversation title or loading a conversation from history, the title displays correctly in the sidebar conversation history but does NOT update in the main header until a full page refresh.
 
-## Steps to Reproduce
+**Root Cause:** Component display logic, not state management. The `ConversationTitle` component was overriding the title prop with "New Conversation" when `messages.length === 0`, even though the parent was passing the correct custom title.
+
+## Steps to Reproduce (FIXED)
 
 ### Scenario 1: New Conversation Title Update
 1. Click "New Conversation" button
 2. Click "Edit conversation title" button
 3. Change title to "Research 1"
 4. Click save (checkmark button)
-5. **Expected:** Header shows "Research 1"
-6. **Actual:** Header still shows "New Conversation"
-7. Title shows correctly in sidebar history
-8. Full page refresh (Ctrl+R) shows correct title
+5. **Expected:** Header shows "Research 1" ✅ NOW WORKS
+6. **Before:** Header still shows "New Conversation" ❌
+7. Title shows correctly in sidebar history ✅
 
 ### Scenario 2: Load Existing Conversation
 1. Have existing conversation titled "Test 5"
 2. Click on "Test 5" in conversation history sidebar
-3. **Expected:** Header shows "Test 5"
-4. **Actual:** Header still shows "New Conversation" (or previous title)
-5. Title shows correctly in sidebar history
-6. Full page refresh (Ctrl+R) shows correct title
+3. **Expected:** Header shows "Test 5" ✅ NOW WORKS
+4. **Before:** Header still shows "New Conversation" (or previous title) ❌
+5. Title shows correctly in sidebar history ✅
 
 ## Current Implementation
 

src/__tests__/components/conversation-title.test.tsx

@@ -426,7 +426,7 @@ describe('ConversationTitle', () => {
 
   describe('Custom Title Display (Bug Fix)', () => {
     it('displays custom title even when isNewConversation is true and has no messages', () => {
-      // BUG: When a new conversation gets a custom title but has no messages yet,
+      // Fixed: When a new conversation gets a custom title but has no messages yet,
       // it should show the custom title, not "New Conversation"
       render(<ConversationTitle {...defaultProps} title="My Custom Title" isNewConversation={true} />);