From 3902755f618da5a175c6a00194326b57fc043207 Mon Sep 17 00:00:00 2001
From: Jean-Luc Makiola <business@jeanlucmakiola.de>
Date: Tue, 17 Mar 2026 11:03:02 +0100
Subject: [PATCH] docs: add project README with features, screenshots, and
 setup instructions

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 README.md | 65 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 64 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index f15ebb9..06b9653 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,65 @@
-# HouseHoldKeaper
+# Household Keeper
 
+Your household, effortlessly organized.
+
+Household Keeper helps you organize and manage your household tasks. Create rooms, assign tasks, set recurring reminders, and keep your home running smoothly.
+
+## Features
+
+- **Room Management** — Create and organize rooms with drag-and-drop reordering
+- **Task Templates** — Quickly add common household tasks or create your own
+- **Recurring Scheduling** — Daily, weekly, monthly, or yearly task recurrence
+- **Calendar View** — Day-by-day task overview with a floating "Today" button
+- **Task History** — View past completions for each task
+- **Task Sorting** — Sort by name, due date, or room with persistent preferences
+- **Notifications** — Local reminders for due tasks
+- **Light & Dark Theme** — Follows your system preference
+- **Localization** — German and English
+
+## Screenshots
+
+<p float="left">
+  <img src="fdroid-metadata/de.jeanlucmakiola.household_keeper/en-US/phoneScreenshots/1_overview.png" width="200" />
+  <img src="fdroid-metadata/de.jeanlucmakiola.household_keeper/en-US/phoneScreenshots/2_create_room.png" width="200" />
+  <img src="fdroid-metadata/de.jeanlucmakiola.household_keeper/en-US/phoneScreenshots/3_task_templates.png" width="200" />
+  <img src="fdroid-metadata/de.jeanlucmakiola.household_keeper/en-US/phoneScreenshots/4_room_tasks.png" width="200" />
+</p>
+
+## Tech Stack
+
+- **Flutter** (SDK ^3.11.0)
+- **Riverpod** — State management
+- **Drift** — Local SQLite database
+- **GoRouter** — Navigation
+- **flutter_local_notifications** — Scheduled reminders
+
+## Getting Started
+
+```bash
+# Clone the repo
+git clone https://gitea.jeanlucmakiola.de/makiolaj/HouseHoldKeaper.git
+cd HouseHoldKeaper
+
+# Install dependencies
+flutter pub get
+
+# Generate code (drift, riverpod, l10n)
+dart run build_runner build --delete-conflicting-outputs
+
+# Run the app
+flutter run
+```
+
+## Building
+
+```bash
+# Debug APK
+flutter build apk --debug
+
+# Release APK (requires signing config)
+flutter build apk --release
+```
+
+## License
+
+[MIT](LICENSE) — Jean-Luc Makiola, 2026