diff --git a/README.md b/README.md
index 95526d3..98455ca 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,82 @@
 # lt-auth-proxy
 
-Language Tool authentication proxy
\ No newline at end of file
+A lightweight, production-ready reverse proxy for [LanguageTool](https://languagetool.org) with API key authentication.
+
+This service acts as a transparent gateway that verifies an `apiKey` before forwarding requests to a running LanguageTool server instance. It is fully self-contained, built in Deno, and distributed as a minimal multi-architecture Docker image.
+
+---
+
+## ✨ Features
+
+* 🔐 **API key authentication** via query or form body
+* 📡 **Transparent proxying** to any LanguageTool backend
+* 🐳 **Minimal Docker image (\~93 MB)**
+* 🧱 **Statically compiled** Deno binary
+* 🧪 **Unit tested** middleware and proxy logic
+* 🛠️ Compatible with VSCode, Nextcloud, and other LT clients
+
+---
+
+## 🚀 Usage
+
+You can run the proxy via Docker:
+
+```bash
+docker run -p 8011:8011 \
+  -e API_KEYS="demo-key,another-key" \
+  -e LT_SERVER_HOST=lt-server \
+  -e LT_SERVER_PORT=8010 \
+  git.0xmax42.io/simdev/lt-auth-proxy:latest
+```
+
+---
+
+## 🧪 Supported Environment Variables
+
+| Variable         | Required | Default     | Description                              |
+| ---------------- | -------- | ----------- | ---------------------------------------- |
+| `API_KEYS`       | ✅ yes    | –           | Comma-separated list of valid API tokens |
+| `PROXY_HOST`     | ❌ no     | `0.0.0.0`   | Host/IP address to bind the proxy to     |
+| `PROXY_PORT`     | ❌ no     | `8011`      | Port the proxy listens on                |
+| `LT_SERVER_HOST` | ❌ no     | `localhost` | Hostname of the LanguageTool backend     |
+| `LT_SERVER_PORT` | ❌ no     | `8010`      | Port of the LanguageTool backend         |
+
+---
+
+## 📁 File Structure
+
+```
+src/
+├── main.ts          # Entry point, sets up the HTTP kernel
+├── env.ts           # Lazy-loaded environment access
+├── ltProxyAuth.ts   # Middleware to check the apiKey
+├── ltProxyHandler.ts# Handler to forward the request to LT
+```
+
+---
+
+## 🐳 Docker Compose Example
+
+```yaml
+services:
+  lt-server:
+    image: languagetool/languagetool:latest
+    ports:
+      - "8010:8010"
+
+  proxy:
+    image: git.0xmax42.io/simdev/lt-auth-proxy:latest
+    ports:
+      - "8011:8011"
+    environment:
+      - API_KEYS=demo-key
+      - LT_SERVER_HOST=lt-server
+      - LT_SERVER_PORT=8010
+```
+
+---
+
+## 📖 License
+
+MIT © 0xMax42
+[https://git.0xmax42.io/maxp/lt-auth-proxy](https://git.0xmax42.io/maxp/lt-auth-proxy)