scripts: add unnecessary descriptions

config/ghostty/.config/.alt/ghostty-niri/ghostty-default

@@ -1 +0,0 @@
-.alt/ghostty-default

config/ghostty/.config/.alt/ghostty-niri/ghostty-niri

@@ -1 +0,0 @@
-.alt/ghostty-niri

config/kitty/.config/.alt/kitty-niri/kitty-default

@@ -1 +0,0 @@
-.alt/kitty-default

config/kitty/.config/.alt/kitty-niri/kitty-niri

@@ -1 +0,0 @@
-.alt/kitty-niri

config/scripts/.local/scripts/change-colortheme

@@ -1,5 +1,12 @@
 #!/usr/bin/env python3
 
+# Description:
+#   Change color theme for various applications based on an image, color, or user selection.
+#   This is done by running application-specific scripts located in the config directory.
+#
+# Requirements:
+#   - colorthief (python3 package) # too lazy to implement color extraction myself :D
+
 import os
 import sys
 from pathlib import Path

config/scripts/.local/scripts/change-wallpaper

@@ -1,6 +1,9 @@
 #!/usr/bin/env bash
 
-# Required tools:
+# Description:
+#   Change the desktop wallpaper and generate a blurred version.
+#
+# Requirs:
 # - zenity (for file selection dialog)
 # - imagemagick (for image processing)
 # - swww (wallpaper daemon)

config/scripts/.local/scripts/config-switch

@@ -1,5 +1,8 @@
 #!/usr/bin/env bash
 
+# Description:
+#   Updates configurations of several apps according to the current (or given as parameter) desktop environment.
+
 if [ -z "$1" ]; then
     desktop="$XDG_CURRENT_DESKTOP"
 else

config/scripts/.local/scripts/fetch-weather

@@ -1,5 +1,14 @@
 #!/usr/bin/env bash
 
+# Description:
+#   Fetch and cache current weather data using OpenWeather API for use in eww widgets.
+#
+# Requirements:
+# - Environment variables:
+#   - OPENWEATHER_API_KEY
+#   - OPENWEATHER_LAT
+#   - OPENWEATHER_LON
+
 ## Collect data
 cache_dir="$HOME/.cache/eww/weather"
 cache_weather_stat=${cache_dir}/weather-stat

config/scripts/.local/scripts/hypr-sdrbrightness

@@ -1,8 +1,8 @@
 #!/usr/bin/env python3
 
-# new_brightness="$1"
-# [ -z "$1" ] && new_brightness=1
-# sed -i "/sdrbrightness/c\    sdrbrightness = $new_brightness" <filename>
+# Description:
+#   Adjust the SDR brightness setting in Hyprland's monitor configuration file.
+#   Useful for adjusting brightness when HDR is enabled.
 
 import sys
 import os

config/scripts/.local/scripts/issu

@@ -1,5 +1,9 @@
 #!/bin/sh
 
+# Description:
+#   Detect if the current user is a root or sudo user. Exits with code 0 if true, 1 otherwise.
+#   This script is required by some other scripts such as `smb-mount` and `wsl-mount`.
+
 if [ "$(id -u)" -eq 0 ]; then
     exit 0
 fi

config/scripts/.local/scripts/lyrics-widgets

@@ -1,5 +1,14 @@
 #!/bin/sh
 
+# Description:
+#   Toggle the visibility of lyrics widgets in eww.
+#   - Ensure only one of the two widgets (lyrics or lyrics-single) is open at a time.
+#   - Cycle through the following states:
+#     1. Both widgets closed -> Open 'lyrics'
+#     2. 'lyrics' open -> Close 'lyrics' and open 'lyrics-single' (if waybar is running)
+#     3. 'lyrics-single' open -> Close 'lyrics-single'
+#     4. Both widgets open -> Close both
+
 LYRICS=$(eww active-windows | grep "lyrics:")
 LYRICS_SINGLE=$(eww active-windows | grep "lyrics-single:")
 

config/scripts/.local/scripts/mpv-hdr

@@ -1,5 +1,8 @@
 #!/bin/sh
 
+# Description:
+#   Launch mpv with HDR support enabled
+
 export ENABLE_HDR_WSI=1
 
 mpv --vo=gpu-next --target-colorspace-hint --gpu-api=vulkan --gpu-context=waylandvk "$@"

config/scripts/.local/scripts/mpv-sm

@@ -1,5 +1,8 @@
 #!/bin/sh
 
+# Description:
+#   Launch mpv with smooth motion interpolation enabled
+
 export NVPRESENT_ENABLE_SMOOTH_MOTION=1
 
 mpv --vo=gpu-next --gpu-api=vulkan --gpu-context=waylandvk --video-sync=audio "$@"

config/scripts/.local/scripts/pacman-reflector

@@ -1,5 +1,8 @@
 #!/usr/bin/env bash
 
+# Description:
+#   Quick snippet of reflector.
+
 [ -z "$COUNTRY" ] && COUNTRY="Germany"
 
 sudo cp -f /etc/pacman.d/mirrorlist /etc/pacman.d/mirrorlist.bak || exit 1

config/scripts/.local/scripts/record-script

@@ -1,5 +1,13 @@
 #!/usr/bin/env bash
-# https://github.com/end-4/dots-hyprland/blob/main/.config/ags/scripts/record-script.sh
+
+# Description:
+#   Script to record screen.
+#   Inspired by https://github.com/end-4/dots-hyprland
+#
+# Requirements:
+# - wf-recorder
+# - slurp
+
 
 [ -z "$codec" ] && codec="av1_nvenc"
 [ -z "$pixel_format" ] && pixel_format="p010le"

config/scripts/.local/scripts/rofi-cliphist

@@ -1,5 +1,7 @@
 #!/bin/sh
 
+# Description:
+#   Quick snippet for cliphist + rofi + wl-copy
 
 cliphist list | rofi -dmenu -config ~/.config/rofi/dmenu.rasi -display-columns 2 -i | \
     cliphist decode | wl-copy

config/scripts/.local/scripts/rofi-emoji

@@ -1,5 +1,8 @@
 #!/bin/bash
-# https://github.com/end-4/dots-hyprland/blob/main/.local/bin/fuzzel-emoji
+
+# Description:
+#   Quick snippet for rofi + emoji + wl-copy
+#   Source: https://github.com/end-4/dots-hyprland
 
 sed '1,/^### DATA ###$/d' $0 | rofi -dmenu -config ~/.config/rofi/dmenu.rasi -i | cut -d ' ' -f 1 | tr -d '\n' | wl-copy
 exit

config/scripts/.local/scripts/screenshot-script

@@ -1,5 +1,15 @@
 #!/usr/bin/env python3
 
+# Description:
+#   A screenshot utility script for Hyprland and Niri desktop environments.
+#   Takes screenshots (full, area, window) and provides an option to edit them immediately
+#
+# Requirements:
+# - hyprshot (for Hyprland)
+# - - (niri has screenshot functionality built-in)
+# - gradia (for editing)
+# - glib bindings for python
+
 import argparse
 import subprocess
 import time

config/scripts/.local/scripts/smb-mount

@@ -1,5 +1,12 @@
 #!/bin/sh
 
+# Description:
+#   Quick snippet for smb mounting via cifs
+#
+# Requirements:
+# - cifs-utils
+# - ./issu
+
 issu && {
     echo "Do not run this script in sudo mode."
     exit 1

config/scripts/.local/scripts/smb-unmount

@@ -1,5 +1,8 @@
 #!/bin/bash
 
+# Description:
+#   Quick snippet for smb unmounting
+
 [ -z "$SMB_MOUNT_POINT" ] && SMB_MOUNT_POINT="/mnt/smb"
 
 if sudo umount "$SMB_MOUNT_POINT" && sudo rmdir "$SMB_MOUNT_POINT"; then

config/scripts/.local/scripts/ssh-init

@@ -1,9 +1,13 @@
 #!/bin/sh
 # shellcheck disable=SC1091,SC1090
 
-# `eval "$(ssh-init)"` to set up environment
-# variables for ssh agent in the current shell.
-# TIPS: `bass "$(ssh-init)"` case in fish
+# Description:
+#   Initialize ssh-agent and set up environment variables for use in the current shell.
+#
+# Usage:
+#   `eval "$(ssh-init)"` to set up environment
+#   variables for ssh agent in the current shell.
+#   TIPS: `bass "$(ssh-init)"` case in fish
 
 mkdir -p "$HOME/.local/state"
 agent_file="$HOME/.local/state/ssh-agent"

config/scripts/.local/scripts/wallpaper-daemon

@@ -1,5 +1,14 @@
 #!/usr/bin/env python3
 
+# Description:
+#   A wallpaper daemon script that integrates with swww and Niri/Hyprland to
+#   automatically switch between normal and blurred wallpapers based on window focus.
+#
+# Requirements:
+# - swww (or awww case you are from the future)
+# - niri/hyprland (obviously)
+# - watchdog (python3 package)
+
 import socket
 import json
 import subprocess

config/scripts/.local/scripts/waybar-toggle

@@ -1,5 +1,13 @@
 #!/usr/bin/env bash
 
+# Description:
+#   Script to toggle Waybar (start/stop/restart).
+#   Also manages the lyrics widget state.
+#
+# Requirements:
+# - waybar
+# - eww (for lyrics widget)
+
 lyrics_widget_closed=0
 
 function close() {

config/scripts/.local/scripts/waydroid-reload

@@ -1,15 +1,16 @@
 #!/usr/bin/env bash
 
-function checkReturn {
-    echo "Executing: $*"
-    if ! "$@"; then
-        echo "Error runnning command"
-        exit 1
-    fi
-}
+# Description:
+#   Quick snippet to reload and restart Waydroid.
+#
+# Requirements:
+# - waydroid
+# - sudo privileges
 
-checkReturn waydroid session stop
-# checkReturn sudo waydroid upgrade # since I'm not using the default image
-checkReturn sudo waydroid init -f
-checkReturn sudo systemctl restart waydroid-container
-checkReturn waydroid show-full-ui
+set -e
+
+waydroid session stop
+# sudo waydroid upgrade # since I'm not using the default image
+sudo waydroid init -f
+sudo systemctl restart waydroid-container
+waydroid show-full-ui

config/scripts/.local/scripts/workspace-new

@@ -1,5 +1,12 @@
 #!/usr/bin/env bash
 
+# Description:
+#   Create and switch to a new workspace in Hyprland.
+#   e.g. if current workspaces are 1,2,4, this will create and switch to workspace 5.
+#
+# Requirements:
+# - hyprctl
+
 # get highest workspace ID
 max_id=$(hyprctl workspaces | grep '^workspace ID ' | awk '{print $3}' | sort -n | tail -1)
 

config/scripts/.local/scripts/wp-vol

@@ -1,5 +1,13 @@
 #!/bin/sh
 
+# Description:
+#   Show current volume level with notification.
+#   Made for mako, and is one of mako's official examples.
+#
+# Requirements:
+# - wpctl
+# - notify-send
+
 # Get the volume level and convert it to a percentage
 volume=$(wpctl get-volume @DEFAULT_AUDIO_SINK@)
 volume=$(echo "$volume" | awk '{print $2}')

config/scripts/.local/scripts/wsl-mount

@@ -1,5 +1,17 @@
 #!/bin/sh
 
+# Description:
+#   Mount a WSL VHDX file to a specified mount point using guestmount.
+#
+# Requirements:
+# - libguestfs-tools
+# - sudo privileges
+#
+# Memo:
+# - set `LIBGUESTFS_DEBUG=1 LIBGUESTFS_TRACE=1` to show details when guestmount fails.
+# - A common issue is that the VHDX file has logs that needs to be "replayed".
+#   This can be done using `qemu-img check -r all <VHDX_PATH>`
+
 issu && {
     echo "Do not run this script in sudo mode."
     exit 1

config/scripts/.local/scripts/wsl-unmount

@@ -1,5 +1,8 @@
 #!/bin/sh
 
+# Description:
+#   Quick snippet for unmounting WSL filesystems and removing the mount point.
+
 [ -z "$1" ] && mount_point="/mnt/wsl" || mount_point="$1"
 
 sudo umount "$mount_point" || {

config/scripts/.local/scripts/xdph-nuclear

@@ -1,4 +1,9 @@
 #!/usr/bin/env bash
+
+# Description:
+#   Restart xdg-desktop-portal and xdg-desktop-portal-hyprland to fix screen sharing issues.
+#   From hyprland documentation.
+
 sleep 1
 killall -e xdg-desktop-portal-hyprland
 killall -e xdg-desktop-portal-wlr

config/scripts/.local/snippets/apply-color-helper

@@ -1,3 +1,9 @@
+# Description:
+#   Helper script to apply color schemes.
+#   - Parse and validate parameters.
+#   - Provide useful aliases and functions.
+#   Should be sourced, not executed directly.
+
 [ "$(basename "$0")" = "apply-color-helper" ] && {
      echo "This script is meant to be sourced, not executed directly."
      exit 1
@@ -10,6 +16,17 @@ colorName="$2"
 [ -z "$3" ] && exit 1
 colorHex="$3"
 
+# remove leading '#' if present
+if [[ $colorHex == \#* ]]; then
+    colorHex="${colorHex#\#}"
+fi
+
+# check if hex
+if ! [[ $colorHex =~ ^[0-9A-Fa-f]{6}$ ]]; then
+    log_error "Invalid color hex: $colorHex"
+    exit 1
+fi
+
 function log_error {
     printf "\033[0;31mError:\033[0m $1\n" >&2
 }
@@ -29,18 +46,6 @@ function color_ansi {
     printf "\033[38;2;%d;%d;%dm" $r $g $b
 }
 
-
-# remove leading '#' if present
-if [[ $colorHex == \#* ]]; then
-    colorHex="${colorHex#\#}"
-fi
-
-# check if hex
-if ! [[ $colorHex =~ ^[0-9A-Fa-f]{6}$ ]]; then
-    log_error "Invalid color hex: $colorHex"
-    exit 1
-fi
-
 function log_success {
     log_info "Applied palette \033[1;34m${palette}\033[0m with primary color $(color_ansi $colorHex)${colorName} (#${colorHex})\033[0m to \033[1;34m$1\033[0m"
 }

config/scripts/.local/snippets/set_display

@@ -1,5 +1,8 @@
 #!/usr/bin/env bash
 
+# Description:
+#   Select which GPU to use for rendering for Hyprland and Niri.
+
 # AMD -> Nvidia -> Intel
 prefer_order=(amd nvidia intel)
 

config/wlogout/.config/.alt/wlogout-niri/wlogout-default

@@ -1 +0,0 @@
-.alt/wlogout-default

config/wlogout/.config/.alt/wlogout-niri/wlogout-niri

@@ -1 +0,0 @@
-.alt/wlogout-niri