docs: rewrite README with features, architecture, and dev setup (#43)

Replace the placeholder README with comprehensive documentation covering
install instructions, feature list, architecture overview, development
prerequisites, build/test/lint commands, data locations, and project
structure. Add CI and Release badges.

README.md

@@ -1,35 +1,129 @@
 # YellowJacket
 
-How music was meant to bee.
+[![CI](https://github.com/onion-4-dinner/yellowjacket/actions/workflows/ci.yml/badge.svg)](https://github.com/onion-4-dinner/yellowjacket/actions/workflows/ci.yml)
+[![Release](https://github.com/onion-4-dinner/yellowjacket/actions/workflows/release.yml/badge.svg)](https://github.com/onion-4-dinner/yellowjacket/actions/workflows/release.yml)
+
+Music how it was meant to bee.
+
+YellowJacket is a cross-platform desktop music player built with Go and web technologies. It focuses on local music library management with a clean, responsive interface.
 
 ## Install
 
-You can grab the latest release [here](https://github.com/LJ-Software/yellowjacket/releases/latest)
+Grab the latest release for your platform:
+
+**[Download Latest Release](https://github.com/onion-4-dinner/yellowjacket/releases/latest)**
+
+| Platform | Binary |
+|----------|--------|
+| Linux | `yellowjacket-linux-amd64` |
+| macOS | `yellowjacket-darwin-universal.app.zip` (Apple Silicon + Intel) |
+| Windows | `yellowjacket-windows-amd64.exe` |
 
 ## Features
 
-TODO: add feature list and screenshots here
+**Playback**
+- Play, pause, seek, and volume control with mute toggle
+- Support for MP3, FLAC, OGG Vorbis, and WAV
+- Queue management with add, remove, reorder, and play-next
+- Shuffle mode (Fisher-Yates) and repeat modes (off, all, one)
+- Session persistence -- resumes volume, track, and seek position on restart
+
+**Library**
+- Concurrent library scanning with automatic metadata extraction
+- ID3v2, Vorbis Comments, and other tag format support
+- Embedded cover art extraction with content-hash deduplication
+- Incremental sync -- only processes new or changed files
+- Orphan cleanup for deleted files
+
+**Interface**
+- Album cover grid view and track list view
+- Now playing display with cover art
+- Resizable sidebar navigation
+- Slide-out queue panel
+- Context menus for tracks and albums (play, add to queue, play next)
+- Settings page for library directory configuration
+
+## Architecture
+
+YellowJacket uses the [Wails v2](https://wails.io/) framework to bridge a Go backend with a TypeScript/[Lit](https://lit.dev/) frontend running in a native webview.
+
+- **Go backend** -- audio decoding and playback ([beep](https://github.com/gopxl/beep)), library scanning, SQLite database, cover art serving, TOML configuration
+- **TypeScript frontend** -- Lit web components, singleton stores with reactive controllers, [Web Awesome](https://www.webawesome.com/) UI components
+- **Communication** -- bidirectional event system via Wails runtime; backend is the source of truth
+- **Database** -- SQLite (pure-Go driver) with type-safe queries generated by [sqlc](https://sqlc.dev/); MusicBrainz-style data model (artists, artist credits, recordings, release groups)
+- **Config page** -- HTMX-based, loads HTML fragments rendered by Go [templ](https://templ.guide/) templates
 
 ## Development
 
-Development documentation can be found [here](./docs/dev/overview.md).
-
 ### Prerequisites
 
-1. First, you will need Go installed.
+| Tool | Version |
+|------|---------|
+| Go | 1.25+ |
+| Node.js | 22+ |
+| pnpm | 10+ |
+| Wails CLI | v2 (`go install github.com/wailsapp/wails/v2/cmd/wails@latest`) |
 
-2. Then, you will need the `wails` cli tool.
+**Linux system dependencies:**
+```bash
+sudo apt-get install libasound2-dev libgtk-3-dev libwebkit2gtk-4.1-dev
+```
 
-    Install it with
+On macOS and Windows, no additional system dependencies are needed. Run `wails doctor` to verify your environment.
 
-    ```shell
+### Build & Run
-    go install github.com/wailsapp/wails/v2/cmd/wails@latest
-    ```
 
-3. After installing the Wails CLI you may need some build dependencies.
+```bash
-    View the missing Wails dependencies by running `wails doctor`.
+make setup        # Install git hooks (lefthook)
-    Using your system's package manager, install the missing dependencies.
+make dev          # Development with hot-reload
+make build-dev    # Debug build
+make build-prod   # Production build (obfuscated + UPX compressed)
+make generate     # Run code generators (sqlc, templ)
+```
 
-### Dev Server
+### Testing
 
-To run the Wails hot-reloading dev server, run `make dev` in the root of the project.
+```bash
+make test         # All tests (race detector, no cache, 2min timeout)
+
+# Run tests manually (build tag required):
+go test -tags webkit2_41 ./backend/player/                           # Single package
+go test -tags webkit2_41 -run TestFunctionName ./backend/player/     # Single test
+go test -tags webkit2_41 -v -run TestFunctionName ./backend/player/  # Verbose
+```
+
+### Linting
+
+```bash
+make lint         # golangci-lint (v2 config, strict rules)
+```
+
+### Data Locations
+
+| | Linux | macOS | Windows |
+|---|---|---|---|
+| Config | `~/.config/yellowjacket/` | `~/.config/yellowjacket/` | `%LOCALAPPDATA%\yellowjacket\config` |
+| Data/DB | `~/.local/share/yellowjacket/` | `~/.local/share/yellowjacket/` | `%LOCALAPPDATA%\yellowjacket\data` |
+
+### Project Structure
+
+```
+backend/           Go backend
+  player/          Audio playback (beep)
+  queue/           Queue management, shuffle, repeat
+  library/         Library scanning, metadata extraction, cover art
+  metadata/        Audio decoding and tag extraction
+  database/        SQLite connection, sqlc-generated queries
+  config/          TOML config, HTTP handler for settings page
+  events/          Event name constants (mirrored in frontend)
+  models/          Shared data types (Album, Track, Artist)
+  system/          OS-specific paths
+frontend/src/      TypeScript/Lit frontend
+  components/      UI components (player, sidebar, track list, cover grid, queue)
+  store/           Singleton stores and reactive controllers
+  pages/           Config page (HTMX entry point)
+internal/dev/      Build-tag dev/prod detection
+test_data/         Audio test fixtures
+```
+
+Further development documentation is available in [`docs/dev/`](./docs/dev/overview.md).