diff --git a/README.md b/README.md
new file mode 100644
index 0000000..0cff35c
--- /dev/null
+++ b/README.md
@@ -0,0 +1,131 @@
+# ym-dl
+
+Yandex Music downloader — Go service for monitoring and downloading tracks/albums from Yandex Music for configured artists.
+
+## Features
+
+- **Token-only authentication** via Yandex Music OAuth token
+- **Artist monitoring** — periodic check for new tracks and albums
+- **Track & album download** with direct URL signing
+- **SQLite storage index** with migration from legacy JSON index
+- **Rich ID3 tags** — genre, comment, lyrics, publisher, ISRC, copyright, original year, encoded by
+- **High-resolution covers** (1000×1000) embedded in MP3 tags and saved as `cover.jpg`
+- **Idempotent downloads** — tracks are not re-downloaded
+- **Structured JSON logging** for Docker environments
+
+## Project structure
+
+```
+ym-dl/
+├── cmd/ym-dl/           # Main entry point
+├── internal/
+│   ├── config/          # Configuration loading (artist IDs, API credentials)
+│   ├── downloader/      # Download orchestration
+│   ├── monitor/         # Periodic check logic for new releases
+│   ├── storage/         # SQLite storage for downloaded tracks/albums
+│   └── yandex/          # Yandex Music API client wrapper
+├── Dockerfile           # Multi-stage build
+├── docker-compose.yml   # Service definition
+├── config.yaml.example  # Sample configuration
+├── docs/yandex-music.yaml   # Yandex Music OpenAPI spec
+└── README.md
+```
+
+## Configuration
+
+Create `config.yaml` based on `config.yaml.example`:
+
+```yaml
+yandex:
+  token: "oauth_token"           # Yandex Music OAuth token (required)
+
+artists:
+  - id: 12345                    # Artist ID from Yandex Music
+  - id: 67890
+
+storage:
+  path: "/data/music"            # Local path for downloads
+  organize: true                 # Organize into Artist/Album/Track structure
+
+monitor:
+  interval: "24h"                # Check interval (duration string, e.g. "24h", "6h30m")
+```
+
+### Authentication
+
+Only OAuth token is supported. Obtain a token from Yandex OAuth and set it in `yandex.token`.
+
+## Build & Run
+
+### Locally
+
+```bash
+go build -o bin/ym-dl ./cmd/ym-dl
+go run ./cmd/ym-dl --config config.yaml
+```
+
+### Docker Compose
+
+```bash
+docker compose up --build
+```
+
+Mount your config at `/config.yaml` and storage at `/data`:
+
+```yaml
+# docker-compose.yml override
+volumes:
+  - ./config.yaml:/config.yaml
+  - ./data:/data
+```
+
+## Development
+
+```bash
+# Run tests
+go test ./...
+
+# Run single test
+go test -v -run TestName ./internal/...
+
+# Lint
+golangci-lint run
+
+# Build
+go build -o bin/ym-dl ./cmd/ym-dl
+```
+
+## Storage
+
+The download index is stored in SQLite (`index.db` inside the storage path). On first launch, an existing legacy `.index.json` is automatically migrated to SQLite and removed.
+
+Albums are considered fully downloaded only when all expected tracks (per `track_count` from Yandex API) are present in the index. Compilation albums where the artist appears on only some tracks are downloaded completely.
+
+## ID3 Tags
+
+MP3 files are tagged with:
+
+| Frame | Field | Source |
+|-------|-------|--------|
+| TIT2 | Title | track title |
+| TPE1 | Artist | all track artists |
+| TPE2 | Album Artist | album artist |
+| TALB | Album | album title |
+| TYER | Year | release year |
+| TCON | Genre | track/album genre |
+| TRCK | Track number | position in album |
+| TPOS | Disc number | volume in album |
+| TCOM | Composer | (reserved) |
+| TPUB | Publisher | album label |
+| TENC | Encoded by | "ym-dl" |
+| TCOP | Copyright | album catalog number |
+| TORY | Original year | release date year |
+| TSRC | ISRC | (reserved) |
+| COMM | Comment | album description |
+| USLT | Lyrics | track lyrics |
+| APIC | Cover art | 1000×1000 JPEG |
+| TXXX | Yandex IDs | track/album/artist IDs |
+
+## License
+
+Private project.
\ No newline at end of file