diff --git a/.gitea/workflows/ci.yaml b/.gitea/workflows/ci.yaml
new file mode 100644
index 0000000..140d4aa
--- /dev/null
+++ b/.gitea/workflows/ci.yaml
@@ -0,0 +1,70 @@
+name: CI
+on: [push, pull_request]
+
+jobs:
+  test-and-build:
+    runs-on: ubuntu-latest
+    container:
+      image: golang:latest
+      options: --network host
+    steps:
+      - name: Check out repository code
+        uses: actions/checkout@v4
+
+      - name: List files in the repository
+        run: ls ${{ gitea.workspace }}
+
+      - name: Download modules
+        run: go mod download
+
+      - name: Test
+        run: make test
+
+      - name: Build
+        run: make build
+
+      - name: Version
+        run: make version
+
+      - name: Upload binary
+        uses: actions/upload-artifact@v3
+        with:
+          name: tm
+          path: ./bin/tm
+
+      - run: echo "This job's status is ${{ job.status }}."
+
+  demo:
+    runs-on: ubuntu-latest
+    needs: test-and-build
+    container:
+      image: ghcr.io/charmbracelet/vhs:latest
+      options: --network host
+    steps:
+      - name: Check out repository code
+        uses: actions/checkout@v4
+
+      - name: Download binary
+        uses: actions/download-artifact@v3
+        with:
+          name: tm
+          path: ./bin
+
+      - name: Make binary executable
+        run: chmod +x ./bin/tm
+
+      - name: Install vim (used as EDITOR in the tape)
+        run: |
+          apt-get update
+          apt-get install -y --no-install-recommends vim
+
+      - name: Record demo
+        run: vhs demo.tape
+
+      - name: Upload demo
+        uses: actions/upload-artifact@v3
+        with:
+          name: demo
+          path: |
+            demo.gif
+            demo.mp4
diff --git a/.gitignore b/.gitignore
index 33a11fa..5b4c4bf 100644
--- a/.gitignore
+++ b/.gitignore
@@ -3,6 +3,6 @@
 *.exe
 *.test
 *.out
-demo.gif
+# Generated by `make demo` / CI — commit demo.gif so the README preview works on Gitea
 demo.mp4
 demo.webm
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..177c136
--- /dev/null
+++ b/README.md
@@ -0,0 +1,95 @@
+# task-master
+
+Offline-first Terminal-Taskmanager (`tm`) — Kanban-Board, Markdown-Tickets, Checklisten, Zeiterfassung und Reports. Gebaut mit [Bubble Tea](https://github.com/charmbracelet/bubbletea).
+
+![Demo](demo.gif)
+
+> Demo wird aus [`demo.tape`](demo.tape) erzeugt (`make demo`). Ohne GIF lokal: siehe [Demo aufnehmen](#demo-aufnehmen).
+
+## Features
+
+- Projekte & Tickets lokal als JSON (kein Server)
+- Board-Filter: All / Backlog / In Progress / Done
+- Tickets in `$EDITOR` bearbeiten (Markdown + Checklisten)
+- Timer, manuelle Zeitbuchungen, Zeiteinträge verwalten
+- Report mit Group-by (Ticket / Tag)
+- Undo / Redo über eine Command-History
+- Vim-Style Keybindings
+
+## Install
+
+Voraussetzung: Go (siehe `go.mod`).
+
+```bash
+git clone git@git.aloxdrim.de:skruecken/task-master.git
+cd task-master
+make install          # → $(go env GOPATH)/bin/tm
+# oder nur bauen:
+make build            # → ./bin/tm
+```
+
+## Nutzung
+
+```bash
+tm                    # TUI starten
+tm version            # Build-Version (Git-Hash)
+tm help
+```
+
+Sandbox ohne echte Config/Daten:
+
+```bash
+make run-dev          # nutzt ./.dev-home
+# oder:
+TASK_MASTER_HOME=/tmp/tm-sandbox tm
+```
+
+Daten landen standardmäßig unter `~/.local/share/task-master`, Config unter `~/.config/task-master`.
+
+| Variable             | Wirkung                                      |
+|----------------------|----------------------------------------------|
+| `TASK_MASTER_HOME`   | Basis für Config + Daten (Dev/Demo)          |
+| `TASK_MASTER_DATA_DIR` | Nur Datenverzeichnis überschreiben         |
+
+## Keybindings (Auszug)
+
+| Taste   | Aktion                |
+|---------|------------------------|
+| `j`/`k` | Navigieren             |
+| `n`     | Neues Ticket/Projekt   |
+| `e`     | Ticket im Editor       |
+| `s`     | Status ändern          |
+| `l`     | Board-Filter           |
+| `/`     | Suche                  |
+| `p`/`P` | Projekt / Ticket verschieben |
+| `t`/`T` | Timer / Zeit buchen    |
+| `m`     | Zeiteinträge           |
+| `r`     | Report                 |
+| `x`/`X` | Löschen / Force-Delete |
+| `u`/`U` | Undo / Redo            |
+| `q`     | Beenden                |
+
+Checklisten im Preview: `J`/`K` + `Space`.
+
+## Entwicklung
+
+```bash
+make test
+make build
+make version
+```
+
+## Demo aufnehmen
+
+Die Walkthrough-Aufnahme steckt in [`demo.tape`](demo.tape) ([VHS](https://github.com/charmbracelet/vhs)):
+
+```bash
+# einmalig: vhs + ttyd/ffmpeg (siehe VHS-Docs)
+make demo             # schreibt demo.gif (+ demo.mp4)
+```
+
+Die Pipeline erzeugt das GIF ebenfalls und lädt es als Artifact hoch.
+
+## Lizenz
+
+Privat / eigener Use — siehe Repository-Einstellungen auf Gitea.
diff --git a/demo.tape b/demo.tape
index 2664366..c40d6ec 100644
--- a/demo.tape
+++ b/demo.tape
@@ -27,7 +27,7 @@ Hide
 Type "rm -rf /tmp/task-master-vhs && mkdir -p /tmp/task-master-vhs"
 Enter
 Sleep 300ms
-Type "make build"
+Type "test -x ./bin/tm || make build"
 Enter
 Sleep 5s
 Show