diff --git a/README.md b/README.md
new file mode 100644
index 0000000..9d98e38
--- /dev/null
+++ b/README.md
@@ -0,0 +1,76 @@
+# iCloud Drive for Linux
+
+A GTK3 GUI for [icloud-linux](https://github.com/IsmaeelAkram/icloud-linux), designed for ElementaryOS with a Granite-inspired interface. Sync your iCloud Drive and download iCloud Photos directly from the desktop.
+
+![ElementaryOS](https://img.shields.io/badge/ElementaryOS-7%2B-64a6e0?style=flat-square)
+![Python](https://img.shields.io/badge/Python-3.10%2B-blue?style=flat-square)
+![GTK](https://img.shields.io/badge/GTK-3.0-green?style=flat-square)
+
+## Features
+
+- **Dashboard** — Start, stop, restart, and sync iCloud Drive. Shows the current file being synced in real time with auto-refreshing status.
+- **Logs** — Live-follow service logs with color-coded ERROR / WARNING / INFO lines.
+- **Photos** — Download your most recent iCloud Photos as JPEGs into `~/Pictures/iCloud Photos` so the Photos app can display them natively.
+- **Settings** — Configure your Apple ID, sync intervals, warmup workers, and more. Prompts to restart the service when saved.
+- **Sign In** — Authenticate with Apple ID and handle two-factor authentication.
+- **Sleep/wake aware** — Automatically reconnects log streams after the computer wakes from sleep.
+
+## Requirements
+
+- ElementaryOS 7+ / Ubuntu 22.04+
+- [icloud-linux](https://github.com/IsmaeelAkram/icloud-linux) installed and configured
+- Python 3.10+
+- GTK 3.0
+
+## Installation
+
+Clone this repo next to your icloud-linux installation and run the installer:
+
+```bash
+git clone https://github.com/nmemmert/icloud_linux_app.git
+cd icloud_linux_app
+bash install.sh
+```
+
+The installer will:
+- Install system dependencies (`python3-gi`, `fuse`, `heif-gdk-pixbuf`, etc.)
+- Set up the GUI at `~/.local/lib/icloud-gui/`
+- Create a launcher at `~/.local/bin/icloud-drive`
+- Add **iCloud Drive** to your app menu (Slingshot)
+
+## Running Without Installing
+
+```bash
+python3 icloud_gui.py
+```
+
+## Uninstall
+
+```bash
+bash uninstall.sh
+```
+
+Your config (`~/.config/icloud-linux`) and downloaded photos (`~/Pictures/iCloud Photos`) are left intact.
+
+## Photos Setup
+
+The Photos tab uses [icloudpd](https://github.com/icloud-photos-downloader/icloud_photos_downloader) (bundled with icloud-linux) to download photos directly to `~/Pictures/iCloud Photos` as JPEGs. The ElementaryOS Photos app will find and display them automatically.
+
+- **Sync Recent (200)** — Downloads your 200 most recent photos
+- **Sync More (1000)** — Downloads your 1000 most recent photos
+- **Open Photos App** — Launches the ElementaryOS Photos app
+- **Open Folder** — Opens the download folder in Files
+
+## Project Structure
+
+| File | Description |
+|------|-------------|
+| `icloud_gui.py` | Main GTK3 application |
+| `icloud_photos_fs.py` | FUSE filesystem for on-demand photo access (experimental) |
+| `install.sh` | Installer script |
+| `uninstall.sh` | Uninstaller script |
+| `com.elementary.icloud-linux.desktop` | App menu desktop entry |
+
+## License
+
+MIT