Docs: Schnellstart-One-Liner zum Klonen und Ausführen zu README.md hinzugefügt

Co-authored-by: Junie <junie@jetbrains.com>
Refactor: Aufteilung in Stage 08 (Flatpaks), 09 (Apps & MIME) und 10 (Hyprland) sowie ShellCheck-Bereinigung
2026-09-06 13:40:20 +02:00 · 2026-09-06 13:36:52 +02:00 · 2026-09-06 13:30:27 +02:00 · 2026-09-06 13:23:32 +02:00 · 2026-09-06 13:12:37 +02:00 · 2026-09-06 13:01:04 +02:00
49 changed files with 2940 additions and 21 deletions
@@ -77,3 +77,18 @@ fabric.properties
 # Android studio 3.1+ serialized cache file
 .idea/caches/build_file_checksums.ser
 # ---> VisualStudioCode
 .vscode/*
 !.vscode/settings.json
 !.vscode/tasks.json
 !.vscode/launch.json
 !.vscode/extensions.json
 !.vscode/*.code-snippets
 # Local History for Visual Studio Code
 .history/
 # Built Visual Studio Code Extensions
 *.vsix
 .junie/plans
@@ -0,0 +1 @@
 {}
@@ -0,0 +1,203 @@
 # AGENTS.md — Richtlinien und Architektur-Leitfaden für KI-Agenten
 Dieses Dokument enthält Richtlinien, Architekturstandards, Konventionen und Arbeitsanweisungen für KI-Agenten und Entwickler, die an diesem Repository arbeiten oder es warten.
 ---
 ## 1. Projektübersicht
 Dieses Repository ist ein modulares, automatisiertes Setup- und Konfigurations-Framework für **Debian GNU/Linux Unstable (Sid)** mit:
 - **Hyprland** (Wayland-Compositor) und Waybar-Desktopumgebung
 - **XanMod-Kernel** (main/edge) mit CPU P-State-Tuning (AMD/Intel) und `auto-cpufreq`
 - **Bootloader & Splash**: GRUB-Konfiguration mit Vimix-Theme und Plymouth Solar-Splash
 - **Gaming & Multimedia**: MangoHud, Gamescope, Lutris, Steam, Wine, Pro-Audio via PipeWire
 - **Virtualisierung & Container**: QEMU/KVM, Libvirt, Docker, Waydroid
 - **Paket- und Anwendungsmanagement**: Deb822-Quellen, APT-Pinning, Flatpaks (Flathub), isolierte Schriften-Installation
 ---
 ## 2. Projekt- und Verzeichnisstruktur
 ```
 .
 ├── setup.sh                         # Zentraler Orchestrator (CLI Flags & whiptail TUI)
 ├── lib/                             # Wiederverwendbare Funktionsbibliotheken
 │   ├── utils.sh                     # Logging, Error-Traps, Benutzer- und Pfadermittlung, Backups
 │   ├── apt.sh                       # Deb822-Quellen, Keyrings (/etc/apt/keyrings), APT-Pinning, Paketinstallation
 │   └── tui.sh                       # Whiptail-TUI-Menüs und Dialoge
 ├── config/                          # Konfigurationsdateien & Paketlisten
 │   ├── setup.conf                   # Globale Umgebungsvariablen und Standardwerte
 │   └── packages/                    # Thematisch gegliederte Paketlisten (*.list)
 │       ├── 01-base.list             # Basiswerkzeuge, Firmware, Microcode
 │       ├── 02-desktop.list          # Hyprland, Waybar, SDDM, XDG-Portale, PipeWire
 │       ├── 03-gaming.list           # Steam, Heroic, Lutris, Gamescope, MangoHud, Wine
 │       ├── 04-virtualization.list   # QEMU, KVM, Libvirt, Bridge-Tools
 │       ├── 05-multimedia.list       # VLC, Amberol, GIMP, Loupe, LibreOffice
 │       └── 06-flatpaks.list         # Flathub App-IDs
 ├── stages/                          # Sequenziell und modular ausführbare Phasen (00 bis 10)
 │   ├── 00-preflight.sh              # Systemvoraussetzungen, Root/User-Erkennung, Internetverbindung
 │   ├── 01-apt-unstable.sh           # Deb822-Quellen, Keyrings, Pinning, apt-listbugs, dist-upgrade
 │   ├── 02-kernel-hardware.sh        # XanMod-Kernel, CPU P-State, Microcode, auto-cpufreq
 │   ├── 03-bootloader.sh             # GRUB Kernel-Parameter, Vimix-Theme, Plymouth Solar
 │   ├── 04-packages.sh               # Installation der thematischen Paketlisten
 │   ├── 05-fonts.sh                  # Download & Installation von Coding- & Nerd-Fonts
 │   ├── 06-services.sh               # Aktivierung von AppArmor, Docker, Libvirt, zram, Ollama
 │   ├── 07-skel-and-user.sh          # /etc/skel Vorlagen, ZSH-Shell-Setzen, Dotfiles-Sync
 │   ├── 08-flatpaks.sh               # Flathub Setup, Flatpak-Paketlisten-Installation
 │   ├── 09-apps.sh                   # Spotify, Waydroid, OpenDeck, Desktop-Starter, MIME-Types
 │   └── 10-hyprland.sh               # LinuxBeginnings Debian-Hyprland Auto-Installer & Desktop-Setup
 ├── data/                            # Statische Konfigurationsdateien & Vorlagen
 │   ├── apt/
 │   │   ├── sources.list.d/          # Deb822-Quellen (debian-unstable.sources, xanmod.sources)
 │   │   └── preferences.d/           # Pinning-Konfigurationen
 │   ├── etc/
 │   │   ├── environment.d/           # Globale Umgebungsvariablen (Raytracing, Upscaling)
 │   │   └── profile.d/               # Globale Profil-Skripte (z. B. XDG User Dirs Update)
 │   ├── skel/                        # Vorlagen für /etc/skel (.zshrc, Dokumentvorlagen)
 │   └── usr/share/applications/      # Desktop-Starter-Dateien
 ├── README.md                        # Projektdokumentation für Endanwender
 └── LICENSE                          # MIT-Lizenz
 ```
 ---
 ## 3. Architekturprinzipien und Entwicklungsrichtlinien
 ### 3.1 Idempotenz (Mehrfache Ausführbarkeit)
 - Jedes Skript und jede Phase muss **vollständig idempotent** sein: Die wiederholte Ausführung darf keine Fehler erzeugen und keine doppelten Konfigurationseinträge hinterlassen.
 - Verwende vor dem Hinzufügen von Zeilen zu Konfigurationsdateien Prüfungen (z. B. `grep -q`) oder nutze saubere Konfigurationsverzeichnisse (`.d/`-Verzeichnisse).
 ### 3.2 Strikte Trennung von Root- und Benutzerrechten
 - Die Skripte laufen grundsätzlich mit Root-Rechten (`sudo ./setup.sh`).
 - **Niemals** Benutzerkonfigurationen unter `/root/` ablegen, wenn sie für den Desktop-Benutzer gedacht sind.
 - Der Zielbenutzer wird in `$TARGET_USER` gespeichert (ermittelt über `prompt_target_user` in `lib/utils.sh`).
 - Befehle im Kontext des regulären Benutzers **müssen** über `run_as_user "<befehl>"` ausgeführt werden.
 - Das Home-Verzeichnis des Zielbenutzers muss über `get_target_home "$TARGET_USER"` ermittelt werden.
 ### 3.3 Fehlerbehandlung und Shell-Standards
 - Alle Bash-Skripte **müssen** mit folgenden Flags starten:
  ```bash
  #!/usr/bin/env bash
  set -euo pipefail
  ```
 - Binde `lib/utils.sh` ein und rufe `setup_err_trap` am Anfang jedes Skripts auf:
  ```bash
  SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
  # shellcheck source=lib/utils.sh
  source "$SCRIPT_DIR/../lib/utils.sh"
  setup_err_trap
  ```
 - Verwende für temporäre Verzeichnisse immer `mktemp -d` und stelle sicher, dass am Skriptende oder bei Fehlern aufgeräumt wird:
  ```bash
  TMP_DIR="$(mktemp -d)"
  trap 'rm -rf "$TMP_DIR"' EXIT
  ```
 ### 3.4 Dateisicherungen (Backups)
 - Modifiziere bestehende Konfigurationsdateien (z. B. in `/etc/default/grub` oder `/etc/apt/`) nie ohne vorheriges Backup.
 - Nutze die Bibliotheksfunktion `backup_file "$DATEIPFAD"`. Diese erstellt Backups im Format `<datei>.backup_YYYYMMDD_HHMMSS`.
 ### 3.5 Debian-Standards & APT-Hygiene
 - **Deb822-Format**: Neue Paketquellen ausschließlich im Deb822-Format (`.sources`) unter `/etc/apt/sources.list.d/` ablegen.
 - **Keyrings**: GPG-Schlüsselbunde gehören nach `/etc/apt/keyrings/` mit Rechten `644`. Das veraltete `apt-key` darf **nicht** verwendet werden.
 - **Pinning**: APT-Prioritäten in `/etc/apt/preferences.d/` verwalten.
 - **Nicht-interaktive Paketinstallation**: APT-Befehle müssen immer `DEBIAN_FRONTEND=noninteractive` und `-y` bzw. `--no-install-recommends` (sofern passend) verwenden. Verwende bevorzugt die Wrapper in `lib/apt.sh` (`safe_apt_update`, `install_packages_from_file`).
 ### 3.6 Keine gefährlichen Login-Hooks & Shell-Verwaltung
 - **Keine Live-Downloads** (`curl | sh` / `wget | bash`) in `/etc/profile.d/` oder Login-Skripten.
 - Dotfiles und Vorlagen gehören nach `/etc/skel/` und werden bei Bedarf einmalig für bestehende Nutzer synchronisiert (`stages/07-skel-and-user.sh`).
 - Ändere Login-Shells niemals durch direkte Bearbeitung von `/etc/passwd` via `sed` oder `awk`, sondern ausschließlich über `chsh -s "$(command -v zsh)" "$TARGET_USER"`.
 ---
 ## 4. Hilfsbibliotheken (`lib/`)
 ### `lib/utils.sh`
 - `log_info "Nachricht"`: Blaue Info-Meldung.
 - `log_success "Nachricht"`: Grüne Erfolgsmeldung (`[✓]`).
 - `log_warn "Nachricht"`: Gelbe Warnung (`[WARN]`).
 - `log_error "Nachricht"`: Rote Fehlermeldung (`[ERROR]`).
 - `log_step "Titel"`: Hervorgehobener Abschnitts-Header.
 - `log_substep "Titel"`: Eingerückter Unterabschnitt.
 - `require_root`: Bricht ab, wenn das Skript nicht mit Root-Rechten ausgeführt wird.
 - `command_exists "tool"`: Prüft, ob ein Befehl im Pfad verfügbar ist.
 - `prompt_target_user`: Erkennt `$SUDO_USER` oder fragt interaktiv nach dem Zielbenutzer.
 - `prompt_ollama_models_path`: Fragt interaktiv nach dem Speicherort für Ollama KI-Modelle oder nutzt Standardpfad.
 - `get_target_home [username]`: Gibt den absoluten Pfad des Home-Verzeichnisses des Nutzers zurück.
 - `run_as_user "command"`: Führt einen Befehl als `$TARGET_USER` via `su - "$TARGET_USER" -c ...` aus.
 - `backup_file "filepath"`: Erstellt ein Backup einer Datei mit Zeitstempel.
 ### `lib/apt.sh`
 - `safe_apt_update`: Führt ein abgesichertes `apt-get update` durch.
 - `install_apt_keyring "name" "url"`: Lädt einen GPG-Schlüssel herunter, de-armort ihn sauber und speichert ihn in `/etc/apt/keyrings/<name>.gpg`.
 - `install_packages_from_file "filepath"`: Liest eine `.list`-Datei ein (ignoriert Kommentare `#` und Leerzeilen) und installiert alle Pakete via `apt-get install -y`.
 ### `lib/tui.sh`
 - `tui_show_stage_selection`: Zeigt ein `whiptail` Checklist-Menü zur interaktiven Auswahl der auszuführenden Phasen.
 ---
 ## 5. Arbeitsanweisungen für Modifikationen
 ### Neue Phase (Stage) hinzufügen
 1. Erstelle eine neue Datei `stages/XX-<name>.sh` (nummeriert nach Reihenfolge, mit `chmod +x`).
 2. Nutze das Standard-Template:
   ```bash
   #!/usr/bin/env bash
   # ==============================================================================
   # stages/XX-<name>.sh - Kurzbeschreibung der Phase
   # ==============================================================================
   set -euo pipefail
   SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
   # shellcheck source=lib/utils.sh
   source "$SCRIPT_DIR/../lib/utils.sh"
   setup_err_trap
   require_root
   log_step "Stage XX: <Name der Phase>"
   TARGET_USER="${TARGET_USER:-$(prompt_target_user)}"
   TARGET_HOME="$(get_target_home "$TARGET_USER")"
   # Implementierung (idempotent) ...
   log_success "Stage XX abgeschlossen."
   ```
 3. Registriere die neue Phase im Orchestrator `setup.sh` (Hilfetext `show_help`, Validierung in `run_stages`).
 4. Ergänze die Phase im TUI-Auswahlmenü in `lib/tui.sh`.
 5. Aktualisiere `README.md`.
 ### Paketlisten anpassen
 - Paketdateien liegen unter `config/packages/<kategorie>.list`.
 - Jede Zeile enthält genau einen Paketnamen.
 - Kommentare beginnen mit `#`. Leerzeilen sind erlaubt.
 ### Vorlagen und Skel-Dateien hinzufügen
 - Konfigurationsvorlagen für neue Benutzer gehören in `data/skel/`.
 - Dateivorlagen für den Dateimanager (XDG Templates) gehören nach `data/skel/Templates/`.
 ---
 ## 6. Verifikation & Qualitätssicherung
 Bevor Änderungen eingecheckt oder abgeschlossen werden:
 1. **ShellCheck ausführen**:
   Alle Bash-Skripte auf statische Fehler und Warnungen prüfen:
   ```bash
   shellcheck setup.sh lib/*.sh stages/*.sh
   ```
 2. **Dry-Run Validierung**:
   Sicherstellen, dass der Orchestrator im Simulationsmodus funktioniert:
   ```bash
   ./setup.sh --dry-run --stages 00,01,02
   ```
 3. **Syntaxprüfung**:
   ```bash
   bash -n setup.sh
   for f in lib/*.sh stages/*.sh; do bash -n "$f"; done
   ```
 4. **Pfad- und Berechtigungskonsistenz**:
   Prüfen, dass keine absoluten Pfade auf Benutzerverzeichnisse (`/home/...`) hartcodiert sind.
@@ -1,32 +1,141 @@
-# Setup
+# Debian Unstable (Sid) & Hyprland Setup Framework
-## Übersicht
+Ein modulares, sicheres und erweiterbares Framework zur automatisierten Einrichtung von **Debian GNU/Linux Unstable (Sid)** mit Hyprland Desktop, XanMod-Kernel, Hardware-Tuning und thematisch gegliederten Anwendungen.
-Dieses Repository enthält Skripte um ein Linux System mit Hyprland und diversen Programmen aufzusetzen.
+---
 Die entsprechenden Skripte befinden sich in den Branches zur jeweiligen Distribution.
-## Anforderungen
+## 🚀 Schnellstart
-Um die Skripte in diesem Repository auszuführen, stelle sicher, dass die folgenden Voraussetzungen erfüllt sind:
+### 1. One-Liner (Klonen & Starten)
 Klonen des Repositories und direkter Start des Setups in einem einzigen Befehl:
 ```bash
 git clone https://gitea.creative-dragonslayer.de/Scripts/Setup.git && cd Setup && sudo ./setup.sh
 ```
 Oder direkt vollautomatisch alle Stages (`00` bis `10`) ausführen:
 ```bash
 git clone https://gitea.creative-dragonslayer.de/Scripts/Setup.git && cd Setup && sudo ./setup.sh --all
 ```
- Die Skripte sind als bash-Skripte konzipiert.
+### 2. Interaktiver TUI-Modus (Empfohlen)
- Für die Skripte muss der richtige Branch der jewiligen Distribution ausgewählt werden.
+Starte das grafische Terminal-Menü (`whiptail`) zur flexiblen Auswahl einzelner Module:
- Daten werden vor der Ausführung nicht gesichert. Datenverlust möglich!
+```bash
 sudo ./setup.sh
 ```
-## Nutzung
+### 3. Vollautomatischer CLI-Modus
 Führe alle Phasen (`00` bis `10`) ohne Interaktion aus:
 ```bash
 sudo ./setup.sh --all
 ```
-1. Klone das Repository:
+### 4. Gezielte Modulauswahl
-   ```bash
+Installiere nur bestimmte Phasen (z. B. nur Paketlisten und Schriften):
-   git clone https://gitea.creative-dragonslayer.de/DragonSlayer_14/Setup.git
+```bash
-   ```
+sudo ./setup.sh --stages 04,05
-2. Wechsle in den richtigen Branch.
+```
 3. Navigiere in das Verzeichnis `Setup`, um die ausführbaren Dateien und Ressourcen zu finden.
 4. Folge den spezifischen Anweisungen in einzelnen Dateien oder Skripten für die korrekte Ausführung.
-## Lizenz
+### 5. Simulationslauf (Dry-Run)
 Überprüfe geplante Aktionen, ohne Änderungen am System vorzunehmen:
 ```bash
 ./setup.sh --dry-run --stages 01,02,04
 ```
-Dieses Projekt steht unter einer Open-Source-Lizenz. Weitere Informationen findest du in der Datei `LICENSE`.
+---
-## Autor
+## 🛠️ CLI-Optionen
-Erstellt und gepflegt von DragonSlayer_14.
+| Option | Argument | Beschreibung |
 | :--- | :--- | :--- |
 | `-a`, `--all` | – | Führt alle Phasen (`00` bis `10`) sequenziell aus |
 | `-s`, `--stages` | `<01,02,...>` | Kommagetrennte Liste der auszuführenden Phasen |
 | `-u`, `--user` | `<username>` | Zielbenutzer für Userland/Dotfiles (Standard: `$SUDO_USER` mit Bestätigungsabfrage) |
 | `-d`, `--dry-run` | – | Simuliert die Ausführung ohne Systemänderungen |
 | `-h`, `--help` | – | Zeigt die Hilfe und alle verfügbaren Stages an |
 ---
 ## 📁 Projektstruktur
 ```
 .
 ├── setup.sh                         # Zentraler Orchestrator (CLI Flags & whiptail TUI)
 ├── lib/                             # Wiederverwendbare Hilfsbibliotheken
 │   ├── utils.sh                     # Logging, Error-Traps (set -euo pipefail), Root/User-Erkennung & Abfrage
 │   ├── apt.sh                       # APT-Keyring-Management (/etc/apt/keyrings/), Deb822, Pinning
 │   └── tui.sh                       # Whiptail-Menüs und Dialoge
 ├── config/                          # Konfigurationsdateien & Paketlisten
 │   ├── setup.conf                   # Globale Variablen (Kernel, GRUB-Theme, Plymouth)
 │   └── packages/                    # Thematische Paketlisten
 │       ├── 01-base.list             # Grundlegende Systemwerkzeuge, Firmware, Microcode
 │       ├── 02-desktop.list          # Hyprland, Waybar, SDDM, Portale, Pipewire
 │       ├── 03-gaming.list           # Steam, Heroic, Lutris, Gamescope, MangoHud, Wine
 │       ├── 04-virtualization.list   # QEMU, KVM, Libvirt, Bridge-Tools
 │       ├── 05-multimedia.list       # VLC, Amberol, GIMP, Loupe, LibreOffice
 │       └── 06-flatpaks.list         # Flatpak App-IDs & Flathub
 ├── stages/                          # Sequenzielle, modular ausführbare Phasen
 │   ├── 00-preflight.sh              # Prüfung von Rechten, Ziel-User ($SUDO_USER) und Internet
 │   ├── 01-apt-unstable.sh           # Deb822-Quellen, Keyrings, Pinning, apt-listbugs, dist-upgrade
 │   ├── 02-kernel-hardware.sh        # XanMod-Kernel (main/edge), CPU P-State, Microcode, auto-cpufreq (Source)
 │   ├── 03-bootloader.sh             # GRUB Kernel-Parameter, Vimix-Theme, Plymouth Solar
 │   ├── 04-packages.sh               # Installation der ausgewählten thematischen Paketlisten
 │   ├── 05-fonts.sh                  # Download & Installation von JetBrainsMono, Fantasque, VictorMono
 │   ├── 06-services.sh               # Aktivierung von AppArmor, Docker, Libvirt, zram, Ollama
 │   ├── 07-skel-and-user.sh          # /etc/skel Vorlagen, ZSH-Shell-Setzen, Dotfiles-Sync
 │   ├── 08-flatpaks.sh               # Flathub Setup, Flatpak-Paketlisten-Installation
 │   ├── 09-apps.sh                   # Spotify, Waydroid, OpenDeck, Desktop-Starter, MIME-Types
 │   └── 10-hyprland.sh               # LinuxBeginnings Debian-Hyprland Auto-Installer & Dotfiles
 └── data/                            # Statische Konfigurationsdateien & Vorlagen
    ├── apt/
    │   ├── sources.list.d/          # debian-unstable.sources, xanmod.sources
    │   └── preferences.d/           # Pinning-Konfigurationen (unstable, xanmod)
    ├── etc/
    │   ├── environment.d/           # 99-raytracing.conf, 99-upscaling.conf
    │   └── profile.d/               # Bereinigte System-Profile-Skripte
    ├── skel/                        # .zshrc, .config/hypr, Templates für Dokumente & Skripte
    └── usr/share/applications/      # Desktop-Dateien (z. B. Spotify)
 ```
 ---
 ## 🔒 Sicherheits- & Stabilitätsmerkmale
 1. **Rechte- und Nutzertrennung**:
   - Automatische Erkennung des regulären Desktop-Benutzers via `$SUDO_USER` / interactivem Fallback.
   - Benutzerkonfigurationen und Gruppenrechte (`sudo`, `docker`, `libvirt`) werden sauber für den Zielbenutzer gesetzt.
 2. **Keine gefährlichen Login-Hooks**:
   - Vollständige Beseitigung unkontrollierter Live-Downloads (`curl | sh`) beim Login.
   - Standardkonforme Bereitstellung über `/etc/skel` für neue und bestehende Benutzer.
 3. **Idempotenz & Backups**:
   - Alle Phasen können beliebig oft wiederholt werden.
   - Vorhandene Dotfiles (`~/.zshrc`) und Konfigurationen (`/etc/default/grub`) werden vor Änderungen automatisch mit Zeitstempel (`.backup_YYYYMMDD_HHMMSS`) gesichert.
 4. **Debian Unstable Absicherung**:
   - Moderne Deb822-Quellen und dedizierte Keyrings in `/etc/apt/keyrings/`.
   - Installation von `apt-listbugs` und `apt-listchanges` vor dem `dist-upgrade` schützt vor bekannten kritischen Paketproblemen.
 5. **Sichere Shell-Verwaltung**:
   - Standardkonforme Änderung der Login-Shell via `chsh -s` statt direkter `/etc/passwd`-Modifikation.
 ---
 ## 🎮 Gaming & Performance-Optimierungen
 ### CPU P-State & Kernel-Parameter
 In `stages/03-bootloader.sh` wird der CPU-Hersteller automatisch ermittelt und in `/etc/default/grub` eingetragen:
 - **AMD CPUs**: `amd_pstate=active`
 - **Intel CPUs**: `intel_pstate=active`
 - **Latenz-Optimierung**: `rcutree.rcu_idle_gp_delay=1 threadirqs`
 ### Game Launch-Parameter (Steam / Lutris)
 ```bash
 # Standard Gaming Launch-Optionen mit MangoHud & Gamescope
 gamemoderun gamescope -W 2560 -H 1440 --force-grab-cursor --hdr-enabled --adaptive-sync -f -o 240 -r 240 -- mangohud %command%
 # Raytracing für DX12 Titel (RADV / Mesa)
 RADV_PERFTEST=gpl,rt,ngg_streamout VKD3D_CONFIG=dxr,dxr11 DXVK_ASYNC=1 AMD_VULKAN_ICD=RADV gamemoderun gamescope -W 2560 -H 1440 --force-grab-cursor --hdr-enabled --adaptive-sync -f -o 240 -r 240 -- mangohud %command%
 ```
 ---
 ## 📜 Lizenz & Autor
 - **Lizenz**: MIT License (siehe `LICENSE`)
 - **Autor**: DragonSlayer_14
@@ -0,0 +1,77 @@
 # ==============================================================================
 # config/packages/01-base.list - Base system utilities, firmware, shell & diagnostics
 # ==============================================================================
 7zip
 adb
 apparmor
 apparmor-notify
 apparmor-profiles
 apparmor-profiles-extra
 apparmor-utils
 apt-listbugs
 apt-listchanges
 aptitude
 baobab
 bat
 bleachbit
 bluetooth
 blueman
 bluez
 bruno
 btop
 ca-certificates
 clamav
 clamav-daemon
 clamav-docs
 clamav-freshclam
 command-not-found
 cpupower-gui
 cryptomator
 curl
 dconf-editor
 debian-goodies
 fastfetch
 file-roller
 firmware-linux
 firmware-linux-nonfree
 firmware-misc-nonfree
 flatpak
 flatseal
 fzf
 git
 glances
 gnome-disk-utility
 gnome-firmware
 gnome-logs
 gnome-system-monitor
 gparted
 htop
 hunspell
 hunspell-de-de-frami
 irqbalance
 keepassxc
 lsd
 man
 network-manager-gnome
 plymouth
 plymouth-themes
 resources
 rfkill
 ripgrep
 rpi-imager
 shellcheck
 sl
 systemd-timesyncd
 tar
 tealdeer
 timeshift
 topgrade
 tree
 unrar
 unzip
 zram-tools
 zsh
 zsh-autosuggestions
 zsh-doc
 zsh-syntax-highlighting
@@ -0,0 +1,40 @@
 # ==============================================================================
 # config/packages/02-desktop.list - Wayland/Hyprland desktop, display manager & tools
 # ==============================================================================
 cava
 codium
 dconf-editor
 flameshot
 floorp
 fragments
 gnome-calculator
 gnome-decoder
 gnome-font-viewer
 gnome-keyring
 gnome-snapshot
 gnome-text-editor
 grim
 impression
 input-remapper
 kitty
 localsend
 nodejs
 nwg-displays
 nwg-look
 obfuscate
 pipewire
 pipewire-pulse
 remmina
 sddm
 slurp
 speech-dispatcher
 swappy
 swaybg
 thunar
 vesktop
 wayland-utils
 wireplumber
 wl-clipboard
 xdg-user-dirs
 yazi
@@ -0,0 +1,22 @@
 # ==============================================================================
 # config/packages/03-gaming.list - Gaming tools, Vulkan drivers, Wine & Emulation
 # ==============================================================================
 gameconqueror
 gamemode
 gamescope
 heroic
 lutris
 mangohud
 mangoapp
 mesa-utils
 mesa-vulkan-drivers
 openrgb
 prismlauncher
 protontricks
 radeontop
 steam-installer
 steam-devices
 vulkan-tools
 wine
 winetricks
@@ -0,0 +1,10 @@
 # ==============================================================================
 # config/packages/04-virtualization.list - QEMU, KVM & Libvirt packages
 # ==============================================================================
 bridge-utils
 libvirt-clients
 libvirt-daemon-system
 qemu-system-x86
 qemu-utils
 virt-manager
@@ -0,0 +1,22 @@
 # ==============================================================================
 # config/packages/05-multimedia.list - Audio, Video, Graphics & Productivity
 # ==============================================================================
 amberol
 easyeffects
 ffmpeg
 gimp
 libreoffice
 libreoffice-gtk4
 libreoffice-l10n-de
 loupe
 simple-scan
 vlc
 vlc-data
 vlc-l10n
 vlc-plugin-access-extra
 vlc-plugin-base
 vlc-plugin-notify
 vlc-plugin-pipewire
 vlc-plugin-qt
 vlc-plugin-video-output
@@ -0,0 +1,17 @@
 # ==============================================================================
 # config/packages/06-flatpaks.list - Flathub Flatpak Application IDs
 # ==============================================================================
 # Communication & Productivity
 eu.betterbird.Betterbird
 im.fluffychat.Fluffychat
 org.pvermeer.WebAppHub
 io.github.giantpinkrobots.flatsweep
 # Creativity & AI
 org.musescore.MuseScore
 com.jeffser.Alpaca
 # Gaming & Compatibility
 net.davidotek.pupgui2
 io.github.rfrench3.scopebuddy-gui
@@ -0,0 +1,26 @@
 # ==============================================================================
 # config/setup.conf - Configuration parameters for Debian Unstable Setup
 # ==============================================================================
 # Kernel & Hardware
 # XanMod branches: "main" (stable & recommended), "edge" (bleeding-edge), "lts" (long-term support), "rt" (real-time)
 XANMOD_BRANCH="main"
 CPU_PSTATE_AUTO=1
 # Bootloader & Appearance
 GRUB_THEME="vimix"
 PLYMOUTH_THEME="solar"
 GRUB_TIMEOUT=0
 GRUB_TIMEOUT_STYLE="hidden"
 # Shell & Userland
 DEFAULT_SHELL="zsh"
 # Ollama AI Configuration
 OLLAMA_MODELS_DEFAULT="/mnt/Data/Software/ollama/models"
 OLLAMA_FLASH_ATTENTION="1"
 OLLAMA_KV_CACHE_TYPE="q8_0"
 OLLAMA_KEEP_ALIVE="30m"
 # Default Stages (if --all is passed or in default batch mode)
 ALL_STAGES="00 01 02 03 04 05 06 07 08 09 10"
@@ -0,0 +1,7 @@
 Package: *
 Pin: release a=unstable
 Pin-Priority: 900
 Package: *
 Pin: release a=experimental
 Pin-Priority: 100
@@ -0,0 +1,3 @@
 Package: *
 Pin: origin deb.xanmod.org
 Pin-Priority: 900
@@ -0,0 +1,5 @@
 Types: deb deb-src
 URIs: http://deb.debian.org/debian/
 Suites: unstable
 Components: main non-free-firmware non-free contrib
 Signed-By: /usr/share/keyrings/debian-archive-keyring.gpg
@@ -0,0 +1,5 @@
 Types: deb
 URIs: https://gitea.creative-dragonslayer.de/api/packages/Linuxapps/debian/
 Suites: stable
 Components: main
 Signed-By: /etc/apt/keyrings/gitea-Linuxapps.asc
@@ -0,0 +1,6 @@
 Types: deb
 URIs: https://gitea.creative-dragonslayer.de/api/packages/Mirror/debian/
 Suites: stable
 Components: main
 Architectures: amd64
 Signed-By: /etc/apt/keyrings/gitea-Mirror.asc
@@ -0,0 +1,5 @@
 Types: deb
 URIs: http://deb.xanmod.org
 Suites: releases
 Components: main
 Signed-By: /etc/apt/keyrings/xanmod-archive-keyring.gpg
@@ -0,0 +1,3 @@
 # Raytracing support environment flags for RADV / Mesa
 VKD3D_CONFIG=dxr11,dxr
 RADV_PERFTEST=rt
@@ -0,0 +1,3 @@
 # Upscaling and gaming enhancement variables
 WINE_FULLSCREEN_FSR=1
 WINE_FULLSCREEN_FSR_STRENGTH=2
@@ -0,0 +1,5 @@
 #!/bin/sh
 # Update XDG User Dirs if tool is present
 if command -v xdg-user-dirs-update >/dev/null 2>&1; then
    xdg-user-dirs-update
 fi
@@ -0,0 +1,10 @@
 #!/bin/sh
 # Hide Waydroid desktop applications from standard desktop menus
 if [ -d "$HOME/.local/share/applications" ]; then
    for app in "$HOME"/.local/share/applications/waydroid.*.desktop; do
        [ -f "$app" ] || continue
        if ! grep -q "NoDisplay" "$app"; then
            sed -i '/^Icon=/a NoDisplay=true' "$app" 2>/dev/null || true
        fi
    done
 fi
@@ -0,0 +1,12 @@
 #!/bin/sh
 # Add sbin and /usr/sbin to PATH for sudoers if not already present
 if groups 2>/dev/null | grep -q "\bsudo\b"; then
    case ":$PATH:" in
        *":/sbin:"*) ;;
        *) export PATH="$PATH:/sbin" ;;
    esac
    case ":$PATH:" in
        *":/usr/sbin:"*) ;;
        *) export PATH="$PATH:/usr/sbin" ;;
    esac
 fi
@@ -0,0 +1,23 @@
 #!/bin/sh
 # Display sudo reminder for administrative users once after initial setup
 SUDO_FILE="$HOME/.sudo_as_admin_successful"
 HUSH_FILE="$HOME/.hushlogin"
 if [ -f "$SUDO_FILE" ]; then
    FILE_MOD_TIME=$(stat -c %Y "$SUDO_FILE" 2>/dev/null || echo 0)
    ONE_WEEK_AGO=$(date -d '7 days ago' +%s 2>/dev/null || echo 0)
    if [ "$FILE_MOD_TIME" -gt 0 ] && [ "$ONE_WEEK_AGO" -gt 0 ] && [ "$FILE_MOD_TIME" -lt "$ONE_WEEK_AGO" ]; then
        rm -f "$SUDO_FILE"
    fi
 fi
 if [ ! -e "$SUDO_FILE" ] && [ ! -e "$HUSH_FILE" ]; then
    case " $(groups 2>/dev/null) " in
        *\ admin\ *|*\ sudo\ *)
            if [ -x /usr/bin/sudo ]; then
                echo 'To run a command as administrator (user "root"), use "sudo <command>".'
                echo 'See "man sudo_root" for details.'
            fi
            ;;
    esac
 fi
@@ -0,0 +1,26 @@
 #!/bin/sh
 # /etc/profile.d/desktop_session_xdg_dirs.sh - Prepend a $DESKTOP_SESSION-named directory to $XDG_CONFIG_DIRS and $XDG_DATA_DIRS
 DEFAULT_XDG_CONFIG_DIRS="/etc/xdg"
 DEFAULT_XDG_DATA_DIRS="/usr/local/share/:/usr/share/"
 if [ -n "$DESKTOP_SESSION" ]; then
 	# readd default if was empty
 	if [ -z "$XDG_CONFIG_DIRS" ]; then
 		XDG_CONFIG_DIRS="$DEFAULT_XDG_CONFIG_DIRS"
 	fi
 	if [ -n "${XDG_CONFIG_DIRS##*"$DEFAULT_XDG_CONFIG_DIRS"/xdg-"$DESKTOP_SESSION"*}" ]; then
 		XDG_CONFIG_DIRS="$DEFAULT_XDG_CONFIG_DIRS"/xdg-"$DESKTOP_SESSION":"$XDG_CONFIG_DIRS"
 	fi
 	export XDG_CONFIG_DIRS
 	# gnome is already added if gnome-session installed
 	if [ "$DESKTOP_SESSION" != "gnome" ]; then
 		if [ -z "$XDG_DATA_DIRS" ]; then
 			XDG_DATA_DIRS="$DEFAULT_XDG_DATA_DIRS"
 		fi
 		if [ -n "${XDG_DATA_DIRS##*/usr/share/"$DESKTOP_SESSION"*}" ]; then
 			XDG_DATA_DIRS=/usr/share/"$DESKTOP_SESSION":"$XDG_DATA_DIRS"
 		fi
 		export XDG_DATA_DIRS
 	fi
 fi
@@ -0,0 +1,97 @@
 # ==============================================================================
 # Rudimentäre Hyprland-Konfiguration (Standard für neue Benutzer)
 # ==============================================================================
 # Monitor Setup (Standard: Automatische Auflösung & Positionierung)
 monitor = , preferred, auto, 1
 # Modifikator-Taste: SUPER (Windows-Taste)
 $mainMod = SUPER
 # Standard-Terminal
 $terminal = kitty
 # ------------------------------------------------------------------------------
 # Tastenbelegungen (Keybindings)
 # ------------------------------------------------------------------------------
 # SUPER + ENTER: Kitty Terminal öffnen
 bind = $mainMod, RETURN, exec, $terminal
 bind = $mainMod, Return, exec, $terminal
 # SUPER + Q: Aktives Fenster schließen
 bind = $mainMod, Q, killactive,
 # Grundlegende Navigation & Fensterverwaltung
 bind = $mainMod, M, exit,
 bind = $mainMod, E, exec, thunar
 bind = $mainMod, V, togglefloating,
 bind = $mainMod, F, fullscreen,
 # Fokus mit Pfeiltasten wechseln
 bind = $mainMod, left, movefocus, l
 bind = $mainMod, right, movefocus, r
 bind = $mainMod, up, movefocus, u
 bind = $mainMod, down, movefocus, d
 # Workspaces 1-10 wechseln
 bind = $mainMod, 1, workspace, 1
 bind = $mainMod, 2, workspace, 2
 bind = $mainMod, 3, workspace, 3
 bind = $mainMod, 4, workspace, 4
 bind = $mainMod, 5, workspace, 5
 bind = $mainMod, 6, workspace, 6
 bind = $mainMod, 7, workspace, 7
 bind = $mainMod, 8, workspace, 8
 bind = $mainMod, 9, workspace, 9
 bind = $mainMod, 0, workspace, 10
 # Aktives Fenster auf Workspace 1-10 verschieben
 bind = $mainMod SHIFT, 1, movetoworkspace, 1
 bind = $mainMod SHIFT, 2, movetoworkspace, 2
 bind = $mainMod SHIFT, 3, movetoworkspace, 3
 bind = $mainMod SHIFT, 4, movetoworkspace, 4
 bind = $mainMod SHIFT, 5, movetoworkspace, 5
 bind = $mainMod SHIFT, 6, movetoworkspace, 6
 bind = $mainMod SHIFT, 7, movetoworkspace, 7
 bind = $mainMod SHIFT, 8, movetoworkspace, 8
 bind = $mainMod SHIFT, 9, movetoworkspace, 9
 bind = $mainMod SHIFT, 0, movetoworkspace, 10
 # Fenster mit Maus bewegen und vergrößern/verkleinern
 bindm = $mainMod, mouse:272, movewindow
 bindm = $mainMod, mouse:273, resizewindow
 # ------------------------------------------------------------------------------
 # Erscheinungsbild & Verhalten
 # ------------------------------------------------------------------------------
 general {
    gaps_in = 4
    gaps_out = 8
    border_size = 2
    col.active_border = rgba(33ccffee) rgba(00ff99ee) 45deg
    col.inactive_border = rgba(595959aa)
    layout = dwindle
 }
 decoration {
    rounding = 8
 }
 animations {
    enabled = yes
 }
 input {
    kb_layout = de
    follow_mouse = 1
    touchpad {
        natural_scroll = yes
    }
 }
 # ------------------------------------------------------------------------------
 # Autostart nach der Anmeldung
 # ------------------------------------------------------------------------------
 # Fragt nach der ersten Anmeldung nach der gewünschten Dotfiles-Konfiguration
 # (LinuxBeginnings Hyprland-Dots oder eigenes Git-Repository für ~/.config)
 exec-once = ~/.config/hypr/scripts/install-dots-prompt.sh
@@ -0,0 +1,357 @@
 #!/usr/bin/env bash
 # ==============================================================================
 # ~/.config/hypr/scripts/install-dots-prompt.sh
 # Ersteinrichtung beim ersten Login:
 # 1) Desktop-Konfiguration (LinuxBeginnings Hyprland-Dots oder eigenes Git-Repo)
 # 2) Installation der JetBrains Junie CLI & AwesomeJunieSkills
 # ==============================================================================
 set -euo pipefail
 MARKER_FILE="$HOME/.config/hypr/.dots_prompted"
 FORCE=0
 for arg in "$@"; do
    case "$arg" in
        -f|--force)
            FORCE=1
            ;;
    esac
 done
 # Wenn bereits abgefragt und kein --force übergeben wurde, beenden
 if [[ "$FORCE" -eq 0 && -f "$MARKER_FILE" ]]; then
    exit 0
 fi
 # Wenn nicht in einem interaktiven Terminal ausgeführt (z. B. via Hyprland exec-once),
 # starte das Skript in einem Kitty-Fenster:
 if [[ ! -t 0 || ! -t 1 ]]; then
    if command -v kitty >/dev/null 2>&1; then
        exec kitty --title "System-Ersteinrichtung & Dotfiles" bash -c "$0 --in-terminal; echo; read -r -p 'Drücke Enter zum Schließen...' || true"
    else
        exit 0
    fi
 fi
 # ANSI Farben
 CLR_RESET='\033[0m'
 CLR_BOLD='\033[1m'
 CLR_CYAN='\033[0;36m'
 CLR_GREEN='\033[0;32m'
 CLR_YELLOW='\033[0;33m'
 CLR_RED='\033[0;31m'
 CLR_BLUE='\033[0;34m'
 CLR_MAGENTA='\033[0;35m'
 mark_as_prompted() {
    mkdir -p "$(dirname "$MARKER_FILE")" 2>/dev/null || true
    touch "$MARKER_FILE" 2>/dev/null || true
 }
 install_oh_my_zsh() {
    local zsh_dir="$HOME/.oh-my-zsh"
    printf "\n"
    printf "%b\n" "${CLR_BOLD}${CLR_CYAN}==============================================================================${CLR_RESET}"
    printf "%b\n" "${CLR_BOLD}${CLR_CYAN}                   Oh-My-Zsh & Shell-Konfiguration                            ${CLR_RESET}"
    printf "%b\n" "${CLR_BOLD}${CLR_CYAN}==============================================================================${CLR_RESET}"
    printf "\n"
    if [[ ! -d "$zsh_dir" ]]; then
        printf "%b\n" "${CLR_CYAN}[INFO] Richte Oh-My-Zsh für $USER ein...${CLR_RESET}"
        if command -v git >/dev/null 2>&1; then
            if git clone --depth=1 https://github.com/ohmyzsh/ohmyzsh.git "$zsh_dir"; then
                mkdir -p "$zsh_dir/custom/plugins"
                git clone --depth=1 https://github.com/zsh-users/zsh-autosuggestions "$zsh_dir/custom/plugins/zsh-autosuggestions" 2>/dev/null || true
                git clone --depth=1 https://github.com/zsh-users/zsh-syntax-highlighting "$zsh_dir/custom/plugins/zsh-syntax-highlighting" 2>/dev/null || true
                printf "%b\n" "${CLR_GREEN}[✓] Oh-My-Zsh erfolgreich eingerichtet.${CLR_RESET}"
            else
                printf "%b\n" "${CLR_YELLOW}[WARNUNG] Oh-My-Zsh konnte nicht geklont werden.${CLR_RESET}"
            fi
        else
            printf "%b\n" "${CLR_RED}[FEHLER] 'git' ist nicht installiert. Oh-My-Zsh konnte nicht eingerichtet werden.${CLR_RESET}"
        fi
    else
        # Plugins sicherstellen
        if [[ ! -d "$zsh_dir/custom/plugins/zsh-autosuggestions" ]] && command -v git >/dev/null 2>&1; then
            git clone --depth=1 https://github.com/zsh-users/zsh-autosuggestions "$zsh_dir/custom/plugins/zsh-autosuggestions" 2>/dev/null || true
        fi
        if [[ ! -d "$zsh_dir/custom/plugins/zsh-syntax-highlighting" ]] && command -v git >/dev/null 2>&1; then
            git clone --depth=1 https://github.com/zsh-users/zsh-syntax-highlighting "$zsh_dir/custom/plugins/zsh-syntax-highlighting" 2>/dev/null || true
        fi
        printf "%b\n" "${CLR_GREEN}[✓] Oh-My-Zsh ist bereits vorhanden und konfiguriert.${CLR_RESET}"
    fi
 }
 install_junie_cli_and_skills() {
    printf "\n"
    printf "%b\n" "${CLR_BOLD}${CLR_CYAN}==============================================================================${CLR_RESET}"
    printf "%b\n" "${CLR_BOLD}${CLR_CYAN}         JetBrains Junie CLI & AwesomeJunieSkills Installation                ${CLR_RESET}"
    printf "%b\n" "${CLR_BOLD}${CLR_CYAN}==============================================================================${CLR_RESET}"
    printf "\n"
    # 1. JetBrains Junie CLI installieren
    printf "%b\n" "${CLR_CYAN}[1/2] Installiere JetBrains Junie CLI...${CLR_RESET}"
    if command -v curl >/dev/null 2>&1; then
        if curl -fsSL https://junie.jetbrains.com/install.sh | bash; then
            printf "%b\n" "${CLR_GREEN}[✓] JetBrains Junie CLI erfolgreich installiert.${CLR_RESET}"
        else
            printf "%b\n" "${CLR_YELLOW}[WARNUNG] Installation von JetBrains Junie CLI fehlgeschlagen oder unterbrochen.${CLR_RESET}"
        fi
    else
        printf "%b\n" "${CLR_RED}[FEHLER] 'curl' ist nicht installiert. Junie CLI konnte nicht geladen werden.${CLR_RESET}"
    fi
    # 2. AwesomeJunieSkills im Benutzer-Skillverzeichnis (~/.junie/skills) klonen / aktualisieren
    printf "\n"
    printf "%b\n" "${CLR_CYAN}[2/2] Installiere AwesomeJunieSkills im Benutzer-Skillverzeichnis (~/.junie/skills)...${CLR_RESET}"
    local skills_dir="$HOME/.junie/skills"
    local repo_dir="$skills_dir/awesome-junie-skills"
    mkdir -p "$skills_dir"
    if command -v git >/dev/null 2>&1; then
        if [[ -d "$repo_dir/.git" ]]; then
            printf "%b\n" "${CLR_BLUE}[INFO] Repository existiert bereits in $repo_dir. Führe 'git pull' aus...${CLR_RESET}"
            if git -C "$repo_dir" pull --ff-only 2>/dev/null; then
                printf "%b\n" "${CLR_GREEN}[✓] AwesomeJunieSkills erfolgreich aktualisiert.${CLR_RESET}"
            else
                printf "%b\n" "${CLR_YELLOW}[WARNUNG] 'git pull' in $repo_dir fehlgeschlagen.${CLR_RESET}"
            fi
        else
            printf "%b\n" "${CLR_BLUE}[INFO] Klone AwesomeJunieSkills nach $repo_dir...${CLR_RESET}"
            rm -rf "$repo_dir" 2>/dev/null || true
            if git clone https://github.com/alebaffa/awesome-junie-skills.git "$repo_dir"; then
                printf "%b\n" "${CLR_GREEN}[✓] AwesomeJunieSkills erfolgreich nach $repo_dir geklont.${CLR_RESET}"
            else
                printf "%b\n" "${CLR_YELLOW}[WARNUNG] Klonen von AwesomeJunieSkills fehlgeschlagen.${CLR_RESET}"
            fi
        fi
        # Symlinks für alle Skills im Skill-Hauptordner erstellen
        if [[ -d "$repo_dir" ]]; then
            local count=0
            for skill_path in "$repo_dir"/*; do
                if [[ -d "$skill_path" && -f "$skill_path/SKILL.md" ]]; then
                    local s_name
                    s_name="$(basename "$skill_path")"
                    ln -sfn "$skill_path" "$skills_dir/$s_name"
                    ((count++)) || true
                fi
            done
            printf "%b\n" "${CLR_GREEN}[✓] $count Skills verknüpft in '$skills_dir' (kann via 'git pull' in '$repo_dir' aktualisiert werden).${CLR_RESET}"
        fi
        # Junie config.json konfigurieren (skill-locations)
        mkdir -p "$HOME/.junie"
        local config_file="$HOME/.junie/config.json"
        if command -v python3 >/dev/null 2>&1; then
            python3 -c "
 import json, os
 cfg_path = os.path.expanduser('$config_file')
 repo_path = os.path.expanduser('$repo_dir')
 data = {}
 if os.path.exists(cfg_path):
    try:
        with open(cfg_path, 'r', encoding='utf-8') as f:
            data = json.load(f)
    except Exception:
        data = {}
 locs = data.get('skill-locations', [])
 if repo_path not in locs:
    locs.append(repo_path)
 data['skill-locations'] = locs
 with open(cfg_path, 'w', encoding='utf-8') as f:
    json.dump(data, f, indent=2)
 " 2>/dev/null || true
        fi
    else
        printf "%b\n" "${CLR_RED}[FEHLER] 'git' ist nicht installiert. AwesomeJunieSkills konnte nicht eingerichtet werden.${CLR_RESET}"
    fi
 }
 install_linuxbeginnings() {
    printf "\n"
    printf "%b\n" "${CLR_GREEN}${CLR_BOLD}[INFO] Starte Installation der LinuxBeginnings Hyprland-Dotfiles...${CLR_RESET}"
    printf "\n"
    if command -v curl >/dev/null 2>&1; then
        sh <(curl -fsSL https://raw.githubusercontent.com/LinuxBeginnings/Hyprland-Dots/main/Distro-Hyprland.sh)
    else
        printf "%b\n" "${CLR_RED}[FEHLER] 'curl' ist nicht installiert. Bitte installieren Sie curl und wiederholen Sie den Vorgang.${CLR_RESET}"
    fi
 }
 clone_custom_repo() {
    if ! command -v git >/dev/null 2>&1; then
        printf "\n%b\n" "${CLR_RED}[FEHLER] 'git' ist nicht installiert. Bitte installieren Sie git zuerst.${CLR_RESET}"
        return 1
    fi
    while true; do
        printf "\n"
        printf "%b\n" "${CLR_BOLD}${CLR_CYAN}--- Eigenes Git-Repository für ~/.config klonen ---${CLR_RESET}"
        printf "%b\n" "Geben Sie die Git-URL Ihres Dotfiles-/Config-Repositories an."
        printf "%b\n" "Beispiele:"
        printf "%b\n" "  HTTPS : ${CLR_BLUE}https://github.com/Benutzername/mein-config-repo.git${CLR_RESET}"
        printf "%b\n" "  SSH   : ${CLR_BLUE}git@github.com:Benutzername/mein-config-repo.git${CLR_RESET}"
        printf "\n"
        printf "%b\n" "${CLR_YELLOW}Hinweise zur Authentifizierung:${CLR_RESET}"
        printf "%b\n" "  - ${CLR_BOLD}HTTPS:${CLR_RESET} Bei privaten Repositories fragt Git nach Benutzername & Personal Access Token (PAT)."
        printf "%b\n" "  - ${CLR_BOLD}SSH:${CLR_RESET}   Erfordert einen hinterlegten SSH-Schlüssel (z. B. in ~/.ssh/ oder via ssh-agent)."
        printf "\n"
        read -r -p "Git-Repository-URL (oder 'q' zum Abbrechen): " repo_url
        repo_url="$(echo "$repo_url" | xargs)"
        if [[ "$repo_url" == "q" || "$repo_url" == "Q" || -z "$repo_url" ]]; then
            printf "%b\n" "${CLR_YELLOW}[INFO] Vorgang abgebrochen. Kehre zum Hauptmenü zurück.${CLR_RESET}"
            return 0
        fi
        # SSH-Prüfung und Hilfestellung
        if [[ "$repo_url" =~ ^git@ || "$repo_url" =~ ^ssh:// ]]; then
            local ssh_keys_found=0
            if [[ -d "$HOME/.ssh" ]]; then
                for k in "$HOME/.ssh"/id_*; do
                    if [[ -f "$k" && ! "$k" =~ \.pub$ ]]; then
                        ssh_keys_found=1
                        break
                    fi
                done
            fi
            if [[ "$ssh_keys_found" -eq 0 ]]; then
                printf "\n"
                printf "%b\n" "${CLR_YELLOW}[WARNUNG] Es wurde kein lokaler SSH-Privatschlüssel in ~/.ssh/ gefunden.${CLR_RESET}"
                read -r -p "Möchten Sie vor dem Klonen ein neues SSH-Schlüsselpaar (ed25519) generieren? [j/N]: " gen_ssh || gen_ssh="n"
                if [[ "$gen_ssh" =~ ^[JjYy] ]]; then
                    mkdir -p "$HOME/.ssh"
                    chmod 700 "$HOME/.ssh"
                    ssh-keygen -t ed25519 -f "$HOME/.ssh/id_ed25519" -C "$USER@$(hostname)"
                    printf "\n%b\n" "${CLR_GREEN}Neuer öffentlicher SSH-Schlüssel (~/.ssh/id_ed25519.pub):${CLR_RESET}"
                    cat "$HOME/.ssh/id_ed25519.pub"
                    printf "\n%b\n" "Bitte fügen Sie diesen Schlüssel bei GitHub/GitLab zu Ihrem Account hinzu."
                    if command -v wl-copy >/dev/null 2>&1; then
                        if wl-copy < "$HOME/.ssh/id_ed25519.pub" 2>/dev/null; then
                            printf "%b\n" "${CLR_GREEN}(In die Zwischenablage kopiert!)${CLR_RESET}"
                        fi
                    fi
                    read -r -p "Drücken Sie Enter, sobald der SSH-Key hinterlegt wurde..."
                fi
            fi
        fi
        # Backup und Klon-Vorgang vorbereiten
        local timestamp
        timestamp="$(date +%Y%m%d_%H%M%S)"
        local backup_dir="$HOME/.config.backup_$timestamp"
        printf "\n"
        printf "%b\n" "${CLR_CYAN}[1/3] Sichere bestehendes ~/.config-Verzeichnis nach ${backup_dir}...${CLR_RESET}"
        if [[ -d "$HOME/.config" ]]; then
            mv "$HOME/.config" "$backup_dir"
        fi
        printf "%b\n" "${CLR_CYAN}[2/3] Klone Repository direkt nach ~/.config...${CLR_RESET}"
        # Git ausführen mit aktivierter Terminal-Eingabeaufforderung für Authentifizierung
        if env GIT_TERMINAL_PROMPT=1 git clone --recurse-submodules "$repo_url" "$HOME/.config"; then
            printf "\n"
            printf "%b\n" "${CLR_GREEN}${CLR_BOLD}[ERFOLG] Repository wurde erfolgreich nach ~/.config geklont!${CLR_RESET}"
            printf "%b\n" "  - Ihr gesamter ${CLR_BOLD}~/.config${CLR_RESET}-Ordner ist nun das Git-Repository."
            printf "%b\n" "  - Vorherige Konfigurationen wurden gesichert in: ${CLR_BOLD}${backup_dir}${CLR_RESET}"
            # Hyprland-Konfiguration neu laden falls aktiv
            if command -v hyprctl >/dev/null 2>&1; then
                printf "\n"
                printf "%b\n" "${CLR_CYAN}[3/3] Lade Hyprland-Konfiguration neu...${CLR_RESET}"
                hyprctl reload 2>/dev/null || true
                printf "%b\n" "${CLR_GREEN}[✓] Hyprland erfolgreich aktualisiert.${CLR_RESET}"
            fi
            printf "\n"
            printf "%b\n" "${CLR_GREEN}Dotfiles-Einrichtung abgeschlossen!${CLR_RESET}"
            return 0
        else
            printf "\n"
            printf "%b\n" "${CLR_RED}${CLR_BOLD}[FEHLER] Git Clone ist fehlgeschlagen (Authentifizierungsfehler, falsche URL oder Netzwerkproblem).${CLR_RESET}"
            printf "%b\n" "${CLR_YELLOW}[ROLLBACK] Stelle vorheriges ~/.config-Verzeichnis aus dem Backup wieder her...${CLR_RESET}"
            rm -rf "$HOME/.config" 2>/dev/null || true
            if [[ -d "$backup_dir" ]]; then
                mv "$backup_dir" "$HOME/.config"
                printf "%b\n" "${CLR_GREEN}[✓] Ursprüngliches ~/.config-Verzeichnis wurde vollständig wiederhergestellt.${CLR_RESET}"
            fi
            printf "\n"
            read -r -p "Möchten Sie es erneut versuchen? [J/n]: " retry || retry="n"
            if [[ ! "$retry" =~ ^[JjYy] && -n "$retry" ]]; then
                return 0
            fi
        fi
    done
 }
 clear 2>/dev/null || true
 printf "%b\n" "${CLR_BOLD}${CLR_CYAN}==============================================================================${CLR_RESET}"
 printf "%b\n" "${CLR_BOLD}${CLR_CYAN}           Hyprland Desktop - Dotfiles Setup & Konfiguration                  ${CLR_RESET}"
 printf "%b\n" "${CLR_BOLD}${CLR_CYAN}==============================================================================${CLR_RESET}"
 printf "\n"
 printf "%b\n" "Willkommen auf Ihrem neuen Debian Unstable Hyprland-System!"
 printf "\n"
 printf "%b\n" "Aktuell ist eine rudimentäre Basiskonfiguration aktiv:"
 printf "%b\n" "  - ${CLR_BOLD}SUPER + ENTER${CLR_RESET} : Terminal (Kitty) öffnen"
 printf "%b\n" "  - ${CLR_BOLD}SUPER + Q${CLR_RESET}     : Aktives Fenster schließen"
 printf "\n"
 printf "%b\n" "Wie möchten Sie Ihre Desktop-Konfiguration (Dotfiles) einrichten?"
 printf "\n"
 printf "%b\n" "  ${CLR_BOLD}[1]${CLR_RESET} ${CLR_GREEN}LinuxBeginnings Hyprland-Dotfiles installieren${CLR_RESET}"
 printf "%b\n" "      Vollständig vorkonfiguriertes Setup (Waybar, Rofi, Animationen, Themes)"
 printf "%b\n" "      URL: https://github.com/LinuxBeginnings/Hyprland-Dots"
 printf "\n"
 printf "%b\n" "  ${CLR_BOLD}[2]${CLR_RESET} ${CLR_MAGENTA}Eigenes Git-Repository als ~/.config klonen${CLR_RESET}"
 printf "%b\n" "      Klont Ihr eigenes Git-Repository direkt als vollständigen ~/.config-Ordner."
 printf "%b\n" "      (Unterstützt HTTPS & SSH inkl. Authentifizierung)"
 printf "\n"
 printf "%b\n" "  ${CLR_BOLD}[3]${CLR_RESET} ${CLR_YELLOW}Überspringen / Basiskonfiguration beibehalten${CLR_RESET}"
 printf "%b\n" "      Keine Änderungen vornehmen (kann später manuell eingerichtet werden)."
 printf "\n"
 printf "%b\n" "${CLR_BOLD}${CLR_CYAN}------------------------------------------------------------------------------${CLR_RESET}"
 while true; do
    read -r -p "Bitte wählen Sie eine Option [1-3] (Standard: 1): " choice || choice="1"
    choice="$(echo "$choice" | xargs)"
    [[ -z "$choice" ]] && choice="1"
    case "$choice" in
        1)
            install_linuxbeginnings
            break
            ;;
        2)
            clone_custom_repo
            break
            ;;
        3)
            printf "\n"
            printf "%b\n" "${CLR_YELLOW}[INFO] Dotfiles-Einrichtung übersprungen. Die Basiskonfiguration bleibt aktiv.${CLR_RESET}"
            break
            ;;
        *)
            printf "%b\n" "${CLR_RED}Ungültige Eingabe. Bitte 1, 2 oder 3 wählen.${CLR_RESET}"
            ;;
    esac
 done
 # Oh-My-Zsh & Plugins einrichten
 install_oh_my_zsh
 # JetBrains Junie CLI & AwesomeJunieSkills installieren
 install_junie_cli_and_skills
 # Marker-Datei setzen
 mark_as_prompted
 printf "\n"
 printf "%b\n" "${CLR_GREEN}${CLR_BOLD}[✓] Ersteinrichtung vollständig abgeschlossen!${CLR_RESET}"
 printf "%b\n" "Sie können dieses Menü jederzeit erneut aufrufen mit:"
 printf "%b\n" "  ${CLR_BOLD}~/.config/hypr/scripts/install-dots-prompt.sh --force${CLR_RESET}"
@@ -0,0 +1,75 @@
 # If you come from bash you might have to change your $PATH.
 # export PATH=$HOME/bin:/usr/local/bin:$PATH
 export ZSH="$HOME/.oh-my-zsh"
 # Automatic Oh-My-Zsh installation on login / shell startup if not yet installed
 if [[ ! -d "$ZSH" ]]; then
    if command -v git >/dev/null 2>&1; then
        echo "Oh-My-Zsh ist nicht eingerichtet. Installiere Oh-My-Zsh für $USER..."
        if git clone --depth=1 https://github.com/ohmyzsh/ohmyzsh.git "$ZSH" 2>/dev/null; then
            mkdir -p "${ZSH_CUSTOM:-$ZSH/custom}/plugins"
            git clone --depth=1 https://github.com/zsh-users/zsh-autosuggestions "${ZSH_CUSTOM:-$ZSH/custom}/plugins/zsh-autosuggestions" 2>/dev/null || true
            git clone --depth=1 https://github.com/zsh-users/zsh-syntax-highlighting "${ZSH_CUSTOM:-$ZSH/custom}/plugins/zsh-syntax-highlighting" 2>/dev/null || true
            echo "Oh-My-Zsh erfolgreich eingerichtet."
        fi
    fi
 else
    # Plugins sicherstellen, falls Oh-My-Zsh existiert aber Custom-Plugins fehlen
    if [[ ! -d "${ZSH_CUSTOM:-$ZSH/custom}/plugins/zsh-autosuggestions" ]] && command -v git >/dev/null 2>&1; then
        git clone --depth=1 https://github.com/zsh-users/zsh-autosuggestions "${ZSH_CUSTOM:-$ZSH/custom}/plugins/zsh-autosuggestions" 2>/dev/null || true
    fi
    if [[ ! -d "${ZSH_CUSTOM:-$ZSH/custom}/plugins/zsh-syntax-highlighting" ]] && command -v git >/dev/null 2>&1; then
        git clone --depth=1 https://github.com/zsh-users/zsh-syntax-highlighting "${ZSH_CUSTOM:-$ZSH/custom}/plugins/zsh-syntax-highlighting" 2>/dev/null || true
    fi
 fi
 apt_pref='apt'
 apt_upgr='upgrade'
 ZSH_THEME="agnosterzak"
 plugins=( 
    alias-finder
    aliases
    colored-man-pages
    command-not-found
    common-aliases
    composer
    cp
    debian
    docker
    git
    jsontools
    kitty
    python
    ssh
    symfony
    themes
    vscode
    zsh-autosuggestions
    zsh-syntax-highlighting
 )
 # Oh-My-Zsh configuration
 if [[ -d "$ZSH" && -f "$ZSH/oh-my-zsh.sh" ]]; then
    source "$ZSH/oh-my-zsh.sh"
 fi
 # Fastfetch system info banner
 if command -v fastfetch >/dev/null 2>&1; then
    if [[ -f "$HOME/.config/fastfetch/config-compact.jsonc" ]]; then
        fastfetch -c "$HOME/.config/fastfetch/config-compact.jsonc"
    else
        fastfetch
    fi
 fi
 # Aliases using modern tools with fallback
 if command -v lsd >/dev/null 2>&1; then
    alias ls='lsd'
    alias l='ls -l'
    alias la='ls -a'
    alias lla='ls -la'
    alias lt='ls --tree'
 fi
@@ -0,0 +1,2 @@
 #!/bin/bash
@@ -0,0 +1 @@
@@ -0,0 +1,2 @@
 #!/usr/bin/env python3
@@ -0,0 +1 @@
@@ -0,0 +1,7 @@
 [Desktop Entry]
 Name=Spotify
 Exec=/usr/bin/spotify
 Icon=spotify-client
 Terminal=false
 Type=Application
 Categories=Audio;Music;
@@ -0,0 +1,151 @@
 #!/usr/bin/env bash
 # ==============================================================================
 # lib/apt.sh - APT, Deb822, GPG Keyring and Package installation utilities
 # ==============================================================================
 set -euo pipefail
 APT_KEYRINGS_DIR="/etc/apt/keyrings"
 APT_SOURCES_DIR="/etc/apt/sources.list.d"
 APT_PREFERENCES_DIR="/etc/apt/preferences.d"
 # Ensure the standard keyring directory exists
 apt_ensure_keyrings_dir() {
    if [[ ! -d "$APT_KEYRINGS_DIR" ]]; then
        log_info "Creating keyrings directory: $APT_KEYRINGS_DIR"
        mkdir -p "$APT_KEYRINGS_DIR"
        chmod 0755 "$APT_KEYRINGS_DIR"
    fi
 }
 # Enable i386 (32-bit) multiarch architecture
 apt_enable_i386() {
    if ! dpkg --print-foreign-architectures | grep -q "^i386$"; then
        log_info "Enabling 32-bit (i386) multiarch architecture..."
        dpkg --add-architecture i386
        log_success "32-bit (i386) architecture enabled."
    else
        log_info "32-bit (i386) architecture is already enabled."
    fi
 }
 # Download and install a GPG key into /etc/apt/keyrings/
 # Usage: apt_add_keyring_from_url "https://example.com/key.gpg" "example.gpg"
 apt_add_keyring_from_url() {
    local url="$1"
    local keyring_filename="$2"
    local dest_path="$APT_KEYRINGS_DIR/$keyring_filename"
    apt_ensure_keyrings_dir
    log_substep "Fetching GPG keyring from: $url -> $dest_path"
    local tmp_key
    tmp_key="$(mktemp /tmp/apt-key.XXXXXX)"
    if curl -fsSL "$url" -o "$tmp_key"; then
        # Check if the key is ASCII armored or binary
        if gpg --dry-run --quiet --import "$tmp_key" >/dev/null 2>&1; then
            if grep -q "BEGIN PGP PUBLIC KEY BLOCK" "$tmp_key"; then
                gpg --dearmor --yes --batch -o "$dest_path" < "$tmp_key" 2>/dev/null || cp "$tmp_key" "$dest_path"
            else
                cp "$tmp_key" "$dest_path"
            fi
            chmod 0644 "$dest_path"
            log_success "Keyring installed: $dest_path"
        else
            # If gpg check fails, fallback to direct copy if non-empty
            if [[ -s "$tmp_key" ]]; then
                cp "$tmp_key" "$dest_path"
                chmod 0644 "$dest_path"
                log_success "Keyring installed (raw): $dest_path"
            else
                log_error "Downloaded key from $url is empty or invalid."
                rm -f "$tmp_key"
                return 1
            fi
        fi
        rm -f "$tmp_key"
    else
        rm -f "$tmp_key"
        log_error "Failed to download GPG key from $url"
        return 1
    fi
 }
 # Install Deb822 sources file
 # Usage: apt_install_sources_file "/path/to/source.sources" "debian-unstable.sources"
 apt_install_sources_file() {
    local src_path="$1"
    local dest_name="$2"
    local dest_path="$APT_SOURCES_DIR/$dest_name"
    if [[ ! -f "$src_path" ]]; then
        log_error "Source file does not exist: $src_path"
        return 1
    fi
    mkdir -p "$APT_SOURCES_DIR"
    cp "$src_path" "$dest_path"
    chmod 0644 "$dest_path"
    log_success "Installed APT Deb822 source: $dest_path"
 }
 # Install APT preferences file
 # Usage: apt_install_preference_file "/path/to/pinning.pref" "99-custom.pref"
 apt_install_preference_file() {
    local src_path="$1"
    local dest_name="$2"
    local dest_path="$APT_PREFERENCES_DIR/$dest_name"
    if [[ ! -f "$src_path" ]]; then
        log_error "Preference file does not exist: $src_path"
        return 1
    fi
    mkdir -p "$APT_PREFERENCES_DIR"
    cp "$src_path" "$dest_path"
    chmod 0644 "$dest_path"
    log_success "Installed APT preference: $dest_path"
 }
 # Update APT package indexes
 apt_update() {
    log_step "Updating APT package indexes..."
    DEBIAN_FRONTEND=noninteractive apt-get update -y
 }
 # Dist-upgrade system
 apt_dist_upgrade() {
    log_step "Upgrading system packages (dist-upgrade)..."
    DEBIAN_FRONTEND=noninteractive apt-get dist-upgrade -y
 }
 # Install packages from a .list file
 # Usage: apt_install_package_list_file "/path/to/packages.list"
 apt_install_package_list_file() {
    local list_file="$1"
    if [[ ! -f "$list_file" ]]; then
        log_error "Package list file not found: $list_file"
        return 1
    fi
    local -a pkgs=()
    while IFS= read -r line || [[ -n "$line" ]]; do
        # Trim leading/trailing whitespace
        line="$(echo "$line" | sed -e 's/^[[:space:]]*//' -e 's/[[:space:]]*$//')"
        # Skip empty lines and comment lines
        [[ -z "$line" || "$line" =~ ^# ]] && continue
        pkgs+=("$line")
    done < "$list_file"
    if [[ ${#pkgs[@]} -eq 0 ]]; then
        log_info "No packages to install from $list_file"
        return 0
    fi
    log_info "Installing ${#pkgs[@]} packages from $(basename "$list_file")..."
    DEBIAN_FRONTEND=noninteractive apt-get install -y "${pkgs[@]}"
    log_success "Installed packages from $(basename "$list_file")"
 }
@@ -0,0 +1,99 @@
 #!/usr/bin/env bash
 # ==============================================================================
 # lib/tui.sh - Interactive Whiptail TUI dialogs and checklists
 # ==============================================================================
 set -euo pipefail
 # Check if whiptail is available
 tui_check_whiptail() {
    if ! command_exists whiptail; then
        log_warn "whiptail is not installed. Attempting to install whiptail..."
        DEBIAN_FRONTEND=noninteractive apt-get update -y && DEBIAN_FRONTEND=noninteractive apt-get install -y whiptail
    fi
 }
 # Display welcome message
 tui_welcome() {
    whiptail --title "Debian Unstable Setup & Hyprland Installer" \
        --msgbox "Willkommen beim Debian Unstable & Desktop Setup!\n\nDieses Skript führt dich durch die modulare Einrichtung deines Debian Sid Systems mit XanMod-Kernel, Hyprland und Optimierungen.\n\nDrücke ENTER um zur Modulauswahl zu gelangen." \
        14 70
 }
 # Present stage checklist to user
 # Returns space-separated list of selected stage numbers (e.g., "01 02 03 04 05 06 07 08 09")
 tui_select_stages() {
    local choices
    choices=$(whiptail --title "Modulauswahl / Stages" \
        --checklist "Wähle die gewünschten Installations-Phasen mit der LEERTASTE aus:" \
        23 78 10 \
        "01" "Debian Unstable (Deb822, Pinning, Upgrade)" ON \
        "02" "Kernel & Hardware (XanMod, P-State, Microcode)" ON \
        "03" "Bootloader & Theme (GRUB, Vimix, Plymouth)" ON \
        "04" "Pakete (Base, Desktop, Gaming, Virtualisierung)" ON \
        "05" "Coding & Nerd Fonts (JetBrainsMono, VictorMono)" ON \
        "06" "System-Dienste (AppArmor, Docker, Libvirt, zram, Ollama)" ON \
        "07" "Userland & Skel (Zsh, Skel-Templates, Dotfiles)" ON \
        "08" "Flatpaks (Flathub Repository & Flatpaks)" ON \
        "09" "Zusatz-Apps & MIME (Spotify, Waydroid, OpenDeck, MIME)" ON \
        "10" "Hyprland Desktop (LinuxBeginnings Debian-Hyprland Installer)" ON \
        3>&1 1>&2 2>&3) || {
            log_info "Setup durch Benutzer abgebrochen."
            exit 0
        }
    # Clean quotes from whiptail output (e.g. '"01" "02"' -> '01 02')
    local cleaned_choices
    cleaned_choices=$(echo "$choices" | tr -d '"')
    echo "$cleaned_choices"
 }
 # Prompt user for target user via Whiptail dialog
 tui_prompt_target_user() {
    local default_user="${1:-}"
    local chosen=""
    if [[ -n "$default_user" && "$default_user" != "root" ]]; then
        if whiptail --title "Ziel-Benutzer bestätigen" \
            --yes-button "Verwenden" \
            --no-button "Anderer Benutzer" \
            --yesno "Erkannter Ziel-Benutzer: $default_user\n\nMöchtest du diesen Benutzer für die Konfiguration (Dotfiles, Gruppen, Hyprland) verwenden?" \
            10 65; then
            chosen="$default_user"
        fi
    fi
    while [[ -z "$chosen" ]]; do
        local input_user
        input_user=$(whiptail --title "Ziel-Benutzer eingeben" \
            --inputbox "Bitte gib den Benutzernamen des Desktop-Benutzers ein:" \
            10 60 "$default_user" \
            3>&1 1>&2 2>&3) || {
                log_info "Setup durch Benutzer abgebrochen."
                exit 0
            }
        input_user="$(echo "$input_user" | tr -d '[:space:]')"
        if [[ -z "$input_user" || "$input_user" == "root" ]]; then
            whiptail --title "Ungültiger Benutzer" --msgbox "Ungültiger Benutzername (darf nicht leer oder root sein)." 8 50
            continue
        fi
        if ! id "$input_user" >/dev/null 2>&1; then
            whiptail --title "Benutzer nicht gefunden" --msgbox "Benutzer '$input_user' existiert nicht im System." 8 50
            continue
        fi
        chosen="$input_user"
    done
    export TARGET_USER="$chosen"
    echo "$chosen"
 }
 # Confirmation dialog before running
 tui_confirm_execution() {
    local selected_stages="$1"
    local target_user="$2"
    whiptail --title "Installation starten" \
        --yesno "Folgende Konfiguration wird ausgeführt:\n\n- Ziel-Benutzer: $target_user\n- Ausgewählte Stages: $selected_stages\n\nMöchtest du die Installation jetzt starten?" \
        14 70
 }
@@ -0,0 +1,271 @@
 #!/usr/bin/env bash
 # ==============================================================================
 # lib/utils.sh - Common utilities, logging, error handling & user detection
 # ==============================================================================
 set -euo pipefail
 # ANSI Color Codes
 export CLR_RESET='\033[0m'
 export CLR_BOLD='\033[1m'
 export CLR_DIM='\033[2m'
 export CLR_RED='\033[0;31m'
 export CLR_GREEN='\033[0;32m'
 export CLR_YELLOW='\033[0;33m'
 export CLR_BLUE='\033[0;34m'
 export CLR_MAGENTA='\033[0;35m'
 export CLR_CYAN='\033[0;36m'
 export CLR_WHITE='\033[0;37m'
 # Disable colors if not running in a terminal
 if [[ ! -t 1 ]]; then
    CLR_RESET=""
    CLR_BOLD=""
    CLR_DIM=""
    CLR_RED=""
    CLR_GREEN=""
    CLR_YELLOW=""
    CLR_BLUE=""
    CLR_MAGENTA=""
    CLR_CYAN=""
    CLR_WHITE=""
 fi
 # Logging functions
 log_info() {
    printf "${CLR_BLUE}[INFO]${CLR_RESET} %s\n" "$*"
 }
 log_success() {
    printf "${CLR_GREEN}[✓]${CLR_RESET} %s\n" "$*"
 }
 log_warn() {
    printf "${CLR_YELLOW}[WARN]${CLR_RESET} %s\n" "$*" >&2
 }
 log_error() {
    printf "${CLR_RED}[ERROR]${CLR_RESET} %s\n" "$*" >&2
 }
 log_step() {
    printf "\n${CLR_BOLD}${CLR_CYAN}==>${CLR_RESET} ${CLR_BOLD}%s${CLR_RESET}\n" "$*"
 }
 log_substep() {
    printf "  ${CLR_CYAN}->${CLR_RESET} %s\n" "$*"
 }
 # Error trap handler
 setup_err_trap() {
    trap 'error_handler $? $LINENO "$BASH_COMMAND"' ERR
 }
 error_handler() {
    local exit_code="$1"
    local line_no="$2"
    local bash_command="$3"
    log_error "Command failed with exit code $exit_code at line $line_no: '$bash_command'"
    exit "$exit_code"
 }
 # Root permission check
 require_root() {
    if [[ "$(id -u)" -ne 0 ]]; then
        log_error "This script must be run as root (or via sudo)!"
        exit 1
    fi
 }
 # Check if command exists
 command_exists() {
    command -v "$1" >/dev/null 2>&1
 }
 # Determine and prompt for the non-root target user
 prompt_target_user() {
    if [[ -n "${TARGET_USER:-}" ]]; then
        echo "$TARGET_USER"
        return 0
    fi
    local candidate=""
    if [[ -n "${SUDO_USER:-}" && "${SUDO_USER}" != "root" ]]; then
        candidate="$SUDO_USER"
    elif [[ -n "${PKEXEC_UID:-}" ]]; then
        candidate="$(id -nu "$PKEXEC_UID" 2>/dev/null || true)"
    elif [[ "$(id -u)" -ne 0 ]]; then
        candidate="$(id -un)"
    fi
    # If candidate is still empty or root, try to detect the first normal user with UID >= 1000
    if [[ -z "$candidate" || "$candidate" == "root" ]]; then
        candidate="$(awk -F: '$3 >= 1000 && $3 < 60000 && $1 != "nobody" {print $1; exit}' /etc/passwd 2>/dev/null || true)"
    fi
    local chosen=""
    local is_interactive=0
    if [[ -t 0 || -c /dev/tty ]] && [[ "${DEBIAN_FRONTEND:-}" != "noninteractive" && "${CI:-}" != "1" && "${AUTO_CONFIRM:-}" != "1" ]]; then
        is_interactive=1
    fi
    if [[ "$is_interactive" -eq 1 ]]; then
        local tty_in="/dev/tty"
        local tty_out="/dev/tty"
        if [[ ! -c /dev/tty ]]; then
            tty_in="/dev/stdin"
            tty_out="/dev/stderr"
        fi
        if [[ -n "$candidate" && "$candidate" != "root" ]]; then
            printf "\n%bTarget User Detection:%b\n" "${CLR_CYAN}" "${CLR_RESET}" > "$tty_out"
            printf "Detected target user: %b%s%b\n" "${CLR_BOLD}" "$candidate" "${CLR_RESET}" > "$tty_out"
            local answer=""
            read -r -p "Use target user '$candidate'? [Y/n]: " answer < "$tty_in" > "$tty_out" 2>&1 || answer="y"
            if [[ -z "$answer" || "$answer" =~ ^[YyJj] ]]; then
                chosen="$candidate"
            fi
        fi
        while [[ -z "$chosen" ]]; do
            local input_user=""
            read -r -p "Please enter the target desktop username: " input_user < "$tty_in" > "$tty_out" 2>&1 || true
            input_user="$(echo "$input_user" | tr -d '[:space:]')"
            if [[ -z "$input_user" ]]; then
                printf "%bUsername cannot be empty.%b\n" "${CLR_YELLOW}" "${CLR_RESET}" > "$tty_out"
                continue
            fi
            if [[ "$input_user" == "root" ]]; then
                printf "%bRoot cannot be used as target desktop user.%b\n" "${CLR_YELLOW}" "${CLR_RESET}" > "$tty_out"
                continue
            fi
            if ! id "$input_user" >/dev/null 2>&1; then
                printf "%bUser '%s' does not exist on this system.%b\n" "${CLR_YELLOW}" "$input_user" "${CLR_RESET}" > "$tty_out"
                continue
            fi
            chosen="$input_user"
        done
    else
        chosen="$candidate"
    fi
    if [[ -z "$chosen" || "$chosen" == "root" ]]; then
        log_error "Could not determine a valid non-root desktop target user."
        return 1
    fi
    if ! id "$chosen" >/dev/null 2>&1; then
        log_error "Target user '$chosen' does not exist."
        return 1
    fi
    export TARGET_USER="$chosen"
    echo "$chosen"
 }
 # Get the target user (memoized / exported in TARGET_USER)
 get_target_user() {
    prompt_target_user
 }
 # Get home directory of target user
 get_target_home() {
    local user
    user="$(get_target_user)"
    local user_home
    user_home="$(getent passwd "$user" | cut -d: -f6)"
    if [[ -z "$user_home" || ! -d "$user_home" ]]; then
        user_home="/home/$user"
    fi
    echo "$user_home"
 }
 # Prompt for Ollama AI models storage path
 prompt_ollama_models_path() {
    if [[ -n "${OLLAMA_MODELS:-}" ]]; then
        echo "$OLLAMA_MODELS"
        return 0
    fi
    local default_path="${OLLAMA_MODELS_DEFAULT:-/mnt/Data/Software/ollama/models}"
    local chosen=""
    local is_interactive=0
    if [[ -t 0 || -c /dev/tty ]] && [[ "${DEBIAN_FRONTEND:-}" != "noninteractive" && "${CI:-}" != "1" && "${AUTO_CONFIRM:-}" != "1" ]]; then
        is_interactive=1
    fi
    if [[ "$is_interactive" -eq 1 ]]; then
        local tty_in="/dev/tty"
        local tty_out="/dev/tty"
        if [[ ! -c /dev/tty ]]; then
            tty_in="/dev/stdin"
            tty_out="/dev/stderr"
        fi
        # If whiptail is available and running on an active terminal, use whiptail dialog
        if command_exists whiptail && [[ -t 1 || -c /dev/tty ]]; then
            local tui_input
            if tui_input=$(whiptail --title "Ollama KI-Modelle Speicherort" \
                --inputbox "Bitte gib den Speicherort für die Ollama KI-Modelle an:" \
                10 70 "$default_path" \
                3>&1 1>&2 2>&3); then
                tui_input="$(echo "$tui_input" | sed -e 's/^[[:space:]]*//' -e 's/[[:space:]]*$//')"
                if [[ -n "$tui_input" ]]; then
                    chosen="$tui_input"
                else
                    chosen="$default_path"
                fi
            fi
        fi
        # CLI fallback if whiptail was not used or failed
        if [[ -z "$chosen" ]]; then
            printf "\n%bOllama KI-Modelle Speicherort:%b\n" "${CLR_CYAN}" "${CLR_RESET}" > "$tty_out"
            printf "Standard-Pfad: %b%s%b\n" "${CLR_BOLD}" "$default_path" "${CLR_RESET}" > "$tty_out"
            local input_path=""
            read -r -p "Speicherort für Ollama-Modelle eingeben [$default_path]: " input_path < "$tty_in" > "$tty_out" 2>&1 || true
            input_path="$(echo "$input_path" | sed -e 's/^[[:space:]]*//' -e 's/[[:space:]]*$//')"
            if [[ -n "$input_path" ]]; then
                chosen="$input_path"
            else
                chosen="$default_path"
            fi
        fi
    else
        chosen="$default_path"
    fi
    export OLLAMA_MODELS="$chosen"
    echo "$chosen"
 }
 # Run a command as the target user
 run_as_target_user() {
    local user
    user="$(get_target_user)"
    if [[ "$(id -un)" == "$user" ]]; then
        "$@"
    else
        su -l "$user" -s /bin/bash -c "$(printf "%q " "$@")"
    fi
 }
 # Create a safe temporary directory with auto-cleanup
 create_temp_dir() {
    local prefix="${1:-setup-temp}"
    local tmp_dir
    tmp_dir="$(mktemp -d "/tmp/${prefix}.XXXXXX")"
    echo "$tmp_dir"
 }
 # Safe backup function
 backup_file_or_dir() {
    local target="$1"
    local timestamp
    timestamp="$(date +%Y%m%d_%H%M%S)"
    if [[ -e "$target" ]]; then
        local backup_path="${target}.backup_${timestamp}"
        cp -r "$target" "$backup_path"
        log_info "Created backup: $backup_path"
    fi
 }
@@ -0,0 +1,210 @@
 #!/usr/bin/env bash
 # ==============================================================================
 # setup.sh - Central Orchestrator for Debian Unstable Setup & Hyprland Installer
 # ==============================================================================
 set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 # Source Libraries & Config
 source "$SCRIPT_DIR/lib/utils.sh"
 source "$SCRIPT_DIR/lib/apt.sh"
 source "$SCRIPT_DIR/lib/tui.sh"
 if [[ -f "$SCRIPT_DIR/config/setup.conf" ]]; then
    # shellcheck source=/dev/null
    source "$SCRIPT_DIR/config/setup.conf"
 fi
 setup_err_trap
 # Show help text
 show_help() {
    cat <<EOF
 Usage: sudo ./setup.sh [OPTIONS]
 Debian Unstable Setup & Desktop Customization Framework
 Options:
  -a, --all               Run all setup stages sequentially (00 through 10)
  -s, --stages <list>     Comma-separated list of stages to run (e.g. --stages 01,02,04)
  -u, --user <username>   Specify target desktop user (defaults to \$SUDO_USER)
  -d, --dry-run           Simulate stage execution without modifying the system
  -h, --help              Show this help message and exit
 Available Stages:
  00: Pre-flight Checks (System, Privileges, Internet)
  01: Debian Unstable Migration (Deb822, Pinning, apt-listbugs, dist-upgrade)
  02: Kernel & Hardware Tuning (XanMod, AMD/Intel P-State, auto-cpufreq)
  03: Bootloader & Splash (GRUB configuration, Vimix Theme, Plymouth Solar)
  04: Package Installation (Base, Desktop, Gaming, Virtualization, Multimedia)
  05: Font Installation (JetBrainsMono, FantasqueSans, VictorMono)
  06: System Services (AppArmor, Docker, Libvirt, zram, Ollama)
  07: Skel & User Environment (Zsh, Templates, Dotfiles Sync)
  08: Flatpak Applications (Flathub, Flatpak package list)
  09: Standalone Applications & MIME (Spotify, Waydroid, OpenDeck, MIME types)
  10: Hyprland Desktop (LinuxBeginnings Auto-Installer)
 Examples:
  sudo ./setup.sh                        # Interactive TUI mode
  sudo ./setup.sh --all                  # Full automated install
  sudo ./setup.sh --stages 04,05         # Install only packages and fonts
  sudo ./setup.sh --stages 01 --dry-run  # Dry-run stage 01
 EOF
 }
 # CLI Flags
 FLAG_ALL=0
 FLAG_STAGES=""
 FLAG_DRY_RUN=0
 CLI_USER=""
 # Parse CLI arguments
 while [[ $# -gt 0 ]]; do
    case "$1" in
        -a|--all)
            FLAG_ALL=1
            shift
            ;;
        -s|--stages)
            if [[ -n "${2:-}" && ! "$2" =~ ^- ]]; then
                FLAG_STAGES="$2"
                shift 2
            else
                log_error "Option '$1' requires a comma-separated list of stages."
                exit 1
            fi
            ;;
        -u|--user)
            if [[ -n "${2:-}" && ! "$2" =~ ^- ]]; then
                CLI_USER="$2"
                shift 2
            else
                log_error "Option '$1' requires a username."
                exit 1
            fi
            ;;
        -d|--dry-run)
            FLAG_DRY_RUN=1
            shift
            ;;
        -h|--help)
            show_help
            exit 0
            ;;
        *)
            log_error "Unknown option: $1"
            show_help
            exit 1
            ;;
    esac
 done
 if [[ -n "$CLI_USER" ]]; then
    export TARGET_USER="$CLI_USER"
 fi
 # Ensure root privileges unless dry-run
 if [[ "$FLAG_DRY_RUN" -eq 0 ]]; then
    require_root
 fi
 # Determine stages to run
 SELECTED_STAGES=()
 if [[ "$FLAG_ALL" -eq 1 ]]; then
    SELECTED_STAGES=(01 02 03 04 05 06 07 08 09 10)
 elif [[ -n "$FLAG_STAGES" ]]; then
    IFS=',' read -r -a raw_stages <<< "$FLAG_STAGES"
    for st in "${raw_stages[@]}"; do
        # Format single digit numbers to two digits (e.g. 1 -> 01)
        st="$(echo "$st" | sed -e 's/^[[:space:]]*//' -e 's/[[:space:]]*$//')"
        if [[ "$st" =~ ^[0-9]$ ]]; then
            st="0$st"
        fi
        SELECTED_STAGES+=("$st")
    done
 else
    # Interactive TUI Mode
    if [[ -t 0 && -t 1 ]]; then
        tui_check_whiptail
        tui_welcome
        TUI_SELECTION=$(tui_select_stages)
        if [[ -z "$TUI_SELECTION" ]]; then
            log_warn "No stages selected. Exiting."
            exit 0
        fi
        read -r -a SELECTED_STAGES <<< "$TUI_SELECTION"
        DETECTED_USER="${TARGET_USER:-$(get_target_user 2>/dev/null || true)}"
        TARGET_USER_NAME="$(tui_prompt_target_user "$DETECTED_USER")"
        export TARGET_USER="$TARGET_USER_NAME"
        if ! tui_confirm_execution "${SELECTED_STAGES[*]}" "$TARGET_USER_NAME"; then
            log_info "Installation aborted by user."
            exit 0
        fi
    else
        log_info "Non-interactive shell and no parameters provided. Defaulting to --all."
        SELECTED_STAGES=(01 02 03 04 05 06 07 08 09 10)
    fi
 fi
 # Ensure TARGET_USER is determined and confirmed for all stages
 if [[ -z "${TARGET_USER:-}" ]]; then
    TARGET_USER="$(get_target_user)"
    export TARGET_USER
 fi
 # Map stage identifier to script file
 get_stage_script() {
    local stage_id="$1"
    local match
    match="$(find "$SCRIPT_DIR/stages" -maxdepth 1 -name "${stage_id}-*.sh" -type f | head -n1)"
    echo "$match"
 }
 # Always run preflight check first unless dry-run
 if [[ "$FLAG_DRY_RUN" -eq 0 ]]; then
    PREFLIGHT_SCRIPT="$(get_stage_script "00")"
    if [[ -n "$PREFLIGHT_SCRIPT" && -f "$PREFLIGHT_SCRIPT" ]]; then
        bash "$PREFLIGHT_SCRIPT"
    fi
 fi
 # Banner
 log_step "Starting Debian Unstable Setup Execution"
 log_info "Target User: $(get_target_user)"
 log_info "Planned Stages: ${SELECTED_STAGES[*]}"
 if [[ "$FLAG_DRY_RUN" -eq 1 ]]; then
    log_warn "DRY-RUN MODE: No changes will be made to the system."
 fi
 # Execute Selected Stages
 for stage in "${SELECTED_STAGES[@]}"; do
    # Skip 00 if it was manually added since it already ran
    if [[ "$stage" == "00" ]]; then
        continue
    fi
    SCRIPT="$(get_stage_script "$stage")"
    if [[ -z "$SCRIPT" || ! -f "$SCRIPT" ]]; then
        log_warn "Stage script for '$stage' not found in $SCRIPT_DIR/stages! Skipping."
        continue
    fi
    STAGE_NAME="$(basename "$SCRIPT" .sh)"
    log_step "Executing Stage: $STAGE_NAME"
    if [[ "$FLAG_DRY_RUN" -eq 1 ]]; then
        log_info "[DRY-RUN] Would execute: bash $SCRIPT"
    else
        bash "$SCRIPT"
        log_success "Completed Stage: $STAGE_NAME"
    fi
 done
 log_step "All selected setup stages completed successfully!"
@@ -0,0 +1,70 @@
 #!/usr/bin/env bash
 # ==============================================================================
 # stages/00-preflight.sh - System pre-flight checks, permissions & internet connectivity
 # ==============================================================================
 set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 source "$SCRIPT_DIR/lib/utils.sh"
 setup_err_trap
 log_step "Running Stage 00: Pre-flight System Checks..."
 # 1. Check Root Privileges
 log_substep "Checking root privileges..."
 require_root
 log_success "Running with root privileges."
 # 2. Check Target Desktop User
 log_substep "Detecting non-root target user..."
 TARGET_USER="$(get_target_user)"
 TARGET_HOME="$(get_target_home)"
 if [[ -z "$TARGET_USER" || "$TARGET_USER" == "root" ]]; then
    log_error "Could not determine target user. Run via 'sudo ./setup.sh' as the desktop user or set TARGET_USER=<user>."
    exit 1
 fi
 log_success "Target user identified: $TARGET_USER (Home: $TARGET_HOME)"
 # 3. Check Internet Connectivity
 log_substep "Checking internet connectivity..."
 INTERNET_OK=0
 for host in "deb.debian.org" "1.1.1.1" "8.8.8.8"; do
    if ping -c 1 -W 3 "$host" >/dev/null 2>&1 || curl -s --head --connect-timeout 3 "http://$host" >/dev/null 2>&1; then
        INTERNET_OK=1
        break
    fi
 done
 if [[ "$INTERNET_OK" -ne 1 ]]; then
    log_error "No active internet connection detected. Please connect to the internet and try again."
    exit 1
 fi
 log_success "Internet connection verified."
 # 4. Check Operating System
 log_substep "Verifying operating system..."
 if [[ -f /etc/os-release ]]; then
    # shellcheck source=/dev/null
    source /etc/os-release
    log_info "Detected OS: ${NAME:-Debian} ${VERSION_ID:-} (${VERSION_CODENAME:-sid})"
    if [[ "${ID:-}" != "debian" && "${ID_LIKE:-}" != *"debian"* ]]; then
        log_warn "This setup script is optimized for Debian GNU/Linux. Current ID is '${ID:-unknown}'."
    fi
 else
    log_warn "/etc/os-release not found. Proceeding with caution."
 fi
 # 5. Check Disk Space
 log_substep "Checking available disk space..."
 AVAILABLE_KB=$(df --output=avail / | tail -n1)
 if [[ "$AVAILABLE_KB" -lt 5242880 ]]; then # Less than 5 GB
    log_warn "Less than 5 GB of free space available on root partition ($(( AVAILABLE_KB / 1024 )) MB free)."
 else
    log_success "Sufficient disk space available ($(( AVAILABLE_KB / 1024 / 1024 )) GB free)."
 fi
 log_success "Stage 00: Pre-flight checks passed successfully."
@@ -0,0 +1,75 @@
 #!/usr/bin/env bash
 # ==============================================================================
 # stages/01-apt-unstable.sh - Migration to Debian Unstable (Deb822), Pinning & Upgrade
 # ==============================================================================
 set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 source "$SCRIPT_DIR/lib/utils.sh"
 source "$SCRIPT_DIR/lib/apt.sh"
 setup_err_trap
 log_step "Running Stage 01: Debian Unstable Migration & Package Sources Configuration"
 require_root
 # 1. Install prerequisites for APT HTTPS & Keyrings
 log_substep "Installing APT prerequisites (curl, gnupg, ca-certificates)..."
 DEBIAN_FRONTEND=noninteractive apt-get update -y
 DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
    curl \
    gnupg \
    gpg \
    ca-certificates \
    apt-transport-https \
    debian-archive-keyring
 # 2. Enable 32-bit (i386) Multiarch Architecture
 log_substep "Enabling 32-bit (i386) multiarch architecture..."
 apt_enable_i386
 # 3. Ensure Keyrings directory exists and install repository keyrings
 apt_ensure_keyrings_dir
 log_substep "Installing custom repository keyrings..."
 apt_add_keyring_from_url "https://gitea.creative-dragonslayer.de/api/packages/Linuxapps/debian/repository.key" "gitea-Linuxapps.asc" || log_warn "Could not fetch gitea-Linuxapps.asc keyring."
 apt_add_keyring_from_url "https://gitea.creative-dragonslayer.de/api/packages/Mirror/debian/repository.key" "gitea-Mirror.asc" || log_warn "Could not fetch gitea-Mirror.asc keyring."
 # 4. Migrate /etc/apt/sources.list to Deb822 format
 log_substep "Migrating APT sources to Deb822 format..."
 if [[ -f /etc/apt/sources.list && ! -f /etc/apt/sources.list.bak_pre_unstable ]]; then
    cp /etc/apt/sources.list /etc/apt/sources.list.bak_pre_unstable
    # Comment out active lines in legacy sources.list to avoid duplicate source warnings
    sed -i 's/^[[:space:]]*deb/# deb/' /etc/apt/sources.list
 fi
 # Deploy Deb822 sources
 log_substep "Deploying Deb822 APT sources..."
 if compgen -G "$SCRIPT_DIR/data/apt/sources.list.d/*.sources" > /dev/null; then
    for src_file in "$SCRIPT_DIR"/data/apt/sources.list.d/*.sources; do
        if [[ "$(basename "$src_file")" != "xanmod.sources" ]]; then
            apt_install_sources_file "$src_file" "$(basename "$src_file")"
        fi
    done
 fi
 # 5. Deploy APT Preferences / Pinning
 log_substep "Configuring APT Pinning preferences..."
 mkdir -p /etc/apt/preferences.d
 if compgen -G "$SCRIPT_DIR/data/apt/preferences.d/*.pref" > /dev/null; then
    for pref_file in "$SCRIPT_DIR"/data/apt/preferences.d/*.pref; do
        apt_install_preference_file "$pref_file" "$(basename "$pref_file")"
    done
 fi
 # 6. Install apt-listbugs and apt-listchanges to safeguard Unstable upgrades
 log_substep "Installing protection tools (apt-listbugs, apt-listchanges)..."
 apt_update
 DEBIAN_FRONTEND=noninteractive apt-get install -y apt-listbugs apt-listchanges
 # 7. Perform Full Dist-Upgrade
 log_substep "Performing full distribution upgrade to Debian Sid..."
 apt_dist_upgrade
 log_success "Stage 01: Debian Unstable migration and upgrade completed successfully!"
@@ -0,0 +1,121 @@
 #!/usr/bin/env bash
 # ==============================================================================
 # stages/02-kernel-hardware.sh - XanMod Kernel, Microcode, auto-cpufreq & Hardware Tuning
 # ==============================================================================
 set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 source "$SCRIPT_DIR/lib/utils.sh"
 source "$SCRIPT_DIR/lib/apt.sh"
 if [[ -f "$SCRIPT_DIR/config/setup.conf" ]]; then
    # shellcheck source=/dev/null
    source "$SCRIPT_DIR/config/setup.conf"
 fi
 setup_err_trap
 log_step "Running Stage 02: Kernel & Hardware Tuning"
 require_root
 # 1. Setup XanMod Kernel Repository
 log_substep "Configuring XanMod Kernel repository..."
 apt_ensure_keyrings_dir
 apt_add_keyring_from_url "https://dl.xanmod.org/archive.key" "xanmod-archive-keyring.gpg"
 if [[ -f "$SCRIPT_DIR/data/apt/sources.list.d/xanmod.sources" ]]; then
    apt_install_sources_file "$SCRIPT_DIR/data/apt/sources.list.d/xanmod.sources" "xanmod.sources"
 fi
 apt_update
 # 2. Determine XanMod Kernel Package
 log_substep "Detecting CPU microarchitecture level and XanMod branch..."
 BRANCH="${XANMOD_BRANCH:-main}"
 log_info "Configured XanMod branch: $BRANCH"
 BRANCH_SUFFIX=""
 if [[ "$BRANCH" != "main" && -n "$BRANCH" ]]; then
    BRANCH_SUFFIX="-$BRANCH"
 fi
 # Detect CPU x86-64 microarchitecture level
 ARCH_SUFFIX="-x64v2"
 if grep -q "avx2" /proc/cpuinfo 2>/dev/null; then
    ARCH_SUFFIX="-x64v3"
    log_info "CPU supports x86-64-v3 (AVX2 detected)."
 else
    log_info "CPU does not support AVX2. Using x86-64-v2."
 fi
 KERNEL_PKG="linux-xanmod${BRANCH_SUFFIX}${ARCH_SUFFIX}"
 FALLBACK_PKG="linux-xanmod${BRANCH_SUFFIX}"
 log_substep "Installing XanMod kernel package ($KERNEL_PKG)..."
 if ! DEBIAN_FRONTEND=noninteractive apt-get install -y "$KERNEL_PKG"; then
    log_warn "Failed to install $KERNEL_PKG, trying fallback package $FALLBACK_PKG..."
    DEBIAN_FRONTEND=noninteractive apt-get install -y "$FALLBACK_PKG" || log_warn "XanMod installation failed, standard kernel will remain active."
 fi
 # 3. CPU Microcode Detection and Installation
 log_substep "Detecting CPU vendor for microcode installation..."
 CPU_VENDOR=$(lscpu 2>/dev/null | grep -oP 'Vendor ID:\s*\K.*' | tr -d ' ' || true)
 case "$CPU_VENDOR" in
    "AuthenticAMD")
        log_info "AMD CPU detected ($CPU_VENDOR) -> Installing amd64-microcode"
        DEBIAN_FRONTEND=noninteractive apt-get install -y amd64-microcode
        ;;
    "GenuineIntel")
        log_info "Intel CPU detected ($CPU_VENDOR) -> Installing intel-microcode"
        DEBIAN_FRONTEND=noninteractive apt-get install -y intel-microcode
        ;;
    *)
        log_warn "Unknown CPU vendor '$CPU_VENDOR'. Skipping vendor-specific microcode."
        ;;
 esac
 # 4. Install & Enable auto-cpufreq from source repository
 log_substep "Installing and configuring auto-cpufreq..."
 if command_exists auto-cpufreq; then
    log_info "auto-cpufreq is already installed."
 else
    log_info "Cloning and building auto-cpufreq from GitHub repository..."
    # Ensure git and python3 build essentials are available
    DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends git python3 python3-pip python3-setuptools 2>/dev/null || true
    TEMP_DIR="$(create_temp_dir "auto-cpufreq")"
    if git clone --depth=1 https://github.com/AdnanHodzic/auto-cpufreq.git "$TEMP_DIR" 2>/dev/null; then
        (
            cd "$TEMP_DIR"
            ./auto-cpufreq-installer --install || ./auto-cpufreq-installer --install --non-interactive || true
        )
        rm -rf "$TEMP_DIR"
    else
        log_warn "Failed to clone auto-cpufreq repository from GitHub."
    fi
 fi
 if command_exists auto-cpufreq; then
    auto-cpufreq --install 2>/dev/null || true
    if command_exists systemctl; then
        systemctl enable --now auto-cpufreq 2>/dev/null || log_warn "Could not enable auto-cpufreq systemd service."
    fi
    log_success "auto-cpufreq installed and service enabled."
 else
    log_warn "auto-cpufreq installation could not be completed."
 fi
 # 5. Environment configuration (Raytracing & Upscaling)
 log_substep "Deploying graphics and performance environment configurations..."
 mkdir -p /etc/environment.d
 if compgen -G "$SCRIPT_DIR/data/etc/environment.d/*.conf" > /dev/null; then
    for env_file in "$SCRIPT_DIR"/data/etc/environment.d/*.conf; do
        cp "$env_file" /etc/environment.d/
        log_info "Installed environment config: $(basename "$env_file")"
    done
 fi
 log_success "Stage 02: Kernel and Hardware Tuning completed successfully!"
@@ -0,0 +1,112 @@
 #!/usr/bin/env bash
 # ==============================================================================
 # stages/03-bootloader.sh - GRUB configuration, CPU P-State, Vimix Theme & Plymouth
 # ==============================================================================
 set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 source "$SCRIPT_DIR/lib/utils.sh"
 if [[ -f "$SCRIPT_DIR/config/setup.conf" ]]; then
    # shellcheck source=/dev/null
    source "$SCRIPT_DIR/config/setup.conf"
 fi
 setup_err_trap
 log_step "Running Stage 03: Bootloader & Splash Screen Configuration"
 require_root
 GRUB_CFG="/etc/default/grub"
 GRUB_TIMEOUT="${GRUB_TIMEOUT:-0}"
 GRUB_TIMEOUT_STYLE="${GRUB_TIMEOUT_STYLE:-hidden}"
 GRUB_CMDLINE_LINUX_DEFAULT_BASE="quiet splash apparmor=1 usbcore.autosuspend=-1 vt.global_cursor_default=0 loglevel=3 rd.luks.options=discard plymouth.ignore-serial-consoles threadirqs"
 GRUB_CMDLINE_LINUX="rcutree.rcu_idle_gp_delay=1"
 GRUB_THEME_DIR="/usr/share/debian-gaming/grub/grub2-themes"
 # 1. CPU P-State Detection
 log_substep "Detecting CPU vendor for P-State parameter..."
 CPU_VENDOR=$(lscpu 2>/dev/null | grep -oP 'Vendor ID:\s*\K.*' | tr -d ' ' || true)
 CPU_MODEL=$(lscpu 2>/dev/null | grep -oP 'Model name:\s*\K.*' | head -c 30 || true)
 log_info "Detected CPU: $CPU_MODEL ($CPU_VENDOR)"
 CPU_PARAM=""
 case "$CPU_VENDOR" in
    "AuthenticAMD")
        CPU_PARAM="amd_pstate=active"
        log_info "AMD CPU detected -> Adding amd_pstate=active"
        ;;
    "GenuineIntel")
        CPU_PARAM="intel_pstate=active"
        log_info "Intel CPU detected -> Adding intel_pstate=active"
        ;;
    *)
        log_warn "Unknown CPU Vendor '$CPU_VENDOR' - no CPU pstate parameter added."
        ;;
 esac
 if [[ -n "$CPU_PARAM" ]]; then
    GRUB_CMDLINE_LINUX_DEFAULT="$GRUB_CMDLINE_LINUX_DEFAULT_BASE $CPU_PARAM"
 else
    GRUB_CMDLINE_LINUX_DEFAULT="$GRUB_CMDLINE_LINUX_DEFAULT_BASE"
 fi
 # 2. Configure /etc/default/grub
 if [[ -f "$GRUB_CFG" ]]; then
    log_substep "Updating $GRUB_CFG..."
    backup_file_or_dir "$GRUB_CFG"
    # Set parameters with sed
    sed -i "s|^GRUB_TIMEOUT=.*|GRUB_TIMEOUT=$GRUB_TIMEOUT|" "$GRUB_CFG"
    sed -i "s|^GRUB_TIMEOUT_STYLE=.*|GRUB_TIMEOUT_STYLE=$GRUB_TIMEOUT_STYLE|" "$GRUB_CFG"
    sed -i "s|^GRUB_CMDLINE_LINUX_DEFAULT=.*|GRUB_CMDLINE_LINUX_DEFAULT=\"$GRUB_CMDLINE_LINUX_DEFAULT\"|" "$GRUB_CFG"
    sed -i "s|^GRUB_CMDLINE_LINUX=.*|GRUB_CMDLINE_LINUX=\"$GRUB_CMDLINE_LINUX\"|" "$GRUB_CFG"
    # Ensure entries exist if sed didn't find them
    grep -q '^GRUB_TIMEOUT=' "$GRUB_CFG" || echo "GRUB_TIMEOUT=$GRUB_TIMEOUT" >> "$GRUB_CFG"
    grep -q '^GRUB_TIMEOUT_STYLE=' "$GRUB_CFG" || echo "GRUB_TIMEOUT_STYLE=$GRUB_TIMEOUT_STYLE" >> "$GRUB_CFG"
    grep -q '^GRUB_CMDLINE_LINUX_DEFAULT=' "$GRUB_CFG" || echo "GRUB_CMDLINE_LINUX_DEFAULT=\"$GRUB_CMDLINE_LINUX_DEFAULT\"" >> "$GRUB_CFG"
    grep -q '^GRUB_CMDLINE_LINUX=' "$GRUB_CFG" || echo "GRUB_CMDLINE_LINUX=\"$GRUB_CMDLINE_LINUX\"" >> "$GRUB_CFG"
 else
    log_warn "$GRUB_CFG not found. Is GRUB installed?"
 fi
 # 3. Install & Configure Plymouth
 log_substep "Installing and configuring Plymouth splash theme..."
 if DEBIAN_FRONTEND=noninteractive apt-get install -y plymouth plymouth-themes 2>/dev/null; then
    PLYMOUTH_THEME="${PLYMOUTH_THEME:-solar}"
    if command_exists plymouth-set-default-theme; then
        plymouth-set-default-theme -R "$PLYMOUTH_THEME" 2>/dev/null || log_warn "Could not set Plymouth theme to $PLYMOUTH_THEME"
        log_success "Plymouth configured with theme: $PLYMOUTH_THEME"
    fi
 fi
 # 4. Install Vimix GRUB Theme
 log_substep "Installing Vimix GRUB theme..."
 DEBIAN_FRONTEND=noninteractive apt-get install -y git 2>/dev/null || true
 mkdir -p "$GRUB_THEME_DIR"
 if [[ ! -d "$GRUB_THEME_DIR/.git" ]]; then
    if git clone --depth 1 https://github.com/vinceliuice/grub2-themes.git "$GRUB_THEME_DIR" 2>/dev/null; then
        "$GRUB_THEME_DIR/install.sh" -b -t "${GRUB_THEME:-vimix}" 2>/dev/null || log_warn "Vimix theme installer encountered an issue."
        log_success "Vimix GRUB theme installed."
    else
        log_warn "Failed to clone grub2-themes repository. Skipping theme."
    fi
 else
    log_info "GRUB Theme repository already cloned; updating..."
    (cd "$GRUB_THEME_DIR" && git pull 2>/dev/null && ./install.sh -b -t "${GRUB_THEME:-vimix}" 2>/dev/null) || log_warn "Vimix theme update skipped."
 fi
 # 5. Update GRUB & Initramfs
 log_substep "Running update-grub and update-initramfs..."
 if command_exists update-grub; then
    update-grub
 fi
 if command_exists update-initramfs; then
    update-initramfs -u 2>/dev/null || true
 fi
 log_success "Stage 03: Bootloader and Splash configuration completed successfully!"
@@ -0,0 +1,50 @@
 #!/usr/bin/env bash
 # ==============================================================================
 # stages/04-packages.sh - Installation of categorised system and desktop packages
 # ==============================================================================
 set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 source "$SCRIPT_DIR/lib/utils.sh"
 source "$SCRIPT_DIR/lib/apt.sh"
 setup_err_trap
 log_step "Running Stage 04: Thematic Package Installation"
 require_root
 PACKAGES_DIR="$SCRIPT_DIR/config/packages"
 if [[ ! -d "$PACKAGES_DIR" ]]; then
    log_error "Package configuration directory $PACKAGES_DIR not found!"
    exit 1
 fi
 # List of APT package lists to process (excluding flatpaks which are handled in stage 08)
 APT_LISTS=(
    "01-base.list"
    "02-desktop.list"
    "03-gaming.list"
    "04-virtualization.list"
    "05-multimedia.list"
 )
 log_substep "Ensuring 32-bit (i386) multiarch architecture is enabled..."
 apt_enable_i386
 log_substep "Updating package lists before installation..."
 apt_update
 for list_name in "${APT_LISTS[@]}"; do
    list_path="$PACKAGES_DIR/$list_name"
    if [[ -f "$list_path" ]]; then
        log_step "Installing package category: $list_name"
        apt_install_package_list_file "$list_path" || log_warn "Some packages from $list_name could not be installed."
    else
        log_warn "Package list file $list_name not found in $PACKAGES_DIR."
    fi
 done
 log_success "Stage 04: Thematic package installation completed successfully!"
@@ -0,0 +1,74 @@
 #!/usr/bin/env bash
 # ==============================================================================
 # stages/05-fonts.sh - Download and clean installation of Coding & Nerd Fonts
 # ==============================================================================
 set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 source "$SCRIPT_DIR/lib/utils.sh"
 setup_err_trap
 log_step "Running Stage 05: Coding & Nerd Fonts Installation"
 require_root
 FONT_DIR="/usr/share/fonts"
 TEMP_DIR="$(create_temp_dir "fonts-setup")"
 # Ensure cleanup of temp directory on exit
 cleanup() {
    if [[ -d "$TEMP_DIR" ]]; then
        log_info "Cleaning up temporary font download directory: $TEMP_DIR"
        rm -rf "$TEMP_DIR"
    fi
 }
 trap cleanup EXIT
 mkdir -p "$FONT_DIR"
 # 1. JetBrains Mono Nerd Font
 log_substep "Downloading and installing JetBrainsMono Nerd Font..."
 JB_ARCHIVE="$TEMP_DIR/JetBrainsMono.tar.xz"
 JB_DEST="$FONT_DIR/JetBrainsMonoNerd"
 if curl -fsSL "https://github.com/ryanoasis/nerd-fonts/releases/latest/download/JetBrainsMono.tar.xz" -o "$JB_ARCHIVE"; then
    mkdir -p "$JB_DEST"
    tar -xJkf "$JB_ARCHIVE" -C "$JB_DEST" 2>/dev/null || tar -xJf "$JB_ARCHIVE" -C "$JB_DEST"
    log_success "JetBrainsMono Nerd Font installed to $JB_DEST"
 else
    log_warn "Failed to download JetBrainsMono Nerd Font."
 fi
 # 2. Fantasque Sans Mono Nerd Font
 log_substep "Downloading and installing Fantasque Sans Mono Nerd Font..."
 FANTASQUE_ARCHIVE="$TEMP_DIR/FantasqueSansMono.zip"
 FANTASQUE_DEST="$FONT_DIR/FantasqueSansMonoNerd"
 if curl -fsSL "https://github.com/ryanoasis/nerd-fonts/releases/download/v3.3.0/FantasqueSansMono.zip" -o "$FANTASQUE_ARCHIVE"; then
    mkdir -p "$FANTASQUE_DEST"
    unzip -o -q "$FANTASQUE_ARCHIVE" -d "$FANTASQUE_DEST"
    log_success "FantasqueSansMono Nerd Font installed to $FANTASQUE_DEST"
 else
    log_warn "Failed to download FantasqueSansMono Nerd Font."
 fi
 # 3. Victor Mono Font
 log_substep "Downloading and installing Victor Mono Font..."
 VICTOR_ARCHIVE="$TEMP_DIR/VictorMonoAll.zip"
 VICTOR_DEST="$FONT_DIR/VictorMono"
 if curl -fsSL "https://rubjo.github.io/victor-mono/VictorMonoAll.zip" -o "$VICTOR_ARCHIVE"; then
    mkdir -p "$VICTOR_DEST"
    unzip -o -q "$VICTOR_ARCHIVE" -d "$VICTOR_DEST"
    log_success "Victor Mono Font installed to $VICTOR_DEST"
 else
    log_warn "Failed to download Victor Mono Font."
 fi
 # 4. Refresh Font Cache
 log_substep "Updating font cache..."
 if command_exists fc-cache; then
    fc-cache -f
    log_success "Font cache refreshed."
 fi
 log_success "Stage 05: Fonts installation completed successfully!"
@@ -0,0 +1,149 @@
 #!/usr/bin/env bash
 # ==============================================================================
 # stages/06-services.sh - System services activation (AppArmor, Docker, Libvirt, zram, Ollama)
 # ==============================================================================
 set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 source "$SCRIPT_DIR/lib/utils.sh"
 source "$SCRIPT_DIR/lib/apt.sh"
 if [[ -f "$SCRIPT_DIR/config/setup.conf" ]]; then
    # shellcheck source=/dev/null
    source "$SCRIPT_DIR/config/setup.conf"
 fi
 setup_err_trap
 log_step "Running Stage 06: System Services Configuration & User Privileges"
 require_root
 TARGET_USER="$(get_target_user)"
 # 1. AppArmor Service
 log_substep "Enabling and starting AppArmor service..."
 if command_exists systemctl; then
    systemctl enable apparmor 2>/dev/null || true
    systemctl start apparmor 2>/dev/null || true
    log_success "AppArmor service enabled."
 fi
 # 2. zram-tools Configuration
 log_substep "Configuring zram swap service..."
 if command_exists systemctl; then
    systemctl enable --now zramswap.service 2>/dev/null || true
    log_success "zram service enabled."
 fi
 # 3. Docker Service & Repository
 log_substep "Setting up Docker service & repository..."
 apt_ensure_keyrings_dir
 apt_add_keyring_from_url "https://download.docker.com/linux/debian/gpg" "docker.asc"
 DEBIAN_CODENAME="trixie"
 if [[ -f /etc/os-release ]]; then
    # shellcheck source=/dev/null
    source /etc/os-release
    DEBIAN_CODENAME="${VERSION_CODENAME:-trixie}"
    # Docker uses 'bookworm' or 'trixie' upstream repo suite for Debian testing/unstable if sid is not explicitly provided
    if [[ "$DEBIAN_CODENAME" == "sid" ]]; then
        DEBIAN_CODENAME="trixie"
    fi
 fi
 ARCH="$(dpkg --print-architecture)"
 cat <<EOF > /etc/apt/sources.list.d/docker.sources
 Types: deb
 URIs: https://download.docker.com/linux/debian
 Suites: $DEBIAN_CODENAME
 Components: stable
 Architectures: $ARCH
 Signed-By: /etc/apt/keyrings/docker.asc
 EOF
 chmod 0644 /etc/apt/sources.list.d/docker.sources
 apt_update
 DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
    docker-ce \
    docker-ce-cli \
    containerd.io \
    docker-buildx-plugin \
    docker-compose-plugin 2>/dev/null || log_warn "Could not install all Docker packages."
 if command_exists systemctl; then
    systemctl enable --now docker.service 2>/dev/null || true
 fi
 # 4. Libvirt / KVM Virtualization
 log_substep "Configuring Virtualization (Libvirt / KVM)..."
 HAS_VIRT=$(grep -Eoc '(vmx|svm)' /proc/cpuinfo 2>/dev/null || echo 0)
 if [[ "$HAS_VIRT" -gt 0 ]]; then
    log_info "Hardware virtualization support detected."
    if command_exists systemctl; then
        systemctl enable --now libvirtd.service 2>/dev/null || true
    fi
    if command_exists virsh; then
        virsh net-start default 2>/dev/null || true
        virsh net-autostart default 2>/dev/null || true
    fi
    # Add target user to libvirt and kvm groups
    groupadd -f libvirt
    groupadd -f kvm
    usermod -aG libvirt,kvm "$TARGET_USER"
    log_success "Target user $TARGET_USER added to libvirt & kvm groups."
 else
    log_info "No hardware virtualization extensions (VT-x/AMD-V) detected in /proc/cpuinfo."
 fi
 # 5. Ollama AI Service & Configuration
 log_substep "Configuring Ollama AI Service..."
 OLLAMA_MODELS_DIR="$(prompt_ollama_models_path)"
 log_info "Ollama models directory set to: $OLLAMA_MODELS_DIR"
 mkdir -p "$OLLAMA_MODELS_DIR"
 log_substep "Installing / Updating Ollama..."
 if curl -fsSL https://ollama.com/install.sh | sh; then
    log_success "Ollama installation completed."
 else
    log_warn "Ollama installation script returned a non-zero exit code."
 fi
 # Ensure permissions on models directory for ollama user
 if id ollama >/dev/null 2>&1; then
    chown -R ollama:ollama "$OLLAMA_MODELS_DIR" 2>/dev/null || true
    chmod -R 775 "$OLLAMA_MODELS_DIR" 2>/dev/null || true
 fi
 # Configure systemd drop-in override for Ollama service
 log_substep "Configuring systemd override for Ollama service..."
 mkdir -p /etc/systemd/system/ollama.service.d
 cat <<EOF > /etc/systemd/system/ollama.service.d/override.conf
 [Service]
 Environment="OLLAMA_MODELS=$OLLAMA_MODELS_DIR"
 Environment="OLLAMA_FLASH_ATTENTION=${OLLAMA_FLASH_ATTENTION:-1}"
 Environment="OLLAMA_KV_CACHE_TYPE=${OLLAMA_KV_CACHE_TYPE:-q8_0}"
 Environment="OLLAMA_KEEP_ALIVE=${OLLAMA_KEEP_ALIVE:-30m}"
 EOF
 chmod 0644 /etc/systemd/system/ollama.service.d/override.conf
 if command_exists systemctl; then
    systemctl daemon-reload 2>/dev/null || true
    systemctl enable --now ollama.service 2>/dev/null || true
    systemctl restart ollama.service 2>/dev/null || true
    log_success "Ollama systemd service configured and enabled."
 fi
 # 6. User Group Memberships
 log_substep "Updating user group memberships for $TARGET_USER..."
 groupadd -f sudo
 groupadd -f docker
 groupadd -f ollama 2>/dev/null || true
 usermod -aG sudo,docker "$TARGET_USER"
 if getent group ollama >/dev/null 2>&1; then
    usermod -aG ollama "$TARGET_USER" 2>/dev/null || true
 fi
 log_success "Target user $TARGET_USER added to sudo, docker and ollama groups."
 log_success "Stage 06: System services configuration completed successfully!"
@@ -0,0 +1,152 @@
 #!/usr/bin/env bash
 # ==============================================================================
 # stages/07-skel-and-user.sh - /etc/skel templates, Zsh setup, user environment sync & chsh
 # ==============================================================================
 set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 source "$SCRIPT_DIR/lib/utils.sh"
 setup_err_trap
 log_step "Running Stage 07: User Environment, Skel Templates & Shell Configuration"
 require_root
 TARGET_USER="$(get_target_user)"
 TARGET_HOME="$(get_target_home)"
 log_info "Configuring userland environment for target user: $TARGET_USER ($TARGET_HOME)"
 # 1. Deploy System Profile Scripts (/etc/profile.d)
 log_substep "Deploying system profile scripts to /etc/profile.d/..."
 mkdir -p /etc/profile.d
 if [[ -d "$SCRIPT_DIR/data/etc/profile.d" ]]; then
    for profile_script in "$SCRIPT_DIR"/data/etc/profile.d/*.sh; do
        [[ -f "$profile_script" ]] || continue
        cp "$profile_script" /etc/profile.d/
        chmod 0755 "/etc/profile.d/$(basename "$profile_script")"
        log_info "Installed profile script: $(basename "$profile_script")"
    done
 fi
 # Ensure Zsh profiles source /etc/profile
 mkdir -p /etc/zsh
 grep -q '^source /etc/profile' /etc/zsh/zprofile 2>/dev/null || echo 'source /etc/profile' >> /etc/zsh/zprofile
 # 2. Provision /etc/skel for Future New Users
 log_substep "Provisioning /etc/skel with default templates and configs..."
 mkdir -p /etc/skel/Templates /etc/skel/.junie/skills
 if [[ -d "$SCRIPT_DIR/data/skel/Templates" ]]; then
    cp -r "$SCRIPT_DIR"/data/skel/Templates/* /etc/skel/Templates/ 2>/dev/null || true
 fi
 if [[ -f "$SCRIPT_DIR/data/skel/.zshrc" ]]; then
    cp "$SCRIPT_DIR/data/skel/.zshrc" /etc/skel/.zshrc
 fi
 if [[ -d "$SCRIPT_DIR/data/skel/.config" ]]; then
    mkdir -p /etc/skel/.config
    cp -r "$SCRIPT_DIR"/data/skel/.config/* /etc/skel/.config/ 2>/dev/null || true
    if [[ -d /etc/skel/.config/hypr/scripts ]]; then
        chmod 0755 /etc/skel/.config/hypr/scripts/*.sh 2>/dev/null || true
    fi
 fi
 # Provision Oh-My-Zsh template in /etc/skel so newly created users receive it automatically
 if command_exists git; then
    if [[ ! -d /etc/skel/.oh-my-zsh ]]; then
        log_info "Provisioning Oh-My-Zsh template in /etc/skel/.oh-my-zsh..."
        git clone --depth=1 https://github.com/ohmyzsh/ohmyzsh.git /etc/skel/.oh-my-zsh 2>/dev/null || log_warn "Could not clone Oh-My-Zsh into /etc/skel."
    fi
    if [[ -d /etc/skel/.oh-my-zsh ]]; then
        mkdir -p /etc/skel/.oh-my-zsh/custom/plugins
        [[ -d /etc/skel/.oh-my-zsh/custom/plugins/zsh-autosuggestions ]] || \
            git clone --depth=1 https://github.com/zsh-users/zsh-autosuggestions /etc/skel/.oh-my-zsh/custom/plugins/zsh-autosuggestions 2>/dev/null || true
        [[ -d /etc/skel/.oh-my-zsh/custom/plugins/zsh-syntax-highlighting ]] || \
            git clone --depth=1 https://github.com/zsh-users/zsh-syntax-highlighting /etc/skel/.oh-my-zsh/custom/plugins/zsh-syntax-highlighting 2>/dev/null || true
    fi
 fi
 chown -R root:root /etc/skel
 # 3. Synchronize User Environment for Target User
 log_substep "Synchronizing Dotfiles & Templates into $TARGET_HOME..."
 mkdir -p "$TARGET_HOME/Templates" "$TARGET_HOME/.config" "$TARGET_HOME/.junie/skills"
 # Backup existing .zshrc if present
 if [[ -f "$TARGET_HOME/.zshrc" ]]; then
    backup_file_or_dir "$TARGET_HOME/.zshrc"
 fi
 if [[ -f "$SCRIPT_DIR/data/skel/.zshrc" ]]; then
    cp "$SCRIPT_DIR/data/skel/.zshrc" "$TARGET_HOME/.zshrc"
 fi
 if [[ -d "$SCRIPT_DIR/data/skel/Templates" ]]; then
    cp -r "$SCRIPT_DIR"/data/skel/Templates/* "$TARGET_HOME/Templates/" 2>/dev/null || true
 fi
 # Backup existing Hyprland config if present
 if [[ -f "$TARGET_HOME/.config/hypr/hyprland.conf" ]]; then
    backup_file_or_dir "$TARGET_HOME/.config/hypr/hyprland.conf"
 fi
 if [[ -d "$SCRIPT_DIR/data/skel/.config" ]]; then
    cp -r "$SCRIPT_DIR"/data/skel/.config/* "$TARGET_HOME/.config/" 2>/dev/null || true
    if [[ -d "$TARGET_HOME/.config/hypr/scripts" ]]; then
        chmod 0755 "$TARGET_HOME"/.config/hypr/scripts/*.sh 2>/dev/null || true
    fi
 fi
 # 4. Install Oh-My-Zsh for Target User (if not already installed)
 if [[ ! -d "$TARGET_HOME/.oh-my-zsh" ]]; then
    log_substep "Installing Oh-My-Zsh repository for $TARGET_USER..."
    if [[ -d /etc/skel/.oh-my-zsh ]]; then
        cp -r /etc/skel/.oh-my-zsh "$TARGET_HOME/.oh-my-zsh"
    elif command_exists git; then
        run_as_target_user git clone --depth=1 https://github.com/ohmyzsh/ohmyzsh.git "$TARGET_HOME/.oh-my-zsh" 2>/dev/null || log_warn "Could not clone Oh-My-Zsh repository."
    fi
 fi
 if [[ -d "$TARGET_HOME/.oh-my-zsh" ]]; then
    mkdir -p "$TARGET_HOME/.oh-my-zsh/custom/plugins"
    if [[ ! -d "$TARGET_HOME/.oh-my-zsh/custom/plugins/zsh-autosuggestions" ]] && command_exists git; then
        run_as_target_user git clone --depth=1 https://github.com/zsh-users/zsh-autosuggestions "$TARGET_HOME/.oh-my-zsh/custom/plugins/zsh-autosuggestions" 2>/dev/null || true
    fi
    if [[ ! -d "$TARGET_HOME/.oh-my-zsh/custom/plugins/zsh-syntax-highlighting" ]] && command_exists git; then
        run_as_target_user git clone --depth=1 https://github.com/zsh-users/zsh-syntax-highlighting "$TARGET_HOME/.oh-my-zsh/custom/plugins/zsh-syntax-highlighting" 2>/dev/null || true
    fi
 fi
 # Fix ownership
 chown -R "$TARGET_USER:$TARGET_USER" "$TARGET_HOME/.zshrc" "$TARGET_HOME/Templates" "$TARGET_HOME/.config" "$TARGET_HOME/.junie"
 if [[ -d "$TARGET_HOME/.oh-my-zsh" ]]; then
    chown -R "$TARGET_USER:$TARGET_USER" "$TARGET_HOME/.oh-my-zsh"
 fi
 # 5. Set Default Shell to Zsh using standard chsh
 log_substep "Setting default shell to Zsh for $TARGET_USER..."
 ZSH_BIN="$(command -v zsh || echo "/usr/bin/zsh")"
 if [[ -x "$ZSH_BIN" ]]; then
    # Ensure zsh is listed in /etc/shells
    grep -q "^$ZSH_BIN$" /etc/shells 2>/dev/null || echo "$ZSH_BIN" >> /etc/shells
    CURRENT_SHELL="$(getent passwd "$TARGET_USER" | cut -d: -f7)"
    if [[ "$CURRENT_SHELL" != "$ZSH_BIN" ]]; then
        chsh -s "$ZSH_BIN" "$TARGET_USER"
        log_success "Default shell for $TARGET_USER set to $ZSH_BIN"
    else
        log_info "Default shell for $TARGET_USER is already $ZSH_BIN"
    fi
    # Configure default shell for newly created users
    if command_exists useradd; then
        useradd -D -s "$ZSH_BIN" 2>/dev/null || true
    fi
    if [[ -f /etc/adduser.conf ]]; then
        sed -i -E 's|^#?\s*DSHELL=.*|DSHELL='"$ZSH_BIN"'|' /etc/adduser.conf 2>/dev/null || true
    fi
 else
    log_warn "Zsh binary not found at $ZSH_BIN. Skipping chsh."
 fi
 log_success "Stage 07: Skel & userland configuration completed successfully!"
@@ -0,0 +1,41 @@
 #!/usr/bin/env bash
 # ==============================================================================
 # stages/08-flatpaks.sh - Flathub repository setup & Flatpak package installation
 # ==============================================================================
 set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 source "$SCRIPT_DIR/lib/utils.sh"
 source "$SCRIPT_DIR/lib/apt.sh"
 setup_err_trap
 log_step "Running Stage 08: Flatpaks & Flathub Repository Setup"
 require_root
 TARGET_USER="$(get_target_user)"
 # 1. Flathub Repository Setup
 log_substep "Configuring Flathub remote repository..."
 if command_exists flatpak; then
    flatpak remote-add --if-not-exists flathub https://dl.flathub.org/repo/flathub.flatpakrepo || log_warn "Could not add Flathub remote."
    log_success "Flathub repository enabled."
 else
    log_warn "flatpak command not found. Skipping Flatpak installation."
 fi
 # 2. Install Flatpaks from config/packages/06-flatpaks.list
 FLATPAK_LIST="$SCRIPT_DIR/config/packages/06-flatpaks.list"
 if command_exists flatpak && [[ -f "$FLATPAK_LIST" ]]; then
    log_substep "Installing Flatpak applications from $FLATPAK_LIST..."
    while IFS= read -r app_id || [[ -n "$app_id" ]]; do
        app_id="$(echo "$app_id" | sed -e 's/^[[:space:]]*//' -e 's/[[:space:]]*$//')"
        [[ -z "$app_id" || "$app_id" =~ ^# ]] && continue
        log_info "Installing Flatpak: $app_id"
        flatpak install -y flathub "$app_id" 2>/dev/null || log_warn "Failed to install Flatpak: $app_id"
    done < "$FLATPAK_LIST"
 fi
 log_success "Stage 08: Flatpaks and Flathub repository setup completed successfully!"
@@ -0,0 +1,76 @@
 #!/usr/bin/env bash
 # ==============================================================================
 # stages/09-apps.sh - Spotify, Waydroid, OpenDeck, custom desktop apps & MIME associations
 # ==============================================================================
 set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 source "$SCRIPT_DIR/lib/utils.sh"
 source "$SCRIPT_DIR/lib/apt.sh"
 setup_err_trap
 log_step "Running Stage 09: Standalone Applications, Integrations & MIME Associations"
 require_root
 TARGET_USER="$(get_target_user)"
 # 1. Spotify Client Installation (Debian APT repo)
 log_substep "Configuring Spotify repository and client..."
 if apt_add_keyring_from_url "https://download.spotify.com/debian/pubkey_5384CE82BA52C83A.asc" "spotify.gpg"; then
    cat <<EOF > /etc/apt/sources.list.d/spotify.sources
 Types: deb
 URIs: http://repository.spotify.com
 Suites: stable
 Components: non-free
 Signed-By: /etc/apt/keyrings/spotify.gpg
 EOF
    chmod 0644 /etc/apt/sources.list.d/spotify.sources
    apt_update
    DEBIAN_FRONTEND=noninteractive apt-get install -y spotify-client 2>/dev/null || log_warn "Could not install spotify-client via APT."
 fi
 # 2. Deploy Custom Desktop Applications
 if [[ -d "$SCRIPT_DIR/data/usr/share/applications" ]]; then
    log_substep "Deploying custom desktop entries..."
    mkdir -p /usr/share/applications
    cp -r "$SCRIPT_DIR"/data/usr/share/applications/* /usr/share/applications/ 2>/dev/null || true
 fi
 # 3. Waydroid Container Setup
 log_substep "Checking Waydroid installation..."
 if ! command_exists waydroid; then
    log_info "Installing Waydroid repository and package..."
    if curl -fsSL https://repo.waydro.id | bash 2>/dev/null; then
        DEBIAN_FRONTEND=noninteractive apt-get install -y waydroid 2>/dev/null || log_warn "Failed to install waydroid package."
    fi
 fi
 if command_exists systemctl && command_exists waydroid; then
    systemctl enable --now waydroid-container 2>/dev/null || true
    log_success "Waydroid container service enabled."
 fi
 # 4. OpenDeck Installation
 log_substep "Installing / Updating OpenDeck..."
 if curl -sSL https://raw.githubusercontent.com/nekename/OpenDeck/main/install_opendeck.sh | bash; then
    log_success "OpenDeck installation completed."
 else
    log_warn "OpenDeck installation script returned a non-zero exit code."
 fi
 # 5. Set Default Desktop MIME Types for Target User
 log_substep "Setting default XDG MIME handlers for $TARGET_USER..."
 run_as_target_user xdg-mime default org.gnome.Loupe.desktop image/jpeg 2>/dev/null || true
 run_as_target_user xdg-mime default org.gnome.Loupe.desktop image/png 2>/dev/null || true
 run_as_target_user xdg-mime default io.bassi.Amberol.desktop audio/mpeg 2>/dev/null || true
 run_as_target_user xdg-mime default io.bassi.Amberol.desktop audio/x-wav 2>/dev/null || true
 run_as_target_user xdg-mime default io.bassi.Amberol.desktop audio/flac 2>/dev/null || true
 run_as_target_user xdg-mime default io.bassi.Amberol.desktop audio/ogg 2>/dev/null || true
 run_as_target_user xdg-mime default org.gnome.TextEditor.desktop text/plain 2>/dev/null || true
 run_as_target_user xdg-mime default org.gnome.TextEditor.desktop text/x-log 2>/dev/null || true
 run_as_target_user xdg-mime default org.gnome.TextEditor.desktop text/markdown 2>/dev/null || true
 run_as_target_user xdg-mime default eu.betterbird.Betterbird.desktop x-scheme-handler/mailto 2>/dev/null || true
 log_success "Stage 09: Standalone Applications, Integrations and MIME associations completed successfully!"
@@ -0,0 +1,71 @@
 #!/usr/bin/env bash
 # ==============================================================================
 # stages/10-hyprland.sh - LinuxBeginnings Debian-Hyprland auto-installer & desktop setup
 # ==============================================================================
 set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 # shellcheck source=lib/utils.sh
 source "$SCRIPT_DIR/lib/utils.sh"
 setup_err_trap
 log_step "Running Stage 10: Hyprland Desktop (LinuxBeginnings Debian-Hyprland Installer)"
 require_root
 TARGET_USER="$(get_target_user)"
 TARGET_HOME="$(get_target_home)"
 log_info "Configuring Hyprland Desktop for target user: $TARGET_USER ($TARGET_HOME)"
 # 1. Execute LinuxBeginnings Debian-Hyprland installer
 log_substep "Downloading and executing LinuxBeginnings Debian-Hyprland installer..."
 if command_exists curl; then
    log_info "Running Debian-Hyprland installer as target user '$TARGET_USER'..."
    if run_as_target_user bash -c 'sh <(curl -L https://raw.githubusercontent.com/LinuxBeginnings/Debian-Hyprland/main/auto-install.sh)'; then
        log_success "LinuxBeginnings Debian-Hyprland installation completed successfully."
    else
        log_warn "LinuxBeginnings installer exited with non-zero status. Check logs if needed."
    fi
 else
    log_error "curl is required to download Debian-Hyprland installer."
    exit 1
 fi
 # 2. Ensure rudimentary Hyprland config is deployed to /etc/skel
 log_substep "Deploying rudimentary Hyprland configuration to /etc/skel..."
 mkdir -p /etc/skel/.config/hypr/scripts
 if [[ -f "$SCRIPT_DIR/data/skel/.config/hypr/hyprland.conf" ]]; then
    cp "$SCRIPT_DIR/data/skel/.config/hypr/hyprland.conf" /etc/skel/.config/hypr/hyprland.conf
 fi
 if [[ -f "$SCRIPT_DIR/data/skel/.config/hypr/scripts/install-dots-prompt.sh" ]]; then
    cp "$SCRIPT_DIR/data/skel/.config/hypr/scripts/install-dots-prompt.sh" /etc/skel/.config/hypr/scripts/install-dots-prompt.sh
    chmod 0755 /etc/skel/.config/hypr/scripts/install-dots-prompt.sh
 fi
 chown -R root:root /etc/skel/.config
 # 3. Deploy rudimentary Hyprland config to target user
 log_substep "Deploying rudimentary Hyprland configuration to $TARGET_HOME/.config/hypr..."
 mkdir -p "$TARGET_HOME/.config/hypr/scripts"
 if [[ -f "$TARGET_HOME/.config/hypr/hyprland.conf" ]]; then
    backup_file_or_dir "$TARGET_HOME/.config/hypr/hyprland.conf"
 fi
 if [[ -f "$SCRIPT_DIR/data/skel/.config/hypr/hyprland.conf" ]]; then
    cp "$SCRIPT_DIR/data/skel/.config/hypr/hyprland.conf" "$TARGET_HOME/.config/hypr/hyprland.conf"
 fi
 if [[ -f "$SCRIPT_DIR/data/skel/.config/hypr/scripts/install-dots-prompt.sh" ]]; then
    cp "$SCRIPT_DIR/data/skel/.config/hypr/scripts/install-dots-prompt.sh" "$TARGET_HOME/.config/hypr/scripts/install-dots-prompt.sh"
    chmod 0755 "$TARGET_HOME/.config/hypr/scripts/install-dots-prompt.sh"
 fi
 chown -R "$TARGET_USER:$TARGET_USER" "$TARGET_HOME/.config/hypr"
 log_success "Rudimentary Hyprland configuration deployed:"
 log_info "  - SUPER+ENTER: Kitty Terminal"
 log_info "  - SUPER+Q: Close Active Window"
 log_info "  - Login Prompt: Asks user after login to choose Dotfiles setup & installs JetBrains Junie CLI + AwesomeJunieSkills"
 log_success "Stage 10: Hyprland Desktop installation & configuration completed successfully!"