Add comprehensive README documentation

- Installation and usage instructions
- Complete keybinding reference
- Configuration examples
- Architecture overview
- Development guidelines

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

1 files changed, 103 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..9160dac
--- /dev/null
+++ b/README.md
@@ -0,0 +1,103 @@
+# Ghetto Blaster 📻
+
+A terminal-based podcast player with vim-style keybindings, built in Rust with ratatui.
+
+## Features
+
+- **TUI Interface**: Clean, terminal-based interface with vim-style navigation
+- **Podcast Feeds**: Subscribe to RSS/XML podcast feeds
+- **mpv Integration**: High-quality audio playback with on-screen controls
+- **Configuration**: YAML-based configuration file
+- **Cross-platform**: Works on macOS, Linux, and Windows
+
+## Prerequisites
+
+- **Rust**: Install from [rustup.rs](https://rustup.rs/)
+- **mpv**: Audio player (`brew install mpv` on macOS, `apt install mpv` on Ubuntu)
+
+## Installation
+
+```bash
+git clone https://github.com/xlgmokha/ghetto-blaster
+cd ghetto-blaster
+cargo build --release
+```
+
+## Usage
+
+```bash
+cargo run
+```
+
+On first run, it creates a config file at `~/.config/ghetto-blaster.yml` with some default feeds.
+
+### Keybindings
+
+**Feed List:**
+- `j`/`k` or `↓`/`↑` - Navigate feeds
+- `Enter` - Select feed and view episodes  
+- `r` - Refresh all feeds
+- `q` - Quit
+
+**Episode List:**
+- `j`/`k` or `↓`/`↑` - Navigate episodes
+- `Enter` or `Space` - Play episode
+- `h` or `←` or `Esc` - Back to feed list
+- `q` - Quit
+
+**During Playback (mpv controls):**
+- `Space` - Pause/unpause
+- `←`/`→` - Seek backward/forward 10s
+- `0`/`9` - Volume down/up
+- `m` - Mute
+- `q` - Stop
+
+## Configuration
+
+Edit `~/.config/ghetto-blaster.yml`:
+
+```yaml
+feeds:
+  "My Podcast": "https://example.com/feed.xml"
+  "Another Show": "https://another.example/rss"
+
+radio:
+  "CBC Radio": "https://radio-stream-url"
+  
+music_dirs:
+  - "~/Music"
+```
+
+## Architecture
+
+- **`main.rs`**: TUI setup and event loop
+- **`app.rs`**: Application state and navigation logic  
+- **`config.rs`**: YAML configuration management
+- **`feed.rs`**: RSS parsing and episode data
+- **`player.rs`**: mpv process management
+
+## Development
+
+```bash
+# Check compilation
+cargo check
+
+# Run with debug info
+RUST_LOG=debug cargo run
+
+# Run tests
+cargo test
+```
+
+## TODO
+
+- [ ] Search functionality
+- [ ] Download episodes for offline listening
+- [ ] Playback position saving/resuming
+- [ ] Episode marking (played/unplayed)
+- [ ] Background downloads
+- [ ] Playlist management
+
+## License
+
+MIT
\ No newline at end of file