diff --git a/README.md b/README.md
index 38013f4..00aa220 100644
--- a/README.md
+++ b/README.md
@@ -1,18 +1,240 @@
-# mitgliederverwaltung
+# Mila
 
-## Testing SSO with rauthy
+**Mila** — simple, usable, self-hostable membership management for small to mid-sized clubs.  
+
+[![CI Status](https://img.shields.io/badge/build-pending-lightgrey.svg)](link-to-ci)  
+![License](https://img.shields.io/badge/license-TBD-blue)  
+
+---
+
+## 🚧 Project Status
+
+⚠️ **Early development** — not production-ready. Expect breaking changes.  
+Contributions and feedback are welcome!
+
+---
+
+## ✨ Overview
+
+Mila is a free and open-source membership management tool designed for real club needs.  
+It is **self-hosting friendly**, aims for **accessibility and GDPR compliance**, and focuses on **usability** instead of feature overload.  
+
+---
+
+## 💡 Why Mila?
+
+Most membership tools for clubs are either:
+
+* **Too complex** — overloaded with features small and mid-sized clubs don’t need
+* **Too expensive** — hidden fees, closed ecosystems, vendor lock-in
+* **Too rigid** — no way to adapt fields, processes, or roles to your club’s reality
+
+**Mila** is different:
+
+* **Simple**: Focused on what clubs really need — members, dues, communication.
+* **Usable**: Clean, accessible UI, GDPR-compliant, designed with everyday volunteers in mind.
+* **Flexible**: Custom fields, role-based permissions, and self-service for members.
+* **Truly open**: 100% free and open source — no lock-in, transparent code, self-host friendly.
+
+Our philosophy: **software should help people spend less time on administration and more time on their community.**
+
+---
+
+## 📸 Screenshots
+
+![Screenshot placeholder](docs/images/screenshot.png)  
+*This is how Mila might look in action.*  
+
+---
+
+## 🔑 Features
+
+- ✅ Manage member data with ease  
+- 🚧 Overview of membership fees & payment status  
+- ✅ Full-text search  
+- 🚧 Sorting & filtering  
+- 🚧 Roles & permissions (e.g. board, treasurer)  
+- ✅ Custom fields (flexible per club needs)  
+- ✅ SSO via OIDC (tested with Rauthy)  
+- 🚧 Self-service & online application  
+- 🚧 Accessibility, GDPR, usability improvements  
+- 🚧 Email sending  
+
+---
+
+## 🚀 Quick Start (Development)
+
+### Prerequisites
+
+We recommend using **[asdf](https://asdf-vm.com/)** for managing tool versions.  
+- Tested with: `asdf 0.16.5`
+- Required versions are documented in `.tool-versions` in this repo  
+
+<details>
+<summary>Install system dependencies (Debian/Ubuntu)</summary>
+
+```bash
+# Debian 12
+apt-get -y install build-essential autoconf m4 libncurses-dev libwxgtk3.2-dev libwxgtk-webview3.2-dev libgl1-mesa-dev libglu1-mesa-dev libpng-dev libssh-dev unixodbc-dev xsltproc fop libxml2-utils openjdk-17-jdk icu-devtools bison flex pkg-config
+
+# Ubuntu 24
+apt-get -y install build-essential autoconf m4 libwxgtk3.2-dev libwxgtk-webview3.2-dev libgl1-mesa-dev libglu1-mesa-dev libpng-dev libssh-dev unixodbc-dev xsltproc fop libxml2-utils libncurses-dev openjdk-11-jdk icu-devtools bison flex libreadline-dev
+```
+</details>
+
+<details>
+<summary>Install asdf</summary>
+
+```bash
+mkdir ~/.asdf
+cd ~/.asdf
+wget https://github.com/asdf-vm/asdf/releases/download/v0.16.5/asdf-v0.16.5-linux-amd64.tar.gz
+tar -xvf asdf-v0.16.5-linux-amd64.tar.gz
+ln -s ~/.asdf/asdf ~/.local/bin/asdf
+```
+
+Then follow the official “Shell Configuration” steps in the asdf docs.  
+
+*Fish example* (`~/.config/fish/config.fish`):  
+
+```fish
+asdf completion fish > ~/.config/fish/completions/asdf.fish
+set -gx PATH "$HOME/.asdf/shims" $PATH
+```
+
+*Bash example* (`~/.bash_profile` and `~/.bashrc`):  
+
+```bash
+export PATH="${ASDF_DATA_DIR:-$HOME/.asdf}/shims:$PATH"
+. <(asdf completion bash)
+```
+</details>
+
+### Install project dependencies
+
+```bash
+git clone https://git.local-it.org/local-it/mitgliederverwaltung.git mila
+cd mila
+asdf install
+
+# Inside the repo folder:
+mix local.hex 2.1.1
+mix archive.install hex phx_new 1.7.20
+```
+
+> Note: running `mix local.hex` must be done inside the repo folder,  
+> because `.tool-versions` defines the Erlang/Elixir versions.
+
+---
+
+### Run the app
+
+1. Copy env file:  
+   ```bash
+   cp .env.example .env
+   # Set OIDC_CLIENT_SECRET inside .env
+   ```
+
+2. Start everything (database, Mailcrab, Rauthy, app):  
+   ```bash
+   just run
+   ```
+
+3. Services will be available at:  
+   - App: <http://localhost:4000>  
+   - Mail UI: <http://localhost:1080>  
+   - Postgres: `localhost:5000`  
+
+---
+
+## 🔐 Testing SSO locally
+
+Mila uses OIDC for Single Sign-On. In development, a local **Rauthy** instance is provided.  
 
 1. `just run`
-1. go to [localhost:8080](http://localhost:8080), go to the Admin area
-1. Login with "admin@localhost" and password from `BOOTSTRAP_ADMIN_PASSWORD_PLAIN` in docker-compose.yml
-1. add client from the admin panel
+2. go to [localhost:8080](http://localhost:8080), go to the Admin area
+3. Login with "admin@localhost" and password from `BOOTSTRAP_ADMIN_PASSWORD_PLAIN` in docker-compose.yml
+4. add client from the admin panel
     - Client ID: mv
     - redirect uris: http://localhost:4000/auth/user/rauthy/callback
     - Authorization Flows: authorization_code
     - allowed origins: http://localhost:4000
     - access/id token algortihm: RS256 (EDDSA did not work for me, found just few infos in the ashauthentication docs)
-1. copy client secret to `.env` file
-1. abort and run `just run` again
+5. copy client secret to `.env` file
+6. abort and run `just run` again
 
+Now you can log in to Mila via OIDC!  
 
+---
 
+## ⚙️ Configuration
+
+- **Env vars:** see `.env.example`  
+  - `OIDC_CLIENT_SECRET` — secret for your OIDC client  
+- Database defaults (Docker Compose):  
+  - Host: `localhost`  
+  - Port: `5000`  
+  - User/pass: `postgres` / `postgres`  
+  - DB: `mila_dev`  
+
+---
+
+## 🏗️ Architecture
+
+- **Backend:** Elixir, Phoenix 1.8, LiveView 1.1, Ash Framework  
+- **Frontend:** Phoenix LiveView + TailwindCSS + Heroicons  
+- **Database:** PostgreSQL (via AshPostgres)  
+- **Auth:** AshAuthentication (OIDC + password strategy)  
+- **Mail:** Swoosh  
+- **i18n:** Gettext  
+
+Code structure:  
+- `lib/mv/` — core Ash resources/domains (`Accounts`, `Membership`)  
+- `lib/mv_web/` — Phoenix controllers, LiveViews, components  
+- `assets/` — frontend assets (Tailwind, JS, etc.)  
+
+---
+
+## 🧑‍💻 Development
+
+Useful `just` commands:  
+- `just run` — start DB, Mailcrab, Rauthy, app  
+- `just test` — run tests  
+- `just lint` — run code style checks (credo, formatter)  
+- `just audit` — run security audits  
+- `just reset-database` — reset local DB  
+- `just regen-migrations <name>` — regenerate migrations  
+
+---
+
+## 📦 Deployment
+
+A production release image is built via the provided `Dockerfile`.  
+Entrypoint: `/app/bin/server`.  
+
+More detailed deployment docs are planned.  
+
+---
+
+## 🤝 Contributing
+
+We welcome contributions!  
+- Open issues and PRs in this repo.  
+- Please follow existing code style and conventions.  
+- Expect breaking changes while the project is in early development.  
+
+---
+
+## 📄 License
+
+**License: TBD** (Free and Open Source).  
+A proper license file will be added soon.  
+
+---
+
+## 📬 Contact
+
+- Issues: [GitLab Issues](https://git.local-it.org/local-it/mitgliederverwaltung/-/issues)  
+- Community links: coming soon.  
+
+---