diff --git a/HANDOFF-MERGE.md b/HANDOFF-MERGE.md
new file mode 100644
index 000000000..ba327feb6
--- /dev/null
+++ b/HANDOFF-MERGE.md
@@ -0,0 +1,427 @@
+# 🚀 HANDOFF: API Keys Refactor - Ready to Merge
+
+**Date:** January 17, 2026
+**Branch:** `feature/api-keys-refactor`
+**Status:** ✅ Ready for merge to `main`
+**Working Tree:** Clean (verified)
+**Commits:** 13 commits ahead of main
+
+---
+
+## ✅ Pre-Merge Verification
+
+```bash
+# Verify current location
+pwd
+# Should be: /home/blitzkriegfc/Personal/qbz/qbz-worktrees/feature-api-keys-refactor
+
+# Verify branch
+git branch
+# Should show: * feature/api-keys-refactor
+
+# Verify clean state
+git status
+# Should show: nothing to commit, working tree clean
+
+# Verify commits ready
+git log --oneline origin/main..HEAD
+# Should show 13 commits
+```
+
+**All checks passed:** ✅
+
+---
+
+## 📋 Commits to Merge (13 total)
+
+```
+34ab753 Add post-merge cleanup instructions for API Keys UI
+7d07f9a Add merge preparation documentation
+81b65bd Add comprehensive CHANGELOG for API keys refactor
+80ba2bf Fix Discogs artwork selection UI issues
+732a489 Improve Discogs artwork selection with multi-release images
+279d433 Add catalog number support for precise Discogs searches
+2a5c181 Fix Discogs artwork selection to show unique images
+dab5c28 Add Discogs artwork selection UI in album edit modal
+dd70f0a Refactor Discogs integration to use Cloudflare Workers proxy
+9099123 Refactor Spotify and Tidal playlist import to use proxy
+179a6b7 Refactor Last.fm integration to use Cloudflare Workers proxy
+3a49e3f Remove embedded Last.fm API secret for Flathub compliance
+b7048fa feat: register qbz:// URI scheme for OAuth callbacks
+```
+
+---
+
+## 🎯 Merge Commands (Copy & Paste)
+
+### Step 1: Ensure you're in the main worktree
+```bash
+cd /home/blitzkriegfc/Personal/qbz/qbz-nix
+```
+
+### Step 2: Ensure main is up to date
+```bash
+git checkout main
+git pull origin main
+```
+
+### Step 3: Merge feature branch (no fast-forward for clean history)
+```bash
+git merge --no-ff feature/api-keys-refactor -m "Merge feature/api-keys-refactor: Remove embedded API keys and add Discogs artwork selector
+
+This major refactor achieves Flathub compliance by removing all embedded
+API credentials from the binary. All API requests now go through a
+Cloudflare Workers proxy for secure credential management.
+
+New Features:
+- Discogs artwork selection UI with multi-release support
+- Catalog number support for audiophile libraries
+- Carousel navigation for artwork options
+- Release metadata display (title, year)
+
+Technical Changes:
+- Cloudflare Workers proxy for Last.fm, Spotify, Tidal, Discogs
+- Database migration adds catalog_number column
+- URI scheme registration (qbz://) for OAuth flows
+- Rate limiting and User-Agent validation server-side
+
+See CHANGELOG-api-keys-refactor.md for complete details.
+See POST-MERGE-CLEANUP.md for removing legacy API Keys UI."
+```
+
+### Step 4: Resolve conflicts (if any)
+```bash
+# If conflicts occur (likely in SettingsView.svelte due to audio config changes)
+git status
+# Check which files have conflicts
+
+# For each conflicted file:
+# 1. Open in editor
+# 2. Look for <<<<<<< HEAD markers
+# 3. Keep BOTH changes (main's audio config + feature's other changes)
+# 4. Remove conflict markers
+# 5. git add <file>
+
+# After resolving all conflicts:
+git merge --continue
+```
+
+### Step 5: Push to origin
+```bash
+git push origin main
+```
+
+### Step 6: Tag the release
+```bash
+git tag -a v1.2.0 -m "API Keys Refactor - Flathub Compliance
+
+Major changes:
+- Removed all embedded API credentials
+- Added Cloudflare Workers proxy for credential management
+- Added Discogs artwork selection UI
+- Added catalog number support
+- Database migration for catalog_number column
+- Flathub submission now possible"
+
+git push origin v1.2.0
+```
+
+### Step 7: Cleanup (optional - can keep branch for reference)
+```bash
+# Delete local feature branch (optional)
+git branch -d feature/api-keys-refactor
+
+# Delete remote feature branch (optional)
+git push origin --delete feature/api-keys-refactor
+
+# Remove worktree (optional)
+git worktree remove /home/blitzkriegfc/Personal/qbz/qbz-worktrees/feature-api-keys-refactor
+```
+
+---
+
+## 🧪 Post-Merge Testing Checklist
+
+### Critical Tests (Must Pass)
+- [ ] App launches without errors
+- [ ] Database migration runs (check logs for catalog_number column)
+- [ ] Last.fm login works
+- [ ] Last.fm scrobbling works
+- [ ] Spotify playlist import works
+- [ ] Tidal playlist import works
+- [ ] Discogs artwork search works
+- [ ] Discogs carousel navigation works (4+ images)
+- [ ] Artwork save works (select image → Save)
+- [ ] Settings view intact (audio config + other sections)
+
+### Regression Tests (Should Still Work)
+- [ ] Audio playback
+- [ ] Local library scanning
+- [ ] Album/Artist browsing
+- [ ] Search functionality
+- [ ] Playlist management
+- [ ] Downloads
+
+### Open browser DevTools and check console for:
+- [ ] No errors on startup
+- [ ] No errors when fetching Discogs artwork
+- [ ] Logs show: "Downloading Discogs artwork from: ..."
+- [ ] Logs show: "Downloaded to: ..."
+- [ ] Logs show: "Set album artwork successfully"
+
+---
+
+## 📊 What Changed - Quick Summary
+
+### 🔐 Security & Compliance
+- ❌ Removed Last.fm API secret from binary
+- ❌ Removed Spotify credentials from binary
+- ❌ Removed Tidal credentials from binary
+- ❌ Removed Discogs credentials from binary
+- ✅ Cloudflare Workers proxy handles all credentials
+- ✅ Flathub submission now possible
+
+### ✨ New Features
+1. **Discogs Artwork Selector**
+   - Visual UI in album edit modal
+   - Multi-release support (4 images from top 2 releases)
+   - Carousel navigation (4 per page)
+   - Shows release title and year
+   - Smart search (uses catalog number if available)
+
+2. **Catalog Number Support**
+   - Reads from audio file tags (CATALOGNUMBER field)
+   - Stored in database
+   - Displayed in UI ("Cat# XXXXX")
+   - Prioritized in Discogs searches
+
+### 🔧 Technical
+- Cloudflare Workers proxy deployed: `https://qbz-api-proxy.blitzkriegfc.workers.dev`
+- Database migration adds `catalog_number` column (automatic, non-destructive)
+- URI scheme `qbz://` registered for OAuth
+- ~715 lines of legacy code documented for removal (POST-MERGE-CLEANUP.md)
+
+---
+
+## ⚠️ Known Issues
+
+### 1. Discogs 429 Rate Limits
+- **Severity:** Low
+- **Frequency:** Occasional (when fetching detailed release info)
+- **Impact:** User must retry after a few seconds
+- **Status:** Acceptable (transient error)
+- **User Experience:** Works on retry
+
+### 2. API Keys UI Still Visible
+- **Why:** Legacy code, avoids conflicts with audio config changes
+- **Status:** Documented for removal
+- **Action:** Follow `POST-MERGE-CLEANUP.md` after merge
+- **Note:** UI accepts input but credentials are ignored (all goes through proxy)
+
+---
+
+## 📄 Important Documentation Files
+
+### 1. CHANGELOG-api-keys-refactor.md
+**Location:** `/home/blitzkriegfc/Personal/qbz/qbz-worktrees/feature-api-keys-refactor/CHANGELOG-api-keys-refactor.md`
+
+**Contains:**
+- Complete list of all changes
+- Security improvements details
+- New features with user benefits
+- Technical architecture changes
+- Database migrations
+- Testing notes
+- Breaking changes (none for users)
+- Deployment requirements
+
+**Read this:** Before announcing release to users
+
+---
+
+### 2. MERGE-PREP.md
+**Location:** `/home/blitzkriegfc/Personal/qbz/qbz-worktrees/feature-api-keys-refactor/MERGE-PREP.md`
+
+**Contains:**
+- Pre-merge checklist (all ✅)
+- Merge strategy recommendations
+- Post-merge testing plan
+- Rollback procedures
+- Release notes template
+- Success criteria
+
+**Read this:** Before doing the merge (you're reading the HANDOFF now, so this is optional)
+
+---
+
+### 3. POST-MERGE-CLEANUP.md
+**Location:** `/home/blitzkriegfc/Personal/qbz/qbz-worktrees/feature-api-keys-refactor/POST-MERGE-CLEANUP.md`
+
+**Contains:**
+- Step-by-step instructions to remove API Keys UI
+- 11 files to modify with line numbers
+- Before/after code examples
+- Verification steps
+- Git commit message template
+- Estimated 30-45 minutes to complete
+
+**Read this:** After merge, when ready to clean up legacy code
+
+---
+
+## 🌐 Cloudflare Workers Proxy
+
+**Status:** ✅ Deployed and operational
+**URL:** `https://qbz-api-proxy.blitzkriegfc.workers.dev`
+**Repository:** `/home/blitzkriegfc/Personal/qbz/qbz-api-proxy`
+
+**Endpoints Active:**
+- Last.fm: `/lastfm/*`
+- Spotify: `/spotify/token`, `/spotify/refresh`
+- Tidal: `/tidal/token`, `/tidal/refresh`
+- Discogs: `/discogs/search`, `/discogs/release/{id}`, `/discogs/image`
+
+**Test Proxy:**
+```bash
+curl https://qbz-api-proxy.blitzkriegfc.workers.dev
+# Should return: {"service":"QBZ API Proxy","version":"1.0.0",...}
+```
+
+---
+
+## 🎉 Release Notes Template
+
+```markdown
+## QBZ v1.2.0 - API Keys Refactor & Discogs Enhancement
+
+### 🔐 Security & Flathub Compliance
+We've completely removed all embedded API credentials from the application.
+All API requests now go through a secure Cloudflare Workers proxy, making
+QBZ ready for Flathub submission and improving overall security.
+
+### ✨ New Features
+
+**Discogs Artwork Selector**
+Browse and select album artwork directly from Discogs! The new visual selector
+shows multiple release variants with metadata, making it easy to find the
+perfect cover for your albums.
+
+- 🎨 Visual artwork browser in album edit modal
+- 🖼️ See images from different release variants
+- 📄 Navigate with carousel (4 images per page)
+- 📋 View release titles and years
+- 🏷️ Smart search using catalog numbers
+
+**Catalog Number Support**
+For audiophile and collector libraries with professional tagging:
+- Automatically reads catalog numbers from audio file tags
+- Displays in album details (e.g., "Cat# MFSL 1-395")
+- Prioritized in Discogs searches for precise results
+
+### 🔧 Technical Improvements
+- Cloudflare Workers proxy for all external APIs
+- Database migration adds catalog_number support
+- Improved error handling and logging
+- Rate limiting and validation server-side
+
+### 🐛 Known Issues
+- Occasional 429 rate limit errors from Discogs (retry after a few seconds)
+
+### 🙏 Thanks
+Special thanks to all users who requested catalog number support!
+```
+
+---
+
+## 🔄 Rollback Plan (If Needed)
+
+If critical issues found after merge:
+
+```bash
+# Find the merge commit
+git log --oneline -10
+
+# Revert the merge (safest option)
+git revert -m 1 <merge-commit-hash>
+git push origin main
+
+# OR hard reset (use with EXTREME caution)
+git reset --hard <commit-before-merge>
+git push --force origin main
+```
+
+---
+
+## 📞 Support Checklist
+
+If users report issues after release:
+
+1. **Proxy Down**
+   - Check: https://qbz-api-proxy.blitzkriegfc.workers.dev
+   - Verify Cloudflare Workers dashboard
+   - Check environment variables are set
+
+2. **Database Migration Failed**
+   - Check app logs for migration errors
+   - May need manual `ALTER TABLE local_tracks ADD COLUMN catalog_number TEXT;`
+
+3. **API Integration Broken**
+   - Check proxy is responding
+   - Verify User-Agent is "QBZ/1.0.0"
+   - Check rate limits not exceeded
+
+4. **UI Issues**
+   - Clear browser cache
+   - Check browser console for errors
+   - Verify Settings changes don't conflict with audio config
+
+---
+
+## ✅ Final Verification Before Merge
+
+```bash
+# You are here
+pwd
+# → /home/blitzkriegfc/Personal/qbz/qbz-worktrees/feature-api-keys-refactor
+
+# Branch is clean
+git status
+# → nothing to commit, working tree clean ✅
+
+# All commits ready
+git log --oneline origin/main..HEAD | wc -l
+# → 13 ✅
+
+# Proxy is up
+curl -s https://qbz-api-proxy.blitzkriegfc.workers.dev | grep service
+# → "service":"QBZ API Proxy" ✅
+
+# Ready to merge!
+```
+
+---
+
+## 🎯 Next Steps After Merge
+
+1. ✅ **Immediate:** Test all integrations (checklist above)
+2. 📢 **Within 24h:** Announce release with release notes
+3. 🧹 **When convenient:** Follow `POST-MERGE-CLEANUP.md` to remove API Keys UI
+4. 🚀 **Future:** Submit to Flathub!
+
+---
+
+## 📝 Notes
+
+- Feature branch can be kept for reference or deleted
+- Worktree can remain or be removed
+- CHANGELOG files will be in main after merge
+- No user data affected by this merge
+- All changes are backward compatible
+
+---
+
+**Prepared by:** Claude Sonnet 4.5
+**Handoff Date:** January 17, 2026
+**Status:** ✅ READY TO MERGE
+
+🚀 **You're all set! Just run the merge commands above.**