diff --git a/README.md b/README.md
new file mode 100644
index 0000000..0363ab9
--- /dev/null
+++ b/README.md
@@ -0,0 +1,51 @@
+<div align="center">
+
+<h1>Drift</h1>
+
+### A music streaming client using Vim keybinds built in Rust.
+
+Stream your favourite music from YouTube Music — all in one client, in your terminal.
+
+</div>
+
+---
+
+<div align="center">
+  <img src="https://github.com/socatlolmeow/drift/blob/main/examples/showcase.gif" alt="Drift showcase" />
+</div>
+
+---
+
+## Features
+
+- **YouTube Music streaming** — search and stream tracks directly from YouTube Music via `yt-dlp` and `mpv`
+- **Vim-style keybinds** — navigate with `j`/`k`, enter commands with `:`, quit with `q`
+- **Queue management** — add, remove, reorder, and clear tracks in your queue
+- **Playlists** — save, load, append, and delete named playlists; import from YouTube/YouTube Music URLs
+- **Shuffle & repeat** — toggle shuffle and cycle through off / repeat-all / repeat-one modes
+- **Volume & seek control** — adjust volume and seek with configurable step sizes
+- **Session restore** — automatically restores your queue and playback position on next launch
+- **Artist search** — drill into an artist's discography from the results view
+- **Command palette** — full `:command` interface (`:search`, `:play`, `:volume`, `:seek`, `:save`, `:load`, `:import`, and more)
+- **Autoplay** — optionally keep playing through results when the queue ends
+- **TOML config** — persistent config at `~/.local/share/drift/config.toml`; comments are preserved across restarts
+
+---
+
+## Installation
+
+> **Not implemented yet.**
+>
+> Package manager installs are not available yet. Distro-specific instructions will be added here (Arch Linux, Void Linux, NixOS, Debian/Ubuntu, etc.) once packages are published.
+
+---
+
+## Star History
+
+[![Star History Chart](https://api.star-history.com/svg?repos=socatlolmeow/drift&type=Date)](https://star-history.com/#socatlolmeow/drift)
+
+---
+
+## License
+
+[Drift](https://github.com/socatlolmeow/drift) is FOSS, released under the [GNU General Public License version 3 or later](https://www.gnu.org/licenses/gpl-3.0.html).