diff --git a/README.md b/README.md
new file mode 100644
index 0000000..6f7b058
--- /dev/null
+++ b/README.md
@@ -0,0 +1,33 @@
+# lockstep-jukebox
+
+Gradle project containing **jukebox**, an Android library that implements the **data layer** for a music player: it syncs playlist and track **metadata** from the Lockstep Spotify wrapper API (`https://api.lockstep.at`) into a local **SQLite** database (via Room), so the app can read playlists and tracks offline after sync.
+
+Repository layout:
+
+- **`jukebox/`** — Android library (Java, Retrofit, Gson, Room).
+- **`docs/playlists.md`** — HTTP contract for `GET /playlists` and `GET /playlists/{id}`.
+- **`schema/playlist_cache.sql`** — reference schema for the on-device cache tables.
+
+The library does **not** handle Spotify login, audio playback, or full Spotify API modeling—only what’s needed to cache the metadata described in the docs.
+
+## Main entry points
+
+| Entry | Role |
+| --- | --- |
+| **`Jukebox.playlistRepository(Context, Interceptor)`** | Convenience factory. Builds `DefaultPlaylistRepository` with default base URL `https://api.lockstep.at/`. Optional overload passes a custom **`baseUrl`**. You supply an **`Interceptor`** so session cookies, `Authorization`, or other headers stay in the host app. |
+| **`DefaultPlaylistRepository.create(...)`** | Same wiring as `Jukebox`; use when you prefer a static factory on the concrete type. |
+| **`PlaylistRepository`** | Primary API surface after construction: **`syncInitial()`** (full refresh), **`syncDelta(retainRemovedPlaylists)`** (incremental sync using `snapshot_id`), **`observePlaylists()`** / **`getPlaylists()`**, **`observeTracks(playlistId)`** / **`getTracks(playlistId)`**. Sync methods **block** and perform I/O—call them off the main thread. Observation returns **`LiveData`** for lifecycle-friendly UI updates. |
+| **`LockstepPlaylistClient`** | Interface implemented by **`PlaylistRemoteClient`**. Lets tests or advanced setups swap the network backend without changing **`SyncCoordinator`**. |
+
+Errors from the API’s `{ "ok": false, "error": "..." }` shape are thrown as **`LockstepApiException`**. Network failures use **`IOException`**.
+
+## Building
+
+From the repo root (with `ANDROID_HOME` / `local.properties` **`sdk.dir`** set):
+
+```bash
+./gradlew :jukebox:assembleDebug
+./gradlew :jukebox:testDebugUnitTest
+```
+
+On Windows, use `gradlew.bat` instead of `./gradlew`.