diff --git a/README.md b/README.md
new file mode 100644
index 0000000..359e015
--- /dev/null
+++ b/README.md
@@ -0,0 +1,111 @@
+# Mastobot — Mastodon Feed Automation Service
+
+Automatically syncs RSS feeds from Finnish and international sources to your custom Mastodon instance.
+
+## Features
+
+- **7 RSS feed rotors** - Pull updates from news, weather, and community sources
+- **Custom content formatting** - Each feed has tailored message formatting (e.g., hashtags for Finnish feeds)
+- **Intelligent tagging** - Uses OpenAI API to generate or translate hashtags for Yle.fi English news
+- **Static embed page** - Generate personalized Mastodon profile pages via S3 upload
+- **Health monitoring** - Built-in health check endpoint
+
+## Available Feed Rotors
+
+| Router | Source | Language | Features |
+|--------|--------|----------|----------|
+| `yle_fi` | Yle.fi News | fi | Includes hashtags, custom cleaning |
+| `yle_en` | Yle.fi News | en | AI-generated translated tags |
+| `the_local` | The Local | en | Includes hashtags |
+| `taloustaito` | Taloustaito | fi | First 3 articles only |
+| `sur` | Sur Weather News | en | Includes hashtags |
+| `hn` | Hacker News | en | Title + link only |
+| `embed` | Your Mastodon | any | Static profile page generator |
+
+## Tech Stack
+
+- **Backend**: FastAPI (Python)
+- **Database**: None (state stored in memory per request)
+- **Deployment**: Docker Compose with development hot-reload
+- **AI Integration**: OpenAI API for tag translation/generation
+- **Storage**: Amazon S3 for embed pages
+- **External APIs**: RSS feedparser, Mastodon v1 API, BeautifulSoup
+
+## Setup
+
+### Prerequisites
+
+- Docker (compose)
+- Custom Mastodon instance with API access
+- OpenAI API key (for `yle_en` rotor only)
+- AWS credentials (for `embed` rotor S3 upload)
+
+### Development
+
+```bash
+# Load environment variables
+# Copy .env.example to .env and fill in:
+# - mastodon_server: https://your.mastodon.local
+# - feeds__: {source_name: {url, account_id, token}}
+# - openai_api_key: sk-your-api-key
+# - aws_access_key_id / aws_secret_access_key (optional)
+
+# Run development server with hot-reload
+uvicorn app.main:app --host 0.0.0.0 --port 8000
+
+# Or use Docker Compose
+docker compose up --build
+```
+
+### Configuration Example
+
+```yaml
+feeds__ :
+  fuengirola__ :
+    url: https://fuengirola.fi/fi/rss/
+    account_id: 12345678
+    token: your_mastodon_token
+  hn__ :
+    url: https://hacker-news.ycombinator.com/hlnews.xml
+    account_id: 12345678
+    token: your_mastodon_token
+```
+
+## Usage
+
+### Health Check
+
+```bash
+curl http://localhost:8000/health
+```
+
+Returns: `{"status": "healthy"}`
+
+### Trigger Manual Feed Update
+
+Call specific rotors via HTTP:
+
+```bash
+curl http://localhost:8000/rss?source=fuengirola
+```
+
+See individual router docs for endpoints.
+
+## API Endpoints
+
+| Endpoint | Description |
+|----------|-------------|
+| `/` | Welcome message |
+| `/health` | Health check |
+| `/embed/generate` | Generate static embed page at S3 key |
+| `/rss?fource=fuengirola` | Fuengirola weather news |
+| `/rss?source=yle_fi` | Yle.fi Finnish news |
+| `/rss?source=yle_en` | Yle.fi English news (AI tags) |
+| `/rss?source=the_local` | The Local articles |
+| `/rss?source=taloustaito` | Taloustaito economics |
+| `/rss?source=sur` | Weather news with hashtags |
+| `/rss?source=hn` | Hacker News |
+
+## License
+
+Proprietary - All Rights Reserved for John Ahlroos