diff --git a/README.md b/README.md
new file mode 100644
index 0000000..482b976
--- /dev/null
+++ b/README.md
@@ -0,0 +1,90 @@
+# MBID Poller
+
+This project provides a polling mechanism, packaged in a **Docker container**, to routinely check the MusicBrainz ID (MBID) status for items and then optionally trigger a search in a **Lidarr** instance.
+
+---
+
+## 💡 Acknowledgements
+
+The core logic for the polling mechanism in this project is based on an existing script generously shared by GitHub user **kchiem**.
+
+We are utilizing and adapting the Perl script found in the following public Gist:
+
+* **Original Script:** `kchiem/lidarr-ping.dist`
+* **Link:** https://gist.github.com/kchiem/eb998ac3c6f5a96cbec03b8e8c3b21a6
+
+We appreciate kchiem's contribution to the community!
+
+---
+
+## 🚀 Setup and Usage
+
+This project is designed to run as a service alongside a **Lidarr** instance using Docker Compose.
+
+### 1. Prerequisites
+
+Before starting, ensure you have:
+
+1.  **Docker** and **Docker Compose** installed.
+2.  A running **Lidarr** instance.
+3.  The project files (`Dockerfile`, `poller.pl`, `docker-compose.yaml`, etc.) in a single directory.
+
+### 2. Configure Docker Compose
+
+The `mbid-poller` container needs to communicate with your Lidarr instance.
+
+1.  **Rename the Example:** Rename the provided `docker-compose.yaml.example` to `docker-compose.yaml`.
+2.  [cite_start]**Network Setup:** Ensure the `lidarr` and `mbid-poller` services are on the **same Docker network** (e.g., `example_network`)[cite: 4, 5]. If you use a different setup (like host network), update `LIDARR_BASE` accordingly.
+3.  [cite_start]**Lidarr Base URL:** Verify the `LIDARR_BASE` environment variable in the `mbid-poller` service points to your Lidarr instance[cite: 5].
+
+    ```yaml
+    # Example for the default setup:
+    - LIDARR_BASE=http://lidarr:8686 
+    ```
+
+### 3. Choose the MBID Input Source
+
+[cite_start]The `poller.pl` script supports three different ways to provide MBIDs, in order of priority[cite: 5, 6]:
+
+| Environment Variable | Priority | Description |
+| :--- | :--- | :--- |
+| `MBID_API_URL` | **1st** (Highest) | A URL that returns a JSON array of objects, each containing a `foreignId` field. |
+| `MBID_JSON_FILE` | **2nd** | A path to a local JSON file (like `ids.json`) containing the MBID array. |
+| `MBID_URL` | **3rd** (Lowest) | A single MusicBrainz URL or ID to process. |
+
+[cite_start]In your `docker-compose.yaml`, **only one** of these should be uncommented and set[cite: 5, 6, 7].
+
+#### A. Using a JSON File (Recommended for simple setups)
+
+1.  [cite_start]Place your list of IDs in an `ids.json` file in the project directory (or adjust the volume mount)[cite: 7].
+2.  In `docker-compose.yaml`, **comment out** `MBID_API_URL` and **uncomment** `MBID_JSON_FILE`:
+
+    ```yaml
+    # ... mbid-poller environment section
+    environment:
+      # ...
+      - LIDARR_BASE=http://lidarr:8686
+      # - MBID_API_URL= 
+      - MBID_JSON_FILE=/config/ids.json
+      # - MBID_URL=... 
+    volumes:
+      - ./ids.json:/config/ids.json:ro # Maps your local file into the container
+    ```
+
+### 4. Build and Run
+
+With your files and `docker-compose.yaml` configured, you can build and run the poller.
+
+1.  [cite_start]**Build the Container:** This compiles the Perl dependencies using the `Dockerfile`[cite: 1, 2, 3].
+
+    ```bash
+    docker compose build mbid-poller
+    ```
+
+2.  [cite_start]**Run the Poller:** Since the `restart` policy is set to `"no"`[cite: 7], this command will run the script once and exit.
+
+    ```bash
+    docker compose up mbid-poller
+    ```
+
+The script will fetch the IDs, then loop through them, pinging the external MusicBrainz API until a successful response is received. It then outputs a Lidarr search URL for you to manually or automatically trigger the import in Lidarr.
\ No newline at end of file