diff --git a/QUICK-REFERENCE.md b/QUICK-REFERENCE.md
new file mode 100644
index 0000000..655f5b6
--- /dev/null
+++ b/QUICK-REFERENCE.md
@@ -0,0 +1,272 @@
+# Services Homepage - Quick Reference
+
+## 🎯 Quick Start
+
+### Access Your Homepage
+- Local: `http://192.168.2.180:8088`
+- Public: `https://homepage.spatulaa.com`
+
+### Essential Keyboard Shortcuts
+- `↑` `↓` `←` `→` - Navigate between services
+- `Enter` - Open selected service
+- Type to search - Instant filter
+
+---
+
+## 🎨 UI Controls
+
+### Header Controls (Top-Right)
+- **🎨 Theme Selector** - Change visual theme
+  - Click icon → Select from 5 themes
+  - Dark, Light, Ocean, Sunset, Forest
+
+### Header Controls (Top-Left)
+- **📥 Export** - Backup configuration to JSON
+- **📤 Import** - Restore from JSON backup
+- **⚙️ Widgets** - Configure dashboard widgets
+
+### Service Groups
+- **Click Group Header** - Collapse/expand group
+- **▼ Icon** - Visual collapse indicator
+
+### Service Cards
+- **Drag & Drop** - Reorder within same group
+- **Status Dot** (top-right) - Health indicator
+  - 🟢 Green (pulsing) = Online
+  - 🔴 Red = Offline
+  - 🟠 Orange = Maintenance
+  - ⚪ Gray (spinning) = Checking
+- **ⓘ Info Button** (bottom-right) - Connection details
+
+---
+
+## 🔧 Configuration Cheat Sheet
+
+### Add a New Service
+
+Edit `services.xml`:
+
+```xml
+<service 
+  id="myservice"
+  name="My Service"
+  proto="http"
+  port="8080"
+  logo="mylogo.svg"
+/>
+```
+
+Then rebuild:
+```bash
+docker compose restart services-homepage
+```
+
+### Custom Health Check Path
+
+For services with non-root health endpoints:
+
+```xml
+<service 
+  id="myapi"
+  health-path="/api/health"
+/>
+```
+
+### Override Health Check IP
+
+Use local IP instead of Tailscale:
+
+```xml
+<service 
+  id="myservice"
+  local-ip="192.168.1.100"
+/>
+```
+
+### Disable Health Check
+
+For services that don't support HEAD requests:
+
+```xml
+<service 
+  id="myservice"
+  check-health="false"
+/>
+```
+
+---
+
+## 🎛️ Widget Configuration
+
+### Enable Clock Widget
+1. Click **⚙️ Widgets**
+2. Check **🕐 Clock**
+3. Click **Save & Reload**
+
+### Enable Weather Widget
+1. Get free API key: https://openweathermap.org/api
+2. Click **⚙️ Widgets**
+3. Check **🌤️ Weather**
+4. Enter API key
+5. Set location (`auto` or city name)
+6. Click **Save & Reload**
+
+### Enable Daily Quote
+1. Click **⚙️ Widgets**
+2. Check **💭 Daily Quote**
+3. Click **Save & Reload**
+
+---
+
+## 💾 Backup & Restore
+
+### Export Configuration
+1. Click **📥 Export**
+2. Save JSON file
+3. Store safely
+
+### Import Configuration
+1. Click **📤 Import**
+2. Select JSON file
+3. Download generated `services.xml`
+4. Replace file and rebuild
+
+---
+
+## 🔄 Reset Functions
+
+### Reset Service Order
+```javascript
+localStorage.removeItem('services-order');
+location.reload();
+```
+
+### Reset Collapsed Groups
+```javascript
+localStorage.removeItem('collapsed-groups');
+location.reload();
+```
+
+### Reset Theme
+```javascript
+localStorage.removeItem('selected-theme');
+location.reload();
+```
+
+### Reset Widgets
+```javascript
+localStorage.removeItem('enabled-widgets');
+location.reload();
+```
+
+### Reset Everything
+```javascript
+localStorage.clear();
+location.reload();
+```
+
+---
+
+## 🐛 Common Issues
+
+### Health Checks Fail (502)
+- **Cause:** Nginx can't resolve health-proxy
+- **Fix:** Ensure `nginx.conf` has `resolver 127.0.0.11;`
+- **Apply:** `docker restart services-homepage`
+
+### Service Shows Offline (But It's Running)
+- **Check:** Health check path correct?
+- **Fix:** Add `health-path="/custom/path"`
+- **Or:** Set `check-health="false"` and use `status="online"`
+
+### Widgets Not Loading
+- **Weather:** Verify API key is valid
+- **Check:** Browser console for errors
+- **Try:** Disable and re-enable in settings
+
+### Drag-Drop Not Working
+- **Check:** JavaScript enabled?
+- **Try:** Different browser
+- **Reset:** Clear localStorage
+
+### Theme Not Saving
+- **Check:** Browser allows localStorage
+- **Try:** Disable private/incognito mode
+- **Fix:** Check browser storage settings
+
+---
+
+## 📊 Health Check Priority
+
+When multiple IPs are configured, health checks use this priority:
+
+1. `local-ip` (service-specific)
+2. `tailscale-ip` (global root attribute)
+3. `host` (parsed from host attribute)
+4. Current browser hostname
+
+---
+
+## 🎯 Pro Tips
+
+### Organize Services
+- Use groups to categorize (Management, Media, Development, etc.)
+- Drag-drop to prioritize frequently used services
+- Collapse rarely used groups
+
+### Theme Switching
+- Use **Dark** for nighttime browsing
+- Use **Light** for daytime
+- Try **Ocean** for reduced eye strain
+
+### Performance
+- Disable health checks for very slow services
+- Use `health-path` to point to lightweight endpoints
+- Collapse large groups when not needed
+
+### Backup Strategy
+- Export configuration monthly
+- Store JSON files in version control (Git)
+- Keep backup before major changes
+
+---
+
+## 📞 Quick Commands
+
+### Rebuild Homepage
+```bash
+cd /home/mayatheshy/dockercompose/services-homepage
+docker compose down
+docker compose up -d
+```
+
+### View Logs
+```bash
+docker logs services-homepage --tail 50
+docker logs services-homepage-health-proxy --tail 50
+```
+
+### Test Health Endpoint
+```bash
+curl http://192.168.2.180:8088/healthcheck?id=SERVICE_ID
+```
+
+### Edit Configuration
+```bash
+nano services.xml
+docker restart services-homepage
+```
+
+---
+
+## 🔗 Useful Links
+
+- OpenWeatherMap API: https://openweathermap.org/api
+- Quotable API: https://api.quotable.io/random
+- Simple Icons: https://simpleicons.org/ (for logos)
+- Three.js Docs: https://threejs.org/docs/
+
+---
+
+**Last Updated:** 2025-11-24  
+**Version:** 2.0.0