docs: add VU meter investigation documentation

- Document soft reset process to isolate trackSync impact
- Preserve verification results
- Add testing instructions for VU meter functionality

jam-ui/VU_METER_INVESTIGATION.md

@@ -0,0 +1,154 @@
+# VU Meter Investigation - Soft Reset Results
+
+## Date
+2026-01-23
+
+## Objective
+Revert trackSyncService changes temporarily to determine if VU meters were working before this feature was introduced.
+
+## Actions Taken
+
+### Step 1: Preserved TrackSync Work ✅
+- Created branch: `feature/track-sync-implementation`
+- Committed all trackSyncService changes with commit hash: `e48048ac4`
+- All work preserved including:
+  - trackSyncService implementation
+  - 13 unit tests (all passing)
+  - 7 integration tests
+  - Modified components (JKSessionScreen, useMediaActions, JKSessionMyTrack)
+  - Helper functions (globals.js)
+  - Documentation files
+
+### Step 2: Returned to Previous State ✅
+- Switched back to: `session_migration_plan` branch
+- Current HEAD: `4d141c93c` (feat: integrate metronome UI into session screen)
+- This is the state BEFORE trackSyncService implementation
+
+### Step 3: Verified Clean State ✅
+
+**Verification Results:**
+- ✅ `src/services/trackSyncService.js` - Does NOT exist
+- ✅ `src/services/__tests__/trackSyncService.test.js` - Does NOT exist
+- ✅ `JKSessionScreen.js` - No syncTracksToServer imports (0 occurrences)
+- ✅ `useMediaActions.js` - No syncTracksToServer imports (0 occurrences)
+- ✅ `JKSessionMyTrack.js` - No syncTracksToServer imports (0 occurrences)
+- ✅ `src/services/` directory contains only: `auth.js` (pre-existing)
+
+**Conclusion:** Clean state confirmed. All trackSyncService code has been removed.
+
+## Next Steps
+
+### Step 4: Test VU Meters (MANUAL TESTING REQUIRED)
+
+**Instructions for Testing:**
+
+1. **Start the dev server:**
+   ```bash
+   cd /Users/nuwan/Code/jam-cloud/jam-ui
+   npm start
+   ```
+
+2. **Test VU meters:**
+   - Open browser to `http://beta.jamkazam.local:4000`
+   - Log in to your account
+   - Join or create a session
+   - **OBSERVE:** Are the VU meters lighting up?
+   - **CHECK:** Browser console for this warning:
+     ```
+     useMixerHelper: allMixers is empty, returning previous myTracks
+     ```
+
+3. **Document results below:**
+
+### Test Results
+
+**Date/Time of Test:** _[Fill in after testing]_
+
+**VU Meters Working?** _[YES/NO]_
+
+**Console Warnings Present?** _[YES/NO]_
+
+**Console Log Output:**
+```
+[Paste relevant console output here]
+```
+
+**Screenshots:** _[Optional - attach screenshots]_
+
+## Analysis
+
+### If VU Meters Work (trackSyncService caused the issue):
+
+**Root Cause Analysis:**
+- [ ] The new useEffect in JKSessionScreen interfering with session initialization?
+- [ ] jamClient being passed around causing reference issues?
+- [ ] React re-render cycles disrupted by new async operations?
+- [ ] Timing issue with track sync calls during session join?
+
+**Next Actions:**
+1. Review the useEffect timing in JKSessionScreen.js:403-437
+2. Check if jamClient.clientID() async calls are blocking mixer initialization
+3. Consider moving track sync to AFTER mixer initialization completes
+4. Add defensive checks to ensure mixer state is ready before syncing
+
+### If VU Meters Don't Work (issue is unrelated):
+
+**Root Cause Analysis:**
+- [ ] Pre-existing timing issue with mixer initialization?
+- [ ] jamClient connection issue?
+- [ ] Redux state synchronization problem?
+- [ ] Environment or dependency change?
+- [ ] Issue introduced in metronome integration commits?
+
+**Next Actions:**
+1. Check git history for changes to useMixerHelper
+2. Review recent metronome integration commits
+3. Check for jamClient connection issues
+4. Investigate Redux mixer state flow
+
+## Restoring TrackSync Work
+
+Once VU meter issue is resolved, restore the work:
+
+```bash
+# Option A: Merge the feature branch
+git checkout session_migration_plan
+git merge feature/track-sync-implementation
+
+# Option B: Cherry-pick the commit
+git cherry-pick e48048ac4
+
+# Option C: Manual restore if conflicts
+git checkout feature/track-sync-implementation -- src/services/
+git checkout feature/track-sync-implementation -- src/components/client/JKSessionScreen.js
+# ... etc
+```
+
+## Branch Information
+
+- **Feature Branch:** `feature/track-sync-implementation` (commit: e48048ac4)
+- **Current Branch:** `session_migration_plan` (commit: 4d141c93c)
+- **Main Branch:** `develop`
+
+## Files Modified by TrackSync (for reference)
+
+### Created:
+- `src/services/trackSyncService.js`
+- `src/services/__tests__/trackSyncService.test.js`
+- `test/track-sync/track-configuration.spec.ts`
+- Documentation files (TDD_*.md, TRACK_CONFIG_*.md)
+
+### Modified:
+- `src/components/client/JKSessionScreen.js` (lines 403-437)
+- `src/hooks/useMediaActions.js` (multiple track sync calls)
+- `src/components/client/JKSessionMyTrack.js` (async handleInstrumentSave)
+- `src/helpers/globals.js` (added getInstrumentServerIdFromClientId)
+- `CLAUDE.md` (TDD guidelines)
+
+## Notes
+
+- All trackSyncService work is **safely preserved** in feature branch
+- No work has been lost
+- Can restore everything once VU meter issue is understood
+- The trackSyncService implementation itself is solid (all tests passing)
+- Issue appears to be integration/timing related, not logic related