Docs Update

- ZRAM Scaling (docs/QUICKSTART.md): Updated Step 9 with the current fixed-4096MB formula: `≤8 GB → 50%`, `>8 GB → 4096 MB fixed`. Replaced obsolete `ram_gb > 16 ? 25% : 50%` and `/4` vs `/2` logic with the new behavior (`ram_gb <= 8 ? 50% : 4096 MB`). Examples: 4GB → 2048 MB, 8GB → 4096 MB, 16GB → 4096 MB, 32GB → 4096 MB. - GPU Configuration (docs/gpu.md): Added AMD GCN Migration subsection with duplicate guard (`content_differs-style` check) and sed fix logic. Added Secure Boot warning for NVIDIA DKMS (`mokutil --sb-state` detection). Documented `|| return 1` protection for `/etc/modprobe.d/nvidia-wayland.conf` writing. Renumbered duplicate sections 7 → 8 → 9 to avoid duplicate headings. - Firmware Installation (docs/firmware.md): Updated Broadcom section with `_run_cmd` wrappers (`|| true`) for `apt install broadcom-sta-dkms` and `modprobe wl`. Added SSH network warning (`WARNING: SSH is not recommended on a router`) before `modprobe -r`. Updated Initramfs step with `_run_cmd` wrapper (`|| true`). - Repo Configuration (docs/repos_config.md): Removed `REPOS_CONFIGURED=true` from the POST-EXECUTION PHASE diagram and Safety Mechanisms. Added `_write_branch_sources` with its `_restore_backup` rollback and "Branch Migration Rollback" safety note to the diagram. - System Info & Pre-flight (docs/system_info.md): Added pre-flight init (auto-install whiptail + lsb-release). Added LSPCI_OUTPUT cache with `command -v lspci` guard. Added `_ensure_apt_updated` deduplication helper. Added `STATE_REFRESHED=true` flag mechanism across all menu branches. - User Home Ownership (docs/user_priv_feed.md): Updated Option 3 (Repair Home Ownership) to use `getent passwd "${SUDO_USER:-$USER}"` instead of the insecure `eval echo "~$USER"` pattern. Added documentation note explaining the security rationale. - QuickStart ZRAM (docs/QUICKSTART.md): Updated Step 9 ZRAM scaling to "50% of RAM (≤8 GB) or 4096 MB fixed (>8 GB)".
2026-09-13 21:52:36 +00:00 · 2026-09-12 16:53:10 -05:00
parent 1fc395c188
commit 53088aad4b
14 changed files with 1193 additions and 509 deletions
@@ -36,193 +36,66 @@ chmod +x debianito.sh && ./debianito.sh
 ---
-## Usage 
+## Usage
 After running the script:
-1. **Select Option:** Use arrow keys or type 1-10.
+1. **Select Option:** Use arrow keys or type 1-14.
 2. **Navigation:** Use Arrow Keys (Up↑/Down↓) to move between list options and ENTER key to confirm selection.
 3. **Confirm Actions:** Installation prompts use whiptail for TUI confirmations.
 4. **Review System Info:** Header displays detected Debian version and hardware summary before each action.
 5. **Repeat as Needed:** Return to main menu at any time or exit when done.
 | Option | Description | What it does |
-|--------|-------------|--------------|
+| -------- | ------------- | -------------- |
 | **1** | [System Info](/docs/system_info.md) | Show detected OS, CPU, RAM, GPU and hardware details |
 | **2** | [User Privileges & Feedback](/docs/user_priv_feed.md) | Configure sudo group membership, enable passwordless sudo for frequent tasks, repair home directory ownership issues, and toggle visual password feedback (asterisks) in terminal |
-| **3** | [Configure Repositories](/docs/repos_config.md) | Setup official repos with non-free/contrib options, optional Backports support and Deb822/classic format injection.|
+| **3** | [System Preferences](/docs/system_prefs.md) | Configure date/time & timezone, language/locales & keyboard layout, and audio stack (PipeWire, ALSA, PulseAudio) |
-| **4** | [Firmware, Wireless & Bluetooth](/docs/firmware.md) | Install essential firmware for GPUs and wireless|
+| **4** | [Configure Repositories](/docs/repos_config.md) | Setup official repos with non-free/contrib options, optional Backports support and Deb822/classic format injection |
-| **5** | [Graphics Drivers & Mesa Stack](/docs/gpu.md) | Configure AMD/Intel/NVIDIA drivers and Mesa graphics stack + monitoring tools |
+| **5** | [Firmware, Wireless & Bluetooth](/docs/firmware.md) | Install essential firmware for GPUs and wireless; configure Bluetooth stack (bluez, bluedevil/blueman) |
-| **6** | [Backports Kernel](/docs/kernel.md) | Install latest kernel from Debian backports|
+| **6** | [Graphics Drivers & Mesa Stack](/docs/gpu.md) | Configure AMD/Intel/NVIDIA drivers and Mesa graphics stack + monitoring tools |
-| **7** | [Gaming Setup ](/docs/gaming.md)| Steam, Heroic Games Launcher, [RetroArch](/docs/retroarch.md) GameMode, MangoHud, OpenRGB, Java JRE (Temurin 8/17/21) |
+| **7** | [Kernel](/docs/kernel.md) | Install kernel variants: Stable, RT, Cloud, or Backports (Debian 13) |
-| **8** | [ZRAM](/docs/zram.md)| Configure compressed RAM for memory optimization|
+| **8** | [Gaming Setup](/docs/gaming.md) | Steam, Heroic Games Launcher, [RetroArch](/docs/retroarch.md), GameMode, MangoHud, OpenRGB, Java JRE (Temurin 8/17/21/25) |
-| **9** | [Swap Management](/docs/swap.md)| Manage swap file or partition size and enable/disable swap space for system stability|
+| **9** | [ZRAM](/docs/zram.md) | Configure compressed RAM for memory optimization |
-| **10** | Install Programs and Software | Browse and install packages by category (Development, Themes, System Tools, etc.) using APT |
+| **10** | [Swap Management](/docs/swap.md) | Manage swap file or partition size and enable/disable swap space for system stability |
-| **11** | [Boot Rescue + GRUB](/docs/boot.md)| Config and fix GRUB bootloader issues, chroot repair, or restore system boot configuration|
+| **11** | Install Programs and Software | Browse and install packages by category (Development, Themes, System Tools, etc.) using APT |
-| **12** | [Desktop & Display](/docs/desktops_display.md)| Install and configure desktops and display managers|
+| **12** | [Boot Rescue + GRUB](/docs/boot.md) | Config and fix GRUB bootloader issues, chroot repair, or restore system boot configuration |
-| **13** | Exit | Return to terminal |
+| **13** | [Desktop & Display](/docs/desktops_display.md) | Install and configure desktops (XFCE, LXDE) and display managers (LightDM, GDM3, SDDM, greetd) |
 | **14** | Exit | Return to terminal |
-### Install Programs and Software (Option 10)
+### Install Programs and Software (Option 11)
 The submenu offers the next categories:
 | Option | Category Title | Description |
-|--------|-------------------------------|-------------|
+| -------- | ------------------------------- | ------------- |
-| **0** | Essential Pack | Quick install of common tools (compression, system info, VLC, MS fonts)|
+| **0** | Essential Pack | Quick install of common tools (compression, system info, VLC, MS fonts) |
 | **1** | Customization System | Desktop themes, icon themes, cursor themes, and fonts |
 | **2** | Download & Network | Downloaders (aria2, ytdlp, FileZilla) + Torrent clients (qBittorrent, Deluge, Transmission) |
-| **3** | Internet (Browsers, Email Clients, VPN) | Web browsers (Firefox, LibreWolf, Floorp, Chromium, Tor), email client (Thunderbird), and VPN tools (RiseUp, Proton, Mullvad)|
+| **3** | Internet (Browsers, Email Clients, VPN) | Web browsers (Firefox, LibreWolf, Floorp, Chromium, Tor), email client (Thunderbird), and VPN tools (RiseUp, Proton, Mullvad) |
-| **4** | Media Players | Multimedia playback with VLC media player and MPV for advanced video/audio support |
+| **4** | Communication | Signal, Telegram, HexChat — chat and messaging clients (GUI only) |
-| **5** | Multimedia & Design | image editing (GIMP), video editing (Kdenlive, HandBrake), 3D modeling (Blender), audio recording (Audacity), and graphics design (Inkscape) |
+| **5** | Media Players | Multimedia playback with VLC media player and MPV for advanced video/audio support |
-| **6** | Code Editors & IDEs | vim, vim-gtk3, Neovim, Helix, nano, Emacs, Kate, Mousepad, Gedit, Geany, GNOME Text Editor, and VSCodium (VS Code open-source) |
+| **6** | Multimedia & Design | Image editing (GIMP), video editing (Kdenlive, HandBrake), 3D modeling (Blender), audio recording (Audacity), and graphics design (Inkscape) |
-| **7** | Servers & Dev Tools | Web servers (Nginx/Apache), databases (PostgreSQL/MariaDB), Java Development Kit (Temurin 17/21/25 JDK), Docker, Python, SSH tools, Jellyfin Server and essential utilities |
+| **7** | Code Editors & IDEs | vim, vim-gtk3, Neovim, Helix, nano, Emacs, Kate, Mousepad, Gedit, Geany, GNOME Text Editor, and VSCodium (VS Code open-source) |
-| **8** | Security & Networking | Wireshark, tcpdump, Zenmap, ClamAV, UFW, fail2ban |
+| **8** | Servers & Dev Tools | Web servers (Nginx/Apache), databases (PostgreSQL/MariaDB), Java Development Kit (Temurin 17/21/25 JDK), Docker, Python, SSH tools, Jellyfin Server and essential utilities |
-| **9** | Software Centers | Choose a software store to install. |
+| **9** | Security & Networking | Wireshark, tcpdump, Zenmap, ClamAV, UFW, fail2ban |
-| **10** | Office & Productivity | Choose a software store to install. |
+| **10** | Software Center & Flatpak | GNOME Software / KDE Discover and Flatpak support |
-| **12** | System Tools | htop/btop, ncdu, Timeshift, tmux/screen, nvme-cli, Flatpak support, extension repository manager and qemu/virtmanager |
+| **11** | Office & Productivity | Office suites (LibreOffice), document tools, productivity apps |
-| **12** | Fetch / System Info | fastfetch/neofetch, hyfetch, Linux logo and screenfetch |
+| **12** | System Tools | htop/btop, ncdu, Timeshift, tmux/screen, nvme-cli, extension repository manager and qemu/virtmanager |
-| **13** | Back to Main Menu | Return directly to the main Debianito menu (exit submenu) |
+| **13** | Fetch / System Info | fastfetch/neofetch, hyfetch, Linux logo and screenfetch |
 | **14** | Back to Main Menu | Return directly to the main Debianito menu (exit submenu) |
 ---
 ## Quick Start — Recommended Setup Order
 This section shows the recommended order to configure a fresh Debian installation for maximum performance and usability. Follow these steps in order — each step builds on the previous one.
 ---
 ### Step 1 — Know Your System
 **Menu:** `1  System Information`
 Check your hardware before installing anything. The script detects your CPU, RAM, GPU vendor and generation, network adapters, and display server. Write down what you see — especially the GPU line (Intel/AMD/NVIDIA) and any WiFi chipset. You'll need this info for steps 4 and 5.
 > 💡 If no GPU is detected, you're likely on a VM or headless server — skip step 5.
 ---
 ### Step 2 — Enable Password Feedback
 **Menu:** `2  User Privileges & Feedback` → select option for Sudo Password Feedback
 Enable asterisks (`****`) when typing your sudo password. This prevents typos during the many installation steps that follow. Toggle it on now, disable it later if you prefer hidden input.
 ---
 ### Step 3 — Configure Repositories
 **Menu:** `3  Configure Repositories`
 This is the foundation — all subsequent installations depend on correct repos.
 1. **Enable Contrib & Non-Free Components** (required for firmware, drivers, Steam)
 2. **Setup/Update Backports repositories** (recommended — gives you newer kernels, Mesa drivers, and firmware for modern hardware)
 > ⚠️ Without non-free enabled, steps 4 and 5 will fail. Do not skip this.
 ---
 ### Step 4 — Install Firmware & Wireless Drivers
 **Menu:** `4  Firmware, Wireless & Bluetooth`
 The script scans ALL network hardware (PCI + USB) and installs exactly the firmware your system needs. Accept the plan it shows — it's based on your actual hardware.
 This step also sets up Bluetooth if your system has Bluetooth hardware (KDE gets bluedevil, XFCE gets blueman, GNOME uses built-in).
 > ⚠️ You need internet for this step. If WiFi isn't working after firmware install, reboot first — the driver needs a fresh load.
 ---
 ### Step 5 — Install Graphics Drivers
 **Menu:** `5  Graphics Drivers & Mesa Stack`
 The script auto-detects your GPU and installs the correct driver:
 - **NVIDIA:** The script chooses the best path automatically (CUDA repo, backports, or stable) based on your GPU generation and kernel. Just confirm the plan.
 - **AMD/Intel:** Installs firmware + Mesa stack + Vulkan drivers. Also installs 32-bit libraries if gaming is planned.
 - **Hybrid (laptop):** Installs Intel/AMD firmware first, then NVIDIA driver.
 > 💡 After installation, reboot before testing. NVIDIA drivers need a fresh kernel load to activate.
 ---
 ### Step 6 — Kernel Configuration
 **Menu:** `6  Kernel`
 If you enabled backports in step 3, you can install a newer kernel (e.g., 7.x) for better hardware support. The script offers stable vs backports:
 | Choice | Best for |
 |--------|----------|
 | Stable (default) | Maximum stability, older hardware |
 | Backports | Modern CPUs (Intel Arrow Lake, AMD Zen 5), new GPUs, better power management |
 > ⚠️ If you installed NVIDIA drivers in step 5, the backports kernel may require DKMS recompilation. The script warns about this — it's usually fine.
 ---
 ### Step 7 — Gaming Setup (Optional)
 **Menu:** `7  Gaming Setup`
 If you plan to game on Debian:
 1. **Enable i386 architecture** when prompted — this is REQUIRED for Steam/Proton and 32-bit game libraries
 2. Select your launchers: Steam, Heroic Games Launcher, Lutris
 3. Select performance tools: GameMode, MangoHud, GOverlay
 4. Select RetroArch if you want retro emulation (pre-installed with GBA, SNES, NES, GB cores)
 > ⚠️ Steam requires the contrib repository (step 3) and i386 architecture. The script warns if either is missing.
 ---
 ### Step 8 — ZRAM Compressed Swap (Optional)
 **Menu:** `8  ZRAM`
 ZRAM compresses memory pages in RAM instead of writing to disk. This is especially useful on systems with limited RAM (8GB or less). The script automatically sets ZRAM to ~50% of your physical RAM with priority 100 (used before disk swap).
 Choose **LZ4** for gaming (fastest compression) or **ZSTD** for general use (better compression ratio).
 > 💡 If you also use disk-based swap (Option 9), ZRAM is used first. Disk swap only kicks in after ZRAM fills up.
 ---
 ### Step 9 — Essential Software
 **Menu:** `10  Install Programs and Software` → option `0  Essential Pack`
 One-click install of the most common tools:
 | Package | What you get |
 |---------|--------------|
 | htop, inxi | System monitoring |
 | neofetch / fastfetch | System info display |
 | vlc | Media player |
 | ufw | Firewall|
 | zip, unrar, p7zip | Compression tools |
 After this, browse the other categories (browsers, editors, dev tools) as needed.
 ---
 ### Complete Flow Summary
 1. System Information ← Know your hardware
 2. User Privileges & Feedback ← Enable password asterisks
 3. Configure Repositories ← Enable contrib + non-free + backports
 4. Firmware, Wireless & Bluetooth ← Install WiFi/BT firmware
 5. Graphics Drivers & Mesa Stack ← Install GPU drivers
 6. Kernel ← Optional: newer kernel (Backports)
 7. Gaming Setup ← Optional: Steam + tools
 8. ZRAM ← Optional: compressed swap
 9. Install Programs → 0 Essential ← Common tools
 **Estimated time:** 15-20 minutes for a full setup (steps 1-5 + 9). Steps 6-8 are optional and depend on your use case.
 ---
 ## File Structure
 | Directory/File | Description |
-|----------------|-------------|
+| ---------------- | ------------- |
 | `debianito.sh` | Main entry point; handles menu navigation and system detection. |
 | `docs/` | Documentation directory containing Markdown files for each module. |
 | `modules/` | Core modular scripts organized by category: repos, gpu, gaming, kernel, firmware, zram, etc. |
 | `modules/bullseye/` | Legacy Debian 11 (Bullseye) specific modules: `extras.sh`, `legacy.sh`, `repos.sh`. |
 | `modules/system/` | System preferences: `system_prefs.sh` (timezone, locale, keyboard) and `audio.sh` (PipeWire, ALSA). |
 | `modules/extras/` | Software installer sub-modules split by category (themes, downloaders, internet, dev tools, etc.). |
 | `modules/gaming/` | Gaming launcher and optimization scripts: Steam, Heroic, Lutris, performance tools. |
 | `modules/gpu/` | GPU driver installation scripts for AMD and NVIDIA with architecture detection. |
@@ -237,10 +110,12 @@ After this, browse the other categories (browsers, editors, dev tools) as needed
 │   ├── gaming.md
 │   ├── gpu.md
 │   ├── kernel.md
 │   ├── QUICKSTART.md
 │   ├── repos_config.md
 │   ├── retroarch.md
 │   ├── swap.md
 │   ├── system_info.md
 │   ├── system_prefs.md
 │   ├── user_priv_feed.md
 │   └── zram.md
 ├── media
@@ -254,6 +129,7 @@ After this, browse the other categories (browsers, editors, dev tools) as needed
 │   │   └── repos.sh
 │   ├── desktop_display.sh
 │   ├── extras
 │   │   ├── audio
 │   │   ├── communication
 │   │   │   └── communication.sh
 │   │   ├── design
@@ -305,6 +181,7 @@ After this, browse the other categories (browsers, editors, dev tools) as needed
 │   ├── gpu
 │   │   ├── amd_intel.sh
 │   │   ├── _helpers.sh
 │   │   ├── nvidia_manage.sh
 │   │   └── nvidia.sh
 │   ├── gpu.sh
 │   ├── kernel.sh
@@ -316,10 +193,14 @@ After this, browse the other categories (browsers, editors, dev tools) as needed
 │   ├── sudo_config.sh
 │   ├── swap.sh
 │   ├── sysinfo.sh
 │   ├── system
 │   │   ├── audio.sh
 │   │   └── system_prefs.sh
 │   ├── utils.sh
 │   └── zram.sh
 └── README.md
 ```
 ---
 > 🤖 **AI-Assisted Development Note**  
@@ -0,0 +1,331 @@
 # Debianito — Quick Start Visual Guide
 > **Scope:** Fresh Debian 11 / 12 / 13 installation → fully configured desktop in ~15-20 minutes.
 > **Prerequisites:** Normal user with `sudo` access. Do **not** run the script as root.
 > **Related:** [README Overview](../README.md) · [System Info](system_info.md) · [Repositories](repos_config.md) · [Firmware](firmware.md) · [GPU](gpu.md) · [Kernel](kernel.md) · [Gaming](gaming.md)
 ---
 ## Before You Start
 ```bash
 git clone https://github.com/stornic56/debianito-post-install
 cd debianito-post-install
 chmod +x debianito.sh && ./debianito.sh
 ```
 The script automatically checks for `whiptail` and `lsb-release`, installs them if missing, verifies `sudo` access, checks network connectivity, and synchronizes the system clock (`systemd-timesyncd` + `tzdata`).
 > **Screenshot placeholder:** `media/screenshots/00-main-menu.png` — Main menu (14 options, whiptail centered at 78×20).
 ---
 ## Recommended Order
 Each step builds on the previous one. Steps 1-5 + 10 are the essential path; 6-9 are optional.
 ### Step 1 — Know Your System
 **Menu:** `1  System Information`
 Opens a whiptail message box populated by `utils.sh` detection functions (`detect_cpu_ram`, `detect_gpu`, `detect_network`, `detect_storage`, `detect_displayserver`, `detect_desktop_environment`).
 You will see:
 - Debian version and codename
 - CPU model and RAM size
 - GPU vendor(s) and device IDs (e.g., `10de:2684` for NVIDIA)
 - Network adapters (Ethernet + WiFi chipset) and their state/IP
 - Storage topology (NVMe / SSD / HDD / USB-SD)
 - Display server (Wayland / X11 / tty) and desktop environment
 Write down the **GPU line** (Intel / AMD / NVIDIA) and any **WiFi chipset** — you will need them in Steps 4-5.
 > **Screenshot placeholder:** `media/screenshots/01-system-info.png` — System Information dialog with hardware summary.
 > **Tip:** If `GPU: No GPU detected` appears, you are on a VM or headless server — skip Step 5 (Graphics Drivers).
 ### Step 2 — Fix Permissions Early (Optional but Recommended)
 **Menu:** `2  User Privileges & Feedback`
 A sub-menu with four toggles:
 | Option | What It Does | When to Enable |
 | -------- | -------------- | ---------------- |
 | Sudo group membership | `usermod -aG sudo $USER` | Fresh install where the first user is not in `sudo` |
 | Passwordless sudo | Creates `/etc/sudoers.d/$USER-nopasswd` with `NOPASSWD` for `apt`, `systemctl`, etc. | Lab / personal machine; skip on shared systems |
 | Repair home ownership | `chown -R $USER:$USER $HOME` | Home files owned by root after a mishandled `sudo` |
 | Sudo password feedback | Writes `Defaults pwfeedback` to `/etc/sudoers.d/pwfeedback` — shows `****` while typing | **Enable now** to avoid typos during the many installs that follow |
 > **Screenshot placeholder:** `media/screenshots/02-user-privileges.png` — User Privileges & Feedback menu.
 > **Screenshot placeholder:** `media/screenshots/02b-pwfeedback.png` — Confirmation dialog for "Sudo Password Feedback" with asterisk preview.
 ### Step 3 — System Preferences (Optional)
 **Menu:** `3  System Preferences`
 ```
 1  Date, Time & Timezone
 2  Language, Locales & Keyboard
 3  Audio & Sound Stack
 4  Back to main menu
 ```
 - **Date, Time & Timezone** — Runs `dpkg-reconfigure tzdata` and then `_ensure_time_synced` (NTP + `systemd-timesyncd`). Fix timezone before `apt update` — a wrong clock breaks GPG verification.
 - **Language, Locales & Keyboard** — Runs `dpkg-reconfigure locales` and `keyboard-configuration`. Requires re-login to apply `LANG`.
 - **Audio & Sound Stack** — Checklist with `pipewire-audio` (or `pipewire` on Bullseye), `alsa-utils`, `pavucontrol` (hidden on TTY), `pulsemixer`, `playerctl`. PipeWire on Trixie offers a Backports vs Stable choice and installs Bluetooth Hi-Res codecs (`LDAC`, `aptX`, `AAC`). See [system_prefs.md](system_prefs.md).
 > **Screenshot placeholder:** `media/screenshots/03-system-prefs.png` — System Preferences menu.
 > **Screenshot placeholder:** `media/screenshots/03b-audio.png` — Audio & Sound checklist with PipeWire selected.
 ### Step 4 — Configure Repositories (Required)
 **Menu:** `4  Configure Repositories`
 ```
 1  Enable Contrib & Non-Free Components
 2  Migrate traditional sources.list to DEB822 format
 3  Setup/Update Backports repositories
 4  [ADVANCED] Upgrade system branch (Testing / SID)
 5  Back to main menu
 ```
 1. Choose **1. Enable Contrib & Non-Free** — adds `contrib`, `non-free`, `non-free-firmware` (Bookworm/Trixie). Required for firmware, NVIDIA drivers, and Steam (`contrib`). The script handles both `/etc/apt/sources.list` (classic) and `/etc/apt/sources.list.d/debian.sources` (DEB822) and validates via `apt update` with automatic rollback.
 2. Choose **3. Setup/Update Backports** — answers `Yes` to enable `trixie-backports` / `bookworm-backports` in a separate file (`debian-backports.sources` or `.list`). Backports gives newer kernels, Mesa, and firmware. See [repos_config.md](repos_config.md).
 > ⚠️ Without `non-free` and `contrib`, Steps 5 and 8 will fail. Do not skip.
 > **Screenshot placeholder:** `media/screenshots/04-repos.png` — Repositories menu.
 > **Screenshot placeholder:** `media/screenshots/04b-backports.png` — Backports confirmation dialog.
 ### Step 5 — Install Firmware & Wireless Drivers
 **Menu:** `5  Firmware, Wireless & Bluetooth`
 The script:
 - Scans **all** network hardware (PCI `lspci -nn` + USB `lsusb`, filtered for Realtek/Intel/Mediatek/Atheros/Qualcomm) and Bluetooth controllers
 - Maps vendors to packages: `firmware-iwlwifi`, `firmware-realtek`, `firmware-mediatek`, `firmware-atheros`, `firmware-intel-misc` — plus `firmware-linux-nonfree` as the base meta-package
 - Builds a plan showing detected controllers and planned packages, including Bluetooth handling (KDE → `bluedevil`, XFCE → `blueman`, GNOME → built-in, plus `pipewire-pulse`/`wireplumber` if PipeWire is active)
 - Asks for confirmation before installing; offers Stable vs Backports for the base firmware
 Accept the plan it shows — it is based on your actual hardware. Broadcom wireless (if present) is handled via `broadcom-sta-dkms` with DKMS build checks and `update-initramfs` + `modprobe wl`.
 > ⚠️ You need internet for this step. If WiFi does not work after firmware install, **reboot** first — the driver needs a fresh load.
 > **Screenshot placeholder:** `media/screenshots/05-firmware-plan.png` — Firmware plan dialog with hardware + package list.
 > **Screenshot placeholder:** `media/screenshots/05b-bluetooth.png` — Bluetooth section of the plan (if applicable).
 ### Step 6 — Install Graphics Drivers
 **Menu:** `6  Graphics Drivers & Mesa Stack`
 Whiptail radiolist with two options:
 ```
 1  Radeon/Intel Mesa
 2  NVIDIA Drivers
 ```
 #### Path A — Radeon/Intel Mesa
 Shows a plan with detected GPUs (`Intel firmware + intel-media-va-driver-non-free` or `i965-va-driver-shaders` for Gen7-, `firmware-amd-graphics` for AMD, plus `Mesa Vulkan/OpenGL/VA-API`). Offers legacy AMD GCN 1.0/1.1 migration to `amdgpu` via GRUB params (`radeon.si_support=0 ... amdgpu.si_support=1`). Installs Mesa from Backports or Stable (`_install_mesa_backports`), verifies `mesa-vulkan-drivers`, and offers vendor-specific telemetry (`radeontop`, `intel-gpu-tools`, `vainfo`).
 #### Path B — NVIDIA Drivers
 Shows detected NVIDIA GPUs and a two-stage menu:
 1. **Manage menu** (if a driver is already installed): *Install / Change Driver Version* vs *Remove Driver and Restore Nouveau*.
 2. **Version menu** (depends on Debian version):
   - Bookworm: `v535` (Recommended) or `v470` (Kepler legacy via `nvidia-tesla-470-driver`)
   - Trixie: `v550` (Debian stable, Recommended), `v590` or `v595` (NVIDIA CUDA Repo with `cuda-keyring` + `nvidia-open` + `firmware-nvidia-gsp`)
 The script auto-detects the GPU architecture (`kepler` / `fermi` / `maxwell` / `pascal` / `turing` / `ampere` / `ada` / `blackwell`) and enforces compatibility — e.g., Blackwell requires `v590+` on Trixie, Maxwell/Pascal on Trixie + backports kernel is forced to `v550` stable, Fermi is vetoed on Bookworm/Trixie with an explanatory message.
 > **Screenshot placeholder:** `media/screenshots/06-gpu-choice.png` — GPU type selector (Radeon/Intel vs NVIDIA).
 > **Screenshot placeholder:** `media/screenshots/06b-nvidia-version.png` — NVIDIA version menu (535 / 470 or 550 / 590 / 595).
 > **Tip:** After installation, **reboot** before testing. NVIDIA drivers need a fresh kernel load.
 ### Step 7 — Kernel Configuration (Optional)
 **Menu:** `7  Kernel`
 ```
 stable     Install linux-image-amd64 (Stable)
 backports  Install from backports (Trixie only)
 rt         Install linux-image-rt-amd64 (Preempt-RT)
 cloud      Install linux-image-cloud-amd64
 back       Return to main menu
 ```
 - **Stable** — default Debian kernel (6.12 LTS on Trixie).
 - **Backports** — only on Trixie; requires `trixie-backports` enabled in Step 4. Newer kernel (e.g., 7.x) for Intel Arrow Lake / AMD Zen 5, Battlemage D3cold, etc.
 - **RT** — Preempt-RT low-latency kernel. Warns if `GPU_TYPE == nvidia` (proprietary drivers may not support RT).
 - **Cloud** — minimal kernel for VMs/containers (`linux-image-cloud-amd64`).
 Each variant installs the matching `linux-headers-*` package atomically (`sudo apt install -y [-t trixie-backports] linux-image-* linux-headers-*`). The script warns about DKMS recompilation if NVIDIA is present.
 > **Screenshot placeholder:** `media/screenshots/07-kernel.png` — Kernel menu with four variants.
 > See [kernel.md](kernel.md) for backports rationale and bootloader details.
 ### Step 8 — Gaming Setup (Optional)
 **Menu:** `8  Gaming Setup`
 A single checklist with all options:
 ```
 [*] i386      Enable 32-bit (i386) architecture
 [*] steam     Steam (requires 32-bit support)
 [*] mangohud  Performance overlay (Vulkan/OpenGL)
 [ ] gamemode  Game performance optimization
 [*] goverlay  MangoHud config GUI
 [ ] heroic    Heroic Launcher (Epic/GOG)
 [ ] java      Minecraft Java Runtime
 [ ] openrgb   OpenRGB (RGB lighting control)
 [ ] lutris    Lutris + Wine (requires 32-bit support)
 [ ] retroarch RetroArch Emulator Frontend
 ```
 - If `steam`, `lutris`, or `i386` is checked, the script runs `dpkg --add-architecture i386` + `apt update`, then installs 32-bit graphics libraries (`_install_nvidia_32bit` or `_install_mesa_32bit`).
 - `steam` checks `contrib` (`ensure_contrib_repo`) and installs `steam-installer`.
 - `heroic` fetches the latest `.deb` from GitHub releases (`api.github.com`).
 - `openrgb` is Bookworm/Trixie only; handles `i2c-dev`, udev, `i2c` group, and `setcap`.
 - `java` offers Temurin 8 / 17 / 21 / 25 via `extrepo adoptium`.
 - Requires GUI for some installers (skipped on headless).
 > **Screenshot placeholder:** `media/screenshots/08-gaming.png` — Gaming checklist with i386 + Steam + MangoHud checked.
 > See [gaming.md](gaming.md) and [retroarch.md](retroarch.md).
 ### Step 9 — ZRAM Compressed Swap (Optional)
 **Menu:** `9  ZRAM`
 ```
 1  View ZRAM status
 2  Create / Reconfigure ZRAM
 3  Remove ZRAM
 4  Back to main menu
 ```
 - **View** — Shows `/etc/default/zramswap` (`ALGO`, `SIZE`, `PRIORITY`) and `zramctl` output.
 - **Create / Reconfigure** — Choice of `lz4` (fastest, gaming) vs `zstd` (better ratio). Recommended size is 50% of RAM (≤8 GB) or 4096 MB fixed (>8 GB), configurable. Writes to `/etc/default/zramswap` (`ALGO`, `SIZE`, `PRIORITY=100`) and `systemctl restart zramswap || true`. Priority 100 ensures ZRAM is used before any disk swap (priority 10).
 - **Remove** — `systemctl stop zramswap`, `swapoff /dev/zram0`, `modprobe -r zram`, `apt purge zram-tools`, removes `/etc/default/zramswap`.
 > **Screenshot placeholder:** `media/screenshots/09-zram-algo.png` — Algorithm choice (lz4 vs zstd).
 > **Screenshot placeholder:** `media/screenshots/09b-zram-status.png` — `zramctl` status output in whiptail.
 > See [zram.md](zram.md).
 ### Step 10 — Swap Management (Optional)
 **Menu:** `10  Swap Management`
 ```
 1  Show current swap & swappiness
 2  Create / resize swapfile
 3  Remove swapfile
 4  Change swappiness
 5  Back to main menu
 ```
 - Uses `/swapfile` with `pri=10` (below ZRAM's 100) and tag `# debianito-managed-swap` in `/etc/fstab`.
 - Btrfs: warns about `nodatacow` (`chattr +C`) and hibernation limitations; uses `dd` instead of `fallocate`.
 - Fstab is written via a temp file and validated with `findmnt --verify` before replacing `/etc/fstab`.
 - Concurrency is guarded by `flock /run/lock/debianito-swap.lock`.
 > **Screenshot placeholder:** `media/screenshots/10-swap.png` — Swap Management menu.
 > See [swap.md](swap.md).
 ### Step 11 — Essential Software
 **Menu:** `11  Install Programs and Software` → `0  Essential Pack`
 One-click install of `htop`, `inxi`, `neofetch`/`fastfetch`, `vlc`, `ufw`, `zip`, `unrar`, `p7zip`, plus `lsb-release` fixes.
 After this, browse the other categories as needed:
 | Category | Example Packages |
 | ---------- | ------------------ |
 | Customization System | Desktop themes, icons, cursors, fonts |
 | Download & Network | aria2, ytdlp, qBittorrent, Deluge |
 | Internet | Firefox, LibreWolf, Chromium, Tor, Thunderbird, RiseUp/Mullvad VPN |
 | Communication | Signal, Telegram, HexChat |
 | Media Players | VLC, MPV |
 | Multimedia & Design | GIMP, Kdenlive, Blender, Audacity, Inkscape |
 | Code Editors & IDEs | Neovim, Helix, Emacs, VSCodium, Geany |
 | Servers & Dev Tools | Nginx, PostgreSQL, Docker, Temurin JDK, Jellyfin |
 | Security & Networking | Wireshark, ClamAV, UFW, fail2ban |
 | Software Center & Flatpak | GNOME Software, KDE Discover, Flatpak |
 | Office & Productivity | LibreOffice, document tools |
 | System Tools | htop/btop, Timeshift, extension-manager, virt-manager |
 | Fetch / System Info | fastfetch, neofetch, hyfetch, screenfetch |
 > **Screenshot placeholder:** `media/screenshots/11-essentials.png` — Category menu with 0-14 options.
 > **Screenshot placeholder:** `media/screenshots/11b-essential-pack.png` — Essential Pack confirmation.
 ### Step 12 — Boot Rescue
 **Menu:** `12  Boot Rescue + GRUB`
 - **GRUB boot menu settings** — 4 presets (hidden 0s / 3s / 5s / custom) writing `GRUB_TIMEOUT`, `GRUB_TIMEOUT_STYLE`, `GRUB_RECORDFAIL_TIMEOUT`, `GRUB_DISABLE_OS_PROBER` to `/etc/default/grub.d/99_script_override.cfg` with `update-grub` + backup/rollback.
 - **UEFI Secure Boot repair** — reinstalls `shim-signed`, `grub-efi-amd64-signed`, `linux-image-amd64`, runs `grub-install` + `update-grub` (UEFI only, checked via `/sys/firmware/efi` + `mokutil`).
 - **Initramfs regeneration** — `update-initramfs -u -k all || true`.
 > See [boot.md](boot.md).
 ### Step 13 — Desktop & Display
 **Menu:** `13  Desktop & Display`
 ```
 1  Desktop Environment
 2  Display Manager
 3  Back to main menu
 ```
 - **Desktop Environment** — XFCE (full / minimal / Wayland `labwc` on Trixie / custom checklist) or LXDE (full / core). Installs polkit rules (`85-suspend.rules`, `89-backlight.rules`) + `backlight` group.
 - **Display Manager** — LightDM (GTK greeter, user list, autologin), GDM3 (user list, autologin, NVIDIA Wayland override via `61-gdm.rules → /dev/null`), SDDM (autologin with session auto-detection `plasmawayland → lxqt-wayland → plasma → lxqt`), greetd (base / tuigreet / gtkgreet / nwg-hello / wlgreet — manual `/etc/greetd/config.toml` required).
 > See [desktops_display.md](desktops_display.md).
 ---
 ## After the Script
 1. **Reboot** if you installed firmware, GPU drivers, or a new kernel.
 2. Verify:
   ```bash
   sudo zramctl              # ZRAM active?
   sudo swapon --show        # Swap with correct priorities?
   vainfo                    # VA-API acceleration?
   nvidia-smi                # NVIDIA driver loaded?
   systemctl status bluetooth # Bluetooth active?
   ```
 3. For gaming, enable `i386` was handled — verify with `dpkg --print-foreign-architectures | grep i386`.
 ---
 ## Troubleshooting Quick Answers
 | Symptom | Fix |
 | --------- | ----- |
 | **WiFi not working after firmware** | Reboot. Check `lspci -nn \| grep Network` and verify the package (`firmware-iwlwifi` etc.) is `ii` via `dpkg -l`. Ensure `non-free` + `non-free-firmware` were enabled in Step 4. |
 | **Black screen after NVIDIA + Wayland (GNOME/GDM3)** | At login, select *GNOME on Xorg* (gear icon) or disable Wayland: `sudo nano /etc/gdm3/daemon.conf` → `WaylandEnable=false`. The script only warns about Debian bug #1109409, it does not force X11. |
 | **GRUB menu hidden and cannot enter** | Hold `ESC` immediately after power-on. Or boot a live USB, `chroot`, and run `12  Boot Rescue → GRUB boot menu settings → Show 5 seconds`. |
 | **Steam fails to start** | Verify `i386` is enabled: `dpkg --print-foreign-architectures`. Check `contrib` is in `/etc/apt/sources.list`. Re-run `8  Gaming Setup` and ensure the checklist had `i386` + `steam` checked. |
 | **greetd installed but cannot log in** | This is expected — you must create `/etc/greetd/config.toml` manually. See `man greetd` and `man 5 greetd-sessions`. |
 | **Bluetooth tray icon missing** | Reboot or `systemctl restart bluetooth`. Ensure `bluez`, `bluedevil` (KDE) or `blueman` (XFCE) is installed. For PipeWire, check `systemctl --user status pipewire pipewire-pulse wireplumber`. |
 | **PipeWire crackling / no Bluetooth Hi-Res codec** | Re-run `3  System Preferences → Audio & Sound → PipeWire Audio Stack`. Verify `libldacbt-*`, `libopenaptx0`, `libfdk-aac2t64` are installed (`dpkg -l \| grep -E 'ldac\|aptx\|fdk'`). |
 ---
 ## Taking Screenshots for This Guide
 Screenshots are taken from `whiptail` dialogs. To capture them:
 1. Run the script inside a terminal that supports image export (e.g., `gnome-terminal` + `gnome-screenshot`, or `asciinema`).
 2. For whiptail, press `PrintScreen` or use `import -window root screenshot.png` (ImageMagick).
 3. Save under `media/screenshots/` with the filenames referenced above (`01-system-info.png`, `04-repos.png`, etc.).
 4. Keep width ≈ 800px; the script uses fixed `TUI_ANCHO=78` and `TUI_ALTO=20` centered dialogs.
 > **Note:** Until real screenshots are added, the placeholders above describe the expected content of each image.
@@ -1,11 +1,13 @@
-## Option 11: Boot Rescue & Repair
+# Option 12: Boot Rescue + GRUB
 ### 1. What does this component do?
 This component serves as a comprehensive rescue toolkit designed to diagnose and fix boot-related issues on Debian systems, specifically targeting GRUB configuration, UEFI Secure Boot integrity, and initrd image validity. It provides three primary operations: configuring the GRUB boot menu behavior (including timeout adjustments and visibility settings), repairing UEFI Secure Boot by reinstalling signed bootloader packages after kernel or driver changes, and regenerating initramfs images to resolve missing driver errors. All modifications are protected by automatic backup creation before system files are altered, with built-in rollback mechanisms that restore the original state if any operation fails during execution.
 ### 2. Logical Execution Flow
 **Block 1 — GRUB Boot Menu Settings**
 - **Menu Options:** Users select from four presets or a custom option to control boot behavior:
    1. Hide GRUB menu entirely (Fastest boot, requires holding ESC during power-on).
    2. Show 3-second countdown (Faster boot).
@@ -16,6 +18,7 @@ This component serves as a comprehensive rescue toolkit designed to diagnose and
 - **Execution & Rollback:** The system runs `update-grub` to apply changes. If this command fails, the script automatically restores the timestamped backup and removes the override file to prevent boot issues.
 **Block 2 — UEFI Secure Boot Repair**
 - **Pre-checks:** Before proceeding, the script verifies two conditions:
    1. The system is running in UEFI mode (checks for existence of `/sys/firmware/efi`).
    2. Secure Boot is currently enabled (uses `mokutil --sb-state` to confirm status).
@@ -26,8 +29,9 @@ This component serves as a comprehensive rescue toolkit designed to diagnose and
    3. Regenerates the GRUB configuration via `update-grub`.
 **Block 3 — Initramfs Regeneration**
 - **Confirmation:** The script prompts for user confirmation before proceeding to avoid unintended rebuilds.
- **Execution:** Upon approval, it runs `update-initramfs -u -k all` to regenerate initrd images for all installed kernels.
+- **Execution:** Upon approval, it runs `update-initramfs -u -k all || true` to regenerate initrd images for all installed kernels.
 - **Purpose:** This fixes boot issues caused by missing drivers or corrupted initrd images that prevent the system from loading properly.
 ### 3. Intelligent Automation
@@ -43,23 +47,26 @@ This component serves as a comprehensive rescue toolkit designed to diagnose and
 ### 4. Paquetes y Recursos Gestionados
 **Boot Packages Reinstalled (Secure Boot Repair):**
 | Package | Purpose |
-|---|---|
+| --- | --- |
 | shim-signed | UEFI Secure Boot shim (first-stage bootloader) |
 | grub-efi-amd64-signed | Signed GRUB for UEFI |
 | linux-image-amd64 | Kernel image (re-signed) |
 **GRUB Settings Modified:**
 | Variable | Option 1 | Option 2 | Option 3 | Custom |
-|---|---|---|---|---|
+| --- | --- | --- | --- | --- |
 | GRUB_TIMEOUT | 0 | 3 | 5 | User value |
 | GRUB_TIMEOUT_STYLE | hidden | menu | menu | menu |
 | GRUB_RECORDFAIL_TIMEOUT | 0 | 3 | 5 | User value |
 | GRUB_DISABLE_OS_PROBER | true | — | — | — |
 **System Files Modified:**
 | Package | Purpose |
-|---|---|
+| --- | --- |
 | /etc/default/grub | Main GRUB configuration |
 | /etc/default/grub.d/99_script_override.cfg | Persistent override (survives grub updates) |
 | /etc/default/grub.backup.* | Timestamped backup (auto-created) |
@@ -1,14 +1,18 @@
-## Option 12: Desktop & Display
+# Option 13: Desktop & Display
 ### 1. What does this component do?
-This component manages display managers (the login screen you see before entering your desktop). It allows users to install and configure LightDM, GDM3, SDDM, or greetd. It handles autologin setup, user list visibility toggles, and a specific Wayland override for NVIDIA GPUs. Currently, Desktop Environment management is marked as "Coming Soon".
+
 This component manages both desktop environments and display managers. Desktop Environment installs XFCE/LXDE with polkit integration; Display Manager handles LightDM, GDM3, SDDM, and greetd (login screens). It handles autologin setup, user list visibility toggles, and a specific Wayland override for NVIDIA GPUs. Desktop Environment management supports **XFCE** (full / minimal / Wayland `labwc` on Trixie / custom) and **LXDE** (full / core), with polkit rules for suspend/backlight.
 ### 2. Logical Flow of Execution
 The execution logic is divided into five functional blocks:
-**Block 1 — Display Manager Selection**
+**Block 1 — Desktop & Display Menu**
- The main menu offers two primary options within Option 12: "Desktop Environment" (currently unavailable) and "Display Manager".
+
- Selecting "Display Manager" opens a submenu listing available display managers based on the Debian version.
+- The main menu (`manage_desktop_display` in `desktop_display.sh`) offers two primary options: `1  Desktop Environment` and `2  Display Manager` (plus `3  Back to main menu`).
 - **Desktop Environment** opens `desktop_environment_menu` — XFCE or LXDE.
 - **Display Manager** opens `display_manager_menu` — LightDM, GDM3, SDDM, and greetd (12/13 only).
 - **Available Managers:**
  - LightDM (available on all Debian versions).
  - GDM3 (available on all Debian versions).
@@ -17,6 +21,7 @@ The execution logic is divided into five functional blocks:
 - Each selected manager opens its own dedicated configuration submenu.
 **Block 2 — LightDM Configuration**
 - A checklist menu presents three options:
  1. Install LightDM + GTK Greeter (auto-selects the display manager via debconf-set-selections).
  2. Enable user list at login screen (writes `greeter-hide-users=false` to a configuration file in `.conf.d`).
@@ -24,6 +29,7 @@ The execution logic is divided into five functional blocks:
 - **Idempotency:** The script checks if `lightdm` and `lightdm-gtk-greeter-settings` are already installed before attempting installation, skipping redundant steps.
 **Block 3 — GDM3 Configuration**
 - A checklist menu presents up to four options:
  1. Install/Reinstall gdm3 (auto-selects via debconf).
  2. Toggle user list visibility (toggles `disable-user-list` in greeter.dconf-defaults).
@@ -35,6 +41,7 @@ The execution logic is divided into five functional blocks:
     - **Toggle Behavior:** If the symlink exists, removing it reverts to default behavior; if not present, creating it enables the override.
 **Block 4 — SDDM Configuration**
 - A submenu offers two options:
  1. Install SDDM (auto-selects via debconf).
  2. Enable Autologin:
@@ -43,6 +50,7 @@ The execution logic is divided into five functional blocks:
     - **Fallback:** If no session is found, it enables autologin but warns that SDDM will use the default session.
 **Block 5 — greetd Configuration**
 - greetd is a minimal, modern display manager designed for Wayland environments.
 - Submenu options vary by Debian version:
  - **All Versions:** Install base `greetd`, Install `greetd` + `tuigreet` (recommended TUI greeter).
@@ -51,7 +59,9 @@ The execution logic is divided into five functional blocks:
 - **Important Warning:** greetd is installed but NOT configured by the script. The user must manually create `/etc/greetd/config.toml` to be able to log in. The script displays a warning with references to man pages for configuration details.
 ### 3. Smart Automations
 The component utilizes several intelligent automation features:
 - **debconf-set-selections:** Pre-selects the display manager as default before `apt install`, preventing the interactive "Configuring shared/default-x-display-manager" dialog that would otherwise pause the script execution.
 - **Session Auto-Detection (SDDM):** Checks `.desktop` files in priority order (Wayland first, then X11) to set the correct session type for autologin configuration.
 - **Wayland Toggle:** Creates or removes a udev rule symlink to `/dev/null`. This is a known workaround that disables the GDM rule blocking NVIDIA Wayland support.
@@ -62,8 +72,9 @@ The component utilizes several intelligent automation features:
 ### 4. Packages and Resources Managed
 **Display Manager Packages:**
 | DM | Packages | Debian Versions |
-|---|---|---|
+| --- | --- | --- |
 | LightDM | lightdm, lightdm-gtk-greeter, lightdm-gtk-greeter-settings | All |
 | GDM3 | gdm3 | All |
 | SDDM | sddm | All |
@@ -74,8 +85,9 @@ The component utilizes several intelligent automation features:
 | greetd + wlgreet | greetd, wlgreet | 13 only |
 **Configuration Files Modified:**
 | DM | File Path | Configuration Purpose |
-|---|---|---|
+| --- | --- | --- |
 | LightDM | /etc/lightdm/lightdm.conf.d/50-debianito-userlist.conf | User list visibility toggle |
 | LightDM | /etc/lightdm/lightdm.conf | Autologin user + timeout settings |
 | GDM3 | /etc/gdm3/greeter.dconf-defaults | User list toggle (disable-user-list) |
@@ -84,8 +96,9 @@ The component utilizes several intelligent automation features:
 | SDDM | /etc/sddm.conf.d/autologin.conf | Autologin user + session type |
 **Session Detection Priority (SDDM Autologin):**
 | Priority | Session File | Session Type |
-|---|---|---|
+| --- | --- | --- |
 | 1 | /usr/share/wayland-sessions/plasmawayland.desktop | KDE Wayland |
 | 2 | /usr/share/wayland-sessions/lxqt-wayland.desktop | LXQt Wayland |
 | 3 | /usr/share/xsessions/plasma.desktop | KDE X11 |
@@ -1,58 +1,103 @@
-# Option 4: Advanced Firmware & Wireless Architecture
+# Option 5: Firmware, Wireless & Bluetooth
 ## 1. The Hidden Debian "Problem"
 In standard Debian packaging, the meta-package `firmware-linux-nonfree` serves as a generic aggregator for hardware blobs. However, due to internal dependency resolution rules and conservative versioning strategies within the repository, this package often fails to automatically include vendor-specific firmware drivers for newer or niche network controllers (specifically Realtek Wi-Fi/Bluetooth and Intel Ethernet/Wi-Fi variants).
 This script acts as an intelligent injector to bridge that gap. It does not rely solely on the meta-package's `Recommends` field; instead, it actively scans the hardware topology to identify missing dependencies. By decoupling the detection from the installation logic, the architecture ensures that even if the base package is installed, specific vendor blobs (e.g., `firmware-iwlwifi`, `firmware-realtek`) are explicitly pulled in only when their corresponding hardware IDs are confirmed present on the system. This prevents "half-baked" network connectivity where the interface exists but lacks the necessary firmware to initialize.
 ## 2. Dual Scan Engine (PCI & USB)
 To ensure comprehensive hardware detection while minimizing false positives, the script utilizes a dual-scan engine that interrogates both PCI and USB buses with strict filtering logic:
-*   **PCI Bus Scanning (`lspci`):** The engine parses `lspci -nn` output specifically targeting lines containing "network controller" or "ethernet controller". This captures both wireless adapters (e.g., Intel AX200) and wired NICs (e.g., Realtek RTL8125 2.5GbE), ensuring that Ethernet firmware requirements are also met during the process.
+* **PCI Bus Scanning (`lspci`):** The engine parses `lspci -nn` output specifically targeting lines containing "network controller" or "ethernet controller". This captures both wireless adapters (e.g., Intel AX200) and wired NICs (e.g., Realtek RTL8125 2.5GbE), ensuring that Ethernet firmware requirements are also met during the process.
-*   **USB Bus Scanning (`lsusb`):** The USB scan applies keyword filtering to ignore peripherals unrelated to networking, such as audio devices or card readers. It specifically looks for terms like "wireless", "wifi", "802.11", and "wlan". Bluetooth devices are also detected separately through `PCI_BT_DEVS` and `USB_BT_DEVS`.
+* **USB Bus Scanning (`lsusb`):** The USB scan applies keyword filtering to ignore peripherals unrelated to networking, such as audio devices or card readers. It specifically looks for terms like "wireless", "wifi", "802.11", and "wlan". Bluetooth devices are also detected separately through `PCI_BT_DEVS` and `USB_BT_DEVS`.
-*   **Deduplication:** The collected device lists are merged into a single array (`dev_list`) to prevent duplicate processing of the same hardware instance across different bus categories, ensuring a clean plan generation.
+* **Deduplication:** The collected device lists are merged into a single array (`dev_list`) to prevent duplicate processing of the same hardware instance across different bus categories, ensuring a clean plan generation.
 ## 3. Dynamic Hardware Mapping Matrix
 The script employs an associative mapping strategy in `_detect_firmware_needs` to translate raw vendor strings from `lspci`/`lsusb` into specific Debian package names. This matrix is critical for handling the "Intel Split" and other vendor-specific requirements:
-*   **Vendor Filtering:** The engine first filters out generic or unsupported vendors (e.g., non-Realtek, non-Intel, non-Atheros) to avoid unnecessary package pulls.
+* **Vendor Filtering:** The engine first filters out generic or unsupported vendors (e.g., non-Realtek, non-Intel, non-Atheros) to avoid unnecessary package pulls.
-*   **Package Assignment Logic:**
+* **Package Assignment Logic:**
-    *   **Intel Wi-Fi Hardware** ➔ `firmware-iwlwifi` (Specific driver for wireless chips).
+  * **Intel Wi-Fi Hardware** ➔ `firmware-iwlwifi` (Specific driver for wireless chips).
-    *   **Intel Ethernet Hardware** ➔ `firmware-intel-misc` (Often pulled via `Recommends` of the base package, but explicitly tracked here).
+  * **Intel Ethernet Hardware** ➔ `firmware-intel-misc` (Often pulled via `Recommends` of the base package, but explicitly tracked here).
-    *   **Realtek Hardware** ➔ `firmware-realtek`.
+  * **Realtek Hardware** ➔ `firmware-realtek`.
-    *   **MediaTek / Ralink Hardware** ➔ `firmware-mediatek`.
+  * **MediaTek / Ralink Hardware** ➔ `firmware-mediatek`.
-    *   **Atheros / Qualcomm Hardware** ➔ `firmware-atheros`.
+  * **Atheros / Qualcomm Hardware** ➔ `firmware-atheros`.
 This mapping ensures that if a system contains an Intel Wi-Fi 6 card, the script explicitly queues `firmware-iwlwifi` regardless of whether the base meta-package claims to cover it. The output is rendered as a deduplicated plan with visual indicators (e.g., `[+] package ← hardware`) for user clarity.
 ## 4. Installation Execution Flow (Atomic Pipeline)
 The installation process follows a strict atomic pipeline defined in `install_firmware`, ensuring system stability and version consistency:
-1.  **Repository Validation:** The script first verifies that `/etc/apt/sources.list` or `.d/` contains the `non-free` component. If absent, it halts to prevent installation failures.
+1. **Repository Validation:** The script first verifies that `/etc/apt/sources.list` or `.d/` contains the `non-free` component. If absent, it halts to prevent installation failures.
-2.  **Plan Rendering & Confirmation:** A diagnostic tree is generated showing detected controllers and planned packages. The user must explicitly confirm ("Apply the network & firmware plan?") before proceeding.
+2. **Plan Rendering & Confirmation:** A diagnostic tree is generated showing detected controllers and planned packages. The user must explicitly confirm ("Apply the network & firmware plan?") before proceeding.
-3.  **Base Meta-Package Selection (Backports vs. Stable):**
+3. **Base Meta-Package Selection (Backports vs. Stable):**
-    *   If `firmware-linux-nonfree` is already installed, the script checks for a newer version in backports (`${DEBIAN_CODENAME}-backports`). It prompts to upgrade if available, as backports often contain firmware for very recent hardware not yet in stable.
+    * If `firmware-linux-nonfree` is already installed, the script checks for a newer version in backports (`${DEBIAN_CODENAME}-backports`). It prompts to upgrade if available, as backports often contain firmware for very recent hardware not yet in stable.
-    *   If not installed, it presents a choice between Stable (Ultra-tested) and Backports (Recommended for modern hardware).
+    * If not installed, it presents a choice between Stable (Ultra-tested) and Backports (Recommended for modern hardware).
-4.  **Sequential Injection:** After the base package is secured, the script iterates through `_DETECTED_FW_PKGS`. It uses `apt-cache policy` to validate availability before installing specific vendor packages (`firmware-realtek`, etc.), skipping those already present or unavailable in repositories.
+4. **Sequential Injection:** After the base package is secured, the script iterates through `_DETECTED_FW_PKGS`. It uses `apt-cache policy` to validate availability before installing specific vendor packages (`firmware-realtek`, etc.), skipping those already present or unavailable in repositories.
-## 5. Broadcom Redundancy System (3-Tier Support)
+## 5. Broadcom Wireless Support (DKMS Single-Path)
 Broadcom chipsets require complex handling due to their mix of open-source and proprietary driver support. The `_handle_wireless` function implements a three-tier logic to maximize compatibility without breaking the kernel:
-*   **Tier 1 (Open/Non-Free Direct):** For supported chips, it attempts to install `firmware-brcm80211`. This is preferred as it uses standard DKMS modules provided by Debian.
+Broadcom chipsets require proprietary handling because no open-source driver covers most `14e4:*` devices on modern kernels. The current implementation in `firmware.sh:_handle_wireless` uses a **single-path DKMS flow** (`broadcom-sta-dkms` + `wl` module) — not a 3-tier fallback:
 *   **Tier 2 (Firmware Emulation):** If Tier 1 fails or the chipset requires firmware emulation (e.g., older B43 chips), the script installs `firmware-b43-installer` or `firmware-b43legacy-installer`. This is a fallback for hardware that cannot be driven by standard kernel modules.
 *   **Tier 3 (Proprietary DKMS):** For unsupported chipsets where open-source drivers are insufficient, the system falls back to compiling proprietary drivers (`broadcom-sta-dkms`). The script explicitly checks for `linux-headers` availability before attempting this compilation, as it requires kernel headers matching the running version. It warns the user that a reboot may be required after installation.
-This tiered approach ensures that even if one method fails (e.g., proprietary driver compilation errors), the system attempts other supported methods to restore network functionality.
+1. **Device detection** — Iterates `PCI_NET_DEVS` (parsed from `lspci -nn` at startup) and extracts the Broadcom ID `14e4:XXXX`. Non-Broadcom devices are skipped.
 2. **Dependency guard** — Verifies `linux-headers-amd64` and `dkms` are available via `apt-cache show`. If missing, shows: `"linux-headers-amd64 or dkms are not available in your repositories."`
 3. **User confirmation** — `whiptail --yesno "Install broadcom-sta-dkms, dkms, and wireless-tools?"`
 4. **Step-by-step install** (allows partial failure without aborting the whole module):
   ```bash
   _run_cmd "Broadcom Dependencies" "sudo DEBIAN_FRONTEND=noninteractive apt install -y dkms wireless-tools linux-headers-amd64" || true
   _run_cmd "Broadcom Driver" "sudo DEBIAN_FRONTEND=noninteractive apt install -y broadcom-sta-dkms" || true
   ```
 5. **Blacklist persistence** — Writes `/etc/modprobe.d/blacklist-broadcom.conf`:
   ```
   blacklist b43
   blacklist b43legacy
   blacklist brcmsmac
   blacklist bcma
   blacklist ssb
   ```
 6. **SSH Warning + Module Switch** — Before unloading current WiFi modules, the script warns about SSH disconnection. Then removes conflicting modules and loads the Broadcom driver:
   ```bash
   _msg "Network Warning" "The script is about to unload current WiFi kernel modules to load the Broadcom driver.
 If you are connected via SSH over WiFi, YOUR CONNECTION WILL DROP. Please reconnect after a few seconds."
   _run_cmd "Modprobe" "sudo modprobe -r b43 b43legacy b44 bcma brcmsmac brcmfmac ssb wl 2>/dev/null || true" || true
   _run_cmd "Modprobe" "sudo modprobe wl" || true
   ```
 7. **Initramfs** — Rebuilds the initramfs to include the new `wl` module:
   ```bash
   _run_cmd "Initramfs" "sudo update-initramfs -u" || true
   ```
 1. **Combo BT handling** — If a Broadcom Bluetooth device is also present (`PCI_BT_DEVS` grep `broadcom`), writes `softdep wl post: btusb` to `/etc/modprobe.d/broadcom-combo.conf`
 2. **Post-DKMS verification** — Checks for `/lib/modules/$(uname -r)/updates/dkms/wl.ko*`. If missing, shows the last 20 lines of `dmesg` and offers `dpkg-reconfigure broadcom-sta-dkms`. On success, verifies `lsmod | grep ^wl` and reports `Broadcom WiFi activated (wl module loaded)` or `driver installed but wl module did not load — reboot required`.
 USB Broadcom (`0a5c` vendor, `lsusb`) is detected but **not auto-installed** — the script shows a message that Linux lacks native drivers for most USB Broadcom WiFi chips and that `ndiswrapper` may be needed.
 > **Historical note:** Earlier drafts of this document described a 3-tier system (`firmware-brcm80211` → `firmware-b43-installer` → `broadcom-sta-dkms`). The current script has consolidated to the DKMS path only. The other firmware packages are still available via the base `firmware-linux-nonfree` metapackage and vendor-specific packages (`firmware-realtek`, etc.).
 ## 6. Bluetooth Stack Integration
 Bluetooth support is handled through a dedicated module (`bluetooth.sh`) that integrates seamlessly with the firmware detection process:
-*   **Hardware Detection:** The script identifies both PCI and USB Bluetooth controllers using `PCI_BT_DEVS` and `USB_BT_DEVS` arrays, ensuring comprehensive coverage of all Bluetooth hardware types.
+* **Hardware Detection:** The script identifies both PCI and USB Bluetooth controllers using `PCI_BT_DEVS` and `USB_BT_DEVS` arrays, ensuring comprehensive coverage of all Bluetooth hardware types.
-*   **Base Stack Installation:** When Bluetooth hardware is detected, the system installs the core stack (`bluez`, `bluez-utils`, `bluez-obexd`) if not already present.
+* **Base Stack Installation:** When Bluetooth hardware is detected, the system installs the core stack (`bluez`, `bluez-utils`, `bluez-obexd`) if not already present.
-*   **Desktop Environment Optimization:** Based on the detected desktop environment:
+* **Desktop Environment Optimization:** Based on the detected desktop environment:
-    *   **KDE:** Installs `bluedevil` and optionally `pipewire-pulse` + `wireplumber` for Pipewire audio server integration.
+  * **KDE:** Installs `bluedevil` and optionally `pipewire-pulse` + `wireplumber` for Pipewire audio server integration.
-    *   **GNOME:** Uses built-in GNOME Bluetooth support in `gnome-control-center`.
+  * **GNOME:** Uses built-in GNOME Bluetooth support in `gnome-control-center`.
-    *   **XFCE/Other:** Installs `blueman` as the GTK Bluetooth manager.
+  * **XFCE/Other:** Installs `blueman` as the GTK Bluetooth manager.
-*   **Service Management:** The script ensures the Bluetooth service is enabled and started automatically on boot, with session restart or reboot recommendation for desktop applets to load properly.
+* **Service Management:** The script ensures the Bluetooth service is enabled and started automatically on boot, with session restart or reboot recommendation for desktop applets to load properly.
 This modular approach keeps Bluetooth handling separate from network firmware while maintaining tight integration through shared device detection arrays and coordinated installation flow.
@@ -1,4 +1,4 @@
-## Option 7: Gaming Ecosystem, Performance Tweaks & Runtimes
+# Option 8: Gaming Ecosystem, Performance Tweaks & Runtimes
 ### 1. Philosophy of the Gaming Environment in Debian
@@ -19,6 +19,7 @@ The module architecture separates concerns into distinct scripts (`steam.sh`, `h
 **Steam Installation Logic:** The `install_steam()` function in `steam.sh` leverages Debian's native package management through the `apt install -y steam-installer` command. This approach differs from Valve's official repository for several reasons:
 1. **32-bit Architecture Requirement:** Steam requires 32-bit libraries to run modern Windows games via Proton. The script explicitly prompts users to enable Multi-Arch support (`dpkg --add-architecture i386`) and install the complete Mesa stack for both amd64 and i386 architectures:
   ```bash
   apt install mesa-vulkan-drivers libglx-mesa0:i386 mesa-vulkan-drivers:i386 \
              libgl1-mesa-dri:i386 libegl-mesa0:i386 mesa-va-drivers:i386
@@ -59,6 +60,7 @@ This approach ensures users always get the latest stable release while maintaini
 4. **Screensaver Inhibition:** Prevents screensavers from activating during gaming sessions
 The `install_gamemode()` function in `tools.sh` ensures the daemon is available system-wide:
 ```bash
 _run_install gamemode
 ```
@@ -73,6 +75,7 @@ This allows users to wrap game launch commands with `gamemoderun %command%` for
 4. **Native Rendering:** Uses Vulkan/OpenGL hooks for efficient overlay rendering without impacting game performance
 The `install_mangohud()` function handles both 64-bit and 32-bit installations:
 ```bash
 if dpkg --print-foreign-architectures | grep -q i386; then
    echo "Installing 32-bit MangoHud..."
@@ -94,6 +97,7 @@ The `goverlay` component extends this functionality by integrating with Wayland
 4. **Capability Assignment:** Sets raw I/O capabilities on the binary using `setcap cap_sys_rawio=ep /usr/bin/openrgb`, allowing direct hardware communication while maintaining user-space execution
 The script includes version-specific download URLs for Debian Bookworm (12) and Trixie (13), ensuring compatibility with different kernel versions:
 ```bash
 if [ "$DEBIAN_VERSION" = "12" ]; then
    url="https://codeberg.org/OpenRGB/OpenRGB/releases/download/release_candidate_1.0rc2/openrgb_1.0rc2_amd64_bookworm_0fca93e.deb"
@@ -111,7 +115,7 @@ This approach eliminates the security risk of running OpenRGB as root while main
 **Multi-Version Support:** The gaming module provides four specific Eclipse Temurin versions to accommodate different game requirements:
 | Version | Use Case | Justification |
-|---------|----------|---------------|
+| --------- | ---------- | --------------- |
 | **Temurin 8** | Legacy Minecraft mods, older Java games | Maintains compatibility with mods written for Java 8 (2014-2019 era) |
 | **Temurin 17** | Modern Minecraft servers, newer game clients | Balances performance and compatibility for post-1.16+ game versions |
 | **Temurin 21** | Latest game engines, cutting-edge mods | Provides best performance for modern Java applications |
@@ -119,20 +123,19 @@ This approach eliminates the security risk of running OpenRGB as root while main
 **Repository Management via extrepo:** The script leverages the `extrepo` utility to manage external repositories cleanly rather than manually injecting repository URLs into system files. This approach offers several advantages:
-1.  **Automated Keyring Handling:** `extrepo` manages GPG keys and source file configurations automatically, eliminating manual intervention with `/etc/apt/sources.list.d/`.
+1. **Automated Keyring Handling:** `extrepo` manages GPG keys and source file configurations automatically, eliminating manual intervention with `/etc/apt/sources.list.d/`.
-2.  **Dependency Resolution:** The utility checks for its own installation and handles the enabling of the Adoptium Temurin repository before proceeding with package installation.
+2. **Dependency Resolution:** The utility checks for its own installation and handles the enabling of the Adoptium Temurin repository before proceeding with package installation.
-3.  **Maintenance Safety:** Updates to the upstream repository are reflected through `extrepo` without requiring direct edits to system configuration files, reducing the risk of breakage during OS updates.
+3. **Maintenance Safety:** Updates to the upstream repository are reflected through `extrepo` without requiring direct edits to system configuration files, reducing the risk of breakage during OS updates.
 **Version Selection Logic:** Users can choose which Temurin version to install based on their specific game requirements via a TUI menu (`install_minecraft_java()`). The module justifies offering all four versions because:
-1.  **Backward Compatibility:** Java 8 remains in use by many Minecraft mods and older game clients that haven't been updated for newer JVMs
+1. **Backward Compatibility:** Java 8 remains in use by many Minecraft mods and older game clients that haven't been updated for newer JVMs
-2.  **Performance Optimization:** Java 21 provides the best performance characteristics for modern games with heavy multithreading requirements
+2. **Performance Optimization:** Java 21 provides the best performance characteristics for modern games with heavy multithreading requirements
-3.  **Security Updates:** All Temurin versions receive regular security patches from the Eclipse Foundation community
+3. **Security Updates:** All Temurin versions receive regular security patches from the Eclipse Foundation community
 The installation process ensures clean repository management without polluting the system with multiple conflicting JRE installations, maintaining Debian's package integrity while providing flexibility for different gaming scenarios. It automatically installs `extrepo` if not present and enables the Adoptium source before proceeding with version-specific packages (e.g., `temurin-8-jre`, `temurin-17-jre`, `temurin-25-jre`).
-
+### References
 ### References:
 - [https://wiki.debian.org/Steam](https://wiki.debian.org/Steam)
 - [wiki.archlinux.org/title/Steam](wiki.archlinux.org/title/Steam)
@@ -145,7 +148,3 @@ The installation process ensures clean repository management without polluting t
 - [https://github.com/feralinteractive/gamemode](https://github.com/feralinteractive/gamemode)
 - [https://gitlab.com/CalcProgrammer1/OpenRGB](https://gitlab.com/CalcProgrammer1/OpenRGB)
 - [https://adoptium.net/es/installation/linux](https://adoptium.net/es/installation/linux)
@@ -1,12 +1,12 @@
-## Option 5: Graphics Drivers, Mesa Stack & Display Architecture
+# Option 6: Graphics Drivers, Mesa Stack & Display Architecture
 ### 1. Philosophy of the Graphics Stack (Open-Source vs. Proprietary)
 The `debianito` script adopts a **hybrid-first architecture philosophy**. It prioritizes the stability and security of the Linux kernel's native open-source drivers while maintaining the capability to inject proprietary solutions where necessary for performance or legacy support. This approach is implemented through three distinct layers:
-1.  **DRM/KMS & Mesa (Open-Source Core)**: For Intel and AMD hardware, the script relies on the `i915`/`amdgpu` kernel drivers (KMS) paired with the `Mesa` user-space stack. This ensures that graphics acceleration is handled by the mainline Linux kernel without requiring third-party blobs or external repositories for basic functionality. The script explicitly installs the necessary Gallium3D drivers (`radeonsi`, `iris`) and Vulkan implementations (`RADV`).
+1. **DRM/KMS & Mesa (Open-Source Core)**: For Intel and AMD hardware, the script relies on the `i915`/`amdgpu` kernel drivers (KMS) paired with the `Mesa` user-space stack. This ensures that graphics acceleration is handled by the mainline Linux kernel without requiring third-party blobs or external repositories for basic functionality. The script explicitly installs the necessary Gallium3D drivers (`radeonsi`, `iris`) and Vulkan implementations (`RADV`).
-2.  **Proprietary Injection (NVIDIA)**: For NVIDIA hardware, the open-source Nouveau driver is often insufficient for gaming or compute workloads. The script manages the installation of proprietary `.run` or DKMS modules via official NVIDIA repositories. This requires careful handling to ensure compatibility with the running kernel version, especially when using backports kernels.
+2. **Proprietary Injection (NVIDIA)**: For NVIDIA hardware, the open-source Nouveau driver is often insufficient for gaming or compute workloads. The script manages the installation of proprietary `.run` or DKMS modules via official NVIDIA repositories. This requires careful handling to ensure compatibility with the running kernel version, especially when using backports kernels.
-3.  **Firmware & Microcode**: A critical prerequisite layer handled by `firmware.sh`. Before any driver can load, the correct firmware blobs (e.g., `iwlwifi`, `amdgpu`, `nvidia`) must be present in `/lib/firmware`. The script scans hardware via `lspci` and `lsusb` to populate a dynamic installation plan for these non-free components.
+3. **Firmware & Microcode**: A critical prerequisite layer handled by `firmware.sh`. Before any driver can load, the correct firmware blobs (e.g., `iwlwifi`, `amdgpu`, `nvidia`) must be present in `/lib/firmware`. The script scans hardware via `lspci` and `lsusb` to populate a dynamic installation plan for these non-free components.
 This philosophy ensures that users on standard Debian Stable releases get maximum compatibility, while advanced users can opt into backports kernels or enterprise NVIDIA repositories without breaking the base system integrity.
@@ -17,11 +17,13 @@ This philosophy ensures that users on standard Debian Stable releases get maximu
 The script utilizes a robust pre-flight detection sequence defined in `utils.sh` and executed within `gpu.sh`. This pipeline minimizes user interaction by automatically categorizing hardware before presenting installation options.
 **Detection Flow:**
-1.  **Hardware Scanning**: The function `detect_gpu()` executes `lspci -nn | grep -E "VGA|3D"`. It parses the output using `sed` and `grep` to identify vendor IDs (e.g., `8086` for Intel, `10de` for NVIDIA).
+
-2.  **Variable State**: Global variables are populated immediately:
+1. **Hardware Scanning**: The function `detect_gpu()` executes `lspci -nn | grep -E "VGA|3D"`. It parses the output using `sed` and `grep` to identify vendor IDs (e.g., `8086` for Intel, `10de` for NVIDIA).
-    *   `GPU_TYPE`: Set to `"intel"`, `"amd"`, or `"nvidia"`. If no GPU is found, it defaults to `"unknown"` (common in VMs or headless servers).
+2. **Variable State**: Global variables are populated immediately:
-    *   `INTEL_GPU_DEVICE_ID` / `NVIDIA_GPU_DEVICE_ID`: Hexadecimal device IDs extracted for precise generation matching.
+    * `GPU_TYPE`: Set to `"intel"`, `"amd"`, or `"nvidia"`. If no GPU is found, it defaults to `"unknown"` (common in VMs or headless servers).
-3.  **Logic Branching**: Inside `install_gpu_drivers()`, the script checks these variables:
+    * `INTEL_GPU_DEVICE_ID` / `NVIDIA_GPU_DEVICE_ID`: Hexadecimal device IDs extracted for precise generation matching.
 3. **Logic Branching**: Inside `install_gpu_drivers()`, the script checks these variables:
    ```bash
    if [ "$GPU_TYPE" = "unknown" ]; then
        # Install generic Mesa stack (Safe fallback)
@@ -33,9 +35,10 @@ The script utilizes a robust pre-flight detection sequence defined in `utils.sh`
        # Route to AMD-specific logic (amdgpu/radeonsi)
        install_amd_firmware && offer_amd_tools
    ```
-4.  **Hybrid Support**: For laptops with hybrid graphics (e.g., Intel iGPU + NVIDIA dGPU), the script detects both `HAS_INTEL=true` and `HAS_NVIDIA=true`. It executes a sequential plan:
+
-    *   Install Intel firmware/drivers first to ensure the base display server works.
+4. **Hybrid Support**: For laptops with hybrid graphics (e.g., Intel iGPU + NVIDIA dGPU), the script detects both `HAS_INTEL=true` and `HAS_NVIDIA=true`. It executes a sequential plan:
-    *   Install NVIDIA drivers second, configuring them for PRIME offloading if detected.
+    * Install Intel firmware/drivers first to ensure the base display server works.
    * Install NVIDIA drivers second, configuring them for PRIME offloading if detected.
 This "detect-then-deploy" model prevents users from installing unnecessary drivers (e.g., `i965` on an RTX 4090) and ensures that critical firmware is present before the driver installation phase begins.
@@ -48,9 +51,9 @@ This "detect-then-deploy" model prevents users from installing unnecessary drive
 | **Gen4** (Broadwater) | 65nm | GMA X4500, GMA X4500HD | `i915` | `i915` | Not supported | Predecessor to HD Graphics. Very limited support. The i915 DRI driver is the original, now obsolete. |
 | **Gen5** (Ironlake) | 32nm | HD Graphics (Westmere/Arrandale) | `i915` | `crocus` | Not supported | First generation "HD Graphics". OpenGL up to 3.3 only. Legacy driver `i965` was **removed** in Mesa 24.1, so `crocus` is now the only option. |
 | **Gen6** (Sandy Bridge) | 32nm | HD Graphics 2000/3000 | `i915` | `crocus` | Not supported | Significant performance improvement. Maximum OpenGL 3.3. |
-| **Gen7** (Ivy Bridge) | 22nm | HD Graphics 2500/4000 | `i915` | `crocus` | `ANV/HASVK` [(incomplete/broken)](https://www.reddit.com/r/vulkan/s/Hnf5zU8WZY) | First Gen at 22nm. `crocus` is the recommended OpenGL driver. Vulkan is exposed but completely non-conformant (0.0.0.0 ), lacks basic features (e.g., texture swizzle), and is [unusable for real-world tasks](https://www.phoronix.com/news/Intel-HasVK-Drop-Dead-Code).|
+| **Gen7** (Ivy Bridge) | 22nm | HD Graphics 2500/4000 | `i915` | `crocus` | `ANV/HASVK` [(incomplete/broken)](https://www.reddit.com/r/vulkan/s/Hnf5zU8WZY) | First Gen at 22nm. `crocus` is the recommended OpenGL driver. Vulkan is exposed but completely non-conformant (0.0.0.0 ), lacks basic features (e.g., texture swizzle), and is [unusable for real-world tasks](https://www.phoronix.com/news/Intel-HasVK-Drop-Dead-Code). |
 | **Gen7** (Bay Trail) | 22nm | HD Graphics (Bay Trail) | `i915` | `crocus` | `ANV`[(incomplete)](https://lists.debian.org/debian-user/2023/07/msg00550.html) | `conformanceVersion = 0.0.0.0` Support is experimental up to Vulkan 1.2, lacks basic extensions, and may cause instability. The separate HASVK driver exists but is not used on this system. |
-| **Gen7.5** (Haswell) | 22nm | HD Graphics 4600, Iris Pro 5200 | `i915` | `crocus` | `hasvk` |  Vulkan support via community driver `hasvk` (Vulkan 1.3). |
+| **Gen7.5** (Haswell) | 22nm | HD Graphics 4600, Iris Pro 5200 | `i915` | `crocus` | `hasvk` | Vulkan support via community driver `hasvk` (Vulkan 1.3). |
 | **Gen8** (Broadwell) | 14nm | HD Graphics 5300, Iris Pro 6200, Iris 6100 | `i915` | `iris` | `hasvk` | First generation at 14nm, `iris` becomes the main OpenGL driver. |
 | **Gen9** (Skylake) | 14nm | HD Graphics 530, Iris 540/550 | `i915` | `iris` | `anv` | Mature architecture with strong Linux support. Major performance boost for iGPU. |
 | **Gen9.5** (Kaby Lake, Coffee Lake, Comet Lake) | 14nm+ / 14nm++ | UHD Graphics 620/630, UHD 610/630 | `i915` | `iris` | `anv` | Process node optimization for 14nm. "UHD" replaces "HD" in naming convention. |
@@ -64,19 +67,19 @@ This "detect-then-deploy" model prevents users from installing unnecessary drive
 ---
-#### Intel Details: 
+#### Intel Details
-1.  **Kernel Driver Transition (`i915` to `xe`)**: The [`i915`](https://www.kernel.org/doc/html/v4.9/gpu/i915.html) driver is reaching its scalability limits. [Xe](https://www.kernel.org/doc/html/v6.8/gpu/rfc/xe.html) is the path for modern hardware, though it still requires forcing and is under development, it already shows significant improvements in various areas.
+1. **Kernel Driver Transition (`i915` to `xe`)**: The [`i915`](https://www.kernel.org/doc/html/v4.9/gpu/i915.html) driver is reaching its scalability limits. [Xe](https://www.kernel.org/doc/html/v6.8/gpu/rfc/xe.html) is the path for modern hardware, though it still requires forcing and is under development, it already shows significant improvements in various areas.
-2.  **Mesa Drivers (User Space)**:
+2. **Mesa Drivers (User Space)**:
-    *   **OpenGL**:
+    * **OpenGL**:
-        *   **Legacy Hardware (Gen5-Gen8)**: The classic `i965` driver was **officially removed from Mesa in version 24.1**. **[`crocus`](https://www.phoronix.com/news/Intel-Crocus-Default-Gallium3D)** (Gallium3D) is the only active driver for this legacy hardware.
+        * **Legacy Hardware (Gen5-Gen8)**: The classic `i965` driver was **officially removed from Mesa in version 24.1**. **[`crocus`](https://www.phoronix.com/news/Intel-Crocus-Default-Gallium3D)** (Gallium3D) is the only active driver for this legacy hardware.
-        *   **Modern Hardware (Gen9 and Xe)**: **`iris`** is the standard driver. It works excellently on both iGPUs and Arc dGPUs (Alchemist/Battlemage).
+        * **Modern Hardware (Gen9 and Xe)**: **`iris`** is the standard driver. It works excellently on both iGPUs and Arc dGPUs (Alchemist/Battlemage).
-    *   **Vulkan**: 
+    * **Vulkan**:
-        *   **Old Hardware about Ivy Bridge and Bay Trail (Gen7)**: Although the ANV/HASVK drivers expose these GPUs as Vulkan devices (reporting API versions as high as 1.2 or 1.3), their state is completely non-compliant (conformanceVersion = 0.0.0.0). The support is purely theoretical, it lacks basic hardware features (e.g., texture swizzle on Ivy Bridge) and is unstable or unusable for real-world applications. Because of this, in Mesa 22.3, the Gen7/Gen8 Vulkan code was separated from the main driver (ANV) and moved to the legacy HASVK driver to avoid hindering the development of modern hardware. You can read the technical details of this decision [here](https://www.phoronix.com/news/Intel-HASVK-Old-Vulkan-Gen7-8).
+        * **Old Hardware about Ivy Bridge and Bay Trail (Gen7)**: Although the ANV/HASVK drivers expose these GPUs as Vulkan devices (reporting API versions as high as 1.2 or 1.3), their state is completely non-compliant (conformanceVersion = 0.0.0.0). The support is purely theoretical, it lacks basic hardware features (e.g., texture swizzle on Ivy Bridge) and is unstable or unusable for real-world applications. Because of this, in Mesa 22.3, the Gen7/Gen8 Vulkan code was separated from the main driver (ANV) and moved to the legacy HASVK driver to avoid hindering the development of modern hardware. You can read the technical details of this decision [here](https://www.phoronix.com/news/Intel-HASVK-Old-Vulkan-Gen7-8).
-        *   **Legacy Hardware (Gen7.5 - Gen8)**: Uses **[`hasvk`](https://www.phoronix.com/news/Intel-ANV-HASVK-Split-Merged)**, a community-maintained driver (not directly by Intel engineers), offering Vulkan 1.2? on 2013-era hardware.
+        * **Legacy Hardware (Gen7.5 - Gen8)**: Uses **[`hasvk`](https://www.phoronix.com/news/Intel-ANV-HASVK-Split-Merged)**, a community-maintained driver (not directly by Intel engineers), offering Vulkan 1.2? on 2013-era hardware.
        *Additionally, in early 2024, the compiler code shared between `iris` and `anv` for [Gen8](https://www.phoronix.com/news/Intel-Mesa-Splitting-Gen8) was also isolated, following the same principle: to enable faster development for modern hardware without breaking Broadwell support*.
-        *   **Modern Hardware (Gen9+)**: **[`anv`](https://docs.mesa3d.org/drivers/anv.html)** is Intel's official driver. On recent hardware (Gen12+, Arc) it reaches the **Vulkan 1.4 standard**.
+        * **Modern Hardware (Gen9+)**: **[`anv`](https://docs.mesa3d.org/drivers/anv.html)** is Intel's official driver. On recent hardware (Gen12+, Arc) it reaches the **Vulkan 1.4 standard**.
-3.  **New Hardware Support Status**: Support for very recent iGPUs (such as Lunar Lake and Panther Lake) often requires very recent versions of the Linux kernel (6.8/6.11 branch or higher) and Mesa library (24.2+), plus updated firmware (`linux-firmware`).
+3. **New Hardware Support Status**: Support for very recent iGPUs (such as Lunar Lake and Panther Lake) often requires very recent versions of the Linux kernel (6.8/6.11 branch or higher) and Mesa library (24.2+), plus updated firmware (`linux-firmware`).
 ---
@@ -89,31 +92,53 @@ AMD's open-source support is divided by architecture families, each mapped to a
 | **TeraScale 1**<br>*(R600/R700)* | Radeon HD 2000, HD 3000, HD 4000 | `radeon` | `r600` | **Not Applicable** | Starting point of the `r600` driver in Mesa. Supports up to OpenGL 3.3. Architecture is completely obsolete, only useful for very basic 2D/3D desktop graphics. |
 | **TeraScale 2**<br>*(Evergreen)* | Radeon HD 5000, HD 6000<br>*(and some low-end HD 7000)* | `radeon` | `r600` | **Not Applicable** | Last evolution of TeraScale. OpenGL support stalled at version 3.3. **No Vulkan support exists or will exist** due to hardware architecture limitations. |
 | **TeraScale 3**<br>*(Northern Islands)* | Radeon HD 6000, HD 7000 (low-end) | `radeon` | `r600` | **Not Applicable** | Intermediate architecture between TeraScale 2 and GCN. OpenGL support remains at 3.3. **No Vulkan support**. Last generation before the jump to GCN. |
-| **GCN 1.0 / 1.1**<br>*(gfx6 / gfx7)* | Radeon HD 7700, R7 200, R9 200/300 | `radeon` (default)<br>`amdgpu` (forced) | `radeonsi` | `RADV` (Vulkan 1.3) | **⚠️ Requires manual configuration:** The kernel loads `radeon` by default. To use `radeonsi`/`RADV`, pass to the kernel: `amdgpu.si_support=1 amdgpu.cik_support=1 radeon.si_support=0 radeon.cik_support=0`. |
+| **GCN 1.0 / 1.1**<br>*(gfx6 / gfx7)* | Radeon HD 7700, R7 200, R9 200/300 | `radeon` (default)<br>`amdgpu` (forced) | `radeonsi` | `RADV` (Vulkan 1.3) | First generation 28nm processor with Vulkan support. The kernel loads the `radeon` module by default. The script injects the system parameters to use `RADV`. |
 | **GCN 3.0**<br>*(gfx8 / gfx8.1)* | Radeon R9 285, R9 Fury X, R9 Nano | `amdgpu` | `radeonsi` | `RADV` (Vulkan 1.4) | Third generation of GCN, direct predecessor to Polaris. Introduces efficiency improvements and initial support for Vulkan 1.3. |
 | **GCN 4.0**<br>*(Polaris, gfx8.0)* | Radeon RX 400, RX 500, Radeon Pro WX | `amdgpu` | `radeonsi` | `RADV` (Vulkan 1.4) | First generation to use the `amdgpu` KMD natively and by default without tricks. Sweet spot for stability of older hardware in current Linux. No Ray Tracing hardware support. |
 | **GCN 5.0**<br>*(Vega, gfx9)* | Radeon RX Vega, Radeon VII, APUs Raven Ridge | `amdgpu` | `radeonsi` | `RADV` (Vulkan 1.4) | Last GCN generation. Significant improvements to the `radeonsi` driver for this hardware. On Vega, using "Override" in RADV sometimes improves performance over default shader cache. |
 | **RDNA 1**<br>*(gfx10)* | Radeon RX 5000 | `amdgpu` | `radeonsi` | `RADV` (Vulkan 1.4) | Architectural jump. Introduces Variable Rate Shading (VRS) support. Mesa drivers quickly achieved performance parity with the proprietary Windows driver on this generation. |
 | **RDNA 2**<br>*(gfx10.3)* | Radeon RX 6000, Steam Deck (Van Gogh) | `amdgpu` | `radeonsi` | `RADV` (Vulkan 1.4) | First generation with hardware **Ray Tracing** in AMD. In Mesa, this is handled through the `VK_KHR_ray_tracing_pipeline` extension. This architecture is in the Steam Deck, which massively accelerated RADV development. |
 | **RDNA 3**<br>*(gfx11)* | Radeon RX 7000 | `amdgpu` | `radeonsi` | `RADV` (Vulkan 1.4) | Introduces **Mesh Shaders** in AMD hardware ([`VK_EXT_mesh_shader`](https://github.com/KhronosGroup/Vulkan-Docs/blob/main/proposals/VK_EXT_mesh_shader.adoc) extension). Requires a relatively recent Linux kernel (6.1+) for complete and stable graphics controller support. |
-| **RDNA 3.5**<br>*(gfx11.5)* | APUs Strix Point/Halo, Krackan Point, Gorgon Halo| `amdgpu` | `radeonsi` | `RADV` (Vulkan 1.4) | Intermediate update to RDNA 3. Shares many features with RDNA 3 (gfx11). Support in drivers (kernel, Mesa, LLVM) is integrated as part of the GFX11 family. |
+| **RDNA 3.5**<br>*(gfx11.5)* | APUs Strix Point/Halo, Krackan Point, Gorgon Halo | `amdgpu` | `radeonsi` | `RADV` (Vulkan 1.4) | Intermediate update to RDNA 3. Shares many features with RDNA 3 (gfx11). Support in drivers (kernel, Mesa, LLVM) is integrated as part of the GFX11 family. |
-| **RDNA 4**<br>*(gfx12)* | Radeon RX 9000 | `amdgpu` | `radeonsi` | `RADV` (Vulkan 1.4) | Latest generation to date. RADV jumps to full support for **Vulkan 1.4** across the entire GFX8+ line (GCN 3 onwards). **Current context:** AMD has officially discontinued their other open Vulkan driver (AMDVLK), leaving 
+| **RDNA 4**<br>*(gfx12)* | Radeon RX 9000 | `amdgpu` | `radeonsi` | `RADV` (Vulkan 1.4) | Latest generation to date. RADV jumps to full support for **Vulkan 1.4** across the entire GFX8+ line (GCN 3 onwards). **Current context:** AMD has officially discontinued their other open Vulkan driver (AMDVLK), leaving
 #### AMD GCN Migration via GRUB Parameters
 For older AMD GCN 1.0/1.1 GPUs (`gfx6`/`gfx7`), the script forces the modern `amdgpu` driver via kernel parameters injected into `GRUB_CMDLINE_LINUX_DEFAULT`. The migration is handled in `gpu.sh:_force_amdgpu()` with a **duplicate guard** to prevent repeated parameter injection:
 ```bash
 local params="radeon.si_support=0 radeon.cik_support=0 amdgpu.si_support=1 amdgpu.cik_support=1"
 # Duplicate guard — skip if already present
 if grep -q "amdgpu.si_support=1" "$file" 2>/dev/null; then
    _msg "AMD GCN" "amdgpu parameters already present in GRUB.\nNo changes made." 8 50
    return
 fi
 # Insert params at the beginning of GRUB_CMDLINE_LINUX_DEFAULT
 if ! sudo grep -q "amdgpu.si_support=1" "$file"; then
    sudo sed -i -E "/^GRUB_CMDLINE_LINUX_DEFAULT=/ s/\"([^\"]*)\"/\"${params} \1\"/" "$file"
 fi
 ```
 The guard checks both `grep -q` (read-only) and `sudo grep -q` (with elevated permissions) to handle systems where `/etc/default/grub` requires root access. If the parameters are already present, the function exits early with a message rather than duplicating the entry.
 #### Additional notes & carifications
-1.  **Regarding GCN Nomenclature**: Names like "GCN 1.0", "1.1", "1.2" were created by the press as a convenient abbreviation, since AMD only started officially numbering their GCN revisions (gen 1 to 4) later. The table now uses more standard terminology.
+1. **Regarding GCN Nomenclature**: Names like "GCN 1.0", "1.1", "1.2" were created by the press as a convenient abbreviation, since AMD only started officially numbering their GCN revisions (gen 1 to 4) later. The table now uses more standard terminology.
-2.  **Relationship Between Drivers and Architectures**:
+2. **Relationship Between Drivers and Architectures**:
-    *   The `radeonsi` driver (OpenGL) and `RADV` (Vulkan) are siblings within the Mesa 3D project. Both depend on the [`amdgpu` kernel](https://docs.kernel.org/gpu/amdgpu/index.html).
+    * The `radeonsi` driver (OpenGL) and `RADV` (Vulkan) are siblings within the Mesa 3D project. Both depend on the [`amdgpu` kernel](https://docs.kernel.org/gpu/amdgpu/index.html).
-    *   The old [`radeon`](https://wiki.freedesktop.org/xorg/radeon/) driver (for TeraScale) is incompatible with modern Mesa drivers (`radeonsi`/`RADV`).
+    * The old [`radeon`](https://wiki.freedesktop.org/xorg/radeon/) driver (for TeraScale) is incompatible with modern Mesa drivers (`radeonsi`/`RADV`).
-    *   **Important milestone**: Starting from Linux kernel 6.19, the `amdgpu` driver will include support for older generations of [AMD GPUs](https://wiki.gentoo.org/wiki/AMDGPU) (such as TeraScale and early GCN) that were previously only supported by the `radeon` driver, unifying support.
+    * **Important milestone**: Starting from Linux kernel 6.19, the `amdgpu` driver will include support for older generations of [AMD GPUs](https://wiki.gentoo.org/wiki/AMDGPU) (such as TeraScale and early GCN) that were previously only supported by the `radeon` driver, unifying support.
-3.  **Vulkan Support in RADV**: Mesa documentation indicates that [RADV supports Vulkan 1.4 for all GFX8 GPUs (GCN 3 onwards) and newer](https://docs.mesa3d.org/drivers/radv.html#supported-hardware). This includes RDNA 3 and RDNA 3.5 architectures, not just RDNA 4. 
+3. **Vulkan Support in RADV**: Mesa documentation indicates that [RADV supports Vulkan 1.4 for all GFX8 GPUs (GCN 3 onwards) and newer](https://docs.mesa3d.org/drivers/radv.html#supported-hardware). This includes RDNA 3 and RDNA 3.5 architectures, not just RDNA 4.
-4.  **RDNA 3.5 Status**: It is an intermediate update that shares the architectural base of RDNA 3 (gfx11). The identifiers `gfx1150` and `gfx1151` correspond to this generation. Support in Mesa drivers and the kernel has been integrated progressively.
+4. **RDNA 3.5 Status**: It is an intermediate update that shares the architectural base of RDNA 3 (gfx11). The identifiers `gfx1150` and `gfx1151` correspond to this generation. Support in Mesa drivers and the kernel has been integrated progressively.
 ---
 ### 5. **NVIDIA Hardware & Driver Support**
-#### Nvidia Legacy (Fermi to Pascal):
+#### Nvidia Legacy (Fermi to Pascal)
 These generations depend **exclusively** on the proprietary driver and closed stack. There is no support for the open kernel module nor NVK.
 | Architecture | Last Driver with Support | Kernel Module (KMD) | Proprietary Vulkan Support | NVK (Mesa) Support | Max CUDA Version | Notes and Particularities |
@@ -125,7 +150,8 @@ These generations depend **exclusively** on the proprietary driver and closed st
 ---
-#### Nvidia: modern era and """Open Source""" (Turing to Blackwell):
+#### Nvidia: modern era and "Open Source" (Turing to Blackwell)
 Starting with Turing, NVIDIA introduced the **open kernel module**. From driver 525, this module is the default. Additionally, it's the range where community driver **NVK** (in Mesa) shines.
 | Architecture | Compatible Active Drivers | Kernel Module (KMD) | Proprietary Vulkan Support | NVK (Mesa) Support | Max CUDA Version | Notes and Particularities |
@@ -135,10 +161,11 @@ Starting with Turing, NVIDIA introduced the **open kernel module**. From driver
 | **Ada Lovelace**<br>*(AD100/102/103/104)* | 525.xx to 610+ | `nvidia` (**Open Module**) | **Vulkan 1.3** | **Yes** (Vulkan 1.3) | **CUDA 12.8+** | NVK added full Ada support recently. Proprietary driver still required if hardware Ray Tracing or DLSS 3 (Frame Generation) is needed, as NVK does not yet implement these proprietary extensions. |
 | **Blackwell**<br>*(GB100/102/202)* | [570.xx](https://docs.nvidia.com/datacenter/tesla/tesla-release-notes-570-211-01/index.html) to 610+ | `nvidia` (**Open Module**) | **Vulkan 1.3** | **Yes** (In development) | **CUDA 12.8+** | Latest generation architecture (RTX 5090/5080). NVK support is landing in the most recent kernel versions (6.12+) and Mesa (24.3+). Requires very updated `linux-firmware`. |
-#### 💡 Quick context glossary for documentation:
+#### 💡 Quick context glossary for documentation
-*   **Open Module:** Starting with driver 515, [NVIDIA releases code that interacts directly with the Linux kernel under MIT/GPL license](https://developer.nvidia.com/blog/nvidia-releases-open-source-gpu-kernel-modules/). However, the GPU still requires loading a proprietary closed microcode called **GSP (GPU System Processor)** to boot.
+
-*   **NVK:** It is the open-source Vulkan driver developed by Red Hat and the community, integrated into the [Mesa project](https://docs.mesa3d.org/drivers/nvk.html). It's the 100% free alternative to `libGLX_nvidia.so`. Does not require NVIDIA proprietary driver installed to function (only kernel firmware).
+* **Open Module:** Starting with driver 515, [NVIDIA releases code that interacts directly with the Linux kernel under MIT/GPL license](https://developer.nvidia.com/blog/nvidia-releases-open-source-gpu-kernel-modules/). However, the GPU still requires loading a proprietary closed microcode called **GSP (GPU System Processor)** to boot.
-*   **CUDA Drop:** When NVIDIA removes an architecture from new drivers (e.g., Pascal in 555), the CUDA version used by that GPU freezes forever (in this case, CUDA 12.0). Cannot run applications compiled for CUDA 12.1 or higher.
+* **NVK:** It is the open-source Vulkan driver developed by Red Hat and the community, integrated into the [Mesa project](https://docs.mesa3d.org/drivers/nvk.html). It's the 100% free alternative to `libGLX_nvidia.so`. Does not require NVIDIA proprietary driver installed to function (only kernel firmware).
 * **CUDA Drop:** When NVIDIA removes an architecture from new drivers (e.g., Pascal in 555), the CUDA version used by that GPU freezes forever (in this case, CUDA 12.0). Cannot run applications compiled for CUDA 12.1 or higher.
 ---
@@ -147,16 +174,17 @@ Starting with Turing, NVIDIA introduced the **open kernel module**. From driver
 When the script detects Intel or AMD hardware, it triggers a specific installation sequence designed to maximize [API support](https://mesamatrix.net/) (OpenGL/Vulkan/VA-API).
 **Core Components Installed:**
-*   **`libgl1-mesa-dri`**: Provides the core OpenGL implementation for 64-bit systems. The script ensures `libgl1-mesa-dri:i386` is included if Wine or legacy applications are required, preventing architecture mismatches.
+
-*   **`mesa-vulkan-drivers`**: Installs `RADV` (AMD) and `anv` (Intel). This enables Vulkan 1.2/1.3 support on modern hardware.
+* **`libgl1-mesa-dri`**: Provides the core OpenGL implementation for 64-bit systems. The script ensures `libgl1-mesa-dri:i386` is included if Wine or legacy applications are required, preventing architecture mismatches.
-*   **`va-driver-all` / `vdpau-va-driver`**: Ensures video decoding acceleration is available for media players like VLC or MPV.
+* **`mesa-vulkan-drivers`**: Installs `RADV` (AMD) and `anv` (Intel). This enables Vulkan 1.2/1.3 support on modern hardware.
 * **`va-driver-all` / `vdpau-va-driver`**: Ensures video decoding acceleration is available for media players like VLC or MPV.
 **Vendor-Specific Logic:**
 | Vendor | Kernel Driver (KMD) | Mesa User-Space Driver | VAAPI Backend Strategy |
 | :--- | :--- | :--- | :--- |
 | **Intel Gen < 8** | `i915` | `crocus` / `iris` | Installs [`i965-va-driver-shaders`](https://github.com/intel/intel-vaapi-driver/). Legacy path for older CPUs. |
-| **Intel Gen 8+** | `i915` | `iris` / `anv` | Installs [`intel-media-va-driver-non-free](https://github.com/intel/media-driver). Modern, preferred backend for Broadwell+. |
+| **Intel Gen 8+** | `i915` | `iris` / `anv` | Installs [`intel-media-va-driver-non-free`](https://github.com/intel/media-driver). Modern, preferred backend for Broadwell+. |
 | **AMD GCN/RDNA** | `amdgpu` | `radeonsi` (GL) + `RADV` (VK) | Uses standard `va-driver-all`. Requires kernel param tuning for older GCN. |
 **Critical Consistency Check:**
@@ -166,18 +194,21 @@ The script enforces the installation of 32-bit Mesa libraries (`libgl1-mesa-dri:
 ### 7.**NVIDIA Driver Management & Kernel Compatibility**
-The NVIDIA driver installation process is inherently complex due to proprietary components, kernel version constraints, and DKMS (Dynamic Kernel Module Support) module compilation. This section outlines how the script navigates these challenges by distinguishing between stable and backports kernels, handling Blackwell architecture GPUs via CUDA v590, and providing appropriate warnings for potential compatibility issues.
+The NVIDIA driver installation process is inherently complex due to proprietary components, kernel version constraints, and DKMS (Dynamic Kernel Module Support) module compilation. This section outlines how the script navigates these challenges by distinguishing between stable and backports kernels, handling Blackwell architecture GPUs via the CUDA repository (production branches v590 / v595), and providing appropriate warnings for potential compatibility issues.
 #### **Kernel Compatibility**
 - **Stable Kernels**: Use `linux-image-amd64`. Compatible with standard NVIDIA `.deb` packages (e.g., `nvidia-driver-535`) and DKMS modules.
 - **Backports Kernels**: Detected via `is_backports_kernel()`. Newer kernels may cause DKMS compilation failures due to driver version lag. The script warns users or suggests using the NVIDIA enterprise repository or manual header compilation (`linux-headers-$(uname -r)`).
-#### **Blackwell Architecture & CUDA v590**
+* **Stable Kernels**: Use `linux-image-amd64`. Compatible with standard NVIDIA `.deb` packages (e.g., `nvidia-driver-535`) and DKMS modules.
- **Detection**: `_helpers.sh` function `is_nvidia_blackwell()` identifies GPUs via PCI IDs `10de:24xx`, `0x2900–0x29BF`, and `0x2B80–0x31FF`.
+* **Backports Kernels**: Detected via `is_backports_kernel()`. Newer kernels may cause DKMS compilation failures due to driver version lag. The script warns users or suggests using the NVIDIA enterprise repository or manual header compilation (`linux-headers-$(uname -r)`).
- **Reason for v590**: Debian 13 (Trixie) stable drivers only support up to v550, which lacks Blackwell (GB20x) architecture. The NVIDIA CUDA repository provides production branch v590 with unified driver packages. Specifically, the goal is to install the latest version of the nvidia-driver from the 590 branch, which would be [590.48.01](https://download.nvidia.com/XFree86/Linux-x86_64/590.48.01/README/supportedchips.html).
+
- **CUDA Repository Enablement**: On Debian 12 (Bookworm) the `nvidia-cuda` repository is enabled via `extrepo`. On Debian 13 (Trixie) the official `cuda-keyring` package is used instead (`wget` + `dpkg -i`), since extrepo cannot configure the repo correctly on Trixie. After enabling, the script always runs an explicit `apt update`, then installs `nvidia-driver-pinning-<ver>` if available (official NVIDIA pinning, optional), and finally installs the unified metapackage `nvidia-open` plus `firmware-nvidia-gsp`. No manual pinning file is written; if `apt install` fails, the real apt error is shown and the installation aborts.
+#### **Blackwell Architecture & CUDA v590/v595 (Production Branches)**
 * **Detection**: `_helpers.sh` function `is_nvidia_blackwell()` identifies GPUs via PCI IDs `10de:24xx`, `0x2900–0x29BF`, and `0x2B80–0x31FF`. The same check gates both CUDA branches — Blackwell is unsupported by Debian stable regardless of the selected CUDA version.
 * **Reason for v590/v595**: Debian 13 (Trixie) stable drivers only support up to v550, which lacks Blackwell (GB20x) architecture. The NVIDIA CUDA repository provides two production branches with unified driver packages: **v590**(current long-lived production, [590.48.01](https://download.nvidia.com/XFree86/Linux-x86_64/590.48.01/README/supportedchips.html)) and **v595** ([595.91.07](https://download.nvidia.com/XFree86/Linux-x86_64/595.91.07/README/supportedchips.html)newer production branch, same GB20x support with more recent fixes/features). Both branches expose the same unified metapackage and replace the need for a distro-packaged driver on Blackwell hardware.
 * **CUDA Repository Enablement**: On Debian 13 (Trixie) — the only release that exposes `590` and `595` (`_show_nvidia_version_menu` gates them behind `DEBIAN_VERSION == 13`) — the script enables the `nvidia-cuda` repository via `extrepo` (`sudo apt install -y extrepo` if missing, then `sudo extrepo enable nvidia-cuda`). After enabling, the script always runs an explicit `apt update`, then installs `nvidia-driver-pinning-<ver>` if available (official NVIDIA pinning, optional and version-specific for 590 vs 595), and finally installs the unified metapackage `nvidia-open` plus `firmware-nvidia-gsp` (pulled as a transitive dependency). No manual pinning file is written; if `apt install` fails, the real `apt` error is shown and the installation aborts.
 #### **Installation Flow**
 The NVIDIA flow is driven by `_install_nvidia_stack` (dispatcher in `modules/gpu.sh`):
 1. **Plan** — `_msg` with detected GPUs, then `_pause`.
@@ -185,12 +216,20 @@ The NVIDIA flow is driven by `_install_nvidia_stack` (dispatcher in `modules/gpu
 3. **Version menu** (`_show_nvidia_version_menu`): Debian 12 → v535 (Recommended) / v470 (Kepler); Debian 13 → v550 (Recommended) / v590 / v595 (NVIDIA CUDA Repo).
 4. **Dispatch by hardware**: Kepler → `nvidia-tesla-470-driver`; Fermi → veto with message; Turing+ → `_install_nvidia_standard` (Debian stable); Blackwell on Trixie → CUDA repo v590.
 5. **CUDA repo (590/595)**: two separate APT transactions — `nvidia-driver-pinning-<ver>` (version lock, mandatory) then `nvidia-open` (driver + open kernel modules, firmware via transitive dependency).
-6. **Post-install**: `/etc/modprobe.d/nvidia-wayland.conf` + DKMS verification.
+6. **Secure Boot warning**: If Secure Boot is active (`mokutil --sb-state` reports `SecureBoot enabled`), the script displays a warning that the NVIDIA DKMS module is compiled but **NOT signed**. The user must sign the module with MOK or disable Secure Boot in BIOS before rebooting:
   ```
   WARNING: Secure Boot is enabled. The NVIDIA DKMS module is compiled but NOT signed.
   You MUST sign the module with MOK or disable Secure Boot in BIOS before rebooting.
   ```
   Installation continues — Secure Boot does not block DKMS compilation, but the module will fail to load until signed.
 7. **Post-install**: `/etc/modprobe.d/nvidia-wayland.conf` (written with `|| return 1` protection) + DKMS verification.
 > Note: Debian 12 (Bookworm) backports reached EOL (2026-08-09); the NVIDIA flow on Bookworm only uses the stable repository.
 ---
-### 8.**NVIDIA Driver Management & Kernel Compatibility**
+### 9.**NVIDIA Driver Compatibility Matrix**
 Depending on your GPU generation and your Debian ecosystem, you must select the appropriate legacy or current driver series. The following table details the verified compatibility matrix across different Debian versions and hardware architectures:
@@ -202,13 +241,16 @@ Depending on your GPU generation and your Debian ecosystem, you must select the
 | **[550.163.01](https://us.download.nvidia.com/XFree86/Linux-x86_64/550.163.01/README/supportedchips.html)** | **Debian 13** (Trixie) | Maxwell to Ada Lovelace | Current stable standard. Blackwell not officially supported yet. |
 #### **Critical Hardware Notes:**
-*   **Kepler (GeForce vs. Quadro)**: The last driver supporting true Kepler architecture is version **470**. If a user has a GTX 680 or similar, they must stay on Debian 11 or use the 470 driver branch in Bookworm/Trixie manually.
+
-*   **Fermi (GTX 400/500)**: Support ended with driver 390. These GPUs are incompatible with modern kernels and drivers beyond Debian 11.
+* **Kepler (GeForce vs. Quadro)**: The last driver supporting true Kepler architecture is version **470**. If a user has a GTX 680 or similar, they must stay on Debian 11 or use the 470 driver branch in Bookworm/Trixie manually.
-*   **Volta (Titan V / V100)**: Excellent longevity, supported from 390 through 550+.
+* **Fermi (GTX 400/500)**: Support ended with driver 390. These GPUs are incompatible with modern kernels and drivers beyond Debian 11.
-*   **Blackwell (RTX 5000)**: Not officially supported by standard Debian drivers yet. The script provides a path to the Enterprise Repo for users who need this hardware to function immediately.
+* **Volta (Titan V / V100)**: Excellent longevity, supported from 390 through 550+.
 * **Blackwell (RTX 5000)**: Not officially supported by standard Debian drivers yet. The script provides a path to the Enterprise Repo for users who need this hardware to function immediately.
 #### **Kepler Interception in Bookworm:**
 When Kepler is detected on Bookworm, `nvidia.sh` forces installation of `nvidia-tesla-470-driver` (the modern v535/v550 branches do not support Kepler):
 ```bash
 if [ "$is_kepler" = "true" ] && [ "$DEBIAN_CODENAME" = "bookworm" ]; then
    nv_pkg="nvidia-tesla-470-driver"
@@ -218,21 +260,22 @@ fi
 ---
-### 9. Performance Monitoring & Telemetry Tools
+### 10. Performance Monitoring & Telemetry Tools
 To ensure the graphics stack is functioning correctly, `gpu.sh` offers an optional installation of telemetry tools. These allow users to verify GPU utilization, memory usage, and codec support post-installation.
-*   **Universal ([`nvtop`](https://github.com/Syllo/nvtop))**:
+* **Universal ([`nvtop`](https://github.com/Syllo/nvtop))**:
-    *   A cross-platform tool that displays real-time metrics for NVIDIA, AMD, and Intel GPUs in a terminal interface (similar to `htop`).
+  * A cross-platform tool that displays real-time metrics for NVIDIA, AMD, and Intel GPUs in a terminal interface (similar to `htop`).
-    *   **Debian 11 Constraint**: In Debian 11 Bullseye, `nvtop` support is limited primarily to NVIDIA GPUs. The script warns users of this limitation on older releases.
+  * **Debian 11 Constraint**: In Debian 11 Bullseye, `nvtop` support is limited primarily to NVIDIA GPUs. The script warns users of this limitation on older releases.
-*   **AMD Specific ([`radeontop`](https://github.com/clbr/radeontop))**:
+* **AMD Specific ([`radeontop`](https://github.com/clbr/radeontop))**:
-    *   Provides detailed metrics for AMD GPUs (GPU usage, memory utilization, power consumption). Essential for verifying that the `amdgpu` driver is active and not falling back to software rendering.
+  * Provides detailed metrics for AMD GPUs (GPU usage, memory utilization, power consumption). Essential for verifying that the `amdgpu` driver is active and not falling back to software rendering.
-*   **Intel Specific ([`intel-gpu-tools`](https://github.com/ChrisCummins/intel-gpu-tools))**:
+* **Intel Specific ([`intel-gpu-tools`](https://github.com/ChrisCummins/intel-gpu-tools))**:
-    *   Only installed if the detected Intel hardware supports it (Gen 6+). Provides information on GPU usage via `inotify` or `/sys/class/drm`.
+  * Only installed if the detected Intel hardware supports it (Gen 6+). Provides information on GPU usage via `inotify` or `/sys/class/drm`.
-*   **Codec Verification ([`vainfo`](https://github.com/intel/libva-utils))**:
+* **Codec Verification ([`vainfo`](https://github.com/intel/libva-utils))**:
-    *   The script runs `vainfo` to verify that VAAPI is correctly configured. This confirms whether the system can utilize hardware acceleration for video decoding (e.g., H.264, HEVC) via Intel QuickSync or AMD Video Core Plus.
+  * The script runs `vainfo` to verify that VAAPI is correctly configured. This confirms whether the system can utilize hardware acceleration for video decoding (e.g., H.264, HEVC) via Intel QuickSync or AMD Video Core Plus.
 **Installation Command Logic:**
 ```bash
 if _confirm "Install Telemetry Tools"; then
    case "$GPU_TYPE" in
@@ -1,77 +1,152 @@
-## Option 6: Debian Backports Kernel Integration
+# Option 7: Kernel Variants (Stable, Backports, RT, Cloud)
-### 1. Why a Backports Kernel?
+## 1. What Does This Component Do?
-The decision to integrate the Debian Backports kernel into `debianito.sh` is driven by the fundamental architectural conflict between **Stability** and **Hardware Enablement**.
+The **Kernel** module (`modules/kernel.sh`) manages which Linux kernel your system boots. Unlike a simple `apt install`, it enforces **atomic installation of image + headers** and validates repository state before touching the boot chain. The menu (`show_kernel_menu`) offers four distinct kernel flavours plus a Backports path that is only available on Debian 13 (Trixie):
-Debian Stable (including Debian 13 "Trixie") prioritizes long-term reliability. As a result, its kernel version is frozen at a Long Term Support (LTS) release—in this case, Linux 6.12 LTS. While 6.12 is robust and secure, it represents a snapshot of the upstream kernel from late 2024/early 2025. It does not include the rapid stream of hardware enablement, scheduler refinements, or power management optimizations that occur in subsequent releases (e.g., Linux 7.0+).
+| Key | Variant | Package | Use Case |
 | ----- | --------- | --------- | ---------- |
 | `stable` | Stable | `linux-image-amd64` | Default Debian kernel (6.12 LTS on Trixie). Maximum stability. |
 | `backports` | Backports | `linux-image-amd64` from `trixie-backports` | Newer kernel (e.g., 7.x) for recent hardware. **Trixie only**, requires backports enabled. |
 | `rt` | Real-Time | `linux-image-rt-amd64` | Preempt-RT kernel for low-latency / audio production. Warns on NVIDIA. |
 | `cloud` | Cloud | `linux-image-cloud-amd64` | Minimal kernel for VMs, containers, and cloud images. |
-For users with modern hardware released between 2025 and 2026, this freeze creates a compatibility gap:
+All variants install the matching **headers** package (`linux-headers-amd64`, `linux-headers-rt-amd64`, `linux-headers-cloud-amd64`) in the same transaction — critical for DKMS modules (NVIDIA, VirtualBox, ZFS).
 *   **New Architectures:** CPUs like Intel Arrow Lake/Panther Lake or AMD Zen 5 require specific microcode, scheduler hints (e.g., "slow workload hints"), and CXL support that are absent in the frozen 6.12 LTS branch.
 *   **Graphics Performance:** New GPUs (Intel Battlemage) may lack optimized power states (like D3cold enablement) or improved driver integration found in newer kernels.
 *   **Filesystem Integrity:** Advanced features like XFS self-healing or Btrfs remap-tree improvements are exclusive to newer kernel versions.
-The `kernel.sh` module leverages the Debian Backports repository (`trixie-backports`) as a "best-effort" bridge. This allows users to opt-in to Kernel 7.0+ without abandoning the Stable base entirely. The script ensures that this upgrade is treated as an exception, providing access to modern enablement while maintaining the safety net of the Stable ecosystem for core system packages.
+> **Position in menu:** This is Option 7 in the current `debianito.sh` main menu. Previous documentation listed it as Option 6 (Backports only). The module was expanded to support RT and Cloud kernels after the initial release.
-### 2. Synchronized Installation Pipeline (Kernel + Headers)
+---
-A critical engineering principle in kernel management is **Atomicity**. Installing a new kernel image without its corresponding headers breaks the build chain for third-party modules (such as NVIDIA DKMS, VirtualBox, or ZFS). The `install_kernel_backports` function enforces this by ensuring the installation command targets both components.
+## 2. Why Offer Backports at All?
-**The Installation Command Logic:**
+Debian Stable freezes its kernel at an LTS release (6.12 LTS on Trixie). This is intentional for reliability, but creates a hardware enablement gap for machines released in 2025-2026:
-The script utilizes `apt` with a specific target release flag to pull packages from the backports suite:
+
 - **New CPUs** (Intel Arrow Lake / Panther Lake, AMD Zen 5) need scheduler hints, CXL, and microcode not in 6.12
 - **New GPUs** (Intel Battlemage D3cold, NVIDIA Blackwell) need power-state and firmware support added after 6.12
 - **Filesystem fixes** (XFS self-healing, Btrfs remap-tree) land only in newer kernels
 The `trixie-backports` repository provides a **best-effort newer kernel** without moving the rest of the system to Testing. Debian backports kernels receive security updates but are not LTS themselves.
 This is why the menu shows `backports` only when `DEBIAN_VERSION == 13` and greys it out otherwise. Bookworm backports is intentionally not offered — its EOL was 2026-08-09 and the NVIDIA path on Bookworm no longer uses backports.
 ---
 ## 3. The Installation Pipeline: Image + Headers Atomically
 ### Function: `_install_kernel_package` (`kernel.sh`)
 ```bash
-sudo apt install -y -t ${DEBIAN_CODENAME}-backports linux-image-amd64
+_install_kernel_package "linux-image-amd64" "Backports" "-t trixie-backports"
 _install_kernel_package "linux-image-rt-amd64" "RT" ""
 ```
-While Debian's dependency resolver often pulls headers automatically when installing `linux-image`, explicit documentation and engineering best practices dictate that the system must be configured to ensure both are present. The pipeline operates as follows:
+Execution steps:
-1.  **Target Specification (`-t`):** The flag `-t ${DEBIAN_CODENAME}-backports` explicitly directs APT to ignore the Stable repository for this specific transaction, ensuring the latest backported version is selected rather than a cached Stable package.
+1. **Availability check** — `apt-cache show <pkg>` must succeed. If the package does not exist for the current Debian version, a whiptail message `Kernel not available` is shown and the function returns.
-2.  **Image Package:** `linux-image-amd64` contains the bootable kernel binary and associated modules.
+2. **Hardware warnings** (flavour-specific):
-3.  **Headers Dependency:** Although often implicit, the documentation mandates that `linux-headers-amd64` must be present for DKMS drivers to recompile successfully after a reboot. If these are missing, external drivers may fail to load until manually rebuilt against the new headers.
+   - **Backports + NVIDIA** (`GPU_TYPE == "nvidia"`): `_confirm "Kernel" "WARNING: Backports kernel changes the kernel version. Your NVIDIA driver will need recompilation (DKMS)."`. Users can still proceed — DKMS will rebuild on next boot if headers match.
   - **RT + NVIDIA**: `_msg "Kernel — RT" "Ensure your NVIDIA driver supports the RT kernel. Some proprietary drivers may not work correctly."`. Not a blocker, but informs that some closed drivers fail with PREEMPT_RT.
 3. **Version resolution** for the confirmation dialog:
-This synchronized approach ensures that when the system boots into the new kernel, all dependent modules have access to the correct symbol tables and build environment provided by the matching headers.
+   ```bash
   # Backports path
   ver=$(apt-cache madison linux-image-amd64 | grep trixie-backports | awk '{print $3}' | head -1)
   headers_ver=$(apt-cache madison linux-headers-amd64 | grep trixie-backports | awk '{print $3}' | head -1)
   # Stable/RT/Cloud path
   ver=$(apt-cache show linux-image-amd64 | sed -n 's/^Version: //p' | grep -v '~bpo' | head -1)
   ```
-### 3. Safety Mechanisms and Atomic Operation
+   The dialog shows `Image: linux-image-amd64 (6.12.22-1)` + `Headers: linux-headers-amd64 (6.12.22-1)` + `From: Trixie-backports` when a backports flag is present.
 4. **User confirmation** — `whiptail --yesno "Install Backports kernel? Image: ... Headers: ..."` with the version string. Declining aborts with `Skipping.`.
 5. **Atomic install**:
-To prevent boot loops or system instability, `kernel.sh` implements several safety checks before executing any installation commands:
+   ```bash
   sudo apt install -y [-t trixie-backports] linux-image-amd64 linux-headers-amd64
   sudo apt install -y linux-image-rt-amd64 linux-headers-rt-amd64
   sudo apt install -y linux-image-cloud-amd64 linux-headers-cloud-amd64
   ```
-*   **Pre-flight Repository Validation:**
+   Both image and headers are passed in a **single `apt` transaction**. This guarantees the symbol tables match and DKMS can rebuild. The helper `_run_cmd "Kernel"` prints the command, captures the exit code, and pauses for the user to review output.
-    The function begins with a strict check using `is_backports_enabled()`. If the backports repository is not active in `/etc/apt/sources.list`, the script halts and instructs the user to enable it via Option 3. This prevents accidental dependency conflicts or installation failures due to missing sources.
+6. **Post-install** — prints `Backports kernel installed. Reboot to use it.` and pauses. The new kernel is added to `/boot` alongside the old one; GRUB will show both at next boot. The script does not remove the old kernel — rollback is simply rebooting into the previous entry.
-*   **Hardware Compatibility Warnings:**
+---
    The script detects if an NVIDIA GPU is present (`GPU_TYPE == "nvidia"`). In this scenario, a warning is displayed: *"WARNING: may break NVIDIA driver."*. This alerts the user that proprietary drivers might require DKMS recompilation against the new headers.
-*   **Bootloader Update (GRUB):**
+## 4. Menu Logic: `show_kernel_menu`
    Although not explicitly shown in the minimal `kernel.sh` snippet provided, standard kernel engineering practice dictates that after a successful installation, the bootloader must be updated to register the new entry:
    ```bash
    sudo update-grub
    ```
    This ensures the new kernel appears in the GRUB menu and can be set as the default.
-*   **Fallback Preservation:**
+```bash
-    The script does not remove the previous kernel. Debian's package manager retains older kernels, preserving them in `/boot`. If the new backports kernel fails to boot (e.g., due to a hardware incompatibility), the user can simply select the previous stable version from the GRUB menu during startup. This "Rollback Safety" is inherent to the Debian Stable model and is reinforced by the script's non-destructive installation approach.
+show_kernel_menu() {
  while true; do
    items=("stable" "Install linux-image-amd64")
    [ "$DEBIAN_VERSION" = "13" ] && items+=("backports" "Install from backports")
    items+=("rt" "Install linux-image-rt-amd64 (Preempt-RT)")
    items+=("cloud" "Install linux-image-cloud-amd64")
    items+=("back" "Return to main menu")
    choice=$(whiptail --menu "Kernel Installation" "Select kernel variant:" 16 65 5 "${items[@]}")
-### 4. Critical Interconnection with Other Modules (Script Ecosystem)
+    case "$choice" in
      stable)    _install_kernel_package "linux-image-amd64" "Stable" "" ;;
      backports)
        if [ "$(is_backports_enabled)" != "true" ]; then
          whiptail --msgbox "Backports repository is not enabled.\nUse option 4 (Configure repositories) to enable backports before installing."
        else
          _install_kernel_package "linux-image-amd64" "Backports" "-t ${DEBIAN_CODENAME}-backports"
        fi ;;
      rt)        _install_kernel_package "linux-image-rt-amd64" "RT" "" ;;
      cloud)     _install_kernel_package "linux-image-cloud-amd64" "Cloud" "" ;;
      back) break ;;
    esac
  done
 }
 ```
-The Backports Kernel module does not operate in isolation; it relies on a tightly coupled ecosystem within `debianito.sh` to ensure full functionality:
+Key details:
-*   **Option 4: Firmware & Wireless Drivers:**
+- **Backports visibility** — The `backports` entry is only appended when `DEBIAN_VERSION == 13`. On Bullseye/Bookworm it does not appear.
-    New kernels often introduce support for new hardware IDs, but they require corresponding firmware blobs (e.g., `firmware-misc-nonfree`). If the user installs Kernel 7.0+ without updating their firmware repository, wireless cards or specific storage controllers may remain unfunctional. The script ensures that Option 4 is logically dependent on a compatible kernel state.
+- **Backports guard** — Selecting `backports` without backports enabled shows a message pointing to **Option 4 (Configure Repositories)**. No install is attempted.
 - **Loop** — The menu is a `while true` loop; the user can install multiple variants sequentially (e.g., Stable + RT) before returning with `back` or `ESC`.
-*   **Option 5: Graphics Drivers (NVIDIA DKMS):**
+---
    For systems with NVIDIA hardware, the installation of a new kernel triggers a dependency chain for `nvidia-dkms`. If the user has proprietary drivers installed, they must be recompiled against the new headers provided by the backports kernel. The script's detection logic (`HAS_NVIDIA`) allows it to warn users or trigger DKMS rebuilds automatically if integrated into a larger workflow.
-*   **Bullseye-Specific Logic:**
+## 5. Safety Mechanisms
    As seen in `debianito.sh`, the Backports Kernel module is conditionally loaded based on the Debian version:
    ```bash
    if [ "$DEBIAN_VERSION" = "11" ]; then
        _msg "Not Available" ...
    else
        install_kernel_backports || true
    fi
    ```
    This ensures that legacy systems (Debian 11 Bullseye) do not attempt to use a backports workflow that may not be supported or stable in older architectures, while newer versions (Bookworm/Trixie) utilize the full feature set.
-*   **Gaming & Extras:**
+| Mechanism | How It Works |
-    The Backports kernel is often recommended for gaming due to improved scheduler performance and low-latency networking features found in Linux 7.0+. By linking Option 6 with `gaming.sh`, users can ensure their hardware is tuned correctly before launching high-performance applications.
+| ----------- | -------------- |
 | **Pre-flight `is_backports_enabled`** | `utils.sh:is_backports_enabled` greps `/etc/apt/sources.list` and `/etc/apt/sources.list.d/*.sources` / `*.list` for `trixie-backports`. Prevents `apt -t` from failing with `E: Release not found`. |
 | **NVIDIA RT warning** | `utils.sh:GPU_TYPE` is set at startup by `detect_gpu` (lspci). RT kernels change scheduling semantics; some `nvidia.ko` builds reject `PREEMPT_RT`. |
 | **Atomic image+headers** | Both packages in one `apt` call. If headers are missing, `dkms` will fail at boot — so they are never installed separately. |
 | **Fallback preservation** | `apt` never removes the running kernel. `/boot` retains `vmlinuz-*` and `initrd.img-*` for both. GRUB keeps both entries; if the new kernel panics, select the old one. |
 | **Version-aware messaging** | The confirmation dialog always shows the exact version string (`apt-cache madison` / `apt-cache show`) so users know they are not reinstalling the same package. |
 GRUB update is **not** explicitly called — `linux-image-*` postinst triggers `update-grub` (or `kernel-install` on systemd-boot) automatically. If GRUB is broken, use **Option 12 (Boot Rescue + GRUB)** to rebuild it.
 ---
 ## 6. Interconnection with Other Modules
 - **Option 4: Repositories** — Must enable `trixie-backports` before `Kernel → backports` is usable. The kernel menu explicitly checks `is_backports_enabled` and directs the user there if missing.
 - **Option 5: Firmware** — Newer kernels expose new hardware IDs (e.g., `8086:7e40` for Panther Lake). Without updated `firmware-linux-nonfree` or `firmware-iwlwifi`, the new kernel will show the device but fail to load firmware. Run Firmware after a kernel upgrade if WiFi/storage is not recognized.
 - **Option 6: Graphics Drivers** — NVIDIA `dkms` needs the exact `linux-headers-*` version. The atomic install ensures headers match. On Bookworm the NVIDIA path deliberately avoids backports kernels; on Trixie a backports kernel + Maxwell/Pascal GPU is forced to the stable NVIDIA driver (`v550`) to avoid `v590` incompatibility.
 - **Gaming (`gaming.sh`)** — The backports kernel is sometimes recommended for gaming (scheduler latency, `SCHED_EXT`), but not required. Benchmarks show <3% difference for most titles; enable it only for newer hardware that needs it.
 ---
 ## 7. Verification After Installation
 ```bash
 uname -r                      # Should show the new kernel after reboot
 dpkg -l linux-image-amd64 | grep ^ii
 dpkg -l linux-headers-amd64 | grep ^ii
 ls -l /boot/vmlinuz-*         # Both old and new kernels present
 grep -E 'menuentry' /boot/grub/grub.cfg | head -5  # GRUB entries
 ```
 If the new kernel fails to boot, hold `ESC` (or `Shift` on BIOS) at power-on, select **Advanced options for Debian** → previous kernel version.
 ---
 ## References
 - [Debian Backports — backports.debian.org](https://backports.debian.org/)
 - [Debian Kernel Handbook](https://kernel-handbook.alioth.debian.org/)
 - [PREEMPT_RT — wiki.debian.org/RealTime](https://wiki.debian.org/RealTime)
 - [Installing a new kernel — wiki.debian.org/DebianKernel](https://wiki.debian.org/DebianKernel)
@@ -1,10 +1,11 @@
-## Option 3: Advanced Repository Configuration
+# Option 4: Repository Configuration
 ### 1. What Does This Component Do?
 The repository configuration module is the foundational engine of Debianito that establishes and maintains a secure, up-to-date package management environment for your Debian system. It performs **idempotent, atomic operations** to configure APT sources with precision while protecting against corruption through automatic rollback mechanisms.
 At its core, this component:
 - Detects your current repository format (Classic `.list` vs modern DEB822 `.sources`)
 - Backs up existing configurations before any modifications
 - Enables critical non-free components required for hardware drivers and proprietary software
@@ -20,19 +21,23 @@ This is not just about "adding repositories"—it's about **system integrity ass
 The script intelligently adapts to your Debian version and existing repository structure:
 #### Classic Format (`/etc/apt/sources.list`)
 - **Structure**: Human-readable text with `deb` lines
 - **Use Case**: Debian 11 (Bullseye) through Debian 12 (Bookworm) default
 - **Characteristics**: Linear, comment-friendly, widely understood by all APT tools
 - **Example**:
 ```bash
 deb https://deb.debian.org/debian bookworm main contrib non-free non-free-firmware
 ```
 #### Modern DEB822 Format (`/etc/apt/sources.list.d/debian.sources`)
 - **Structure**: Declarative YAML-like format with `Types`, `URIs`, and `Suites` blocks
 - **Use Case**: Debian 13 (Trixie) default, future-proofing for newer releases
 - **Characteristics**: Machine-parseable, structured, supports complex repository hierarchies
 - **Example**:
 ```yaml
 Types: deb
 URIs: https://deb.debian.org/debian
@@ -41,7 +46,9 @@ Components: main contrib non-free non-free-firmware
 ```
 #### Migration Logic
 The script automatically detects your current format and offers migration options:
 - On Debian 13 (Trixie): Prompts to migrate TO DEB822 or stay with Classic
 - Format changes are atomic—backup is created before any modification
 - Old files are renamed with `.disabled` extension rather than deleted
@@ -52,7 +59,6 @@ The script automatically detects your current format and offers migration option
 The `configure_repos()` function in `repos.sh` executes the following sequence:
 ```bash
 ┌─────────────────────────────────────────────────────────────┐
 │                    INITIAL DETECTION PHASE                  │
@@ -111,6 +117,11 @@ The `configure_repos()` function in `repos.sh` executes the following sequence:
 │    ├── Creates appropriate file(s)                          │
 │    └── Includes main + backports if enabled                 │
 │                                                             │
 │ 8b. Branch Migration (if applicable)                        │
 │    ├── _write_branch_sources() → writes new branch sources  │
 │    ├── If failure → _restore_backup() || true               │
 │    └── return 1                                             │
 │                                                             │
 │ 9. Update Package Lists                                     │
 │     └── sudo apt update                                     │
 └─────────────────────────────────────────────────────────────┘
@@ -119,7 +130,6 @@ The `configure_repos()` function in `repos.sh` executes the following sequence:
 │                   POST-EXECUTION PHASE                      │
 ├─────────────────────────────────────────────────────────────┤
 │ 10. Success Path                                            │
 │     ├── REPOS_CONFIGURED=true                               │
 │     ├── Cleanup disabled files                              │
 │     └── Optional: Upgrade system if packages available      │
 │                                                             │
@@ -130,9 +140,11 @@ The `configure_repos()` function in `repos.sh` executes the following sequence:
 ```
 **Key Safety Mechanisms:**
 - **Atomic Operations**: Backup created before any write operation
 - **Idempotency Check**: `content_differs()` prevents unnecessary modifications
- **Rollback on Failure**: If `apt update` fails, original configuration is restored
+- **Rollback on Failure**: If `apt update` fails, original configuration is restored via `restore_previous_repos()`
 - **Branch Migration Rollback**: `_write_branch_sources()` failure triggers `_restore_backup() || true`
 - **Disabled File Extension**: Old formats renamed with `.disabled` rather than deleted
 ---
@@ -142,7 +154,7 @@ The `configure_repos()` function in `repos.sh` executes the following sequence:
 The script enables specific APT component branches that are essential for hardware functionality and software availability:
 | Component | Purpose | Critical For | Debian Version Notes |
-|-----------|---------|--------------|---------------------|
+| ----------- | --------- | -------------- | --------------------- |
 | **main** | Free, open-source software (Debian official) | All packages | Always enabled |
 | **contrib** | Free software that uses non-free components | Proprietary codecs, drivers | Enabled in all versions |
 | **non-free** | Non-free firmware and proprietary software | NVIDIA GPU drivers, Wi-Fi firmware | Required for hardware support |
@@ -161,12 +173,14 @@ deb https://deb.debian.org/debian bookworm main contrib non-free non-free-firmwa
 ```
 **Impact of Missing `non-free-firmware`:**
 - ❌ Wi-Fi adapters won't work without firmware blobs
 - ❌ Bluetooth devices may fail to initialize
 - ❌ Some GPU drivers require proprietary microcode
 - ❌ Embedded hardware (Raspberry Pi, etc.) becomes unusable
 The script ensures all four components are present because:
 1. **Hardware Compatibility**: Modern Debian kernels depend on these for out-of-the-box functionality
 2. **Security Updates**: `non-free-firmware` receives security patches separately
 3. **Future-Proofing**: Newer hardware releases firmware in this component exclusively
@@ -188,6 +202,7 @@ The backports integration is a sophisticated feature that enables access to newe
 ```
 **Return Values:**
 - `"standalone-deb822"` → Separate `.sources` file (recommended)
 - `"standalone-classic"` → Separate `.list` file
 - `"embedded-deb822"` → Inside `debian.sources`
@@ -231,7 +246,7 @@ The backports integration is a sophisticated feature that enables access to newe
 The script includes a detailed explanation because backports enable critical features:
 | Feature | Without Backports | With Backports |
-|---------|-------------------|----------------|
+| --------- | ------------------- | ---------------- |
 | **Linux Kernel** | Stable kernel only (e.g., 6.1-6.12) | Newer kernels (e.g., 6.x/7.x series) |
 | **GPU "Drivers"** | Latest Mesa from stable | Latest Mesa from testing |
 | **Wi-Fi Firmware** | Older firmware versions | Newest firmware for modern cards |
@@ -240,6 +255,7 @@ The script includes a detailed explanation because backports enable critical fea
 #### Backports Warning System
 The script includes safeguards:
 - Only enabled if user explicitly confirms
 - Warns about potential compatibility issues
 - Can be disabled anytime via Option 3 again
@@ -250,6 +266,7 @@ The script includes safeguards:
 ### Technical Implementation Notes
 **Idempotency Guarantee:**
 ```bash
 # content_differs() ensures no duplicate writes
 if [ "$current" = "$generated" ]; then
@@ -259,6 +276,7 @@ return 0  # Changes required
 ```
 **Atomic Backup Mechanism:**
 ```bash
 backup_current_repos() {
    REPO_BACKUP_DIR=$(mktemp -d)
@@ -276,6 +294,7 @@ restore_previous_repos() {
 **Component Activation Pattern:**
 All four components are written in a single operation to prevent partial configurations:
 ```bash
 Components: main contrib non-free non-free-firmware  # Atomic write
 # Not written as separate lines to avoid merge conflicts
@@ -1,72 +1,77 @@
-## Option 9: Swap
+# Option 10: Swap Management
 ### 1. What does this component do?
 This module is responsible for the secure management of disk-based swap space within the `debianito` environment. Unlike standard Linux tools that might overwrite existing configurations or conflict with memory compression features (like ZRAM), this script operates as a **priority-aware, persistent swap manager**.
 Its primary functions include:
-*   **Dynamic Allocation:** Creating and resizing swapfiles based on detected RAM capacity without requiring physical partition changes.
+
-*   **Priority Integration:** Explicitly setting the swap priority (`pri=10`) to ensure it sits below ZRAM (which uses `priority=100`). This prevents the system from using disk I/O for memory swapping until compressed RAM is exhausted, optimizing performance.
+* **Dynamic Allocation:** Creating and resizing swapfiles based on detected RAM capacity without requiring physical partition changes.
-*   **Persistence Management:** Safely editing `/etc/fstab` with a unique tag (`# debianito-managed-swap`) to ensure swap survives reboots without corrupting manual entries.
+* **Priority Integration:** Explicitly setting the swap priority (`pri=10`) to ensure it sits below ZRAM (which uses `priority=100`). This prevents the system from using disk I/O for memory swapping until compressed RAM is exhausted, optimizing performance.
-*   **Safety Locking:** Prevents concurrent operations using file locking mechanisms to avoid race conditions during active system usage.
+* **Persistence Management:** Safely editing `/etc/fstab` with a unique tag (`# debianito-managed-swap`) to ensure swap survives reboots without corrupting manual entries.
 * **Safety Locking:** Prevents concurrent operations using file locking mechanisms to avoid race conditions during active system usage.
 ### 2. How does it work?
 The script leverages several advanced Linux subsystems and safety protocols:
-1.  **File System Detection:** It identifies the filesystem type of the target partition (e.g., `ext4`, `btrfs`). For Btrfs, it applies specific flags (`chattr +C` for copy-on-write optimization) to prevent performance degradation during swap operations.
+1. **File System Detection:** It identifies the filesystem type of the target partition (e.g., `ext4`, `btrfs`). For Btrfs, it applies specific flags (`chattr +C` for copy-on-write optimization) to prevent performance degradation during swap operations.
-2.  **Allocation Strategy:** It prefers `fallocate` for instant space reservation on supported filesystems, falling back to `dd if=/dev/zero` for compatibility or zeroing requirements (like Btrfs).
+2. **Allocation Strategy:** It prefers `fallocate` for instant space reservation on supported filesystems, falling back to `dd if=/dev/zero` for compatibility or zeroing requirements (like Btrfs).
-3.  **Fstab Validation:** Before writing changes to `/etc/fstab`, it creates a temporary file and validates the syntax using `findmnt --verify`. If validation fails, the script aborts and restores the original state.
+3. **Fstab Validation:** Before writing changes to `/etc/fstab`, it creates a temporary file and validates the syntax using `findmnt --verify`. If validation fails, the script aborts and restores the original state.
-4.  **Concurrency Control:** It utilizes `flock` on `/run/lock/debianito-swap.lock`. This ensures that if another process is modifying swap settings (e.g., a system update), this script will wait or exit gracefully to prevent filesystem corruption.
+4. **Concurrency Control:** It utilizes `flock` on `/run/lock/debianito-swap.lock`. This ensures that if another process is modifying swap settings (e.g., a system update), this script will wait or exit gracefully to prevent filesystem corruption.
-5.  **Swappiness Tuning:** It configures `vm.swappiness` via both runtime (`sysctl -w`) and persistent (`/etc/sysctl.d/99-swappiness-debianito.conf`) mechanisms, defaulting to values that favor RAM usage over disk swapping (e.g., 10-20).
+5. **Swappiness Tuning:** It configures `vm.swappiness` via both runtime (`sysctl -w`) and persistent (`/etc/sysctl.d/99-swappiness-debianito.conf`) mechanisms, defaulting to values that favor RAM usage over disk swapping (e.g., 10-20).
 ### 3. The Logical Decision Tree (Step by Step)
 The execution flow follows a strict logical tree designed for safety and idempotency:
-1.  **Initialization & Locking:**
+1. **Initialization & Locking:**
-    *   The `manage_swap()` function attempts to acquire an exclusive lock (`flock -n`). If the lock is held by another process, it immediately exits with a "Busy" message to prevent conflicts.
+    * The `manage_swap()` function attempts to acquire an exclusive lock (`flock -n`). If the lock is held by another process, it immediately exits with a "Busy" message to prevent conflicts.
-2.  **Menu Selection Loop:**
+2. **Menu Selection Loop:**
-    *   Enters a continuous loop presenting options (Status, Create, Remove, Swappiness).
+    * Enters a continuous loop presenting options (Status, Create, Remove, Swappiness).
-    *   Breaks only when the user selects "Back to main menu".
+    * Breaks only when the user selects "Back to main menu".
-3.  **Action Execution Paths:**
+3. **Action Execution Paths:**
-    *   **Path A: Status Check (`_swap_current_status`)**
+    * **Path A: Status Check (`_swap_current_status`)**
-        *   Reads active swap entries via `swapon --show`.
+        * Reads active swap entries via `swapon --show`.
-        *   Reads current swappiness from `/proc/sys/vm/swappiness`.
+        * Reads current swappiness from `/proc/sys/vm/swappiness`.
-        *   Parses `/etc/fstab` for managed tags.
+        * Parses `/etc/fstab` for managed tags.
-    *   **Path B: Create/Resize (`_swap_create_file`)**
+    * **Path B: Create/Resize (`_swap_create_file`)**
-        *   **Recommendation:** Calculates optimal size based on RAM (e.g., 2GB for >16GB RAM, 4GB for 8-16GB).
+        * **Recommendation:** Calculates optimal size based on RAM (e.g., 2GB for >16GB RAM, 4GB for 8-16GB).
-        *   **Btrfs Check:** If the filesystem is Btrfs, it warns about `nodatacow` requirements and hibernation limitations.
+        * **Btrfs Check:** If the filesystem is Btrfs, it warns about `nodatacow` requirements and hibernation limitations.
-        *   **Existence Check:** If `/swapfile` exists, it prompts to confirm recreation (deleting old data first via `swapoff`).
+        * **Existence Check:** If `/swapfile` exists, it prompts to confirm recreation (deleting old data first via `swapoff`).
-        *   **Allocation:** Uses `fallocate` or `dd` to zero the file. Sets permissions (`chmod 600`) and initializes swap (`mkswap`).
+        * **Allocation:** Uses `fallocate` or `dd` to zero the file. Sets permissions (`chmod 600`) and initializes swap (`mkswap`).
-        *   **Persistence:** Attempts to write the new entry to `/etc/fstab`. If validation fails, it cleans up (removes file) before exiting.
+        * **Persistence:** Attempts to write the new entry to `/etc/fstab`. If validation fails, it cleans up (removes file) before exiting.
-    *   **Path C: Remove (`_swap_remove_file`)**
+    * **Path C: Remove (`_swap_remove_file`)**
-        *   Checks for the unique `SWAP_FSTAB_TAG` in fstab.
+        * Checks for the unique `SWAP_FSTAB_TAG` in fstab.
-        *   Confirms user intent to delete.
+        * Confirms user intent to delete.
-        *   Executes `swapoff`, removes the fstab line, and deletes the physical file.
+        * Executes `swapoff`, removes the fstab line, and deletes the physical file.
-    *   **Path D: Swappiness (`_swap_set_swappiness`)**
+    * **Path D: Swappiness (`_swap_set_swappiness`)**
-        *   Validates input (0-100 integer).
+        * Validates input (0-100 integer).
-        *   Writes a temporary sysctl config file.
+        * Writes a temporary sysctl config file.
-        *   Applies changes immediately via `sysctl -w`.
+        * Applies changes immediately via `sysctl -w`.
 ### 4. What does each menu item do and what does it mean?
 Each option in the swap management submenu serves a specific technical purpose:
-*   **Option 1: Show current swap & swappiness**
+* **Option 1: Show current swap & swappiness**
-    *   **Technical Action:** Aggregates data from `/proc/swaps`, `/proc/sys/vm/swappiness`, and `/etc/fstab`.
+  * **Technical Action:** Aggregates data from `/proc/swaps`, `/proc/sys/vm/swappiness`, and `/etc/fstab`.
-    *   **Significance:** Provides an audit trail of the current memory management state. It verifies if ZRAM is active (implied by priority check) and how much disk swap is currently in use.
+  * **Significance:** Provides an audit trail of the current memory management state. It verifies if ZRAM is active (implied by priority check) and how much disk swap is currently in use.
-*   **Option 2: Create / resize swapfile**
+* **Option 2: Create / resize swapfile**
-    *   **Technical Action:** Allocates a new block device file (`/swapfile`) or expands an existing one. Sets the `pri=10` flag to ensure it acts as a secondary memory layer after ZRAM fills up.
+  * **Technical Action:** Allocates a new block device file (`/swapfile`) or expands an existing one. Sets the `pri=10` flag to ensure it acts as a secondary memory layer after ZRAM fills up.
-    *   **Significance:** Essential for systems with low RAM that need overflow protection without installing physical partitions. The "Resize" capability allows adapting to new hardware configurations dynamically.
+  * **Significance:** Essential for systems with low RAM that need overflow protection without installing physical partitions. The "Resize" capability allows adapting to new hardware configurations dynamically.
-*   **Option 3: Remove swapfile**
+* **Option 3: Remove swapfile**
-    *   **Technical Action:** Disables the swapfile (`swapoff`), removes it from `/etc/fstab`, and deletes the file from disk.
+  * **Technical Action:** Disables the swapfile (`swapoff`), removes it from `/etc/fstab`, and deletes the file from disk.
-    *   **Significance:** Useful for troubleshooting, freeing up disk space (e.g., on SSDs where write cycles are a concern), or migrating to ZRAM-only configurations if RAM is sufficient.
+  * **Significance:** Useful for troubleshooting, freeing up disk space (e.g., on SSDs where write cycles are a concern), or migrating to ZRAM-only configurations if RAM is sufficient.
-*   **Option 4: Change swappiness**
+* **Option 4: Change swappiness**
-    *   **Technical Action:** Modifies the kernel parameter `vm.swappiness`.
+  * **Technical Action:** Modifies the kernel parameter `vm.swappiness`.
-    *   **Significance:** Controls the "aggressiveness" of swapping. A lower value (e.g., 10) tells the kernel to keep data in RAM longer, only using swap as a last resort. This is critical for desktop performance and battery life on laptops.
+  * **Significance:** Controls the "aggressiveness" of swapping. A lower value (e.g., 10) tells the kernel to keep data in RAM longer, only using swap as a last resort. This is critical for desktop performance and battery life on laptops.
-*   **Option 5: Back to main menu**
+* **Option 5: Back to main menu**
-    *   **Technical Action:** Releases the file lock (`exec 9>&-`) and terminates the submenu loop.
+  * **Technical Action:** Releases the file lock (`exec 9>&-`) and terminates the submenu loop.
-    *   **Significance:** Returns control to the user, ensuring no swap operations are running in the background before they navigate to other system configurations.
+  * **Significance:** Returns control to the user, ensuring no swap operations are running in the background before they navigate to other system configurations.
@@ -1,11 +1,20 @@
-## Option 1: Hardware Detection & System Information
+# Option 1: Hardware Detection & System Information
 ### 1. What Does This Component Do?
 This component serves as the **System Abstraction Layer** and diagnostic engine of the Debianito script. It is not merely a display utility; it acts as the foundational state initializer that runs prior to the main menu loop (`main_menu`). Its primary function is to perform pre-flight hardware enumeration, OS validation, and environment checks in "cold" mode (before any configuration changes are made).
 **Pre-flight initialization** (`debianito.sh` startup sequence):
 1. **Dependency auto-install**: The script checks for `whiptail` and `lsb-release`, installing them automatically if missing — ensuring the TUI and version detection work on minimal systems.
 2. **`lspci` guard and cache**: `command -v lspci &>/dev/null` validates availability before execution. If present, the full `lspci -nn` output is captured once into the global variable `LSPCI_OUTPUT`. All subsequent GPU, Ethernet, and network detection reads from this cache — avoiding redundant `lspci` invocations and ensuring consistent data throughout the session.
 3. **APT update deduplication**: The helper `_ensure_apt_updated` prevents redundant `apt update` calls by tracking whether the package lists have been refreshed recently. This is critical for performance when multiple modules (repos, firmware, GPU, kernel) each need to verify repository state.
 4. **State refresh flag**: `STATE_REFRESHED=true` is set before `;;` in every `case` branch of the main menu loop, ensuring that each menu entry starts with a clean, consistent state rather than stale cached data.
 By populating global variables such as `DEBIAN_VERSION`, `GPU_TYPE`, `CPU_SUMMARY`, and network interface states, it ensures that the subsequent menu options have access to accurate context. This prevents the user from making blind decisions—for example, attempting to install proprietary drivers on a system without detected hardware or selecting repositories incompatible with the current Debian codename. It transforms raw kernel data into actionable configuration parameters.
 ### 2. System Commands Used (Technical Mapping)
 The following table details the native Linux tools and file descriptors utilized by `utils.sh` to extract specific diagnostic data points. This mapping demonstrates reliance on standard, non-intrusive system utilities rather than proprietary binaries.
 | Feature | Command / Tool | Technical Purpose & Logic |
@@ -13,24 +22,28 @@ The following table details the native Linux tools and file descriptors utilized
 | **OS Version** | `lsb_release -cs`, `/etc/os-release` | Parses `VERSION_CODENAME` to determine Debian release (Bullseye, Bookworm, Trixie). Critical for selecting correct repository backports. |
 | **CPU Info** | `/proc/cpuinfo` | Reads `model name` and counts cores/threads. Provides cosmetic summary without needing heavy tools like `lscpu`. |
 | **Memory** | `/proc/meminfo` | Extracts `MemTotal` to calculate RAM in GB. Used for compatibility warnings with specific software packages. |
-| **GPU Detection** | `lspci -nn`, `nvidia-smi` | Identifies VGA/3D controllers via PCI IDs (`10de` for NVIDIA). Checks driver versions via `dpkg` if `nvidia-smi` fails. |
+| **GPU Detection** | `command -v lspci` guard → cached `LSPCI_OUTPUT` | `lspci -nn` output is cached in the global variable `LSPCI_OUTPUT` at startup. All subsequent GPU detection (PCI/USB buses, Ethernet, network) reads from this cache instead of re-running `lspci`. Identifies VGA/3D controllers via PCI IDs (`10de` for NVIDIA). Checks driver versions via `dpkg` if `nvidia-smi` fails. |
 | **Network (Eth)** | `ip -o link show` | Enumerates Ethernet interfaces, state (UP/DOWN), and IP addresses using the `iproute2` suite. |
 | **Network (Wi-Fi)** | `iwgetid`, `lspci` | Identifies wireless chipsets via PCI and retrieves SSID/Connection status for network diagnostics. |
 | **Storage** | `lsblk -d -o NAME,SIZE,ROTA` | Distinguishes between NVMe (`nvme`), SSD (RoT=0), and HDD (RoT=1) to provide storage topology summary. |
-| **Display Server**| Environment Vars (`XDG_SESSION_TYPE`) | Checks `WAYLAND_DISPLAY` vs `DISPLAY` variables to determine if the system is running Wayland, X11, or TTY. |
+| **Display Server** | Environment Vars (`XDG_SESSION_TYPE`) | Checks `WAYLAND_DISPLAY` vs `DISPLAY` variables to determine if the system is running Wayland, X11, or TTY. |
 ### 3. Strategic Importance for the Script
 This diagnostic phase is vital for engineering stability and user experience (UX) integrity within the script architecture:
-*   **Context-Aware Configuration:** The detection of `HAS_NVIDIA`, `HAS_AMD`, or `HAS_INTEL` directly dictates which sub-modules are loaded in `debianito.sh`. If no GPU is detected, graphics driver menus are skipped. This prevents "false positive" installation prompts that confuse the user.
+* **Context-Aware Configuration:** The detection of `HAS_NVIDIA`, `HAS_AMD`, or `HAS_INTEL` directly dictates which sub-modules are loaded in `debianito.sh`. If no GPU is detected, graphics driver menus are skipped. This prevents "false positive" installation prompts that confuse the user.
-*   **Repository Compatibility Guardrails:** The `detect_debian_version` function validates the OS against supported codenames (11, 12, 13). It specifically triggers Bullseye-specific logic (`configure_repos_bullseye`) only when necessary, preventing repository errors on newer or older distributions.
+* **Repository Compatibility Guardrails:** The `detect_debian_version` function validates the OS against supported codenames (11, 12, 13). It specifically triggers Bullseye-specific logic (`configure_repos_bullseye`) only when necessary, preventing repository errors on newer or older distributions.
-*   **Time Synchronization Safety:** The `check_system_time` function prevents package installation failures caused by clock skew (which breaks GPG signatures in APT). By offering an automated NTP sync before proceeding, it ensures the integrity of the entire software supply chain within the script.
+* **APT Update Deduplication:** The `_ensure_apt_updated` helper tracks whether `apt update` has been run recently. Multiple modules (repos, firmware, GPU, kernel) share a single update cycle, preventing redundant network calls and inconsistent package state between modules.
-*   **Root/Sudo Enforcement:** Early execution of `check_root` and `check_sudo` enforces security best practices. It prevents accidental privilege escalation or silent failures that often occur when scripts run with incorrect permissions.
+* **State Refresh Consistency:** `STATE_REFRESHED=true` is set before `;;` in every `case` branch of the main menu loop, ensuring each menu entry starts with a clean state and preventing stale variable propagation between sequential selections.
 * **Time Synchronization Safety:** The `check_system_time` function prevents package installation failures caused by clock skew (which breaks GPG signatures in APT). By offering an automated NTP sync before proceeding, it ensures the integrity of the entire software supply chain within the script.
 * **Root/Sudo Enforcement:** Early execution of `check_root` and `check_sudo` enforces security best practices. It prevents accidental privilege escalation or silent failures that often occur when scripts run with incorrect permissions.
 ### 4. Formatting and UX in the Terminal
 The raw data collected by these functions is processed into a human-readable format before being passed to the TUI (Text User Interface) via `whiptail`.
-*   **Structured String Assembly:** Functions like `_show_sysinfo` build multi-line strings (`msg+="...")`, appending newlines and conditional logic. This ensures that if multiple GPUs are found, they are listed sequentially with drivers identified below each entry.
+* **Structured String Assembly:** Functions like `_show_sysinfo` build multi-line strings (`msg+="...")`, appending newlines and conditional logic. This ensures that if multiple GPUs are found, they are listed sequentially with drivers identified below each entry.
-*   **Visual Hierarchy:** The data is organized into logical blocks (OS, Hardware, GPU, Network) with clear separators (`───`). This allows the user to quickly scan specific subsystems without scrolling through a monolithic log.
+* **Visual Hierarchy:** The data is organized into logical blocks (OS, Hardware, GPU, Network) with clear separators (`───`). This allows the user to quickly scan specific subsystems without scrolling through a monolithic log.
-*   **Conditional Rendering:** The script checks for command availability (e.g., `if ! command -v ip &>/dev/null`) before attempting to parse network data. If tools are missing, it gracefully degrades to a warning message rather than crashing the TUI.
+* **Conditional Rendering:** The script checks for command availability (e.g., `if ! command -v lspci &>/dev/null` guards GPU detection, `if ! command -v ip &>/dev/null` guards network data). If tools are missing, it gracefully degrades to a warning message rather than crashing the TUI. When `lspci` is present, its output is cached in `LSPCI_OUTPUT` for all subsequent detection calls.
-*   **TUI Integration:** The final formatted string is passed to `_msg`, which wraps the output in a `whiptail --msgbox`. This ensures the diagnostic information appears as a modal dialog with consistent dimensions and styling (colors defined globally in `debianito.sh`), maintaining a professional look regardless of the underlying terminal emulator.
+* **TUI Integration:** The final formatted string is passed to `_msg`, which wraps the output in a `whiptail --msgbox`. This ensures the diagnostic information appears as a modal dialog with consistent dimensions and styling (colors defined globally in `debianito.sh`), maintaining a professional look regardless of the underlying terminal emulator.
@@ -0,0 +1,216 @@
 # Option 3: System Preferences
 ## 1. What Does This Component Do?
 The **System Preferences** module (`modules/system/system_prefs.sh` + `modules/system/audio.sh`) consolidates first-boot personalization into a single menu. It is the only place in Debianito where **locale, timezone, and audio** are configured together — settings that Debian's installer often leaves at generic defaults and that affect every subsequent module.
 It groups three independent preference domains behind one entry point:
 | Sub-menu | Script | What It Configures |
 | ---------- | -------- | --------------------- |
 | **Date, Time & Timezone** | `system_prefs.sh:_prefs_date_time` | System clock, NTP sync, `tzdata` |
 | **Language, Locales & Keyboard** | `system_prefs.sh:_prefs_locale_keyboard` | `locales`, `keyboard-configuration` |
 | **Audio & Sound Stack** | `system/audio.sh:_prefs_audio_menu` | PipeWire, ALSA, pavucontrol, pulsemixer, playerctl |
 The menu itself is `_system_preferences_menu` in `system_prefs.sh` — a simple `while true` loop with `whiptail --menu`:
 ```
 1  Date, Time & Timezone
 2  Language, Locales & Keyboard
 3  Audio & Sound Stack
 4  Back to main menu
 ```
 > **Note:** This option was added after the initial repository setup. The main `README.md` menu previously started directly at "Configure Repositories". All Quick Start guides now reference System Preferences as Step 3.
 ---
 ## 2. Date, Time & Timezone
 ### Function: `_prefs_date_time` (`system_prefs.sh`)
 ```
 Current system date/time: 2026-03-15 14:22
 Timezone: America/Santiago
  → Confirm "Change the system timezone (dpkg-reconfigure tzdata)?"
      → sudo dpkg-reconfigure tzdata
  → _ensure_time_synced
 ```
 **What it does technically:**
 1. Prints the current date/time (`date '+%Y-%m-%d %H:%M'`) and timezone (`timedatectl show -p Timezone --value`).
 2. Prompts via `_confirm "Timezone"` to run `sudo dpkg-reconfigure tzdata` — the Debian-standard interactive timezone selector (ncurses).
 3. Calls `_ensure_time_synced` from `utils.sh` regardless of the answer:
   - Forces `timedatectl set-ntp true`
   - Validates the timezone is not `n/a` or `Etc/UTC`; if it is and a display is available, opens `tzdata` again
   - Ensures `systemd-timesyncd` is installed, enabled and restarted
   - Waits 2 seconds and checks `timedatectl show --property=NTPSynchronized --value` for `yes`
 **Why it matters:** An incorrect clock breaks APT GPG verification (`Release file is not valid yet`) and TLS certificates. The script runs a similar check automatically at startup (`_ensure_time_synced` in `debianito.sh` line 108), but this menu allows the user to fix timezone manually without re-running the whole script.
 ---
 ## 3. Language, Locales & Keyboard
 ### Function: `_prefs_locale_keyboard` (`system_prefs.sh`)
 ```bash
 sudo dpkg-reconfigure locales
 sudo dpkg-reconfigure keyboard-configuration
 ```
 **What it does technically:**
 - **`dpkg-reconfigure locales`** — Opens the Debian locales selector (e.g., `en_US.UTF-8`, `es_CL.UTF-8`). Generates the selected locales via `locale-gen` and updates `/etc/default/locale`. No reboot is required, but a re-login is needed for the new `LANG` to take effect.
 - **`dpkg-reconfigure keyboard-configuration`** — Configures `/etc/default/keyboard` (`XKBMODEL`, `XKBLAYOUT`, `XKBVARIANT`, `XKBOPTIONS`) and, on console, the keymap via `setupcon`. This affects both X11/Wayland and TTY.
 Both commands are run with `env LC_ALL=C LANGUAGE=C` to guarantee the debconf dialogs render in English even when the current locale is broken.
 This option has **no detection logic** — it delegates entirely to Debian's standard tools. It is idempotent and safe to run repeatedly.
 ---
 ## 4. Audio & Sound Stack
 ### Function: `_prefs_audio_menu` (`system/audio.sh`)
 This is the most complex sub-menu. It presents a checklist built dynamically based on system state:
 #### 4.1 Menu Construction
 ```bash
 items+=("pipewire-audio" "PipeWire Audio Stack (Bluetooth Hi-Res)" $state)
 items+=("alsa-utils"     "ALSA Utilities (alsa-utils, alsa-ucm-conf)" $state)
 # headless check — pavucontrol is GUI-only
 if ! _is_headless; then
  items+=("pavucontrol"  "Volume Control GUI (pavucontrol)" $state)
 fi
 items+=("pulsemixer"     "Terminal audio mixer (pulsemixer)" $state)
 items+=("playerctl"      "Multimedia key controller (playerctl)" $state)
 ```
 - **`_state <pkg>`** (in `utils.sh`) returns `ON` if `dpkg -l <pkg>` shows `^ii`, otherwise `OFF`.
 - **`_is_headless`** returns true when both `$DISPLAY` and `$WAYLAND_DISPLAY` are empty — in that case `pavucontrol` is hidden because it requires a GUI.
 - Package name for PipeWire varies by Debian version:
  - Debian 11 Bullseye → `pipewire` (the `pipewire-audio` metapackage does not exist)
  - Debian 12/13 → `pipewire-audio`
 The checklist is shown via `whiptail --checklist` with the title **"Audio & Sound"**.
 #### 4.2 PipeWire Installation Logic: `_install_pipewire_standard`
 This function handles the **PipeWire Audio Stack with Bluetooth Hi-Res codecs** — the core of modern Linux audio.
 **Codec package resolution:**
 ```bash
 bt_pkgs="libldacbt-abr2 libldacbt-enc2 libopenaptx0 libspa-0.2-bluetooth"
 # Transitional package name: libfdk-aac2t64 on Trixie (64-bit time_t), libfdk-aac2 on older
 if apt-cache show libfdk-aac2t64; then bt_pkgs+=" libfdk-aac2t64"
 elif apt-cache show libfdk-aac2; then bt_pkgs+=" libfdk-aac2"
 fi
 ```
 These packages provide **LDAC** (Sony), **aptX** (Qualcomm), and **AAC** (via FDK) Bluetooth codecs that are not in the default PipeWire installation.
 **Version selection (Trixie only, when backports is enabled):**
 | Condition | Dialog | Effect |
 | ----------- | -------- | -------- |
 | Already installed + backports available | `Upgrade to backports vX?` (Yes/No) | `sudo apt install --reinstall -t trixie-backports pipewire-audio $bt_pkgs` + `systemctl --user restart wireplumber pipewire pipewire-pulse` |
 | Not installed + backports available | `Backports vX` vs `Stable vY` (Backports/Stable buttons) | Installs from chosen repository; on Trixie `apt_target="-t trixie-backports"` if Backports chosen |
 | No backports | `Install PipeWire vX with Hi-Res codecs?` | Installs from stable |
 **Per-Debian-version install commands:**
 ```bash
 # Debian 11 Bullseye
 sudo apt install -y pipewire libspa-0.2-bluetooth pipewire-alsa libspa-0.2-jack $bt_pkgs
 # Debian 12 Bookworm
 sudo apt install -y pipewire-audio $bt_pkgs
 # Debian 13 Trixie
 sudo apt install -y [-t trixie-backports] pipewire-audio $bt_pkgs
 ```
 After installation on Debian 12/13, user PipeWire services are restarted:
 ```bash
 systemctl --user restart wireplumber pipewire pipewire-pulse
 ```
 #### 4.3 Other Audio Packages
 | Package | Purpose | Install Guard |
 | --------- | --------- | --------------- |
 | `alsa-utils` + `alsa-ucm-conf` | ALSA CLI tools (`aplay`, `amixer`, `alsamixer`) and UCM configs for modern sound cards | `is_installed alsa-utils` |
 | `pavucontrol` | GTK GUI volume control (PulseAudio/PipeWire compatible). Hidden in headless mode. | `is_installed pavucontrol` |
 | `pulsemixer` | Terminal (ncurses) mixer — works in TTY and headless | `is_installed pulsemixer` |
 | `playerctl` | MPRIS CLI to control media players via keyboard shortcuts | `is_installed playerctl` |
 Each package is installed via `_run_install <pkg>` which confirms the version via `apt-cache policy` before installing.
 ---
 ## 5. Logical Execution Flow
 ```
 ┌──────────────────────────────────────────────────────────┐
 │           _system_preferences_menu (system_prefs.sh)     │
 ├──────────────────────────────────────────────────────────┤
 │  whiptail --menu "System Preferences"                    │
 │    1  Date, Time & Timezone                              │
 │    2  Language, Locales & Keyboard                       │
 │    3  Audio & Sound Stack                                │
 │    4  Back to main menu                                  │
 └──────────────────────────────────────────────────────────┘
         │              │                  │
         ▼              ▼                  ▼
   _prefs_date_time  _prefs_locale_   _prefs_audio
                     keyboard         → _prefs_audio_menu
         │              │                  │
         │              │          ┌───────┴────────┐
         │              │          │ Dynamic checklist│
         │              │          │ based on         │
         │              │          │ _state + headless│
         │              │          └───────┬────────┘
         │              │                  │
         │              │          pipewire-audio ──→ _install_pipewire_standard
         │              │          alsa-utils     ──→ apt install alsa-utils
         │              │          pavucontrol    ──→ apt install pavucontrol
         │              │          pulsemixer     ──→ apt install pulsemixer
         │              │          playerctl      ──→ apt install playerctl
 ```
 ---
 ## 6. Integration with Other Modules
 - **Firmware (`firmware.sh`)** — Bluetooth firmware packages (`firmware-iwlwifi`, etc.) are separate from the Bluetooth *stack* (`bluez`). This menu complements firmware by ensuring the audio side of Bluetooth (PipeWire codecs) is ready.
 - **Desktop & Display (`desktop_display.sh`)** — XFCE/LXDE installations often need audio configured afterwards. Running System Preferences → Audio after a new desktop ensures the correct mixer is available.
 - **Gaming (`gaming.sh`)** — Many games require PipeWire/PulseAudio for voice chat. The gaming module assumes audio is already functional.
 - **Time sync (`utils.sh:_ensure_time_synced`)** — Also called automatically at script startup. This menu is the manual override.
 ---
 ## 7. Detection & State Variables
 | Variable / Function | Source | Used Here |
 | --------------------- | -------- | ----------- |
 | `DEBIAN_VERSION` (`11`/`12`/`13`) | `utils.sh:detect_debian_version` | PipeWire package name + install path |
 | `AUDIO_SERVER` (`pipewire`/`pulseaudio`/`none`) | `utils.sh:detect_audio_server` | Bluetooth integration in `firmware.sh` |
 | `is_backports_enabled` | `utils.sh:is_backports_enabled` | PipeWire backports version choice (Trixie) |
 | `_is_headless` | `utils.sh:_is_headless` | Hides `pavucontrol` in TTY/SSH |
 | `_state <pkg>` | `utils.sh:_state` | Checklist ON/OFF state |
 | `_ensure_time_synced` | `utils.sh:_ensure_time_synced` | Called after timezone change |
 ---
 ## References
 - [Debian TimeZone Config — wiki.debian.org/TimeZoneChanges](https://wiki.debian.org/TimeZoneChanges)
 - [Debian Locales — wiki.debian.org/Locale](https://wiki.debian.org/Locale)
 - [PipeWire — wiki.debian.org/PipeWire](https://wiki.debian.org/PipeWire)
 - [PipeWire Bluetooth Codecs — GitLab PipeWire wiki](https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/FAQ#bluetooth)
@@ -1,80 +1,95 @@
-## Option 2: User Privileges & Feedback
+# Option 2: User Privileges & Feedback
 ### 1. What does this component do?
 This component serves as a centralized utility suite designed to streamline administrative access, enhance usability during system maintenance, and correct common permission inconsistencies found in fresh Debian installations or environments where `sudo` usage has been mishandled. It acts as an automated "First-Time User" setup tool that bridges the gap between strict Linux security policies (where standard users cannot modify system files) and practical daily workflow needs (such as installing software without constant password prompts).
 At a high level, it manages four critical aspects of user privilege:
-1.  **Elevated Permissions:** Ensures the current user has membership in the `sudo` group.
+
-2.  **Workflow Efficiency:** Configures specific commands to run without authentication (NOPASSWD) for maintenance tasks.
+1. **Elevated Permissions:** Ensures the current user has membership in the `sudo` group.
-3.  **Data Integrity:** Repairs ownership issues on the home directory caused by accidental root-level file creation.
+2. **Workflow Efficiency:** Configures specific commands to run without authentication (NOPASSWD) for maintenance tasks.
-4.  **User Experience:** Modifies terminal behavior during password entry to provide visual feedback.
+3. **Data Integrity:** Repairs ownership issues on the home directory caused by accidental root-level file creation.
 4. **User Experience:** Modifies terminal behavior during password entry to provide visual feedback.
 ### 2. What exactly does it do and why
 The script executes a sub-menu loop that allows the user to toggle between four distinct configurations. Each option addresses a specific pain point in Linux administration:
-*   **Sudo Group Membership (Option 1):**
+* **Sudo Group Membership (Option 1):**
-    *   **Action:** Checks if the current username exists within the `/etc/group` file under the `sudo` group entry. If absent, it adds the user via `usermod -aG sudo`.
+  * **Action:** Checks if the current username exists within the `/etc/group` file under the `sudo` group entry. If absent, it adds the user via `usermod -aG sudo`.
-    *   **Why:** By default, Debian creates a standard user without administrative rights to prevent accidental system damage. This ensures the user can execute privileged commands (`sudo`) immediately after installation or recovery.
+  * **Why:** By default, Debian creates a standard user without administrative rights to prevent accidental system damage. This ensures the user can execute privileged commands (`sudo`) immediately after installation or recovery.
-*   **Passwordless Sudo (Option 2):**
+* **Passwordless Sudo (Option 2):**
-    *   **Action:** Creates an isolated configuration file in `/etc/sudoers.d/` containing `NOPASSWD` rules for specific binaries (e.g., `/usr/bin/apt`, `/sbin/reboot`). It enforces strict path matching to prevent privilege escalation risks.
+  * **Action:** Creates an isolated configuration file in `/etc/sudoers.d/` containing `NOPASSWD` rules for specific binaries (e.g., `/usr/bin/apt`, `/sbin/reboot`). It enforces strict path matching to prevent privilege escalation risks.
-    *   **Why:** Frequent password prompts interrupt workflows during updates or system reboots. This allows automation and quick access for maintenance tasks without compromising security on other commands.
+  * **Why:** Frequent password prompts interrupt workflows during updates or system reboots. This allows automation and quick access for maintenance tasks without compromising security on other commands.
-*   **Repair Home Directory Ownership (Option 3):**
+* **Repair Home Directory Ownership (Option 3):**
-    *   **Action:** Scans the user's home directory (`/home/$USER`) to verify if files are owned by `root` (UID 0) instead of the user. If a mismatch is found, it recursively resets ownership via `chown -R`.
+  * **Action:** Scans the user's home directory (`/home/$USER`) to verify if files are owned by `root` (UID 0) instead of the user. If a mismatch is found, it recursively resets ownership via `chown -R`.
-    *   **Why:** Misconfigured file permissions often occur when users attempt to fix issues using root privileges directly in their home folders. This restores data integrity so applications can read/write their own configuration files without permission errors.
+  * **Why:** Misconfigured file permissions often occur when users attempt to fix issues using root privileges directly in their home folders. This restores data integrity so applications can read/write their own configuration files without permission errors.
-*   **Sudo Password Feedback (Option 4):**
+* **Sudo Password Feedback (Option 4):**
-    *   **Action:** Toggles the `Defaults pwfeedback` directive within a dedicated sudoers file. When enabled, typing a password displays asterisks (`****`) instead of being hidden.
+  * **Action:** Toggles the `Defaults pwfeedback` directive within a dedicated sudoers file. When enabled, typing a password displays asterisks (`****`) instead of being hidden.
-    *   **Why:** Linux terminals hide input by default to prevent shoulder surfing. This option improves usability for users who need visual confirmation that their keystrokes are registering correctly, reducing the risk of typos in complex passwords.
+  * **Why:** Linux terminals hide input by default to prevent shoulder surfing. This option improves usability for users who need visual confirmation that their keystrokes are registering correctly, reducing the risk of typos in complex passwords.
 ### 3. The Logical Decision Tree (Step-by-Step)
 The execution flow is governed by `sudo_config.sh`, which acts as a state machine within the main menu loop. Below is the chronological logic for each option:
 **Entry Point:**
-1.  The script enters the `config_sudo()` function and loops until the user selects "Back to main menu".
+
-2.  It presents a Whiptail menu with options 1–5.
+1. The script enters the `config_sudo()` function and loops until the user selects "Back to main menu".
 2. It presents a Whiptail menu with options 1–5.
 **Option 1: Sudo Group Membership (`_check_sudo_group`)**
-*   **Step A:** Execute `groups "$USER"` via pipe to grep for `\bsudo\b`.
+
-*   **Decision:**
+* **Step A:** Execute `groups "$USER"` via pipe to grep for `\bsudo\b`.
-    *   *If Match:* Display success message ("User is already in sudo group"). Exit function.
+* **Decision:**
-    *   *If No Match:* Prompt user with a confirmation dialog asking if they want to add the user to the `sudo` group.
+  * *If Match:* Display success message ("User is already in sudo group"). Exit function.
-        *   *On Confirm:* Execute `sudo usermod -aG sudo "$USER"`. If successful, display message instructing logout/login for changes to take effect. If failure, log error and return status 1.
+  * *If No Match:* Prompt user with a confirmation dialog asking if they want to add the user to the `sudo` group.
    * *On Confirm:* Execute `sudo usermod -aG sudo "$USER"`. If successful, display message instructing logout/login for changes to take effect. If failure, log error and return status 1.
 **Option 2: Passwordless Sudo (`_configure_nopasswd`)**
-*   **Step A:** Check if `/etc/sudoers.d/${USER}-nopasswd` exists.
+
-    *   *If Exists:* Prompt to remove the configuration (restore password prompts). If confirmed, delete file and notify success. Return function.
+* **Step A:** Check if `/etc/sudoers.d/${USER}-nopasswd` exists.
-    *   *If Not Exists:* Prompt user to configure NOPASSWD for maintenance commands.
+  * *If Exists:* Prompt to remove the configuration (restore password prompts). If confirmed, delete file and notify success. Return function.
-        *   *On Confirm:* Display a checklist menu allowing selection of `apt`, `systemctl`, or `power` commands.
+  * *If Not Exists:* Prompt user to configure NOPASSWD for maintenance commands.
-*   **Step B:** Process selected commands:
+    * *On Confirm:* Display a checklist menu allowing selection of `apt`, `systemctl`, or `power` commands.
-    *   Construct the content string based on selections, explicitly defining paths (e.g., `/usr/bin/apt`, `/sbin/shutdown`) to ensure compatibility across Debian versions.
+* **Step B:** Process selected commands:
-*   **Step C:** Write configuration:
+  * Construct the content string based on selections, explicitly defining paths (e.g., `/usr/bin/apt`, `/sbin/shutdown`) to ensure compatibility across Debian versions.
-    *   Pipe content to `sudo tee /etc/sudoers.d/${USER}-nopasswd`.
+* **Step C:** Write configuration:
-    *   Set file permissions to `0440` (readable only by root and owner).
+  * Pipe content to `sudo tee /etc/sudoers.d/${USER}-nopasswd`.
-    *   Notify success or failure.
+  * Set file permissions to `0440` (readable only by root and owner).
  * Notify success or failure.
 **Option 3: Repair Home Directory Ownership (`_repair_home_ownership`)**
-*   **Step A:** Resolve the absolute path of `$HOME`. If directory does not exist, notify error and return status 1.
+
-*   **Step B:** Retrieve User ID (UID) using `id -u "$USER"`.
+* **Step A:** Resolve the home directory path securely using `getent passwd "${SUDO_USER:-$USER}"` instead of the legacy insecure `eval echo "~$USER"` pattern. This prevents command injection and ensures correct resolution across all shell environments:
-*   **Step C:** Check current owner UID of `$HOME` using `stat -c '%u'`.
+
-    *   *If Match:* Notify that ownership is correct and exit.
+  ```bash
-    *   *If Mismatch:* Identify the expected username for the conflicting UID. Prompt user to confirm repair.
+  home=$(getent passwd "${SUDO_USER:-$USER}" | cut -d: -f6)
-        *   *On Confirm:* Execute `sudo chown -R "$USER:$USER" "$home"`. If successful, notify success. If failure, log error and return status 1.
+  ```
 * **Step B:** Retrieve User ID (UID) using `id -u "$USER"`.
 * **Step C:** Check current owner UID of `$HOME` using `stat -c '%u'`.
  * *If Match:* Notify that ownership is correct and exit.
  * *If Mismatch:* Identify the expected username for the conflicting UID. Prompt user to confirm repair.
    * *On Confirm:* Execute `sudo chown -R "$USER:$USER" "$home"`. If successful, notify success. If failure, log error and return status 1.
 **Option 4: Sudo Password Feedback (`_toggle_pwfeedback`)**
-*   **Step A:** Check if `/etc/sudoers.d/pwfeedback` exists.
+
-    *   *If Exists:* Prompt to disable asterisks (restore hidden input). If confirmed, delete file and notify success. Return function.
+* **Step A:** Check if `/etc/sudoers.d/pwfeedback` exists.
-    *   *If Not Exists:* Prompt user to enable visual feedback.
+  * *If Exists:* Prompt to disable asterisks (restore hidden input). If confirmed, delete file and notify success. Return function.
-        *   *On Confirm:* Write `Defaults pwfeedback` to `/etc/sudoers.d/pwfeedback`.
+  * *If Not Exists:* Prompt user to enable visual feedback.
-*   **Step B:** Verify write permission. If successful, notify success; otherwise, log error and return status 1.
+    * *On Confirm:* Write `Defaults pwfeedback` to `/etc/sudoers.d/pwfeedback`.
 * **Step B:** Verify write permission. If successful, notify success; otherwise, log error and return status 1.
 ### 4. Compatibility with all Debian
 This module is designed for universal compatibility across the Debian family (Bullseye, Bookworm, Trixie, etc.) due to its reliance on standard POSIX-compliant tools and strict path handling.
-*   **Architecture Independence:** The script utilizes `usermod`, `chown`, and `grep` which are available on all x86_64, arm64, and i386 Debian architectures.
+* **Architecture Independence:** The script utilizes `usermod`, `chown`, and `grep` which are available on all x86_64, arm64, and i386 Debian architectures.
-*   **Version Agnosticism (Debian 11+):**
+* **Version Agnosticism (Debian 11+):**
-    *   **Sudoers Syntax:** The script writes to `/etc/sudoers.d/`, a directory introduced in `sudo` version 1.9.0p5 (available since Debian 7). It avoids editing the master file (`/etc/sudoers`) directly, preventing lockfile issues and syntax errors regardless of the specific Debian version's sudo configuration style.
+  * **Sudoers Syntax:** The script writes to `/etc/sudoers.d/`, a directory introduced in `sudo` version 1.9.0p5 (available since Debian 7). It avoids editing the master file (`/etc/sudoers`) directly, preventing lockfile issues and syntax errors regardless of the specific Debian version's sudo configuration style.
-    *   **Path Hardening:** The NOPASSWD logic explicitly includes both `/usr/bin` and `/bin` paths for commands like `apt`. This ensures that on older Debian versions (e.g., Bullseye) where binaries might reside in different locations or symlinks differ, the permissions remain valid.
+  * **Path Hardening:** The NOPASSWD logic explicitly includes both `/usr/bin` and `/bin` paths for commands like `apt`. This ensures that on older Debian versions (e.g., Bullseye) where binaries might reside in different locations or symlinks differ, the permissions remain valid.
-*   **Security Best Practices:** By isolating configurations into separate files (`/etc/sudoers.d/`) and setting restrictive permissions (`0440`), it adheres to Debian's security guidelines for `sudo`. This ensures that even on older systems with stricter default policies, the configuration is accepted without requiring a full system reboot or sudo upgrade.
+* **Security Best Practices:** By isolating configurations into separate files (`/etc/sudoers.d/`) and setting restrictive permissions (`0440`), it adheres to Debian's security guidelines for `sudo`. This ensures that even on older systems with stricter default policies, the configuration is accepted without requiring a full system reboot or sudo upgrade.
-*   **Importance:** Consistent behavior across versions means users can migrate between Debian releases (e.g., from 11 to 12) without needing to manually reconfigure these specific privileges, ensuring a stable and secure environment regardless of the underlying OS version.
+* **Importance:** Consistent behavior across versions means users can migrate between Debian releases (e.g., from 11 to 12) without needing to manually reconfigure these specific privileges, ensuring a stable and secure environment regardless of the underlying OS version.
@@ -1,4 +1,4 @@
-# Option 8: ZRAM Configuration & Memory Optimization
+# Option 9: ZRAM Configuration & Memory Optimization
 ## 1. The Science of ZRAM vs. Traditional Swap
@@ -7,11 +7,11 @@
 Traditional swap storage operates on a fundamental latency gap that becomes critical under memory pressure:
 | Storage Medium | Latency Range | Write Amplification | SSD Wear Impact |
-|---------------|---------------|---------------------|-----------------|
+| --------------- | --------------- | --------------------- | ----------------- |
 | **DRAM (RAM)** | ~10–50 nanoseconds | None | Zero |
-| **NVMe SSD**   | ~20–70 microseconds | 1.2x–3.0x | Moderate to High |
+| **NVMe SSD** | ~20–70 microseconds | 1.2x–3.0x | Moderate to High |
-| **SATA SSD**   | ~100–200 microseconds | 1.5x–4.0x | High |
+| **SATA SSD** | ~100–200 microseconds | 1.5x–4.0x | High |
-| **HDD**        | ~5–10 milliseconds | N/A (mechanical) | Irrelevant |
+| **HDD** | ~5–10 milliseconds | N/A (mechanical) | Irrelevant |
 When a Linux system experiences memory pressure, the kernel must decide what to swap out. Traditional swap writes pages directly to disk storage:
@@ -74,11 +74,13 @@ The script follows a deterministic flow to ensure safe, reproducible configurati
 │                                                             │
 │ 3. Size Calculation Logic                                   │
 │    ┌──────────────────────────────────────────────┐         │
-│    │ ram_gb > 16 ? 25% : 50% of total RAM         │         │
+│    │ ram_gb <= 8 ? 50% : 4096 MB fixed      │         │
-│    │ recommended_mb = ((RAM_KB/1024/1024 + 1)     │          │
+│    │ recommended_mb = (ram_gb <= 8)              │         │
-│    │                / (ram_gb > 16 ? 4 : 2))      │         │
+│    │                ? (RAM_KB/1024/1024 + 1)      │         │
 │    │                  / 2 * 1024                 │         │
 │    │                : 4096                       │         │
 │    └──────────────────────────────────────────────┘         │
-│    └─ Result: ~25% RAM if > 16 GB, else ~50% in MB          │
+│    └─ Result: 50% RAM if ≤8 GB, else fixed 4096 MB      │
 │                                                             │
 │ 4. Configuration Confirmation                               │
 │    ├─ Display summary with algorithm, size, priority=100    │
@@ -100,7 +102,7 @@ The script follows a deterministic flow to ensure safe, reproducible configurati
 │    PRIORITY=100                                             │
 │                                                             │
 │ 8. Service Restart                                          │
-│    sudo systemctl restart zramswap                          │
+│    sudo systemctl restart zramswap || true || true                  │
 │    └─ Verify: comp_algorithm shows [algo]; sudo zramctl     │
 └─────────────────────────────────────────────────────────────┘
 ```
@@ -111,36 +113,43 @@ The script uses this formula to determine ZRAM size:
 ```bash
 ram_gb=$(( RAM_KB / 1024 / 1024 ))
-if [ "$ram_gb" -gt 16 ]; then
+if [ "$ram_gb" -le 8 ]; then
    recommended_mb=$(( ((RAM_KB / 1024 / 1024 + 1) / 4) * 1024 ))
 else
    recommended_mb=$(( ((RAM_KB / 1024 / 1024 + 1) / 2) * 1024 ))
 else
    recommended_mb=4096
 fi
 ```
 **Breakdown:**
 - `RAM_KB`: Total RAM in kilobytes from `/proc/meminfo`
- `/ 1024 / 1024`: Convert KB to MB
+- `/ 1024 / 1024`: Convert KB to GB
 - `+ 1`: Add rounding buffer for odd values
- `/ 4`: Target 25% of total RAM on systems with more than 16 GB (avoids excessive RAM reservation on high-memory machines)
+- **≤8 GB**: Target 50% of total RAM (generous swap for low-memory systems)
- `/ 2`: Target 50% of total RAM on systems with 16 GB or less
+- **>8 GB**: Fixed 4096 MB — avoids excessive RAM reservation on high-memory machines while still providing meaningful swap space
 - `* 1024`: Round back to nearest MB
 **Examples:**
 ```
 System with 32 GB (33554432 KB) RAM (>16 GB):
 recommended_mb = ((33554432 / 1024 / 1024 + 1) / 4) * 1024
              = ((32 + 1) / 4) * 1024
              = (33 / 4) * 1024
              = 8 * 1024
              = 8192 MB (8 GB)
-System with 8 GB (8388608 KB) RAM (<=16 GB):
+```
 System with 4 GB (4194304 KB) RAM (<=8 GB):
 recommended_mb = ((4194304 / 1024 / 1024 + 1) / 2) * 1024
              = ((4 + 1) / 2) * 1024
              = (5 / 2) * 1024
              = 2 * 1024
              = 2048 MB (2 GB)
 System with 8 GB (8388608 KB) RAM (<=8 GB):
 recommended_mb = ((8388608 / 1024 / 1024 + 1) / 2) * 1024
              = ((8 + 1) / 2) * 1024
              = (9 / 2) * 1024
              = 4 * 1024
              = 4096 MB (4 GB)
 System with 16 GB (16777216 KB) RAM (>8 GB):
 recommended_mb = 4096 MB (fixed)
 System with 32 GB (33554432 KB) RAM (>8 GB):
 recommended_mb = 4096 MB (fixed)
 ```
 ### Priority Configuration (`PRIORITY=100`)
@@ -155,39 +164,51 @@ This prevents thrashing where pages bounce between slow disk swap and fast RAM-b
 ---
-## 3. Kernel Parameter Tuning (`sysctl`)
+## 3. Priority & Swappiness Integration
-### Essential VM Parameters for Aggressive ZRAM Usage
+### How ZRAM Coexists with Disk Swap
-While the current script focuses on `zram-tools` configuration, optimal performance requires complementary kernel parameter tuning:
+The script does **not** hardcode `vm.swappiness` or watermark tuning. Instead, it uses a **priority-based swap hierarchy** combined with an explicit swappiness control in the Swap module:
 | Swap Device | Priority | Config Location | When It Is Used |
 |-------------|----------|-----------------|-----------------|
 | **ZRAM** | `100` | `/etc/default/zramswap` (`PRIORITY=100`) | **First** — kernel prefers higher priority |
 | **Disk swapfile** (`/swapfile`) | `10` | `/etc/fstab` (`pri=10`) + `# debianito-managed-swap` tag | **Second** — only after ZRAM device is full |
 This is implemented in `zram.sh:_zram_create` (writes `PRIORITY=100`) and `swap.sh:_swap_create_file` (writes `pri=10`). Priority is the canonical Linux `swapon` mechanism: `swapon --show` lists `PRIO` and the kernel always fills the highest-priority device first.
 ### Swappiness Is Managed Separately
 Swappiness (`vm.swappiness`, 0–100, default 60 on Debian) controls **how eagerly the kernel swaps at all**, regardless of which device is preferred.
 - The ZRAM module **does not change swappiness**. Changing it would affect both ZRAM and disk swap in ways that are workload-specific.
 - To tune it, use **Option 10 → Swap Management → 4. Change swappiness** (`swap.sh:_swap_set_swappiness`):
  ```bash
  cat /proc/sys/vm/swappiness          # current value
  # Persistent config
  /etc/sysctl.d/99-swappiness-debianito.conf  → vm.swappiness=<value>
  # Applied immediately
  sudo sysctl -w vm.swappiness=<value>
  ```
 - Recommended starting points (not enforced by the script):
  - **General desktop**: `60` (Debian default)
  - **Gaming / 8 GB or less**: `80–100` — allows ZRAM to be used earlier, trading CPU for reduced disk I/O
  - **ZRAM-only, no disk swap**: `100–150` is safe because swap *is* RAM (compressed); there is no SSD wear cost
 > **Previous documentation** recommended `vm.swappiness = 180` plus `watermark_*` and `page-cluster` tuning for ZRAM. Those values are **not written by the current script** and are omitted here to avoid drifting from the implemented behavior. If you need watermark tuning, add it manually to `/etc/sysctl.d/` and validate with your workload.
 ### Verifying the Hierarchy
 ```bash
-# Recommended sysctl configuration for ZRAM systems
+sudo swapon --show
-vm.swappiness = 180
+# NAME       TYPE      SIZE USED PRIO
-vm.watermark_boost_factor = 0
+# /dev/zram0 partition   4G   0B  100
-vm.watermark_scale_factor = 125
+# /swapfile  file        4G   0B   10
-vm.page-cluster = 0
+cat /proc/sys/vm/swappiness
 ```
 ### Parameter Explanations
 | Parameter | Value | Purpose |
 |-----------|-------|---------|
 | **`vm.swappiness`** | `180–200` | Aggressively prefer swap over keeping pages in RAM. Higher values (up to 200) are ideal for ZRAM because it's faster than disk swap. Default 60 is too conservative for memory-constrained systems. |
 | **`vm.watermark_boost_factor`** | `0` | Disable additional watermark boosting that could cause premature page reclaim |
 | **`vm.watermark_scale_factor`** | `125` | Adjust low-memory watermark thresholds to trigger swap earlier when RAM is constrained |
 | **`vm.page-cluster`** | `0` | Disable page clustering. Research shows this reduces unnecessary sequential reads during swap operations, improving ZRAM efficiency by ~15% in gaming workloads |
 ### Why High Swappiness for ZRAM?
 Traditional wisdom suggests keeping swappiness low (20–40) to avoid swapping frequently. However:
 - **ZRAM is faster than disk**: Microseconds vs milliseconds
 - **Thrashing prevention**: Higher swappiness moves pages to ZRAM before they hit slow disk swap
 - **Effective RAM expansion**: Compressed pages in ZRAM can store 2–3x more data, effectively increasing available memory
 The Pop!_OS project and Linux kernel documentation both recommend values beyond 100 for in-memory swap scenarios like ZRAM/ZSWAP.
 ---
 ## 4. Service Lifecycle and Validation
@@ -195,10 +216,11 @@ The Pop!_OS project and Linux kernel documentation both recommend values beyond
 ### Safe Service Initialization
 ```bash
-sudo systemctl restart zramswap
+sudo systemctl restart zramswap || true
 ```
 **Why `restart` instead of `start`:**
 - Ensures previous configuration is cleanly terminated
 - Prevents orphaned processes from conflicting with new settings
 - Reloads systemd unit files if they were modified during installation
@@ -212,13 +234,14 @@ sudo zramctl
 ```
 **Output Interpretation:**
 ```
 NAME       ALGORITHM DISKSIZE  DATA   COMPR    TOTAL STREAMS MOUNTPOINT
 /dev/zram0 lz4           4G     2.1G 318.6M 424.9M        [SWAP]
 ```
 | Column | Meaning |
-|--------|---------|
+| -------- | --------- |
 | **NAME** | Device identifier (/dev/zram0) |
 | **ALGORITHM** | Active compression algorithm (lz4, zstd, etc.) |
 | **DISKSIZE** | Maximum uncompressed data capacity configured |
@@ -250,7 +273,7 @@ watch -n 5 'free -h && zramctl'
 ### Troubleshooting Indicators
 | Symptom | Likely Cause | Solution |
-|---------|--------------|----------|
+| --------- | -------------- | ---------- |
 | `DATA` equals `DISKSIZE` but `COMPR` is near zero | System under memory pressure, ZRAM not being used | Increase `vm.swappiness` or check if physical swap has lower priority |
 | High CPU usage with low compression ratio | Incompressible data (e.g., encrypted files) | Consider backing device for incompressible pages |
 | Service fails to start | Missing dependencies (`zram-tools`, kernel module) | Run `sudo apt install zram-tools` and verify `modprobe zram` |
@@ -263,8 +286,7 @@ To ensure ZRAM persists across reboots, the script writes configuration to `/etc
 echo "zram" | sudo tee /etc/modules-load.d/zram.conf
 ```
-
+### References
 ### References:
 - [https://docs.kernel.org/admin-guide/blockdev/zram.html](https://docs.kernel.org/admin-guide/blockdev/zram.html)
 - [https://wiki.debian.org/ZRam](https://wiki.debian.org/ZRam)