combor · Oct 1, 2026 · Oct 1, 2026 · Oct 1, 2026
diff --git a/README.md b/README.md
@@ -1,3 +1,10 @@
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="docs/images/logo-dark.svg">
+    <img src="docs/images/logo-light.svg" width="104" alt="">
+  </picture>
+</p>
+
 <h1 align="center">magnetowid</h1>
 
 <p align="center">
@@ -6,23 +13,56 @@
 
 <p align="center">
   <a href="https://github.com/combor/magnetowid/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/combor/magnetowid/ci.yml?branch=main&amp;event=push&amp;style=flat-square&amp;label=CI" alt="CI status"></a>
-  <a href="LICENSE"><img src="https://img.shields.io/badge/License-BSD--3--Clause-blue?style=flat-square" alt="License: BSD-3-Clause"></a>
   <a href="https://github.com/combor/magnetowid/releases/latest"><img src="https://img.shields.io/github/v/release/combor/magnetowid?style=flat-square" alt="Latest release"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-BSD--3--Clause-blue?style=flat-square" alt="License: BSD-3-Clause"></a>
 </p>
 
 <p align="center">
   <a href="#quick-start">Quick start</a> ·
-  <a href="#how-it-works">How it works</a> ·
-  <a href="docs/usage.md#configuration">Configuration</a> ·
-  <a href="docs/usage.md#troubleshooting">Troubleshooting</a> ·
-  <a href="https://github.com/combor/magnetowid/issues">Report an issue</a>
+  <a href="#connect-sonarr-and-radarr">Connect your apps</a> ·
+  <a href="#web-interface">Web interface</a> ·
+  <a href="docs/usage.md">Documentation</a> ·
+  <a href="docs/usage.md#troubleshooting">Troubleshooting</a>
 </p>
 
-magnetowid searches and downloads video-on-demand movies and series through
-Sonarr and Radarr. It provides a Newznab indexer and a SABnzbd-compatible
-download client. No separate SABnzbd installation is needed.
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="docs/images/queue-dark.png">
+    <img src="docs/images/queue-light.png" alt="The magnetowid queue: an episode downloading at 42%, with four more downloads waiting, one of them paused">
+  </picture>
+</p>
+
+magnetowid brings video-on-demand sites to Sonarr and Radarr. Search for a
+series or a film as you always do, and it arrives in your library as an MP4
+file, with subtitles.
+
+To your apps it is an ordinary indexer and download client: a Newznab indexer
+for each site, and a SABnzbd-compatible client that does the downloading
+itself. No separate SABnzbd installation is needed.
+
+## Supported sites
+
+| Site | Indexer | Good to know |
+|---|---|---|
+| **TVP VOD** | `/tvp` | Polish series and films. [TVP VOD notes](internal/provider/tvp/README.md) |
+| **BBC iPlayer** | `/bbc` | Streams need a UK connection. [BBC iPlayer notes](internal/provider/bbc/README.md) |
 
-Supported: **TVP VOD** and **BBC iPlayer**.
+Only what a site offers for free is found: DRM-protected, paid and
+region-blocked streams are left out of the results.
+
+## What you get
+
+- **Search and RSS.** Sonarr and Radarr search each site and pick up new
+  episodes and newly available films on their own.
+- **Releases named like any other.** Names carry the resolution, codecs and
+  audio language, so your quality and language profiles keep working.
+- **Subtitles.** Saved beside the video as SRT, labelled with their language.
+- **Downloads that pick up where they stopped.** Pause one, restart
+  magnetowid or lose the connection, and it continues from the last segment.
+- **A web interface.** Watch the queue, pause and remove downloads, and browse
+  the history.
+- **Overrides.** When a title is missed or episodes are paired wrongly,
+  correct the match yourself.
 
 ## How it works
 
@@ -36,10 +76,11 @@ flowchart LR
 
 ## Quick start
 
-Install [Docker with Compose](https://docs.docker.com/compose/install/). The
+You need [Docker with Compose](https://docs.docker.com/compose/install/). The
 container image includes ffmpeg.
 
-Download the [Compose configuration](compose.yaml) and environment template:
+**1. Get the configuration.** Download the [Compose file](compose.yaml) and the
+environment template:
 
 ```sh
 mkdir magnetowid
@@ -49,55 +90,78 @@ curl -fsSL https://raw.githubusercontent.com/combor/magnetowid/main/.env.example
 mkdir -p downloads
 ```
 
-Edit `.env` before starting:
+**2. Edit `.env`.**
 
-- Set `MAGNETOWID_API_KEY` to a long, random key. Use this same key in both Sonarr/Radarr connections.
-- Set `MAGNETOWID_DOWNLOAD_PATH` to your shared download folder, or keep `./downloads`.
-- On Linux, set `MAGNETOWID_UID` and `MAGNETOWID_GID` to the IDs of the account that owns
-  that folder. Run `id -u` and `id -g` to check your current account's IDs.
+| Setting | What to enter |
+|---|---|
+| `MAGNETOWID_API_KEY` | A long, random key. Sonarr and Radarr use the same one. |
+| `MAGNETOWID_DOWNLOAD_PATH` | Your shared download folder, or keep `./downloads`. |
+| `MAGNETOWID_UID`, `MAGNETOWID_GID` | On Linux, the IDs of the account that owns that folder. `id -u` and `id -g` show yours. |
 
-Start magnetowid:
+**3. Start magnetowid.**
 
 ```sh
 docker compose up -d
 ```
 
-Compose pulls `ghcr.io/combor/magnetowid:latest` and exposes the APIs on port **8484**.
-For a native installation, see the
-[Linux service](docs/usage.md#linux-service) or
-[building from source](docs/usage.md#build-from-source).
+Compose pulls `ghcr.io/combor/magnetowid:latest` and serves everything on port
+**8484**.
+
+Not using Docker? Install the [Linux service](docs/usage.md#linux-service) from
+the `.deb`, `.rpm` or AUR package, or
+[build from source](docs/usage.md#build-from-source).
 
 ## Connect Sonarr and Radarr
 
-In each app, add these two connections using the API key from `.env`:
+Open `http://<magnetowid-host>:8484/`, sign in with the API key and go to
+**Setup**. The page lists the values for your install, ready to copy.
 
-1. **Download client:** open **Settings → Download Clients**, add **SABnzbd** and
-   name it `magnetowid`. Enter magnetowid's host and port `8484`. Set the
-   category to `tv` in Sonarr or `movies` in Radarr.
-2. **Indexer:** open **Settings → Indexers** and add **Newznab**, one per site.
-   For TVP VOD, use `http://<magnetowid-host>:8484/tvp` with API path `/api`;
-   for BBC iPlayer, `http://<magnetowid-host>:8484/bbc`. Select categories
-   `5000, 5040` in Sonarr or `2000, 2040` in Radarr. Set **Download Client** to
-   the `magnetowid` client from step 1.
-3. **Test** and **Save** both connections, then search from Sonarr or Radarr.
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="docs/images/setup-dark.png">
+    <img src="docs/images/setup-light.png" width="760" alt="The Setup page, listing the download client's host, port and category, and each site's indexer URL, API path and categories">
+  </picture>
+</p>
 
-Use a host address reachable from your apps, and make sure both can read the
-download folder. See [Docker networking and shared downloads](docs/usage.md#docker-networking-and-shared-downloads)
-for container hostnames, volume mounts and Remote Path Mappings.
+In each app, add two connections with the API key from `.env`:
+
+1. **Download client.** Under **Settings → Download Clients**, add **SABnzbd**
+   and name it `magnetowid`. Enter magnetowid's host and port `8484`. Set the
+   category to `tv` in Sonarr or `movies` in Radarr.
+2. **Indexers.** Under **Settings → Indexers**, add **Newznab**, one for each
+   site: `http://<magnetowid-host>:8484/tvp` for TVP VOD and
+   `http://<magnetowid-host>:8484/bbc` for BBC iPlayer, both with API path
+   `/api`. Select categories `5000, 5040` in Sonarr or `2000, 2040` in Radarr,
+   and set **Download Client** to the `magnetowid` client from step 1.
+3. **Test** and **Save** both, then search from Sonarr or Radarr.
+
+> [!NOTE]
+> Use a host address your apps can reach, and make sure they can read the
+> download folder. [Docker networking and shared downloads](docs/usage.md#docker-networking-and-shared-downloads)
+> covers container hostnames, volume mounts and Remote Path Mappings.
 
 ## Web interface
 
-Open `http://<magnetowid-host>:8484/` and sign in with the API key to see the
-queue and history, to pause, resume or remove downloads, and to correct matches
-with overrides. Its Setup page lists the values to enter in Sonarr and Radarr.
-See [Web interface](docs/usage.md#web-interface).
+Open `http://<magnetowid-host>:8484/` and sign in with the API key.
+
+| Page | What it is for |
+|---|---|
+| **Queue** | The running download's progress and time left, and what is up next. Pause, resume or remove downloads. |
+| **History** | Finished and failed downloads from the last 30 days, with the error of any that failed. |
+| **Overrides** | Forms to [correct a match](docs/usage.md#correcting-matches) for a series or a film. |
+| **Setup** | The values to enter in Sonarr and Radarr, and whether each site is reachable. |
+
+See [Web interface](docs/usage.md#web-interface) for the details.
+
+## Documentation
 
-## Help and contributing
+- [Setup and configuration](docs/usage.md): installation options and every setting.
+- [Correcting matches](docs/usage.md#correcting-matches): overrides for titles, seasons and single episodes.
+- [Troubleshooting](docs/usage.md#troubleshooting): help with connections, downloads and imports.
+- [Limitations](docs/usage.md#limitations): what magnetowid can't do.
+- [Adding a site](docs/usage.md#adding-a-site) and the [development guide](docs/usage.md#development).
 
-- [Setup and configuration](docs/usage.md): installation options and settings.
-- [Troubleshooting](docs/usage.md#troubleshooting): help with connections and downloads.
-- [GitHub Issues](https://github.com/combor/magnetowid/issues): report a bug or suggest an improvement.
-- [Add a provider](docs/usage.md#adding-a-site) or use the [development guide](docs/usage.md#development).
+Found a bug or missing something? [Open an issue](https://github.com/combor/magnetowid/issues).
 
 ## License
 

diff --git a/docs/images/logo-dark.svg b/docs/images/logo-dark.svg
diff --git a/docs/images/logo-light.svg b/docs/images/logo-light.svg
diff --git a/docs/images/queue-dark.png b/docs/images/queue-dark.png
diff --git a/docs/images/queue-light.png b/docs/images/queue-light.png
diff --git a/docs/images/setup-dark.png b/docs/images/setup-dark.png
diff --git a/docs/images/setup-light.png b/docs/images/setup-light.png
diff --git a/docs/usage.md b/docs/usage.md
@@ -249,8 +249,8 @@ An override replaces magnetowid's matching for everything it covers,
 including its checks. An episode it places where the site has none, or only a
 paid one, gets no release; other episodes are matched as before. Overrides
 apply to searches and RSS, including the title searches Sonarr makes when its
-TVDB ID search finds nothing. Specials are not supported. See each site's
-notes for its numbering.
+TVDB ID search finds nothing. Season rules cover numbered seasons only; pin
+specials one by one, as `S00E01`. See each site's notes for its numbering.
 
 ## Docker networking and shared downloads