diff --git a/README.md b/README.md
new file mode 100644
index 0000000..d838f2c
--- /dev/null
+++ b/README.md
@@ -0,0 +1,63 @@
+# slskd-auto-disconnect
+
+Automatically disconnects [slskd](https://github.com/slskd/slskd) from the Soulseek network after a period of inactivity. Prevents 24/7 file sharing when you forget to disconnect after downloading music.
+
+## How it works
+
+A cron job runs the script every 5 minutes. When slskd is connected, the script checks for activity:
+
+- **Active downloads** (in progress, queued, or initializing) via the slskd API
+- **Recent docker log activity** (searches, folder browsing, downloads, connections)
+
+If no activity is detected for the configured timeout (default 30 minutes), slskd is disconnected from the Soulseek network.
+
+Uploads are intentionally **not** counted as activity — they're what you're trying to avoid. However, if an upload is mid-transfer when the idle threshold is reached, the script will wait for it to finish before disconnecting.
+
+## Requirements
+
+- `curl`, `jq` on the host
+- Docker (the script reads container logs)
+- Root/sudo access (for `docker logs`)
+
+## Installation
+
+1. Copy the script to your server:
+   ```bash
+   sudo mkdir -p /opt/arr/slskd/scripts
+   sudo cp auto-disconnect.sh /opt/arr/slskd/scripts/
+   sudo chmod +x /opt/arr/slskd/scripts/auto-disconnect.sh
+   ```
+
+2. Edit the configuration variables at the top of the script (`SLSKD_URL`, `SLSKD_USER`, `SLSKD_PASS`, `CONTAINER_NAME`, etc.)
+
+3. Add a cron job (as root):
+   ```bash
+   sudo crontab -e
+   ```
+   ```
+   */5 * * * * /opt/arr/slskd/scripts/auto-disconnect.sh 2>/dev/null
+   ```
+
+## Configuration
+
+Variables at the top of the script:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `SLSKD_URL` | `http://localhost:5030` | slskd API base URL |
+| `SLSKD_USER` | `slskd` | slskd web UI username |
+| `SLSKD_PASS` | `slskd` | slskd web UI password |
+| `CONTAINER_NAME` | `slskd` | Docker container name |
+| `LOG_CHECK_MIN` | `5` | How far back to check docker logs (minutes) |
+| `LOG_MAX_LINES` | `500` | Max log file lines before truncation |
+
+Environment variable overrides:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `SLSKD_IDLE_TIMEOUT` | `30` | Minutes of inactivity before disconnect |
+| `SLSKD_GOTIFY_TOKEN` | *(empty)* | Gotify app token for push notifications |
+
+## Logs
+
+The script logs disconnect events and errors to `auto-disconnect.log` in the same directory. The log auto-truncates at 500 lines.