diff --git a/README.md b/README.md
index 27ed796..42be79a 100644
--- a/README.md
+++ b/README.md
@@ -1,18 +1,91 @@
- forgejo-blog-manager/
- ├── src/
- │   └── dlw/
- │       ├── __init__.py
- │       ├── admin.py             # Flask App: Routing, Formulare, Vorschau-Logik
- │       ├── commands.py          # CLI Entry Point: Setup, Server Start
- │       ├── git_ops.py           # GitPython Wrapper: Commit und Push
- │       └── ssg_config/          # Pelican Konfiguration und Templates
- │           ├── pelicanconf.py
- │           ├── article_template.j2 # Für die Vorschau
- │           └── templates/       # Die eigentlichen Blog-Templates
- │               └── ...
- ├── content/                     # Hier landen die generierten Markdown-Artikel
- ├── downloads/                   # Hier landen PDF- und Audio-Dateien
- ├── .gitignore
- ├── README.md
- └── pyproject.toml               # PEP 621 Konfiguration
-
+# Forgejo Blog Manager (SSG)
+
+> **Ansatz:** Documentation-Driven Development (DDD)
+> Dieses Dokument definiert den Funktionsumfang und die Schnittstellen für den Python-basierten Blog-Manager, bevor die finale Implementierung der Logik (Uploads/Rendering) abgeschlossen wird.
+
+---
+
+## 📝 Übersicht
+
+Der Forgejo Blog Manager ist ein Tool zur Verwaltung eines statischen Blogs (Pelican). Es bietet der Autorin ein Web-Interface zur Erstellung von Artikeln inklusive Datei-Uploads (PDF/Audio) und automatisiert den Git-Workflow (Commit & Push) zu einer Forgejo-Instanz.
+
+### Kern-Features
+* **Web-Interface:** Flask-basiertes Formular zur Inhaltserfassung.
+* **Vorschau-Modus:** Rendering des Artikels vor der Veröffentlichung.
+* **Asset-Management:** Automatisches Einsortieren von PDF- und Audio-Downloads.
+* **GitOps:** Automatischer Push in den `master`-Branch zur Triggerung der CI/CD-Pipeline.
+
+---
+
+## 🏗 Projektstruktur
+
+Das Projekt folgt einer sauberen `src`-Struktur mit dem Paketnamen `dlw`:
+
+```text
+forgejo-blog-manager/
+├── src/
+│   └── dlw/
+│       ├── admin.py             # Flask App: Routing & Formulare
+│       ├── commands.py          # CLI Entry Point (blog-cli)
+│       ├── git_ops.py           # GitPython Wrapper
+│       └── ssg_config/          # Pelican Konfiguration & Templates
+├── content/                     # Generierte Markdown-Artikel
+├── downloads/                   # PDF- und Audio-Dateien
+├── pyproject.toml               # Paket-Konfiguration (PEP 621)
+└── README.md
+```
+
+---
+
+## 🚀 Installation & Setup
+
+### 1. Umgebung vorbereiten
+```bash
+python3 -m venv venv
+source venv/bin/activate
+pip install .
+```
+
+### 2. Initialisierung
+```bash
+blog-cli setup
+```
+
+---
+
+## ⚙️ Lokale Konfiguration
+
+Für eine reibungslose Entwicklung empfiehlt es sich, die Projektumgebung in der `~/.profile` (oder `.zshrc`/`.bashrc`) zu hinterlegen.
+
+### Beispiel für `~/.profile` Snippet
+```bash
+# --- FORGEJO BLOG MANAGER SETUP START ---
+# Pfad zum lokalen Repository
+export BLOG_PROJECT_ROOT="$HOME/pfad/zu/forgejo-blog-manager"
+
+# Flask Konfiguration
+export FLASK_ENV="development"
+export APP_SECRET_KEY="dein-super-geheimer-schluessel"
+
+# Hilfs-Alias für den schnellen Start
+alias blog-admin='cd $BLOG_PROJECT_ROOT && source venv/bin/activate && blog-cli start'
+# --- FORGEJO BLOG MANAGER SETUP ENDE ---
+```
+*Nach dem Hinzufügen: `source ~/.profile` ausführen.*
+
+---
+
+## 🛠 Nutzung
+
+1. Starten des Admin-Interfaces: `blog-cli start`
+2. Öffnen von `http://127.0.0.1:5000` im Browser.
+3. Artikel schreiben, Dateien hochladen und auf **Vorschau** klicken.
+4. Nach Prüfung auf **Veröffentlichen** klicken.
+   * Das Tool erstellt die `.md`-Datei in `content/`.
+   * Assets werden nach `downloads/` verschoben.
+   * Ein Git-Commit & Push wird automatisch ausgeführt.
+
+---
+
+*Status: In Entwicklung (Dokumentations-Phase)*
+*Letzte Aktualisierung: 2026-01-03*
\ No newline at end of file