docs: Add comprehensive troubleshooting guide

📝 Created TROUBLESHOOTING.md:
- Quick diagnosis steps
- Common issues with solutions
- Verification procedures
- Emergency rollback guide
- Help gathering checklist
- Prevention tips

🎯 Covers All Issues:
1. Blank page in WP-Admin
   - Files not found (404)
   - Wrong extraction path
   - Dev mode enabled
2. API 500 errors (namespace)
3. WordPress media not loading
4. Changes not reflecting (caches)
5. File permissions

✅ Step-by-Step Solutions:
- Clear instructions
- Copy-paste commands
- Expected outputs
- Verification steps

🚀 Quick Reference:
- Installation checker usage
- Cache clearing commands
- File structure verification
- API/asset testing
- Error log locations

TROUBLESHOOTING.md

@@ -0,0 +1,340 @@
+# Troubleshooting Guide
+
+## Quick Diagnosis
+
+### Step 1: Run Installation Checker
+Upload `check-installation.php` to your server and visit:
+```
+https://yoursite.com/wp-content/plugins/woonoow/check-installation.php
+```
+
+This will show you exactly what's wrong.
+
+---
+
+## Common Issues
+
+### Issue 1: Blank Page in WP-Admin
+
+**Symptoms:**
+- Blank white page when visiting `/wp-admin/admin.php?page=woonoow`
+- Or shows "Please Configure Marketing Setup first"
+- No SPA loads
+
+**Diagnosis:**
+1. Open browser console (F12)
+2. Check Network tab
+3. Look for `app.js` and `app.css`
+
+**Possible Causes & Solutions:**
+
+#### A. Files Not Found (404)
+```
+❌ admin-spa/dist/app.js → 404 Not Found
+❌ admin-spa/dist/app.css → 404 Not Found
+```
+
+**Solution:**
+```bash
+# The dist files are missing!
+# Re-extract the zip file:
+cd /path/to/wp-content/plugins
+rm -rf woonoow
+unzip woonoow.zip
+
+# Verify files exist:
+ls -la woonoow/admin-spa/dist/
+# Should show: app.js (2.4MB) and app.css (70KB)
+```
+
+#### B. Wrong Extraction Path
+If you extracted into `plugins/woonoow/woonoow/`, the paths will be wrong.
+
+**Solution:**
+```bash
+# Correct structure:
+wp-content/plugins/woonoow/woonoow.php ✓
+wp-content/plugins/woonoow/admin-spa/dist/app.js ✓
+
+# Wrong structure:
+wp-content/plugins/woonoow/woonoow/woonoow.php ✗
+wp-content/plugins/woonoow/woonoow/admin-spa/dist/app.js ✗
+
+# Fix:
+cd /path/to/wp-content/plugins
+rm -rf woonoow
+unzip woonoow.zip
+# This creates: plugins/woonoow/ (correct!)
+```
+
+#### C. Dev Mode Enabled
+```
+❌ Trying to load from localhost:5173
+```
+
+**Solution:**
+Edit `wp-config.php` and remove or set to false:
+```php
+// Remove this line:
+define('WOONOOW_ADMIN_DEV', true);
+
+// Or set to false:
+define('WOONOOW_ADMIN_DEV', false);
+```
+
+Then clear caches:
+```bash
+php -r "opcache_reset();"
+wp cache flush
+```
+
+---
+
+### Issue 2: API 500 Errors
+
+**Symptoms:**
+- All API endpoints return 500
+- Console shows: "Internal Server Error"
+- Error log: `Class "WooNooWAPIPaymentsController" not found`
+
+**Cause:**
+Namespace case mismatch (old code)
+
+**Solution:**
+```bash
+# Check if you have the fix:
+grep "use WooNooW" includes/Api/Routes.php
+
+# Should show (lowercase 'i'):
+# use WooNooW\Api\PaymentsController;
+
+# If it shows (uppercase 'I'):
+# use WooNooW\API\PaymentsController;
+# Then you need to update!
+
+# Update:
+git pull origin main
+# Or re-upload the latest zip
+
+# Clear caches:
+php -r "opcache_reset();"
+wp cache flush
+```
+
+---
+
+### Issue 3: WordPress Media Not Loading (Standalone)
+
+**Symptoms:**
+- Error: "WordPress Media library is not loaded"
+- "Choose from Media Library" button doesn't work
+- Only in standalone mode (`/admin`)
+
+**Cause:**
+Missing wp.media scripts
+
+**Solution:**
+Already fixed in latest code. Update:
+```bash
+git pull origin main
+# Or re-upload the latest zip
+
+php -r "opcache_reset();"
+```
+
+---
+
+### Issue 4: Changes Not Reflecting
+
+**Symptoms:**
+- Uploaded new code but still seeing old errors
+- Fixed files but issues persist
+
+**Cause:**
+Multiple cache layers
+
+**Solution:**
+```bash
+# 1. Clear PHP OPcache (MOST IMPORTANT!)
+php -r "opcache_reset();"
+
+# Or visit:
+# https://yoursite.com/wp-content/plugins/woonoow/check-installation.php?action=clear_opcache
+
+# 2. Clear WordPress object cache
+wp cache flush
+
+# 3. Restart PHP-FPM (if above doesn't work)
+sudo systemctl restart php8.1-fpm
+# or
+sudo systemctl restart php-fpm
+
+# 4. Clear browser cache
+# Hard refresh: Ctrl+Shift+R (Windows/Linux)
+# Hard refresh: Cmd+Shift+R (Mac)
+```
+
+---
+
+### Issue 5: File Permissions
+
+**Symptoms:**
+- 403 Forbidden errors
+- Can't access files
+
+**Solution:**
+```bash
+cd /path/to/wp-content/plugins/woonoow
+
+# Set correct permissions:
+find . -type f -exec chmod 644 {} \;
+find . -type d -exec chmod 755 {} \;
+
+# Verify:
+ls -la admin-spa/dist/
+# Should show: -rw-r--r-- (644) for files
+```
+
+---
+
+## Verification Steps
+
+After fixing, verify everything works:
+
+### 1. Check Files
+```bash
+cd /path/to/wp-content/plugins/woonoow
+
+# These files MUST exist:
+ls -lh woonoow.php                    # Main plugin file
+ls -lh includes/Admin/Assets.php      # Assets handler
+ls -lh includes/Api/Routes.php        # API routes
+ls -lh admin-spa/dist/app.js          # SPA JS (2.4MB)
+ls -lh admin-spa/dist/app.css         # SPA CSS (70KB)
+```
+
+### 2. Test API
+```bash
+curl -I https://yoursite.com/wp-json/woonoow/v1/store/settings
+
+# Should return:
+# HTTP/2 200 OK
+```
+
+### 3. Test Assets
+```bash
+curl -I https://yoursite.com/wp-content/plugins/woonoow/admin-spa/dist/app.js
+
+# Should return:
+# HTTP/2 200 OK
+# Content-Length: 2489867
+```
+
+### 4. Test WP-Admin
+Visit: `https://yoursite.com/wp-admin/admin.php?page=woonoow`
+
+**Should see:**
+- ✓ WooNooW dashboard loads
+- ✓ No console errors
+- ✓ Navigation works
+
+**Should NOT see:**
+- ✗ Blank page
+- ✗ "Please Configure Marketing Setup"
+- ✗ Errors about localhost:5173
+
+### 5. Test Standalone
+Visit: `https://yoursite.com/admin`
+
+**Should see:**
+- ✓ Standalone admin loads
+- ✓ Login page (if not logged in)
+- ✓ Dashboard (if logged in)
+
+---
+
+## Emergency Rollback
+
+If everything breaks:
+
+```bash
+# 1. Deactivate plugin
+wp plugin deactivate woonoow
+
+# 2. Remove plugin
+rm -rf /path/to/wp-content/plugins/woonoow
+
+# 3. Re-upload fresh zip
+unzip woonoow.zip -d /path/to/wp-content/plugins/
+
+# 4. Reactivate
+wp plugin activate woonoow
+
+# 5. Clear all caches
+php -r "opcache_reset();"
+wp cache flush
+```
+
+---
+
+## Getting Help
+
+If issues persist, gather this info:
+
+1. **Run installation checker:**
+   ```
+   https://yoursite.com/wp-content/plugins/woonoow/check-installation.php
+   ```
+   Take screenshot of results
+
+2. **Check error logs:**
+   ```bash
+   tail -50 /path/to/wp-content/debug.log
+   tail -50 /var/log/php-fpm/error.log
+   ```
+
+3. **Browser console:**
+   - Open DevTools (F12)
+   - Go to Console tab
+   - Take screenshot of errors
+
+4. **Network tab:**
+   - Open DevTools (F12)
+   - Go to Network tab
+   - Reload page
+   - Take screenshot showing failed requests
+
+5. **File structure:**
+   ```bash
+   ls -la /path/to/wp-content/plugins/woonoow/
+   ls -la /path/to/wp-content/plugins/woonoow/admin-spa/dist/
+   ```
+
+Send all this info when requesting help.
+
+---
+
+## Prevention
+
+To avoid issues in the future:
+
+1. **Always clear caches after updates:**
+   ```bash
+   php -r "opcache_reset();"
+   wp cache flush
+   ```
+
+2. **Verify files after extraction:**
+   ```bash
+   ls -lh admin-spa/dist/app.js
+   # Should be ~2.4MB
+   ```
+
+3. **Use installation checker:**
+   Run it after every deployment
+
+4. **Keep backups:**
+   Before updating, backup the working version
+
+5. **Test in staging first:**
+   Don't deploy directly to production