docs: add literate programming guidelines and project notes

Add comprehensive documentation for literate programming approach:
- Phase 1 guidelines focusing on why/what without implementation
- General literate programming principles for code documentation
- Project notes explaining wrapper script concept and strategy

Decision: Follow literate programming to make the wrapper
maintainable and educational. Comments tell the story, code
implements it. This foundation enables better collaboration
and knowledge transfer.

The notes.md establishes the core concept: a reproducible
wrapper around the Void installer that automates error-prone
LUKS encryption setup while keeping user control over system
configuration choices.

.agents/git-commits-rules.md

@@ -0,0 +1,41 @@
+# Git-Commit-Regeln
+
+## Muss
+
+- Keine KI-/Assistant-Attribution in Commit-Messages (z.B. `Co-authored-by: ChatGPT`).
+- Vor dem Commit: verfügbare Checks passend zur Änderung ausführen (Tests/Lint/Format).
+
+## Umfang
+
+- 1 logische Änderung pro Commit; klein & atomar.
+- Zugehöriges zusammen committen (Code + Tests + Docs derselben Änderung).
+
+## Message (Conventional Commits)
+
+```
+<type>(<scope>): <subject im imperativ>
+
+<body: was + warum, bei ~72 chars umbrechen>
+
+<optional: entscheidungen/alternativen/trade-offs>
+<optional footer: issue refs>
+```
+
+- Subject: Imperativ, kein Punkt, ideal `<= 50` Zeichen.
+- Body: **was** und **warum**; Kontext nur wenn relevant.
+
+### Types
+
+`feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `chore`
+
+## Vermeiden
+
+- Nachrichten wie `fix`, `update`, `refactoring`.
+- Unrelated changes in einem Commit.
+- Lange Subjects; "was" ohne "warum".
+
+## Ablauf
+
+1. In atomare Commits splitten (z.B. `git add -p`).
+2. Checks laufen lassen.
+3. Commit mit aussagekräftiger Message.

.agents/literate-programming.md

@@ -0,0 +1,101 @@
+# Literate Programming
+
+Hier ist eine **kurze, prägnante und sprachagnostische Anleitung** zu *Literate Programming* **ausschließlich mit Kommentaren in klassischen Quellcode-Dateien**, sodass **kein Build- oder Extraktionsschritt** nötig ist.
+
+## Ziel
+
+Der Code bleibt **direkt ausführbar**, während die **Kommentare die primäre Erzählung** bilden. Menschen lesen die Geschichte, Maschinen ignorieren sie.
+
+## Grundprinzipien
+
+### 1. Kommentare sind das Hauptmedium
+
+* Erkläre **Warum**, **Was** und **Wie** im Kommentar.
+* Code ist die **konkrete Umsetzung**, nicht der Text.
+
+```text
+# This module computes X.
+# The algorithm follows from Y to avoid Z.
+```
+
+### 2. Erzählerische Struktur statt technischer Reihenfolge
+
+* Gliedere Kommentare logisch:
+
+  * Motivation
+  * Konzepte
+  * Entscheidungen
+  * Einschränkungen
+* Code folgt der Erzählung, nicht umgekehrt.
+
+```text
+# Step 1: Prepare input data
+code...
+
+# Step 2: Core logic
+code...
+```
+
+### 3. Kleine, erklärbare Codeblöcke
+
+* Jeder Block beantwortet:
+  **„Was tut dieser Abschnitt – und warum?“**
+* Maximal wenige Zeilen Code pro Erklärungseinheit.
+
+```text
+# Filter invalid entries to avoid later edge cases.
+code...
+```
+
+### 4. Kommentare beschreiben Absichten, nicht Syntax
+
+❌ Schlecht:
+
+```text
+# increment i by 1
+```
+
+✅ Gut:
+
+```text
+# Iterate sequentially because order is semantically relevant.
+```
+
+### 5. Entscheidungen explizit machen
+
+* Halte Alternativen und Gründe fest.
+* Besonders wichtig bei „ungewöhnlichem“ Code.
+
+```text
+# Use an iterative approach instead of recursion
+# because maximum depth is unknown at runtime.
+```
+
+### 6. Stabiler Kommentar-Stil
+
+* Einheitliche Marker (z. B. `#`, `//`, `/* */`)
+* Optional: leichte Strukturierung
+
+```text
+# === Motivation ===
+# === Algorithm ===
+# === Edge cases ===
+```
+
+### 7. Leserorientiert schreiben
+
+* Schreibe für einen **zukünftigen Menschen**, nicht für dich selbst.
+* Setze kein implizites Kontextwissen voraus.
+
+## Faustregel
+
+> **Wenn man die Kommentare entfernt, sollte der Code schwer verständlich sein.
+> Wenn man den Code entfernt, sollte die Idee klar bleiben.**
+
+## Vorteile dieses Ansatzes
+
+* ✔ Kein Build- oder Extraktionsschritt
+* ✔ Funktioniert in jeder Sprache
+* ✔ Versionskontroll-freundlich
+* ✔ Direkt im Editor lesbar
+* ✔ Wartung und Wissenstransfer verbessert

.agents/lp-phase-1.md

@@ -0,0 +1,37 @@
+# Phase 1 beim Literate Programming
+
+- In dieser Phase wird **kein Sourcecode** geschrieben; es entstehen nur narrative Kommentartexte.
+- Schreibe den literalen Anteil dessen, was umgesetzt werden soll: **Warum** und **Was** (Motivation, Konzepte, Entscheidungen, Einschränkungen), **nicht** das **Wie**.
+- Halte Entscheidungen und Alternativen explizit fest, aber **ohne** Implementierungsdetails oder API-/Algorithmus-Spezifika.
+- Stelle Rückfragen, wenn Dinge unklar sind oder mehrere sinnvolle Optionen bestehen; diese Phase ist ein Dialog zur Klärung.
+- Strukturiere die Texte in klaren, kleinen Abschnitten, die später als Kommentarblöcke vor Codeblöcken stehen können.
+- Verteile die Texte über mehrere Dateien entsprechend der späteren Modulstruktur; jede Datei erzählt einen zusammenhängenden Abschnitt.
+- Zielkriterium: Wenn man den Code entfernt, bleibt die Idee vollständig verständlich.
+
+## Vorlage Phase 1 Textblock
+
+- Passe das Kommentar-Praefix an die Zielsprache an (z. B. `#`, `//`, `/* */`).
+- Schreibe die Inhalte in technischem Englisch; vermeide Implementierungsdetails.
+
+```text
+# === Motivation ===
+# <Why this exists and who benefits>
+# === Problem Statement ===
+# <What needs to change or be achieved>
+# === Scope ===
+# In scope: <...>
+# Out of scope: <...>
+# === Concepts ===
+# <Key terms and relationships>
+# === Decisions ===
+# <Decision> because <reason>
+# === Alternatives Considered ===
+# <Option> rejected because <reason>
+# === Constraints ===
+# <Operational, legal, performance, security, time>
+# === Open Questions ===
+# <Unresolved items that need clarification>
+# === Success Criteria ===
+# <Observable outcomes and acceptance criteria>
+```
+

AGENTS.md

@@ -0,0 +1,3 @@
+- **WICHTIG**: Lies zuerst `README.md` (falls vorhanden).
+- Sprache im Chat: Deutsch.
+- Sprache in Sourcecode & Kommentaren: technisches Englisch.

notes.md

@@ -0,0 +1,121 @@
+Hier ist eine **kurze, kompakte Übersicht** zu einem **eigenen Wrapper-Skript für eine verschlüsselte Void-Linux-Installation**.
+
+---
+
+## Was ist ein Wrapper-Skript?
+
+Ein Wrapper-Skript ist ein **eigenes Bash-Skript**, das **vor und um den Void-Installer herum** läuft.
+Es übernimmt die **kritischen Schritte**, die der offizielle Installer nicht automatisiert kann, vor allem:
+
+* Partitionierung
+* LUKS-Verschlüsselung (`cryptsetup`)
+* Anlegen von Dateisystemen
+* Vorbereitung der Mountpoints (`/dev/mapper/...`)
+* Optional: LVM, Swap, btrfs
+
+Der **Void-Installer selbst** wird danach weiterhin benutzt – aber auf bereits vorbereiteten Devices.
+
+---
+
+## Warum ein Wrapper-Skript nutzen?
+
+**Vorteile:**
+
+* 🔐 **Reproduzierbare, sichere Installation**
+* 🧠 Weniger manuelle Fehler bei LUKS / crypttab / dracut
+* ⚙️ Anpassbar an **UEFI vs. BIOS**, **LUKS1 vs. LUKS2**, **ext4 vs. btrfs**
+* 🧪 Ideal für Tests, VMs oder mehrere Maschinen
+* 📜 Dokumentiert dein Setup besser als Klicks im Installer
+
+Kurz:
+
+> Du automatisierst das **Fehleranfällige**, nicht das **Flexible**.
+
+---
+
+## Wie ist die Grundidee?
+
+### Ablauf (High-Level)
+
+1. **Sanity Checks**
+
+   * Root-Rechte
+   * Richtige Disk (`/dev/sda`, `/dev/nvme0n1`)
+   * Warnung: *Alle Daten werden gelöscht*
+
+2. **Partitionierung**
+
+   * EFI (unverschlüsselt)
+   * Root-Partition (für LUKS)
+   * Optional: separate `/boot`
+
+3. **Verschlüsselung**
+
+   * `cryptsetup luksFormat`
+   * `cryptsetup open → /dev/mapper/cryptroot`
+   * Optional: LUKS1 erzwingen
+
+4. **Dateisysteme**
+
+   * `mkfs.ext4` oder `mkfs.btrfs`
+   * EFI: `mkfs.vfat`
+
+5. **Mounten**
+
+   * Root nach `/mnt`
+   * EFI nach `/mnt/boot/efi`
+
+6. **Void-Installer starten**
+
+   * Manuelle Partitionierung
+   * Nur Mountpoints setzen, **nicht formatieren**
+
+7. **Post-Install (chroot)**
+
+   * `/etc/crypttab`
+   * `dracut` konfigurieren
+   * `xbps-reconfigure -fa`
+   * `grub-mkconfig`
+
+---
+
+## Worauf sollte man beim „Wie“ achten?
+
+### 🔴 Sicherheit & Zuverlässigkeit
+
+* **Disk-Variable hart prüfen** (`lsblk`!)
+* Kein automatisches Überschreiben ohne Bestätigung
+* Passphrase **nicht im Skript speichern**
+
+### 🟡 Kompatibilität
+
+* GRUB ist am stabilsten mit **LUKS1**
+* EFI immer **unverschlüsselt**
+* Initramfs muss **crypt-Modul** enthalten
+
+### 🟢 Wartbarkeit
+
+* Variablen am Anfang (`DISK=`, `FS=`, `HOSTNAME=`)
+* Keine „magischen“ Werte
+* Kommentare zu jedem destruktiven Schritt
+
+### 🧪 Testbarkeit
+
+* Erst in einer **VM**
+* Skript **idempotent** halten, wo möglich
+* Klare Exit-Points bei Fehlern (`set -e`)
+
+---
+
+## Fazit
+
+Ein eigenes Wrapper-Skript ist der **beste Kompromiss** zwischen:
+
+* kompletter Handarbeit ❌
+* fragilen „One-Click-Installern“ ❌
+
+und bietet:
+
+* Kontrolle ✅
+* Wiederholbarkeit ✅
+* Sicherheit ✅