Phase 2 complete.

docs/SCRIPTS.md

@@ -0,0 +1,201 @@
+# EVE Development Scripts
+
+Quick reference for all development scripts in the EVE project.
+
+## Running the Application
+
+### Linux/macOS
+```bash
+./run.sh
+```
+
+### Windows
+```powershell
+.\run.ps1
+```
+
+**What it does:**
+- Checks for `.env` file (creates from template if missing)
+- Checks for `node_modules` (installs if missing)
+- Starts the Tauri development server with hot-reload
+- Shows the app window with live code updates
+
+**Stop the server:**
+- Press `Ctrl+C` in the terminal
+- Or run the kill script (see below)
+
+## Stopping the Application
+
+### Linux/macOS
+```bash
+./kill.sh
+```
+
+### Windows
+```powershell
+.\kill.ps1
+```
+
+**What it does:**
+- Finds all EVE-related processes (Tauri, Vite, Cargo, etc.)
+- Kills process trees cleanly
+- Frees up ports (5173, 1420, etc.)
+- Removes lock files
+
+**When to use:**
+- When `Ctrl+C` doesn't fully stop the server
+- When you get "port already in use" errors
+- When processes are stuck in the background
+- Before switching branches or rebuilding
+
+## Setup Scripts
+
+### Linux/macOS
+```bash
+./setup.sh
+```
+
+### Windows
+```powershell
+.\setup.ps1
+```
+
+**What it does:**
+- Detects your operating system
+- Checks for Node.js, Rust, and dependencies
+- Installs missing components (with permission)
+- Sets up `.env` file
+- Installs npm packages
+- Verifies installation
+
+See [DEV_SETUP.md](./setup/DEV_SETUP.md) for detailed setup documentation.
+
+## npm Scripts
+
+You can also use npm commands directly:
+
+```bash
+# Start development server (same as run.sh)
+npm run tauri:dev
+
+# Start frontend only (browser, no desktop app)
+npm run dev
+
+# Build for production
+npm run tauri:build
+
+# Build frontend only
+npm run build
+
+# Lint code
+npm run lint
+
+# Format code
+npm run format
+
+# Preview production build
+npm run preview
+```
+
+## Common Workflows
+
+### Start Fresh Development Session
+```bash
+./run.sh
+# App starts with hot-reload enabled
+```
+
+### Quick Restart
+```bash
+./kill.sh && ./run.sh
+# Stops everything, then starts fresh
+```
+
+### Clean Build
+```bash
+./kill.sh
+rm -rf node_modules src-tauri/target
+npm install
+npm run tauri:build
+```
+
+### Port Conflict Resolution
+```bash
+# If you get "address already in use" error
+./kill.sh
+# Then start again
+./run.sh
+```
+
+### Switch Branches
+```bash
+# Stop app first to avoid conflicts
+./kill.sh
+git checkout feature-branch
+npm install  # Update dependencies if needed
+./run.sh
+```
+
+## Troubleshooting
+
+### "Permission denied" (Linux/macOS)
+```bash
+chmod +x run.sh kill.sh setup.sh
+```
+
+### Scripts don't find processes (Linux/macOS)
+The kill script uses `pgrep`, `lsof`, and `ps`. These should be available on most systems. If not:
+```bash
+# Ubuntu/Debian
+sudo apt install procps lsof
+
+# macOS (usually pre-installed)
+# No action needed
+```
+
+### PowerShell execution policy (Windows)
+```powershell
+Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
+```
+
+### Processes still running after kill script
+```bash
+# Nuclear option - find and kill manually
+ps aux | grep -E "vite|tauri|eve"
+kill -9 <PID>
+
+# Or on Windows
+tasklist | findstr /i "node cargo"
+taskkill /F /PID <PID>
+```
+
+### Script starts but app window is blank
+This is usually a graphics driver issue on Linux. The project includes a fix:
+```bash
+# The run script already includes this, but you can also run:
+WEBKIT_DISABLE_COMPOSITING_MODE=1 npm run tauri:dev
+```
+
+## Tips
+
+1. **Use `run.sh` for daily development** - it's simpler than typing the full npm command
+2. **Use `kill.sh` liberally** - it's safe and thorough
+3. **Run `setup.sh` once** - when first setting up or after major changes
+4. **Check `.env` file** - if the app shows "Configure Settings" on startup
+
+## Script Locations
+
+All scripts are in the project root:
+```
+eve-alpha/
+├── run.sh          # Start app (Linux/macOS)
+├── run.ps1         # Start app (Windows)
+├── kill.sh         # Stop app (Linux/macOS)
+├── kill.ps1        # Stop app (Windows)
+├── setup.sh        # Setup environment (Linux/macOS)
+└── setup.ps1       # Setup environment (Windows)
+```
+
+---
+
+**Last Updated**: October 6, 2025