diff --git a/README.md b/README.md
new file mode 100644
index 0000000..66bb38c
--- /dev/null
+++ b/README.md
@@ -0,0 +1,185 @@
+# lidarr-mb-gap
+
+A tool to identify missing albums on MusicBrainz from Deezer releases for artists monitored in Lidarr, and generate submission links for easy import.
+
+## Features
+
+- 🔍 **Automated Discovery**: Finds missing albums by comparing Lidarr monitored artists with Deezer releases via SAMBL
+- 📊 **Dual Reports**: Generates both JSON and interactive HTML reports
+- 🔗 **Submission Links**: Automatically generates a-tisket and Harmony links for MusicBrainz submissions
+- 🎯 **Smart Filtering**: 
+  - Identifies albums that need to be **added** to MusicBrainz (missing)
+  - Identifies albums that need to be **updated** (exist but need linking/updates)
+- 🎨 **Interactive HTML Report**: Filter by type (add/update) and by artist
+- 🐍 **Python-based**: Clean, functional codebase with proper logging
+- ❄️ **Nix Support**: Fully packaged with Nix flake for reproducible builds
+
+## Requirements
+
+- Lidarr instance with API access
+- SAMBL instance (defaults to `https://sambl.lioncat6.com`)
+- Python 3.8+ (or use Nix)
+
+## Installation
+
+### Using Nix (Recommended)
+
+```bash
+# Run directly
+nix run .#lidarr-mb-gap
+
+# Or build and install
+nix build .#lidarr-mb-gap
+nix profile install .#lidarr-mb-gap
+```
+
+### Development Setup
+
+```bash
+# Enter development shell
+nix develop
+
+# Run the script
+python src/main.py
+
+# Format code
+black src/
+```
+
+## Configuration
+
+Create a `.env` file in the project root:
+
+```env
+# Required
+LIDARR_URL=http://your-lidarr-instance:8686
+LIDARR_API_KEY=your-api-key-here
+
+# Optional
+SAMBL_URL=https://sambl.lioncat6.com
+MAX_ARTISTS=5  # Limit number of artists processed (0 = no limit)
+```
+
+### Getting Your Lidarr API Key
+
+1. Open Lidarr web interface
+2. Go to **Settings** → **General**
+3. Copy your **API Key**
+
+## Usage
+
+### Basic Usage
+
+```bash
+# Using Nix
+nix run .#lidarr-mb-gap
+
+# Or if installed
+lidarr-mb-gap
+```
+
+The script will:
+1. Fetch all artists from Lidarr with `monitorNewItems` set to "new" or "all"
+2. For each artist, query SAMBL to find missing albums on MusicBrainz
+3. Generate submission links (a-tisket and Harmony)
+4. Create two output files:
+   - `missing_albums.json` - Machine-readable JSON report
+   - `missing_albums.html` - Interactive HTML report with filters
+
+### Output Files
+
+#### `missing_albums.json`
+Contains structured data with:
+- `albums_to_add`: Albums not in MusicBrainz
+- `albums_to_update`: Albums that exist but need updates/linking
+- `summary`: Counts and totals
+
+#### `missing_albums.html`
+Interactive HTML report with:
+- Filter buttons for type (Add/Update/All)
+- Filter buttons for each artist
+- Clickable submission links (a-tisket and Harmony)
+- Direct links to Deezer and MusicBrainz
+
+## Project Structure
+
+```
+.
+├── src/
+│   ├── __init__.py
+│   ├── main.py              # Main application logic
+│   ├── html_report.py       # HTML report generation
+│   └── pyproject.toml      # Python package configuration
+├── flake.nix                # Nix flake definition
+├── .env                     # Environment variables (create this)
+└── README.md
+```
+
+## How It Works
+
+1. **Lidarr Integration**: Queries Lidarr API for monitored artists
+2. **Deezer Search**: Uses Deezer API to find artist IDs
+3. **SAMBL Comparison**: Calls SAMBL's `/api/compareArtistAlbums` endpoint to compare Deezer releases with MusicBrainz
+4. **Categorization**: 
+   - **Red status** or **no MBID** → Album to ADD
+   - **Orange status** → Album to UPDATE
+5. **Link Generation**: Creates submission links using:
+   - [a-tisket](https://atisket.pulsewidth.org.uk/) - For adding new releases
+   - [Harmony](https://harmony.pulsewidth.org.uk/) - For adding/updating releases
+
+## Logging
+
+The application uses Python's logging module with systemd-friendly output:
+- `[INFO]` - Informational messages
+- `[WARNING]` - Warnings (e.g., missing MusicBrainz ID)
+- `[ERROR]` - Errors (e.g., missing configuration, API failures)
+
+Perfect for running as a systemd service.
+
+## Example Output
+
+```
+[INFO] Fetching monitored artists from Lidarr...
+[INFO] Found 10 monitored artists
+[INFO] ================================================================================
+[INFO] Artist: Angus & Julia Stone
+[INFO] MusicBrainz ID: abc123-def456-...
+[INFO] Albums to ADD (3):
+[INFO]       📀 Life Is Strange
+[INFO]          Deezer: https://www.deezer.com/album/12345
+[INFO]          a-tisket: https://atisket.pulsewidth.org.uk/?url=...
+[INFO]          Harmony: https://harmony.pulsewidth.org.uk/release?url=...
+...
+```
+
+## Troubleshooting
+
+### "LIDARR_URL not set" or "LIDARR_API_KEY not set"
+- Ensure your `.env` file exists and contains the required variables
+- Check that the file is in the project root directory
+
+### "No artists found"
+- Verify that you have artists in Lidarr with `monitorNewItems` set to "new" or "all"
+- Check your Lidarr API key is correct
+
+### "ModuleNotFoundError: No module named 'html_report'"
+- Make sure you're running from the project root
+- If using Nix, ensure the flake is properly built
+
+## Contributing
+
+1. Format code with `black src/`
+2. Ensure the flake builds: `nix flake check`
+3. Test your changes: `nix run .#lidarr-mb-gap`
+
+## License
+
+This project is open source. Use it as you wish!
+
+## Acknowledgments
+
+- [Lidarr](https://lidarr.audio/) - Music collection manager
+- [SAMBL](https://github.com/Lioncat6/SAMBL-React) - MusicBrainz comparison tool
+- [a-tisket](https://atisket.pulsewidth.org.uk/) - MusicBrainz submission tool
+- [Harmony](https://harmony.pulsewidth.org.uk/) - MusicBrainz metadata aggregator
+