diff --git a/README.md b/README.md
new file mode 100644
index 0000000..8c277cb
--- /dev/null
+++ b/README.md
@@ -0,0 +1,259 @@
+# scr33ny
+
+OLED-friendly screensaver for Linux / Wayland with customization support.
+
+```
+scr33ny
+```
+
+The screen goes black. OLED pixels turn off. Burn-in protection kicks in.
+
+---
+
+## Features
+
+- **Pure black by default** — all OLED pixels off, near-zero power draw
+- **Anti burn-in shift** — content shifts by a few pixels every N minutes
+- **Screensavers** — blank · GIF animation · static image · text animation
+- **Widgets** — digital/analog clock · date · weather
+- **Wayland-native** — winit + softbuffer, no Xorg required
+- **TOML config** — one readable file, no boilerplate
+
+---
+
+## Install
+
+```bash
+git clone <repo>
+cd scr33ny
+cargo install --path .
+```
+
+Requires a Rust toolchain (`rustup.rs`). No system libraries beyond Wayland.
+
+---
+
+## Usage
+
+```bash
+scr33ny                            # launch with default config
+scr33ny --config ~/my.toml         # custom config path
+scr33ny --monitor 1                # display on monitor 1
+scr33ny monitors                   # list connected monitors
+scr33ny config-path                # print default config location
+scr33ny daemon                     # start idle-based auto-launch daemon
+```
+
+**Exit:** press `Q` or `Esc`.
+
+---
+
+## Quick config
+
+```bash
+mkdir -p ~/.config/scr33ny
+cp config.toml.example ~/.config/scr33ny/config.toml
+$EDITOR ~/.config/scr33ny/config.toml
+```
+
+---
+
+## Screensaver types
+
+### blank *(default)*
+
+Pure black. Best for OLED.
+
+```toml
+[screensaver]
+type = "blank"
+```
+
+### gif
+
+Animated GIF, looped.
+
+```toml
+[screensaver]
+type  = "gif"
+path  = "~/.config/scr33ny/cat.gif"
+scale = "fit"                        # fit | fill | original
+```
+
+### image
+
+Static image — PNG, JPEG, BMP, WebP.
+
+```toml
+[screensaver]
+type  = "image"
+path  = "~/.config/scr33ny/wallpaper.png"
+scale = "fill"
+```
+
+### text
+
+Text with animation.
+
+```toml
+[screensaver]
+type      = "text"
+content   = "scr33ny"
+font_size = 96.0
+color     = "#ffffff"
+animation = "float"                  # float | typewriter | fade
+```
+
+| Animation | Description |
+|-----------|-------------|
+| `float` | Lissajous orbit — smooth, non-repeating, maximum OLED protection |
+| `typewriter` | Types characters one by one, then restarts |
+| `fade` | Fade in → hold → fade out cycle |
+
+---
+
+## Widgets
+
+Each widget is a `[[widgets]]` block in your config.
+
+### Clock
+
+```toml
+[[widgets]]
+type         = "clock"
+style        = "digital"             # digital | analog
+font_size    = 72.0
+color        = "#ffffff"
+show_seconds = true
+
+[widgets.position]
+x = "center"                         # left | center | right | <0-100>
+y = "center"                         # top  | center | bottom | <0-100>
+```
+
+### Date
+
+```toml
+[[widgets]]
+type      = "date"
+font_size = 28.0
+color     = "#888888"
+format    = "%A, %B %d"              # strftime format
+
+[widgets.position]
+x = "center"
+y = 62.0                             # 62% from top
+```
+
+### Weather
+
+Requires a free [OpenWeatherMap](https://openweathermap.org/api) API key.
+
+```toml
+[[widgets]]
+type      = "weather"
+api_key   = "YOUR_KEY_HERE"
+location  = "Moscow"
+units     = "metric"                 # metric (°C) | imperial (°F)
+font_size = 22.0
+color     = "#cccccc"
+
+[widgets.position]
+x = "right"
+y = "top"
+```
+
+Weather refreshes every 30 minutes in the background.
+
+---
+
+## Anti burn-in
+
+Two layers of protection:
+
+1. **Screensaver content moves** — `float` animation follows a Lissajous curve so the same pixel is never lit for long.
+2. **Global pixel shift** — the entire frame is offset by a few pixels every N seconds, cycling through 4 corner positions.
+
+```toml
+[display]
+burn_shift     = 2     # pixels to shift
+shift_interval = 120   # seconds between shifts
+```
+
+---
+
+## Idle daemon
+
+### With swayidle/hypridle/other idle (recommended)
+
+Example:
+
+```bash
+# ~/.config/sway/config
+exec swayidle -w \
+  timeout 300 'scr33ny' \
+  resume   'killall scr33ny'
+```
+
+### Built-in daemon
+
+```toml
+[daemon]
+enabled      = true
+idle_timeout = 300
+```
+
+```bash
+scr33ny daemon
+```
+
+Uses `swayidle` if available; falls back to a simple sleep loop otherwise.
+
+---
+
+## Fonts
+
+scr33ny searches common system font paths automatically (DejaVu, Noto, Liberation, Ubuntu, Hack, FreeSans, user fonts in `~/.local/share/fonts/`).
+
+If no font is found:
+
+```bash
+# Arch Linux
+sudo pacman -S ttf-dejavu
+
+# Ubuntu / Debian
+sudo apt install fonts-dejavu
+```
+
+---
+
+## Full config reference
+
+See [docs/config.md](docs/config.md).
+
+---
+
+## Project structure
+
+```
+src/
+├── main.rs              CLI entry point
+├── config.rs            TOML config (serde)
+├── canvas.rs            Pixel buffer, drawing primitives, font loading
+├── app.rs               Event loop, render orchestration
+├── screensaver/
+│   ├── blank.rs         Pure black
+│   ├── gif.rs           GIF animation (frame timing)
+│   ├── image_ss.rs      Static image
+│   └── text.rs          Text animations
+└── widget/
+    ├── clock.rs         Digital and analog clock
+    ├── date.rs          Date display
+    └── weather.rs       OpenWeatherMap widget (async)
+```
+
+---
+
+## License
+
+MIT