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)
2 weeks ago · 781fe23363
2 changed files with 260 additions and 60 deletions
--- a/README.md
+++ b/README.md
@ -47,6 +47,85 @@ npm run dev

 See [BUILDING.md](BUILDING.md) for more details.

+## Development Database Clearing
+
+TimeSafari provides a simple script-based approach to clear the database for development purposes.
+
+### Quick Usage
+```bash
+# Run the database clearing script
+./scripts/clear-database.sh
+
+# Then restart your development server
+npm run build:electron:dev  # For Electron
+npm run build:web:dev       # For Web
+```
+
+### What It Does
+
+#### **Electron (Desktop App)**
+- Automatically finds and clears the SQLite database files
+- Works on Linux, macOS, and Windows
+- Clears all data and forces fresh migrations on next startup
+
+#### **Web Browser**
+- Provides instructions for using custom browser data directories
+- Shows manual clearing via browser DevTools
+- Ensures reliable database clearing without browser complications
+
+### Safety Features
+- ✅ **Interactive Script**: Guides you through the process
+- ✅ **Platform Detection**: Automatically detects your OS
+- ✅ **Clear Instructions**: Step-by-step guidance for each platform
+- ✅ **Safe Paths**: Only clears TimeSafari-specific data
+
+### Manual Commands (if needed)
+
+#### **Electron Database Location**
+```bash
+# Linux
+rm -rf ~/.config/TimeSafari/*
+
+# macOS  
+rm -rf ~/Library/Application\ Support/TimeSafari/*
+
+# Windows
+rmdir /s /q %APPDATA%\TimeSafari
+```
+
+#### **Web Browser (Custom Data Directory)**
+```bash
+# Create isolated browser profile
+mkdir ~/timesafari-dev-data
+
+# Start browser with custom profile
+google-chrome --user-data-dir=~/timesafari-dev-data
+
+# Clear when needed
+rm -rf ~/timesafari-dev-data
+```
+
+See the script for complete platform-specific instructions.
+
+## Electron Build Scripts
+
+### **Development vs Package Builds**
+
+- **Development Scripts**: Run the app directly after building
+  ```bash
+  npm run build:electron:dev    # Runs app immediately
+  npm run build:electron:test   # Runs app immediately
+  ```
+
+- **Package Scripts**: Create executable files for distribution
+  ```bash
+  npm run build:electron:appimage  # Creates AppImage executable
+  npm run build:electron:deb       # Creates DEB package
+  npm run build:electron:dmg       # Creates DMG package
+  ```
+
+See [Electron Build Scripts Guide](docs/electron-build-scripts.md) for complete details.
+
 ## Tests

 See [TESTING.md](test-playwright/TESTING.md) for detailed test instructions.
@ -118,63 +197,3 @@ Gifts make the world go 'round!
 * Time Safari logo assisted by [DALL-E in ChatGPT](https://chat.openai.com/g/g-2fkFE8rbu-dall-e)
 * [DiceBear](https://www.dicebear.com/licenses/) and [Avataaars](https://www.dicebear.com/styles/avataaars/#details) for human-looking identicons
 * Some gratitude prompts thanks to [Develop Good Habits](https://www.developgoodhabits.com/gratitude-journal-prompts/)
-
-## Development Database Clearing
-
-TimeSafari provides a simple script-based approach to clear the database for development purposes.
-
-### Quick Usage
-```bash
-# Run the database clearing script
-./scripts/clear-database.sh
-
-# Then restart your development server
-npm run build:electron:dev  # For Electron
-npm run build:web:dev       # For Web
-```
-
-### What It Does
-
-#### **Electron (Desktop App)**
- Automatically finds and clears the SQLite database files
- Works on Linux, macOS, and Windows
- Clears all data and forces fresh migrations on next startup
-
-#### **Web Browser**
- Provides instructions for using custom browser data directories
- Shows manual clearing via browser DevTools
- Ensures reliable database clearing without browser complications
-
-### Safety Features
- ✅ **Interactive Script**: Guides you through the process
- ✅ **Platform Detection**: Automatically detects your OS
- ✅ **Clear Instructions**: Step-by-step guidance for each platform
- ✅ **Safe Paths**: Only clears TimeSafari-specific data
-
-### Manual Commands (if needed)
-
-#### **Electron Database Location**
-```bash
-# Linux
-rm -rf ~/.config/TimeSafari/*
-
-# macOS  
-rm -rf ~/Library/Application\ Support/TimeSafari/*
-
-# Windows
-rmdir /s /q %APPDATA%\TimeSafari
-```
-
-#### **Web Browser (Custom Data Directory)**
-```bash
-# Create isolated browser profile
-mkdir ~/timesafari-dev-data
-
-# Start browser with custom profile
-google-chrome --user-data-dir=~/timesafari-dev-data
-
-# Clear when needed
-rm -rf ~/timesafari-dev-data
-```
-
-See the script for complete platform-specific instructions.
--- a/docs/electron-build-scripts.md
+++ b/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