diff --git a/README.md b/README.md
new file mode 100644
index 0000000..a4be75d
--- /dev/null
+++ b/README.md
@@ -0,0 +1,113 @@
+# VidFlow
+
+A personal MTV-style music video TV channel that runs entirely in your browser. Add YouTube playlists as channels, flip between them like cable TV, and let it run in the background. Late 90s / TRL-era aesthetic.
+
+**One file. No build step. No server required.**
+
+---
+
+## Quick Start
+
+### Option A — Open locally (simplest)
+
+YouTube's IFrame API requires an HTTP origin, so you can't just double-click the file. Serve it with Python:
+
+```bash
+python3 -m http.server 8080
+```
+
+Then open **http://localhost:8080/vidflow.html**
+
+### Option B — Drop it anywhere
+
+Upload `vidflow.html` to any static host — GitHub Pages, Netlify, Cloudflare Pages, your own web server. No configuration needed. It's a single file.
+
+---
+
+## First-time Setup
+
+VidFlow will walk you through two things on first launch:
+
+### 1. YouTube Data API key
+
+You need a free API key to search for playlists. It takes about 2 minutes:
+
+1. Go to [Google Cloud Console](https://console.cloud.google.com/)
+2. Create a project (or use an existing one)
+3. Enable **YouTube Data API v3**
+4. Go to **Credentials → Create Credentials → API key**
+5. Copy the key — paste it into the setup screen
+
+> The key is stored in your browser's localStorage only. It never leaves your machine.
+
+### 2. Add your first channel
+
+Each "channel" is a YouTube playlist. You can:
+- **Search** for a playlist by name
+- **Paste** a playlist URL or ID directly
+
+Add a few channels and you're watching.
+
+---
+
+## Features
+
+| Feature | How it works |
+|---|---|
+| **Channel surfing** | Click channel tabs or use `[` / `]` keyboard shortcuts |
+| **Idle / broadcast mode** | UI hides after 3 seconds of inactivity — just the video |
+| **Pop-out player** | Detach into a small floating window (shares your channels) |
+| **Shuffle** | On by default — plays a random video from the playlist |
+| **Now playing** | Artist + title ticker scrolls across the bottom |
+| **PWA** | Add to home screen on mobile for a full-screen TV experience |
+
+### Keyboard shortcuts
+
+| Key | Action |
+|---|---|
+| `Space` | Play / pause |
+| `[` / `]` | Previous / next channel |
+| `↑` / `↓` | Volume up / down |
+| `←` / `→` | Previous / next video in playlist |
+| `M` | Mute toggle |
+| `F` | Fullscreen |
+
+---
+
+## Hosting on Gitea / GitHub Pages
+
+Since VidFlow is a single HTML file, deploying is just copying the file:
+
+**GitHub Pages**: push to a repo, enable Pages from the repo settings, visit `https://yourusername.github.io/vidflow/vidflow.html`
+
+**Any static host**: upload `vidflow.html` — done.
+
+---
+
+## Customizing
+
+Open `vidflow.html` in any text editor. The design tokens are CSS custom properties near the top of the `<style>` block:
+
+```css
+--bg: #06060f        /* page background */
+--accent: #ff2200    /* red highlights */
+--accent2: #00d4ff   /* cyan highlights */
+```
+
+Change them to make it your own.
+
+---
+
+## Privacy
+
+- Your API key and channel list live in `localStorage` in your browser only
+- No data is sent anywhere except directly to the YouTube APIs (Google's servers)
+- No analytics, no tracking, no backend
+
+---
+
+## Requirements
+
+- A modern browser (Chrome, Firefox, Safari, Edge)
+- A YouTube Data API v3 key (free tier is plenty for personal use)
+- An HTTP server for local use (Python's built-in one works great)