dictation-service/docs/MIGRATION_GUIDE.md

# Migration Guide - Updated Features

## Summary of Changes

This update introduces significant UX improvements based on user feedback:

### ✅ Changes Made

1. **Dictation Mode: System Tray Icon Instead of Notifications**
   - **Old:** System notifications for every dictation start/stop/status
   - **New:** Clean system tray icon that changes based on state
   - **Benefit:** No more notification spam, cleaner UX

2. **Read-Aloud: Middle-Click Instead of Automatic**
   - **Old:** Automatic reading of all highlighted text via system tray service
   - **New:** On-demand reading via middle-click on selected text
   - **Benefit:** More control, less annoying, works on-demand only

3. **Conversation Mode: Unchanged**
   - Still works with Super+Alt+D (Windows+Alt+D)
   - Still maintains persistent context across calls
   - Still sends notifications (intentionally kept for this feature)

## Migration Steps

### 1. Update the Dictation Service

The main dictation service now includes a system tray icon:

```bash
# Stop the old service
systemctl --user stop dictation.service

# Restart with new code (already updated)
systemctl --user restart dictation.service
```

**What to expect:**
- A microphone icon will appear in your system tray
- Icon changes from "muted" (OFF) to "high" (ON) when dictating
- Click the icon to toggle dictation, or continue using Alt+D
- No more notifications when dictating

### 2. Remove Old Read-Aloud Service

The automatic read-aloud service has been replaced:

```bash
# Stop and disable old service
systemctl --user stop read-aloud.service 2>/dev/null || true
systemctl --user disable read-aloud.service 2>/dev/null || true

# Remove old service file
rm -f ~/.config/systemd/user/read-aloud.service

# Reload systemd
systemctl --user daemon-reload
```

### 3. Install New Middle-Click Reader

Set up the new on-demand read-aloud service:

```bash
# Run setup script
cd /mnt/storage/Development/dictation-service
./scripts/setup-middle-click-reader.sh
```

**What to expect:**
- No visible tray icon (runs in background)
- Highlight text anywhere
- Middle-click (press scroll wheel) to read it
- Only reads when you explicitly request it

### 4. Test Everything

**Test Dictation:**
1. Look for microphone icon in system tray
2. Press Alt+D or click the icon
3. Icon should change to "microphone-high"
4. Speak - text should type
5. Press Alt+D or click icon again to stop
6. No notifications should appear

**Test Read-Aloud:**
1. Highlight some text in a browser or editor
2. Middle-click on the highlighted text
3. It should be read aloud
4. Try highlighting different text and middle-clicking again

**Test Conversation (unchanged):**
1. Press Super+Alt+D
2. Should see "Conversation Started" notification (this is kept)
3. Speak with AI
4. Press Super+Alt+D to end

## Deprecated Files

These files have been renamed with `.deprecated` suffix and are no longer used:

- `read-aloud.service.deprecated` (old automatic service)
- `scripts/setup-read-aloud.sh.deprecated` (old setup script)
- `scripts/toggle-read-aloud.sh.deprecated` (old toggle script)
- `src/dictation_service/read_aloud_service.py.deprecated` (old implementation)

You can safely delete these files if desired.

## New Files

- `src/dictation_service/middle_click_reader.py` - New middle-click service
- `middle-click-reader.service` - Systemd service file
- `scripts/setup-middle-click-reader.sh` - Setup script

## Troubleshooting

### System Tray Icon Not Appearing

1. Make sure AppIndicator3 is installed:
   ```bash
   sudo apt-get install gir1.2-appindicator3-0.1
   ```

2. Check service logs:
   ```bash
   journalctl --user -u dictation.service -f
   ```

3. Some desktop environments need additional packages:
   ```bash
   # For GNOME Shell
   sudo apt-get install gnome-shell-extension-appindicator
   ```

### Middle-Click Not Working

1. Check if service is running:
   ```bash
   systemctl --user status middle-click-reader
   ```

2. Check logs:
   ```bash
   journalctl --user -u middle-click-reader -f
   ```

3. Test xclip manually:
   ```bash
   echo "test" | xclip -selection primary
   xclip -o -selection primary
   ```

4. Verify edge-tts is installed:
   ```bash
   edge-tts --list-voices | grep Christopher
   ```

### Notifications Still Appearing for Dictation

This means you might be running an old version of the code:

```bash
# Force restart the service
systemctl --user restart dictation.service

# Verify the new code is running
journalctl --user -u dictation.service -n 20 | grep "system tray"
```

## Rollback Instructions

If you need to revert to the old behavior:

```bash
# Restore old files (if you didn't delete them)
mv read-aloud.service.deprecated read-aloud.service
mv scripts/setup-read-aloud.sh.deprecated scripts/setup-read-aloud.sh
mv scripts/toggle-read-aloud.sh.deprecated scripts/toggle-read-aloud.sh

# Use git to restore old dictation code
git checkout HEAD~1 -- src/dictation_service/ai_dictation_simple.py

# Restart services
systemctl --user restart dictation.service
./scripts/setup-read-aloud.sh
```

## Benefits of New Approach

### Dictation
- ✅ No notification spam
- ✅ Visual status always visible in tray
- ✅ One-click toggle from tray menu
- ✅ Cleaner, less intrusive UX

### Read-Aloud
- ✅ Only reads when you want it to
- ✅ No background polling
- ✅ Lower resource usage
- ✅ Works everywhere (not just when service is "on")
- ✅ No accidental readings

## Questions?

Check the updated [AI_DICTATION_GUIDE.md](./AI_DICTATION_GUIDE.md) for complete usage instructions.