diff --git a/README.md b/README.md
new file mode 100644
index 0000000..03142cb
--- /dev/null
+++ b/README.md
@@ -0,0 +1,41 @@
+# Komga Manager Bot
+
+Small vibe-coded telegram bot for uploading files into a komga instance.
+
+- Send a document to the bot. Files are saved to `BASE_DIR/DEFAULT_SUBDIR` (defaults to `/data/books`).
+- If a filename already exists, the bot appends a suffix (`_1`, `_2`, ...).
+- If `KOMGA_USER` and `KOMGA_PASS` are set, the bot will trigger Komga library scans after saving.
+
+## Environment
+
+| Variable                    | Description                               | Default / Example |
+| --------------------------- | ----------------------------------------- | ----------------- |
+| `TELEGRAM_TOKEN`            | Telegram bot token (required)             |                   |
+| `USER_IDS`                  | Comma-separated allowed Telegram user IDs | `12345,67890`     |
+| `BASE_DIR`                  | Base path for saved files                 | `/data`           |
+| `DEFAULT_SUBDIR`            | Subdirectory under `BASE_DIR`             | `books`           |
+| `KOMGA_URL`                 | Komga base URL                            | (optional)        |
+| `KOMGA_USER` / `KOMGA_PASS` | Komga credentials (enable rescan)         |                   |
+
+## Getting started
+
+### Docker
+
+Build and run in background:
+
+```sh
+docker compose up -d --build
+```
+
+The service mounts `./data` into the container at `/data`.
+
+### Run locally
+
+> Requires Python 3.11 + pip
+
+- Install dependencies and run:
+
+```sh
+pip install python-telegram-bot httpx
+python bot.py
+```