diff --git a/README.md b/README.md
new file mode 100644
index 0000000..945e49c
--- /dev/null
+++ b/README.md
@@ -0,0 +1,63 @@
+# livetv
+
+Self-hosted live-TV stack: an Xtream IPTV source is mirrored through this VPS and
+served to **Jellyfin** so it can be watched ad-free in Jellyfin's apps.
+
+```
+Xtream provider (API only)
+        │  player_api.php  (URL + username + password)
+        ▼
+   Dispatcharr        ← ingests via the Xtream API, regenerates a clean
+        │               HDHomeRun tuner + M3U + EPG
+        ▼
+    Jellyfin          ← Live TV: adds Dispatcharr as a tuner + guide
+        │
+        ▼
+  Jellyfin apps (HTTPS via Nginx Proxy Manager)
+```
+
+Both services run on the shared external Docker network **`proxy`**, where
+Nginx Proxy Manager (NPM) reaches them by name — no raw host ports are opened.
+
+## Services
+
+| Service      | Internal address        | Public (via NPM)                     |
+|--------------|-------------------------|--------------------------------------|
+| `jellyfin`   | `jellyfin:8096`         | `https://jellyfin.altricade.com`     |
+| `dispatcharr`| `dispatcharr:9191`      | `https://dispatcharr.altricade.com` (admin, behind an Access List) |
+
+## Deploy
+
+Pushing to `master` triggers `.forgejo/workflows/deploy.yaml`, which runs
+`docker compose up -d` on the VPS runner. The compose project name is pinned to
+`livetv` so the named volumes persist across deploys.
+
+```bash
+git add -A
+git commit -m "..."
+git push origin master
+```
+
+## NPM proxy hosts
+
+Create two hosts (both forward over the `proxy` network, scheme `http`, Websockets on, SSL via Let's Encrypt):
+
+- `jellyfin.altricade.com` → `jellyfin` : `8096`
+- `dispatcharr.altricade.com` → `dispatcharr` : `9191`  (add an **Access List** — this is the admin UI)
+
+## First-time configuration
+
+1. **Dispatcharr** (`https://dispatcharr.altricade.com`): create admin login →
+   add an **Xtream Codes** account (server URL + username + password) → let it
+   scan channels via the API → add the EPG source.
+2. **Jellyfin** (`https://jellyfin.altricade.com`): Dashboard → Live TV →
+   - Tuner Devices → add **HDHomeRun** `http://dispatcharr:9191` (or an M3U Tuner).
+   - TV Guide Data → add **XMLTV** using Dispatcharr's EPG URL.
+   - Refresh guide and map channels.
+
+## Notes
+
+- No credentials are stored in this repo. The Xtream login is entered in the
+  Dispatcharr UI and lives in the `dispatcharr_data` volume on the VPS.
+- Confirm the shared network is named `proxy` (`docker network ls`); adjust
+  `docker-compose.yaml` if NPM is on a different network.