refactor(functions): standardize documentation, metadata, and wrappers

- Add comprehensive `--description` flags to all fish functions for better `help` and `functions` output.
- Introduce and correct `--wraps` flags to ensure proper completions for aliased commands (e.g., `top` wrapping `btop`, `zellij`, `upgrade` wrapping `paru`).
- Prepend descriptive comments before function definitions for better source readability.
- Add standard copyright and SPDX license identifiers to shell scripts.
- Enhance script robustness by ensuring consistent terminal checks (Kitty, WezTerm) and graceful fallbacks in window/tab spawning functions (`spwin`, `tab`).
- Implement graceful fallbacks to basic core utilities when preferred modern alternatives are missing (e.g., `top` falling back to system `top` if `btop` is missing, `view` falling back to `less` or `cat` if `nvim` is unavailable).
- Improve overall code consistency across the `functions/` directory.

functions/__insert_previous_path_head.fish

@@ -1,3 +1,7 @@
+# Copyright (C) 2026 Rootiest
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+# Inserts the directory path (dirname) of the last argument from the previous command
 function __insert_previous_path_head
     # Get the last command tokens
     set -l tokens (string split -n " " -- $history[1])

functions/__interactive_history_sub.fish

@@ -1,3 +1,7 @@
+# Copyright (C) 2026 Rootiest
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+# Provides interactive history substitution using old/new pattern or sudo fallback
 function __interactive_history_sub
     set -l current_line (commandline -b)
     set -l last_cmd $history[1]

functions/__substitute_typo.fish

@@ -1,3 +1,7 @@
+# Copyright (C) 2026 Rootiest
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+# Substitutes text in the command line using the ^old^new pattern from the previous command
 function __substitute_typo
     set -l cursor_pos (commandline -C)
     set -l cmd (commandline)

functions/_replace_command_token.fish

@@ -1,3 +1,7 @@
+# Copyright (C) 2026 Rootiest
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+# Removes the first token from the command line and places the cursor at the start
 function _replace_command_token --description 'Remove first token from commandline and place cursor at start'
     set -l cmd (commandline)
     set -l rest (string replace -r '^\S+' '' -- $cmd)

functions/antigravity.fish

@@ -1,7 +1,8 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-function antigravity
+# alias antigravity=antigravity
+function antigravity --wraps='antigravity' --description 'alias antigravity=antigravity'
     # In fish, we pipe stderr using '2>|' to another command
     command antigravity $argv 2>| grep -v "'app' is not in the list of known options" >&2
 end

functions/bash.fish

@@ -1,7 +1,8 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-function bash --wraps=bash --description 'bash switches to bash shell'
+# bash switches to bash shell
+function bash --wraps='bash' --description 'bash switches to bash shell'
     set SHELL $(which bash) # Set shell to bash
     command bash $argv # run bash
     set SHELL $(which fish) # Reset shell

functions/bd-pull.fish

@@ -1,12 +1,13 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-function bd-pull -d "Pull new Gitea issues into local Beads and link them"
+# Pull new Gitea issues into local Beads and link them
+function bd-pull --description 'Pull new Gitea issues into local Beads and link them'
     if not set -q argv[1]; echo "Need repo owner/name"; return 1; end
     if not set -q GITEA_TOKEN; echo "\$GITEA_TOKEN not set"; return 1; end
 
     set -l REPO $argv[1]
-    set -l GITEA_URL "https://git.rootiest.dev"
+    if not set -q GITEA_URL; echo "\$GITEA_URL not set"; return 1; end
     set -l IMPORT_COUNT 0
 
     echo (set_color blue)"📡 Checking Gitea: $REPO..."(set_color normal)

functions/bkg.fish

@@ -12,7 +12,8 @@
 #   bkg firefox
 #   bkg code .
 #
-function bkg
+# Execute bkg
+function bkg --description 'Execute bkg'
     # Check if a command was provided as an argument.
     if test -z "$argv[1]"
         echo "Usage: bkg <command> [arguments...]"

functions/branch.fish

@@ -1,3 +1,4 @@
+# Switch to or create a git branch
 function branch --description 'Switch to or create a git branch'
     if not git rev-parse --is-inside-work-tree >/dev/null 2>&1
         echo "Not a git repo."

functions/cat.fish

@@ -1,6 +1,11 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-function cat --wraps=bat --description 'alias cat=bat'
+# alias cat=bat
-    bat --plain --no-pager $argv
+function cat --wraps='bat' --description 'alias cat=bat'
+    if type -q bat
+        bat --plain --no-pager $argv
+    else
+        command cat $argv
+    end
 end

functions/cb.fish

@@ -1,6 +1,7 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
+# Copy to clipboard
 function cb --description 'Copy to clipboard'
     if type -q wl-copy
         if set -q argv[1]

functions/cffetch.fish

@@ -1,7 +1,8 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-function cffetch --wraps='clear;fastfetch' --description 'alias cffetch=clear;fastfetch'
+# alias cffetch=clear;fastfetch
+function cffetch --description 'alias cffetch=clear;fastfetch'
     clear
     if which fastfetch >/dev/null 2>&1
         if ls ~/.fastfetch.jsonc >/dev/null 2>&1

functions/cheat.fish

@@ -1,7 +1,14 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-function cheat --description 'alias cheat=cheat -c'
+# alias cheat=cheat -c
- command cheat -c $argv
+function cheat --wraps='cheat' --description 'alias cheat=cheat -c'
+    if type -q cheat
+        command cheat -c $argv
+    else if type -q tldr
+        tldr $argv
+    else
+        man $argv
+    end
         
 end

functions/check_fish_deps.fish

@@ -1,7 +1,8 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-function check_fish_deps --description "Check all fish-related dependencies"
+# Check all fish-related dependencies
+function check_fish_deps --description 'Check all fish-related dependencies'
     set -l required fish fisher starship fzf zoxide direnv paru
     set -l integrations wakatime tailscale
     set -l recommended eza lsd bat btop dust duf prettyping most rg lazygit lazydocker trash kitty wezterm

functions/claude-resume.fish

@@ -1,7 +1,17 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-function claude-resume
+# Execute claude-resume
+function claude-resume --description 'Execute claude-resume'
+    if not type -q claude
+        echo "Error: The 'claude' command is not installed or not in PATH." >&2
+        return 1
+    end
+    if not type -q save_claude_session
+        echo "Error: The companion function 'save_claude_session' is missing." >&2
+        return 1
+    end
+
     if test -f .claude_session
         set -l sid (cat .claude_session)
         claude --resume $sid

functions/cleanup.fish

@@ -1,7 +1,8 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-function cleanup -d "Log orphans to ~/.removed_orphans and remove them"
+# Log orphans to ~/.removed_orphans and remove them
+function cleanup --description 'Log orphans to ~/.removed_orphans and remove them'
     set -l orphans (pacman -Qtdq)
     if test -n "$orphans"
         echo "📝 Logging orphans to ~/.removed_orphans..."

functions/clone.fish

@@ -1,7 +1,8 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-function clone --wraps=clone-in-kitty --description 'alias clone=clone-in-kitty'
+# alias clone=clone-in-kitty
+function clone --wraps='clone-in-kitty' --description 'alias clone=clone-in-kitty'
     if test "$TERM" != xterm-kitty
         echo "Error: The 'clone' command requires Kitty terminal." >&2
         return 1

functions/clonet.fish

@@ -1,6 +1,7 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
+# alias clonet=clone-in-kitty --type=tab
 function clonet --wraps='clone-in-kitty --type=tab' --description 'alias clonet=clone-in-kitty --type=tab'
     if test "$TERM" != xterm-kitty
         echo "Error: The 'clonet' command requires Kitty terminal." >&2

functions/code-resume.fish

@@ -1,7 +1,8 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-function code-resume
+# Execute code-resume
+function code-resume --description 'Execute code-resume'
     if test -f .claude_session
         set -l sid (cat .claude_session)
         echo "Resuming Claude session: $sid"

functions/detach.fish

@@ -1,7 +1,8 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-function detach
+# Execute detach
+function detach --description 'Execute detach'
     set -l show_help 0
     set -l args
 

functions/dng2avif.fish

@@ -1,6 +1,7 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
+# Convert DNG raw to 10-bit HDR AVIF
 function dng2avif --description 'Convert DNG raw to 10-bit HDR AVIF'
     set -l options (fish_opt -s h -l help)
     set -a options (fish_opt -s i -l input -r)

functions/dockup.fish

@@ -1,6 +1,7 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
+# Pull and restart docker compose containers
 function dockup --description 'Pull and restart docker compose containers'
     # Define colors
     set -l clr_error (set_color red)

functions/dops.fish

@@ -1,7 +1,8 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-function docker
+# Execute docker
+function docker --description 'Execute docker'
     if test -n "$argv[1]"
         switch $argv[1]
             case ps

functions/du.fish

@@ -1,7 +1,8 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-function du
+# Execute du
+function du --description 'Execute du'
     set cmd ""
     set args
 

functions/dusize.fish

@@ -1,6 +1,7 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-function dusize
+# alias dusize=du
+function dusize --wraps='du' --description 'alias dusize=du'
     du -sh (test -n "$argv[1]"; and echo $argv[1]; or echo .)
 end

functions/edit.fish

@@ -1,6 +1,15 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-function edit --wraps=nvim --description 'alias edit=nvim'
+# alias edit=nvim
-    nvim $argv
+function edit --wraps='nvim' --description 'alias edit=nvim'
+    if type -q nvim
+        nvim $argv
+    else if set -q EDITOR
+        $EDITOR $argv
+    else if type -q nano
+        nano $argv
+    else
+        vi $argv
+    end
 end

functions/expand_bang_all.fish

@@ -1,4 +1,5 @@
-function expand_bang_all
+# Execute expand_bang_all
+function expand_bang_all --description 'Execute expand_bang_all'
     set -l token $argv[1]
     if test -z "$token"; set token (commandline -t); end
     

functions/expand_bang_caret.fish

@@ -1,4 +1,5 @@
-function expand_bang_caret
+# Execute expand_bang_caret
+function expand_bang_caret --description 'Execute expand_bang_caret'
     # Split the last history item into a list
     set -l tokens (string split -n ' ' -- $history[1])
     # tokens[1] is the command, tokens[2] is the first argument

functions/expand_bang_minus_n.fish

@@ -1,4 +1,5 @@
-function expand_bang_minus_n
+# Execute expand_bang_minus_n
+function expand_bang_minus_n --description 'Execute expand_bang_minus_n'
     set -l token $argv[1]
     if test -z "$token"; set token (commandline -t); end
     

functions/expand_bang_search.fish

@@ -1,4 +1,5 @@
-function expand_bang_search
+# Execute expand_bang_search
+function expand_bang_search --description 'Execute expand_bang_search'
     set -l token $argv[1]
     if test -z "$token"
         set token (commandline -t)

functions/expand_bang_string.fish

@@ -1,4 +1,5 @@
-function expand_bang_string
+# Execute expand_bang_string
+function expand_bang_string --description 'Execute expand_bang_string'
     # Fish 4.x passes the matched token as argv[1]
     set -l token $argv[1]
     if test -z "$token"

functions/expand_typo_sub.fish

@@ -1,4 +1,5 @@
-function expand_typo_sub
+# Execute expand_typo_sub
+function expand_typo_sub --description 'Execute expand_typo_sub'
     # In newer Fish, the matched token is often passed as $argv[1] 
     # if the abbr is set up correctly. We'll fallback to commandline just in case.
         set -l last_cmd $history[1]

functions/fc.fish

@@ -1,4 +1,5 @@
-function fc --description "Edit and execute the last command (Bash-style fc)"
+# Edit and execute the last command (Bash-style fc)
+function fc --description 'Edit and execute the last command (Bash-style fc)'
     set -l tmpfile (mktemp /tmp/fish_fc.XXXXXX).fish
 
     if count $argv >/dev/null

functions/ffetch.fish

@@ -1,6 +1,7 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
+# alias ffetch=fastfetch
 function ffetch --wraps='fastfetch' --description 'alias ffetch=fastfetch'
     if which fastfetch >/dev/null 2>&1
         if ls ~/.fastfetch.jsonc >/dev/null 2>&1

functions/fish_right_prompt.fish

@@ -1,7 +1,8 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-function fish_right_prompt
+# Execute fish_right_prompt
+function fish_right_prompt --description 'Execute fish_right_prompt'
     # 1. Docker Context in Blue
     set -l docker_ctx (docker context show 2>/dev/null)
     if test -n "$docker_ctx"; and test "$docker_ctx" != default

functions/gemini-resume.fish

@@ -1,7 +1,17 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-function gemini-resume
+# Execute gemini-resume
+function gemini-resume --description 'Execute gemini-resume'
+    if not type -q gemini-cli
+        echo "Error: The 'gemini-cli' command is not installed or not in PATH." >&2
+        return 1
+    end
+    if not type -q save_gemini_session
+        echo "Error: The companion function 'save_gemini_session' is missing." >&2
+        return 1
+    end
+
     if test -f .gemini_session
         set -l sid (cat .gemini_session)
         # Use --resume (or -r) to jump back in

functions/gi.fish

@@ -1,4 +1,5 @@
-function gi --description "Generate .gitignore files using the gitignore.io API"
+# Generate .gitignore files using the gitignore.io API
+function gi --description 'Generate .gitignore files using the gitignore.io API'
     # Define the flags
     argparse h/help d/description l/list -- $argv
     or return 1

functions/gip.fish

@@ -1,7 +1,8 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-function gip -d "Show all public IP addresses"
+# Show all public IP addresses
+function gip --description 'Show all public IP addresses'
     echo -n "IPv4: "
     curl -4 -s --max-time 2 https://icanhazip.com || echo "Not detected"
     echo -n "IPv6: "

functions/gip4.fish

@@ -1,6 +1,7 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-function gip4 -d "Get public IPv4 address"
+# Get public IPv4 address
+function gip4 --wraps='curl' --description 'Get public IPv4 address'
     curl -4 -s https://icanhazip.com
 end

functions/gip6.fish

@@ -1,7 +1,8 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-function gip6 -d "Get public IPv6 address"
+# Get public IPv6 address
+function gip6 --description 'Get public IPv6 address'
     # Use -6 to force IPv6 and --fail to catch network errors
     set -l ip (curl -6 -s --fail https://icanhazip.com 2>/dev/null)
     

functions/git-clean.fish

@@ -1,6 +1,7 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
+# Sync main, prune remotes, and delete orphaned branches
 function git-clean --description 'Sync main, prune remotes, and delete orphaned branches'
     set -l options h/help f/force
     argparse $options -- $argv

functions/gitui.fish

@@ -1,7 +1,8 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-function gitui --description 'alias gitui=gitui -t mocha.ron'
+# alias gitui=gitui -t mocha.ron
+function gitui --wraps='gitui' --description 'alias gitui=gitui -t mocha.ron'
     command gitui -t frappe.ron $argv
 
 end

functions/gitup.fish

@@ -1,3 +1,4 @@
+# Fetch updates and show git status
 function gitup --description 'Fetch updates and show git status'
     # Check if we are even in a git repository
     if not git rev-parse --is-inside-work-tree >/dev/null 2>&1

functions/hist.fish

@@ -1,7 +1,8 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-function hist -d "Search fish history and put it in the prompt"
+# Search fish history and put it in the prompt
+function hist --description 'Search fish history and put it in the prompt'
     set -l selected (history | fzf --reverse --height 40% --with-nth 3..)
 
     if test -n "$selected"

functions/lD.fish

@@ -1,6 +1,7 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
+# List directories only
 function lD --description 'List directories only'
     if which eza >/dev/null 2>&1
         eza --only-dirs --long --icons --color=auto --hyperlink $argv

functions/less.fish

@@ -1,7 +1,8 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-function less --wraps=most --description 'alias less=most'
+# alias less=most
+function less --wraps='most' --description 'alias less=most'
     if which most >/dev/null 2>&1
         most $argv
     else

functions/limine-edit.fish

@@ -1,6 +1,7 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
+# Safely edit and re-verify Limine configuration
 function limine-edit --description 'Safely edit and re-verify Limine configuration'
     # 1. Open the config with sudoedit
     sudoedit /boot/limine.conf

functions/lock.fish

@@ -1,6 +1,7 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-function lock
+# alias lock=loginctl
+function lock --wraps='loginctl' --description 'alias lock=loginctl'
     loginctl lock-session
 end

functions/ls.fish

@@ -1,6 +1,7 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
+# List all files
 function ls --description 'List all files'
     if which eza >/dev/null 2>&1
         eza -l -a --icons --color=auto --hyperlink $argv

functions/lsr.fish

@@ -1,6 +1,7 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
+# Reversed time-sorted listing
 function lsr --description 'Reversed time-sorted listing'
     if which eza >/dev/null 2>&1
         eza --oneline --sort=modified --reverse --icons --color=auto --hyperlink $argv

functions/lss.fish

@@ -1,6 +1,7 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
+# Size-sorted listing
 function lss --description 'Size-sorted listing'
     if which eza >/dev/null 2>&1
         eza --oneline --long --all --sort=size --icons --color=auto --hyperlink --color-scale=size --color-scale-mode=gradient $argv

functions/lstree.fish

@@ -1,6 +1,7 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
+# Full recursive tree listing
 function lstree --description 'Full recursive tree listing'
     if which eza >/dev/null 2>&1
         eza --tree --icons --color=auto --hyperlink $argv

functions/lt.fish

@@ -1,6 +1,7 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
+# Tree listing, depth 2
 function lt --description 'Tree listing, depth 2'
     if which eza >/dev/null 2>&1
         eza --tree --level=2 --icons --color=auto --hyperlink $argv

functions/ltr.fish

@@ -1,6 +1,7 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
+# Reversed time-sorted listing
 function ltr --description 'Reversed time-sorted listing'
     if which eza >/dev/null 2>&1
         eza --long --all --sort=modified --icons --hyperlink --color=auto --color-scale=age --color-scale-mode=gradient $argv

functions/lx.fish

@@ -1,6 +1,7 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
+# Extension-sorted listing
 function lx --description 'Extension-sorted listing'
     if which eza >/dev/null 2>&1
         eza --long --all --sort=extension --icons --color=auto --hyperlink $argv

functions/mkdir.fish

@@ -1,7 +1,8 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-function mkdir
+# Execute mkdir
+function mkdir --description 'Execute mkdir'
     if status is-interactive
         command mkdir -p $argv
     else

functions/p.fish

@@ -1,6 +1,7 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
+# Put from clipboard
 function p --description 'Put from clipboard'
     # Check for help flag
     if contains -- -h $argv; or contains -- --help $argv

functions/parur.fish

@@ -1,6 +1,7 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
+# Interactively search and remove an installed package using fzf
 function parur --description 'Interactively search and remove an installed package using fzf'
     # 1. Use command substitution to get the package list from fzf
     set -l pkg_list (

functions/paste.fish

@@ -1,6 +1,7 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
+# Paste from clipboard
 function paste --description 'Paste from clipboard'
     if type -q wl-paste
         wl-paste $argv

functions/ping.fish

@@ -1,6 +1,7 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
+# prettyping with default nolegend
 function ping --description 'prettyping with default nolegend'
     if command -q prettyping
         # Check if the user specifically asked for the legend

functions/pkg.fish

@@ -5,6 +5,6 @@
 # This runs `paru` with the `-S` flag to install one or more packages.
 # The `$argv` variable passes all arguments given to the `pkg` function
 # directly to the `paru` command.
-function pkg
+function pkg --wraps='paru' --description 'directly to the `paru` command.'
     paru -S $argv
 end

functions/ports.fish

@@ -1,6 +1,7 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-function ports -d "Show active network listeners"
+# Show active network listeners
+function ports --wraps='sudo' --description 'Show active network listeners'
     sudo lsof -iTCP -sTCP:LISTEN -P -n
 end

functions/qr.fish

@@ -1,10 +1,20 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-function qr -d "Generate a QR code from text or pipe"
+# Generate a QR code from text or pipe
-    if set -q argv[1]
+function qr --description 'Generate a QR code from text or pipe'
-        echo $argv | qrencode -t utf8
+    if type -q qrencode
+        if set -q argv[1]
+            echo $argv | qrencode -t utf8
+        else
+            cat | qrencode -t utf8
+        end
     else
-        cat | qrencode -t utf8
+        if set -q argv[1]
+            curl -s "qrenco.de/$argv"
+        else
+            set -l input (cat)
+            curl -s "qrenco.de/$input"
+        end
     end
 end

functions/rawfish.fish

@@ -1,6 +1,7 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
+# alias rawfish=env NO_TMUX=1 fish
 function rawfish --wraps='env NO_TMUX=1 fish' --description 'alias rawfish=env NO_TMUX=1 fish'
   env NO_TMUX=1 fish $argv
         

functions/replay.fish

@@ -1,7 +1,8 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-function replay --description "Run Bash commands replaying changes in Fish"
+# Run Bash commands replaying changes in Fish
+function replay --description 'Run Bash commands replaying changes in Fish'
     switch "$argv"
         case -v --version
             echo "replay, version 1.2.1"

functions/rg.fish

@@ -1,6 +1,7 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
+# alias rg=rg --hyperlink-format=kitty
 function rg --description 'alias rg=rg --hyperlink-format=kitty'
     if test "$TERM" = xterm-kitty
         command rg --hyperlink-format=kitty $argv

functions/rm.fish

@@ -1,6 +1,7 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
+# Ultimate rm: trash, list, empty, and secure-erase
 function rm --description 'Ultimate rm: trash, list, empty, and secure-erase'
     # 1. No arguments: Show the Trash contents (Quick view)
     if not set -q argv[1]

functions/sbver.fish

@@ -1,7 +1,65 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-function sbver --wraps='~/sbctl-verify-clean.sh' --description 'alias sbver=~/sbctl-verify-clean.sh'
+###############################################################################
-  ~/sbctl-verify-clean.sh $argv
+# Purpose: Verifies Secure Boot status of EFI binaries using 'sbctl'.
-        
+# 
+# Behavior: 
+#   - Filters out 'invalid PE header' noise from sbctl output.
+#   - Parsers output to count successfully signed vs. unsigned images.
+#   - Color-codes output: Green for verified (✓), Red for failed (✗).
+#   - Provides a final summary of the system's signature status.
+#
+# Arguments:
+#   --brief : Suppresses individual file status and only shows the final summary.
+###############################################################################
+
+function sbver --description 'Verifies Secure Boot status of EFI binaries using sbctl'
+  if not type -q sbctl
+    echo "Error: 'sbctl' is not installed."
+    return 1
+  end
+
+  # ANSI color codes (Fish uses set_color for easier management)
+  set RED (set_color red)
+  set GREEN (set_color green)
+  set NC (set_color normal)
+
+  # Flags
+  set brief_mode false
+  if test "$argv[1]" = "--brief"
+      set brief_mode true
+  end
+
+  # Counters
+  set pass_count 0
+  set fail_count 0
+
+  # Run and process sbctl output
+  # Fish doesn't use 'done < <()'; we pipe directly into the while loop
+  sudo sbctl verify 2>&1 | grep -v -i 'invalid pe header' | while read -l line
+      if string match -q "*✓*" -- "$line"
+          set pass_count (math $pass_count + 1)
+          if not $brief_mode
+              echo -e "$GREEN$line$NC"
+          end
+      else if string match -q "*✗*" -- "$line"
+          set fail_count (math $fail_count + 1)
+          if not $brief_mode
+              echo -e "$RED$line$NC"
+          end
+      else
+          if not $brief_mode
+              echo "$line"
+          end
+      end
+  end
+
+  # Summary
+  echo
+  if test $fail_count -eq 0
+      echo -e "$GREEN✅ All images are signed ($pass_count verified)$NC"
+  else
+      echo -e "$RED❌ Some images are not signed ($fail_count failed, $pass_count passed)$NC"
+  end
 end

functions/screensleep.fish

@@ -1,6 +1,7 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
+# Turn off the display using KDE PowerDevil
 function screensleep --description 'Turn off the display using KDE PowerDevil'
     # Optional: 1-second delay to ensure no keystrokes wake it immediately
     sleep 1

functions/search.fish

@@ -5,6 +5,6 @@
 # This runs `paru` with the search flags.
 # The `$argv` variable passes all arguments given to the `search` function
 # directly to the `paru` command.
-function search
+function search --wraps='paru' --description 'directly to the `paru` command.'
     paru $argv
 end

functions/spark.fish

@@ -1,7 +1,8 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-function spark --description Sparklines
+# Sparklines
+function spark --description 'Sparklines'
     argparse --ignore-unknown --name=spark v/version h/help m/min= M/max= -- $argv || return
 
     if set --query _flag_version[1]

functions/split.fish

@@ -1,6 +1,7 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
+# Run a command in a new Kitty split
 function split --description 'Run a command in a new Kitty split'
     if test "$TERM" != xterm-kitty
         echo "Error: The 'split' command requires Kitty terminal." >&2

functions/spwin.fish

@@ -1,10 +1,18 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-function spwin --wraps='~/.config/kitty/spawn-window.sh' --description 'alias spwin=~/.config/kitty/spawn-window.sh'
+# spawn window in kitty or wezterm
-    if test "$TERM" != xterm-kitty
+function spwin --wraps='~/.config/kitty/spawn-window.sh' --description 'spawn window in kitty or wezterm'
-        echo "Error: The 'spwin' command requires Kitty terminal." >&2
+    if test "$TERM" = xterm-kitty
+        if test -x ~/.config/kitty/spawn-window.sh
+            ~/.config/kitty/spawn-window.sh $argv
+        else
+            kitty @ launch --type=window $argv
+        end
+    else if test "$TERM_PROGRAM" = WezTerm
+        wezterm cli spawn $argv
+    else
+        echo "Error: The 'spwin' command requires Kitty or WezTerm." >&2
         return 1
     end
-    ~/.config/kitty/spawn-window.sh $argv
 end

functions/ssh.fish

@@ -1,6 +1,7 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
+# Alias ssh to kitten ssh when using Kitty terminal
 function ssh --description 'Alias ssh to kitten ssh when using Kitty terminal'
     if test "$TERM" = xterm-kitty
         kitten ssh $argv

functions/steam-dl.fish

@@ -1,6 +1,7 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
+# Run Steam while inhibiting system sleep
 function steam-dl --description 'Run Steam while inhibiting system sleep'
     echo "Inhibiting sleep while Steam downloads..."
     systemd-inhibit --why="Active Download" --who="User" --what=idle:sleep steam

functions/superpowers.fish

@@ -1,7 +1,8 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-function superpowers --description "Toggle superpowers extension for Gemini and Claude"
+# Toggle superpowers extension for Gemini and Claude
+function superpowers --description 'Toggle superpowers extension for Gemini and Claude'
     set -l scope_gemini workspace
     set -l scope_claude project
     set -l mode ""

functions/swapstat.fish

@@ -1,7 +1,8 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-function swapstat --description "View colorized zRAM and swappiness status"
+# View colorized zRAM and swappiness status
+function swapstat --description 'View colorized zRAM and swappiness status'
     set -l swappiness (sysctl -n vm.swappiness)
     set -l zdata (zramctl --bytes --noheadings --output DATA,TOTAL /dev/zram0 2>/dev/null)
     

functions/tab.fish

@@ -1,7 +1,21 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-function tab --wraps='konsole --new-tab --workdir "$cdto"' --description 'alias tab=konsole --new-tab --workdir "$cdto"'
+# Spawn a new tab in the current terminal
-  konsole --new-tab --workdir "$cdto" $argv
+function tab --description 'Spawn a new tab in the current terminal'
-        
+    set -l dir "$cdto"
+    if test -z "$dir"
+        set dir "$PWD"
+    end
+
+    if test "$TERM" = xterm-kitty
+        kitty @ launch --type=tab --cwd="$dir" $argv
+    else if test "$TERM_PROGRAM" = WezTerm
+        wezterm cli spawn --cwd "$dir" $argv
+    else if set -q KONSOLE_VERSION
+        konsole --new-tab --workdir "$dir" $argv
+    else
+        echo "Error: No supported terminal found. Try Kitty, WezTerm, or Konsole." >&2
+        return 1
+    end
 end

functions/tmux-clean.fish

@@ -1,6 +1,7 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
+# Kill all tmux sessions except the current one
 function tmux-clean --description 'Kill all tmux sessions except the current one'
     # Get a list of all session names that are NOT currently attached
     set sessions (tmux list-sessions -F '#{session_name} #{session_attached}' | string match -rv ' 1$' | string split -f1 ' ')

functions/top.fish

@@ -1,14 +1,14 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-function top --wraps=btop --description 'Use btop as a modern replacement for top'
+# Use btop as a modern replacement for top
+function top --wraps='btop' --description 'Use btop as a modern replacement for top'
     # 1. Check if btop is actually installed
     if type -q btop
         # 2. Launch btop with any arguments passed
         btop $argv
     else
         # 3. Fallback to the original system top if btop is missing
-        echo "btop not found, falling back to classic top..."
         command top $argv
     end
 end

functions/upgrade.fish

@@ -4,6 +4,6 @@
 # Function for upgrading the system with paru.
 # This runs `paru` with the `-Syu` flags to sync, refresh, and upgrade all
 # packages, and adds `--no-confirm` to bypass the confirmation prompt.
-function upgrade
+function upgrade --wraps='paru' --description 'packages, and adds `--no-confirm` to bypass the confirmation prompt.'
     paru -Syu --noconfirm
 end

functions/view.fish

@@ -1,7 +1,14 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-function view --wraps='neovim -R' --wraps='nvim -R' --description 'alias view=nvim -R'
+# alias view=nvim -R
-  nvim -R $argv
+function view --wraps='nvim -R' --description 'alias view=nvim -R'
+    if type -q nvim
+        nvim -R $argv
+    else if type -q less
+        less $argv
+    else
+        command cat $argv
+    end
         
 end

functions/wake-lock.fish

@@ -1,6 +1,7 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
+# Run a command while inhibiting system sleep
 function wake-lock --description 'Run a command while inhibiting system sleep'
     if test (count $argv) -eq 0
         echo "Usage: wake-lock [command] [args...]"

functions/y.fish

@@ -1,6 +1,7 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
+# Yank to clipboard
 function y --description 'Yank to clipboard'
     # Check for help flag
     if contains -- -h $argv; or contains -- --help $argv

functions/zellij.fish

@@ -1,7 +1,8 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-function zellij --description 'alias zellij=zellij options --theme catppuccin-mocha'
+# alias zellij=zellij options --theme catppuccin-mocha
+function zellij --wraps='zellij' --description 'alias zellij=zellij options --theme catppuccin-mocha'
  command zellij options --theme catppuccin-mocha $argv
         
 end