docs: update README and installation guide with professional branding - Enhanced README with professional description, logo integration, comprehensive feature sections, app icon generation documentation, updated INSTALLATION_GUIDE with multiple installation methods and troubleshooting

Author: nicksoftware

INSTALLATION_GUIDE.md

@@ -0,0 +1,174 @@
+# Mac Snap Installation Guide
+
+Welcome to Mac Snap! This guide will help you install and set up the ultimate window management tool for macOS.
+
+## 📥 Installation Methods
+
+### Method 1: DMG Installer (Recommended)
+
+1. **Download the latest release:**
+   - Visit the [Mac Snap Releases](https://github.com/nicolusmaluleke/MacSnapper/releases) page
+   - Download the latest `MacSnap-Installer-X.X.X.dmg` file
+
+2. **Install the app:**
+   - Double-click the downloaded DMG file
+   - Drag "Mac Snap.app" to the Applications folder
+   - Eject the DMG when done
+
+3. **Launch and setup:**
+   - Open Mac Snap from Applications folder
+   - Grant Accessibility permissions when prompted
+   - Configure your preferred hotkeys
+
+### Method 2: Build from Source
+
+If you're a developer or want to build the latest version:
+
+```bash
+# Clone the repository
+git clone https://github.com/nicolusmaluleke/MacSnapper.git
+cd MacSnapper
+
+# Build using Xcode
+xcodebuild -project MacSnapper.xcodeproj \
+  -scheme MacSnapper \
+  -configuration Release \
+  clean build
+
+# Or create a DMG installer
+chmod +x scripts/create_dmg.sh
+./scripts/create_dmg.sh
+```
+
+### Method 3: Direct App Bundle
+
+For quick testing (unsigned version):
+
+1. Download the app bundle from GitHub Actions artifacts
+2. Move to Applications folder
+3. Right-click → Open (to bypass Gatekeeper)
+4. Grant required permissions
+
+## 🔐 Required Permissions
+
+Mac Snap needs these permissions to function:
+
+### Accessibility Permission (Required)
+- **Purpose:** Control and resize windows
+- **How to grant:**
+  1. System Preferences → Security & Privacy → Privacy
+  2. Select "Accessibility" from the left sidebar
+  3. Click the lock icon and enter your password
+  4. Check the box next to "Mac Snap"
+
+### Screen Recording Permission (Optional)
+- **Purpose:** Enhanced window detection on some systems
+- **Note:** Only required on macOS 10.15+ with certain security settings
+
+## ⚙️ Initial Setup
+
+### 1. Configure Global Hotkeys
+
+Default hotkeys:
+- `⌘ + ←` - Snap left half
+- `⌘ + →` - Snap right half
+- `⌘ + ↑` - Maximize window
+- `⌘ + ↓` - Center window
+
+To customize:
+1. Open Mac Snap preferences
+2. Go to "Shortcuts" tab
+3. Click on any hotkey to change it
+4. Test your new hotkeys
+
+### 2. Choose Your Operating Mode
+
+**Menu Bar Mode (Recommended):**
+- App runs in background
+- Access via menu bar icon
+- Minimal system impact
+
+**Window Mode:**
+- Traditional app window
+- Full settings interface
+- Easy access to all features
+
+### 3. Premium Features (Optional)
+
+Unlock advanced features:
+- Advanced snapping patterns (thirds, custom zones)
+- Custom keyboard shortcuts
+- Multi-monitor window management
+- Window presets and exclusions
+
+**Free Trial:** 7 days of all premium features
+**Subscription:** $4.99/month or $39.99/year
+
+## 🔧 Troubleshooting
+
+### Common Issues
+
+**App won't launch:**
+- Check that you've granted Accessibility permission
+- Try right-clicking and selecting "Open" (for unsigned builds)
+- Restart your Mac if permissions were just granted
+
+**Hotkeys not working:**
+- Verify Accessibility permission is granted
+- Check for conflicting system shortcuts
+- Try different key combinations
+
+**Window snapping not precise:**
+- Ensure you're using the latest version
+- Check for conflicting window management apps
+- Try toggling the Accessibility permission off and on
+
+### Performance Tips
+
+1. **Enable "Launch at Login"** for seamless experience
+2. **Use Menu Bar mode** for better performance
+3. **Exclude problematic apps** in settings if needed
+4. **Keep the app updated** for latest improvements
+
+## 🆘 Getting Help
+
+- **Issues:** [GitHub Issues](https://github.com/nicolusmaluleke/MacSnapper/issues)
+- **Feature Requests:** [GitHub Discussions](https://github.com/nicolusmaluleke/MacSnapper/discussions)
+- **Email Support:** nicolusmaluleke@gmail.com
+
+## 🔄 Updating
+
+### Automatic Updates (Coming Soon)
+The app will check for updates automatically and notify you.
+
+### Manual Updates
+1. Download the latest DMG from releases
+2. Replace the old app in Applications folder
+3. Your settings will be preserved
+
+## 🗑️ Uninstalling
+
+To completely remove Mac Snap:
+
+1. **Quit the app:**
+   - Right-click menu bar icon → Quit
+   - Or force quit if needed
+
+2. **Remove the app:**
+   ```bash
+   rm -rf /Applications/Mac\ Snap.app
+   ```
+
+3. **Remove preferences (optional):**
+   ```bash
+   rm -rf ~/Library/Preferences/com.nicksoftware.macsnap.plist
+   rm -rf ~/Library/Application\ Support/Mac\ Snap/
+   ```
+
+4. **Remove Accessibility permission:**
+   - System Preferences → Security & Privacy → Privacy
+   - Select "Accessibility" and remove Mac Snap
+
+---
+
+**Enjoy effortless window management with Mac Snap! 🪟✨**

README.md

@@ -1,6 +1,10 @@
 # Mac Snap 🪟
 
-A professional macOS window manager built with SwiftUI and Clean Architecture principles. Mac Snap provides powerful window snapping and management capabilities with a beautiful, intuitive interface.
+**Professional Window Snapping for macOS**
+
+![Mac Snap Logo](logo.svg)
+
+Mac Snap is a powerful and intuitive window management utility for macOS that makes organizing your workspace effortless. With intelligent window snapping, customizable shortcuts, and a clean interface, Mac Snap helps you maximize productivity by keeping your windows perfectly organized.
 
 ![Swift](https://img.shields.io/badge/Swift-5.9-orange.svg)
 ![Platform](https://img.shields.io/badge/Platform-macOS%2014.0+-blue.svg)
@@ -9,6 +13,24 @@ A professional macOS window manager built with SwiftUI and Clean Architecture pr
 
 ## ✨ Features
 
+### 🎯 Core Functionality
+- **Smart Window Snapping**: Snap windows to halves, quarters, thirds, and custom positions
+- **Drag & Drop Snapping**: Intuitive window snapping by dragging to screen edges
+- **Multi-Monitor Support**: Full support for multiple displays with individual snapping zones
+- **Custom Presets**: Create and save custom window arrangements
+
+### 🔧 Customization
+- **Global Hotkeys**: Customizable keyboard shortcuts for all snapping actions
+- **Exclusion Lists**: Exclude specific applications from snapping
+- **Visual Feedback**: Real-time preview of window positions during snapping
+- **Menu Bar Integration**: Quick access via menu bar icon
+
+### 💎 Professional Design
+- **Modern macOS Interface**: Native SwiftUI design following Apple's Human Interface Guidelines
+- **Professional Logo**: Custom-designed gradient app icon with window snapping iconography
+- **Clean Architecture**: Built with Domain-Driven Design and SOLID principles
+- **Performance Optimized**: Minimal memory footprint and CPU usage
+
 ### Core Window Management
 - **Precise Window Snapping**: Left/Right halves, quarters, thirds, and custom positions
 - **Multiple Screen Support**: Intelligent screen detection and window positioning
@@ -302,6 +324,21 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 - Architecture influenced by Clean Architecture principles by Uncle Bob
 - SwiftUI design patterns from Apple's Human Interface Guidelines
 
+## Development
+
+### 🎨 App Icon Generation
+The professional app icon is generated from the SVG logo using the included script:
+
+```bash
+./scripts/create_app_icon.sh
+```
+
+This script:
+- Converts the SVG logo to all required macOS icon sizes (16x16 to 1024x1024)
+- Creates both 1x and 2x (retina) versions
+- Generates the .icns file for the app bundle
+- Updates the Xcode asset catalog with proper file references
+
 ---
 
 **MacSnapper** - Professional window management for macOS developers and power users.