diff --git a/README.md b/README.md
new file mode 100644
index 0000000..3bada58
--- /dev/null
+++ b/README.md
@@ -0,0 +1,211 @@
+# Chroma
+
+A simple, lightweight and efficientt wallpaper daeemon for Wayland compositors
+with multi-monitor & automatic hotplugging support. Born from my woes with
+Hyprpaper, swaybg and most ironically SWWW, which turned out to be NOT a
+solution to my Wayland wallpaper woes.
+
+## Features
+
+I did not expect to be writing something too feature-rich, but I still ended up
+with something relatively convoluted. Chroma (mostly) reliably supports:
+
+- **Multi-monitors**: Automatically detects and manages wallpapers for all
+  connected displays
+- **Hotplugging**: Dynamically handles monitor connection/disconnection events
+- **Per-output configuration**: Set different wallpapers for each monitor
+- **Multiple image formats**: Supports JPEG, PNG, BMP, TGA, PSD, GIF, HDR, PIC,
+  PPM, PGM
+- **EGL/OpenGL rendering**: Hardware-accelerated wallpaper rendering
+- **Configuration file support**: Easy setup with INI-style config files
+- **Signal handling**: Graceful shutdown and configuration reload (SIGHUP)
+
+## Usage
+
+### Requirements
+
+#### Dependencies
+
+- **Wayland**: wayland-client, wayland-egl
+- **Graphics**: EGL, OpenGL
+- **System**: glibc, libm, libdl
+
+#### Development Dependencies
+
+- GCC or Clang compiler
+- Make
+- pkg-config
+- Wayland development headers
+- EGL/OpenGL development headers
+
+### Building
+
+#### Quick Build
+
+```bash
+# Check dependencies
+make check-deps
+
+# Build the daemon
+make
+
+# Or build debug version
+make debug
+```
+
+### Installation
+
+```bash
+# Install to /usr/local (default)
+sudo make install
+
+# Install to /usr
+sudo make PREFIX=/usr install
+
+# Create systemd service file
+make systemd-service
+
+# Create sample configuration
+make sample-config
+```
+
+### Configuration
+
+#### Configuration File
+
+Chroma looks for configuration files in this order:
+
+1. `~/.config/chroma/chroma.conf`
+2. `$XDG_CONFIG_HOME/chroma/chroma.conf`
+3. `./chroma.conf` (current directory)
+
+#### Sample Configuration
+
+```ini
+# Default wallpaper for outputs without specific mapping
+default_image = ~/.config/chroma/default.jpg
+
+# Output-specific wallpapers
+# Format: output.OUTPUT_NAME = /path/to/image.jpg
+output.DP-1 = ~/Pictures/monitor1.jpg
+output.DP-2 = ~/Pictures/monitor2.png
+output.HDMI-A-1 = ~/Pictures/hdmi_wallpaper.jpg
+```
+
+### Finding Output Names
+
+Use `wlr-randr` or similar tools to find your output names:
+
+```bash
+wlr-randr
+```
+
+### Command Line Options
+
+```plaintext
+Usage: chroma [OPTIONS]
+
+Options:
+  -c, --config FILE    Configuration file path
+  -d, --daemon         Run as daemon
+  -v, --verbose        Verbose logging
+  -h, --help          Show help
+  --version           Show version information
+
+Examples:
+  chroma -c ~/.config/chroma/chroma.conf
+  chroma --daemon
+```
+
+### Running Manually
+
+```bash
+# Run in foreground
+chroma
+
+# Run as daemon
+chroma --daemon
+
+# Use custom config
+chroma -c /path/to/config.conf
+```
+
+### Systemd Service
+
+```bash
+# Enable and start the service
+systemctl --user enable chroma.service
+systemctl --user start chroma.service
+
+# Check status
+systemctl --user status chroma.service
+
+# View logs
+journalctl --user -u chroma.service -f
+
+# Reload configuration
+systemctl --user reload chroma.service
+```
+
+### Auto-start with Desktop Session
+
+```bash
+# Enable the service for auto-start
+systemctl --user enable chroma.service
+
+# The service will start automatically with your graphical session
+```
+
+### Supported Wayland Compositors
+
+Chroma works with any Wayland compositor that supports:
+
+- `wl_compositor` interface
+- `wl_output` interface
+- EGL window surface creation
+
+Tested only on Hyprland.
+
+## Development
+
+### Building Debug Version
+
+```bash
+make debug
+```
+
+### Code Formatting
+
+```bash
+make format  # requires clang-format
+```
+
+### Static Analysis
+
+```bash
+make analyze  # requires cppcheck
+```
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Test thoroughly
+5. Submit a pull request
+
+### Code Style
+
+- C11 standard
+- 2-space indentation
+- No tabs
+- Function names: `chroma_function_name`
+- Constants: `CHROMA_CONSTANT_NAME`
+
+## License
+
+<!--markdownlint-disable MD059 -->
+
+This project is made available under Mozilla Public License (MPL) version 2.0.
+See [LICENSE](LICENSE) for more details on the exact conditions. An online copy
+is provided [here](https://www.mozilla.org/en-US/MPL/2.0/).