docs: clarify Electron build scripts vs development scripts

- Add comprehensive documentation explaining difference between development
  scripts (run app directly) and package build scripts (create executables)
- Update main README to reference new Electron build documentation
- Document all available Electron build commands with clear usage examples
- Clarify that AppImage, DEB, and DMG packages create standalone executables
- Update documentation dates to current (July 11, 2025)

docs/electron-build-scripts.md

@@ -0,0 +1,181 @@
+# Electron Build Scripts Guide
+
+**Author**: Matthew Raymer  
+**Date**: 2025-07-11  
+**Status**: **ACTIVE** - Production Ready
+
+## Overview
+
+This document clarifies the difference between Electron build scripts that create executable packages versus those that run the app directly.
+
+## Script Categories
+
+### 🚀 **Development Scripts (Run App Directly)**
+
+These scripts build the app and then run it immediately for development:
+
+```bash
+# Development mode - runs app directly
+npm run build:electron:dev
+
+# Test mode - runs app directly  
+npm run build:electron:test
+
+# Production mode - runs app directly
+npm run build:electron:prod
+```
+
+### 📦 **Package Build Scripts (Create Executables)**
+
+These scripts build executable packages that can be distributed and run by users:
+
+#### **Platform-Specific Executables**
+```bash
+# Windows executable (.exe)
+npm run build:electron:windows
+npm run build:electron:windows:dev
+npm run build:electron:windows:test
+npm run build:electron:windows:prod
+
+# macOS app bundle (.app)
+npm run build:electron:mac
+npm run build:electron:mac:dev
+npm run build:electron:mac:test
+npm run build:electron:mac:prod
+
+# Linux executable
+npm run build:electron:linux
+npm run build:electron:linux:dev
+npm run build:electron:linux:test
+npm run build:electron:linux:prod
+```
+
+#### **Package Formats**
+```bash
+# Linux AppImage (portable executable)
+npm run build:electron:appimage
+npm run build:electron:appimage:dev
+npm run build:electron:appimage:test
+npm run build:electron:appimage:prod
+
+# Linux DEB package (installable)
+npm run build:electron:deb
+npm run build:electron:deb:dev
+npm run build:electron:deb:test
+npm run build:electron:deb:prod
+
+# macOS DMG package (installable)
+npm run build:electron:dmg
+npm run build:electron:dmg:dev
+npm run build:electron:dmg:test
+npm run build:electron:dmg:prod
+```
+
+## Output Locations
+
+### **Development Scripts**
+- Run the app directly in development mode
+- No files created for distribution
+- App runs immediately after build
+
+### **Package Scripts**
+- Create executable files in `electron/dist/`
+- Files can be distributed to users
+- Users can run the executables by hand
+
+#### **Package Output Examples**
+```bash
+# AppImage
+electron/dist/TimeSafari-1.0.3-beta.AppImage
+
+# DEB package
+electron/dist/TimeSafari_1.0.3-beta_amd64.deb
+
+# DMG package
+electron/dist/TimeSafari-1.0.3-beta.dmg
+
+# Windows executable
+electron/dist/TimeSafari Setup 1.0.3-beta.exe
+```
+
+## Usage Examples
+
+### **Development Workflow**
+```bash
+# Start development (runs app directly)
+npm run build:electron:dev
+
+# Test with production build (runs app directly)
+npm run build:electron:test
+```
+
+### **Distribution Workflow**
+```bash
+# Build AppImage for Linux distribution
+npm run build:electron:appimage:prod
+
+# Build DMG for macOS distribution
+npm run build:electron:dmg:prod
+
+# Build Windows installer
+npm run build:electron:windows:prod
+```
+
+### **Testing Packages**
+```bash
+# Build test version of AppImage
+npm run build:electron:appimage:test
+
+# Test the generated executable
+./electron/dist/TimeSafari-1.0.3-beta.AppImage
+```
+
+## Key Differences
+
+| Script Type | Purpose | Output | User Action |
+|-------------|---------|--------|-------------|
+| Development | Run app directly | None | App starts automatically |
+| Package | Create executable | `electron/dist/` | User runs executable by hand |
+
+## Best Practices
+
+### **For Development**
+- Use `npm run build:electron:dev` for daily development
+- Use `npm run build:electron:test` for testing production builds
+- App runs immediately after build
+
+### **For Distribution**
+- Use `npm run build:electron:*:prod` for production packages
+- Test packages before distribution
+- Users install/run the generated executables
+
+### **For Testing**
+- Use `npm run build:electron:*:test` for test packages
+- Verify executables work on target platforms
+- Test installation and uninstallation
+
+## Troubleshooting
+
+### **Package Build Issues**
+```bash
+# Check if package was created
+ls -la electron/dist/
+
+# Verify package integrity
+file electron/dist/*.AppImage
+file electron/dist/*.deb
+file electron/dist/*.dmg
+```
+
+### **Development Issues**
+```bash
+# Clean and rebuild
+npm run clean:electron
+npm run build:electron:dev
+```
+
+---
+
+**Last Updated**: 2025-07-11  
+**Version**: 1.0.3-beta  
+**Status**: Production Ready