From c2b032ea0c830dd3983aa0fe76f000b0b9a38fdb Mon Sep 17 00:00:00 2001
From: cottongin <cottongin@users.noreply.github.com>
Date: Thu, 12 Mar 2026 01:43:11 -0400
Subject: [PATCH] docs: add README with quick start and API reference

Made-with: Cursor
---
 README.md | 46 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 46 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..38cec4c
--- /dev/null
+++ b/README.md
@@ -0,0 +1,46 @@
+# NtR SoundCloud Fetcher
+
+Fetches SoundCloud likes from NicktheRat's profile, builds weekly playlists
+aligned to the Wednesday 22:00 ET show schedule, and serves them via a JSON
+API.
+
+## Quick Start
+
+```bash
+pip install -e ".[dev]"
+export NTR_ADMIN_TOKEN="your-secret-here"
+ntr-fetcher
+```
+
+The API starts at `http://127.0.0.1:8000`.
+
+## API
+
+| Endpoint | Description |
+|----------|-------------|
+| `GET /playlist` | Current week's playlist |
+| `GET /playlist/{n}` | Track at position n |
+| `GET /shows` | List all shows |
+| `GET /shows/{id}` | Specific show's playlist |
+| `GET /health` | Service health check |
+| `POST /admin/refresh` | Trigger SoundCloud fetch (token required) |
+
+## Configuration
+
+Environment variables (prefix `NTR_`):
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `NTR_PORT` | `8000` | API port |
+| `NTR_HOST` | `127.0.0.1` | Bind address |
+| `NTR_DB_PATH` | `./ntr_fetcher.db` | SQLite path |
+| `NTR_POLL_INTERVAL_SECONDS` | `3600` | Poll frequency |
+| `NTR_ADMIN_TOKEN` | (required) | Admin bearer token |
+| `NTR_SOUNDCLOUD_USER` | `nicktherat` | SoundCloud user |
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```