docs(functions): standardize all function doc blocks to UNIX man-page style

Replace all ad-hoc inline comments between license headers and function
declarations with consistent SYNOPSIS / DESCRIPTION / ARGUMENTS / RETURNS /
EXAMPLE blocks across all 99 project-owned functions/ files. No executable
logic, variable names, or exit codes were modified.

Completes Task #6 from AGENTS.md (Retroactive Function Documentation
Standardization).

functions/__auto_source_fallback_venv.fish

@@ -1,6 +1,17 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
+# SYNOPSIS
+#   __auto_source_fallback_venv
+#
+# DESCRIPTION
+#   Event handler that auto-activates a .venv Python virtual environment when
+#   entering a directory. Deactivates when leaving the project tree. Skipped
+#   when direnv is already managing the directory.
+#
+# EXAMPLE
+#   # Triggered automatically on directory change; not called directly.
+#   cd ~/myproject  # activates .venv if present
 function __auto_source_fallback_venv --on-variable PWD
     status --is-command-substitution; and return
     

functions/__fish_variable_check.fish

@@ -6,24 +6,23 @@
 #
 # DESCRIPTION
 #   Evaluates a given variable's value to determine its truthiness or falsiness.
-#   It safely dereferences the variable name and performs case-insensitive matching.
+#   Safely dereferences the variable name and performs case-insensitive matching.
+#   Pass the variable name (without $), not its value.
 #
 # ARGUMENTS
-#   variable_name  The name of the variable to check (e.g., __fish_config_strict_mode)
-#                  Do NOT pass the value directly (do not use the $ prefix).
+#   variable_name  Name of the variable to check (without $ prefix)
 #
 # RETURNS
-#   0  True    (Opt-In)  : Matches 1, true, yes, on, y
-#   1  False   (Opt-Out) : Matches 0, false, no, off, n
-#   2  Empty             : Variable is unset or contains an empty string
-#   3  Garbage           : Variable contains an unrecognized value
+#   0  True (opt-in): value matches 1, true, yes, on, or y
+#   1  False (opt-out): value matches 0, false, no, off, or n
+#   2  Empty: variable is unset or empty
+#   3  Garbage: value is unrecognized
 #
 # EXAMPLE
 #   __fish_variable_check __fish_config_strict_mode
 #   if test $status -eq 0
 #       echo "Strict mode enabled!"
 #   end
-#
 function __fish_variable_check --description "Check if a variable is set to a truthy or falsy value."
     set -l var_name $argv[1]
 

functions/__fzf_inline_picker.fish

@@ -7,15 +7,13 @@
 # DESCRIPTION
 #   Opens an interactive fzf session and injects the selected item directly
 #   into the command line at the cursor position. Bound to @@ by default.
-#   Requires fzf to be installed. Repaints the prompt after insertion.
+#   Repaints the prompt after selection or cancellation.
 #
 # RETURNS
-#   0  A selection was made and inserted into the command line
-#   0  No selection was made (fzf cancelled); command line is unchanged
+#   0  Always; no-op if fzf is cancelled
 #
 # EXAMPLE
-#   # Press @@ at the prompt — fzf opens, pick an item, it appears at cursor
-#
+#   # Press @@ at the command prompt to open fzf and insert the selected item.
 function __fzf_inline_picker
     # Open fzf and capture selection
     set -l selection (fzf)

functions/__insert_previous_path_head.fish

@@ -1,7 +1,16 @@
 # 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
+# SYNOPSIS
+#   __insert_previous_path_head
+#
+# DESCRIPTION
+#   Inserts the directory component (dirname) of the last argument from the
+#   previous history command into the current commandline. Used as a keybinding
+#   helper to quickly reuse a directory path.
+#
+# EXAMPLE
+#   # Bind to a key to insert the directory from the last 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,7 +1,16 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-# Provides interactive history substitution using old/new pattern or sudo fallback
+# SYNOPSIS
+#   __interactive_history_sub
+#
+# DESCRIPTION
+#   Provides interactive history substitution at the prompt. When the buffer
+#   contains old/new, replaces all occurrences of 'old' with 'new' in the last
+#   history entry. When the buffer is empty, prepends 'sudo' to the last command.
+#
+# EXAMPLE
+#   # Type "foo/bar" at prompt to replace "foo" with "bar" in the last command.
 function __interactive_history_sub
     set -l current_line (commandline -b)
     set -l last_cmd $history[1]

functions/__substitute_typo.fish

@@ -1,7 +1,18 @@
 # 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
+# SYNOPSIS
+#   __substitute_typo
+#
+# DESCRIPTION
+#   Reads the commandline buffer and applies ^old^new substitution against
+#   the most recent history entry, replacing the buffer with the expanded
+#   result. If the buffer does not match the ^old^new pattern, inserts a
+#   literal caret character instead. Intended to be bound to ^ in
+#   key_bindings.fish.
+#
+# EXAMPLE
+#   bind ^ __substitute_typo
 function __substitute_typo
     set -l cursor_pos (commandline -C)
     set -l cmd (commandline)

functions/_fish_deps_catalog.fish

@@ -1,19 +1,17 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-# Populates parallel arrays describing every managed dependency.
-# Callers must invoke this function before accessing _fdc_* arrays.
+# SYNOPSIS
+#   _fish_deps_catalog
 #
-# Array layout (same index across all sets):
-#   _fdc_bins    — binary name (what `type -q` checks)
-#   _fdc_tiers   — req | int | rec
-#   _fdc_cargo   — cargo crate name, or "" if not on crates.io
-#   _fdc_pm      — system PM package name, or "" if not in repos
-#   _fdc_special — special install key: rustup-installer | fisher-bootstrap |
-#                  fzf-update | paru-build | pipx | curl-installer |
-#                  git-cargo-fish | curl-uv | "" (none)
+# DESCRIPTION
+#   Populates parallel global arrays (_fdc_bins, _fdc_tiers, _fdc_cargo,
+#   _fdc_pm, _fdc_special) describing every managed shell dependency.
+#   Must be called before accessing any _fdc_* array.
 #
-# uv and cargo are listed first so both are available before fish and other Rust tools.
+# EXAMPLE
+#   _fish_deps_catalog
+#   echo $_fdc_bins
 function _fish_deps_catalog
     set -g _fdc_bins \
         uv cargo fish fisher starship fzf zoxide direnv paru yay \
@@ -41,7 +39,22 @@ function _fish_deps_catalog
         "" "" "" "" "" "" "" "" "" "" curl-lazydocker "" "" ""
 end
 
-# Returns the index (1-based) of $argv[1] in the catalog, or "" if not found.
+# SYNOPSIS
+#   _fish_deps_catalog_idx <bin>
+#
+# DESCRIPTION
+#   Returns the 1-based index of a binary name in the _fdc_bins catalog array,
+#   or an empty string if the binary is not found.
+#
+# ARGUMENTS
+#   bin  The binary name to look up in the catalog
+#
+# RETURNS
+#   0  Index printed to stdout
+#   1  Binary not found (empty output)
+#
+# EXAMPLE
+#   _fish_deps_catalog_idx fzf
 function _fish_deps_catalog_idx --argument-names bin
     _fish_deps_catalog
     set -l i 1

functions/_fish_deps_detect_pm.fish

@@ -1,7 +1,16 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-# Detect the first available system package manager.
+# SYNOPSIS
+#   _fish_deps_detect_pm
+#
+# DESCRIPTION
+#   Detects and prints the name of the first available system package manager
+#   from the priority list: paru, yay, pacman, apt, brew, pkg, dnf, yum.
+#   Prints an empty string if none are found.
+#
+# EXAMPLE
+#   set pm (_fish_deps_detect_pm)
 function _fish_deps_detect_pm
     for pm in paru yay pacman apt brew pkg dnf yum
         if type -q $pm

functions/_fish_deps_install.fish

@@ -1,8 +1,16 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-# Interactively install missing deps.
-# For each missing dep: prompts yes/no, then prompts install method when multiple exist.
+# SYNOPSIS
+#   _fish_deps_install
+#
+# DESCRIPTION
+#   Interactively installs each missing fish shell dependency from the catalog.
+#   For each missing entry, prompts yes/no and the preferred install method
+#   when multiple options are available.
+#
+# EXAMPLE
+#   _fish_deps_install
 function _fish_deps_install
     _fish_deps_catalog
 

functions/_fish_deps_pm_install.fish

@@ -1,8 +1,23 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-# Install a package via the system PM.
-# Usage: _fish_deps_pm_install <pkg>
+# SYNOPSIS
+#   _fish_deps_pm_install <pkg>
+#
+# DESCRIPTION
+#   Installs a single package via the detected system package manager, running
+#   with sudo where required. Supports paru, yay, pacman, apt, brew, pkg, dnf,
+#   and yum.
+#
+# ARGUMENTS
+#   pkg  The package name to install
+#
+# RETURNS
+#   0  Package installed successfully
+#   1  No supported package manager found
+#
+# EXAMPLE
+#   _fish_deps_pm_install ripgrep
 function _fish_deps_pm_install --argument-names pkg
     set -l pm (_fish_deps_detect_pm)
     if test -z "$pm"

functions/_fish_deps_pm_upgrade.fish

@@ -1,8 +1,23 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-# Upgrade an already-installed package via the system PM.
-# Usage: _fish_deps_pm_upgrade <pkg>
+# SYNOPSIS
+#   _fish_deps_pm_upgrade <pkg>
+#
+# DESCRIPTION
+#   Upgrades an installed package via the detected system package manager,
+#   running with sudo where required. Supports paru, yay, pacman, apt, brew,
+#   pkg, dnf, and yum.
+#
+# ARGUMENTS
+#   pkg  The package name to upgrade
+#
+# RETURNS
+#   0  Package upgraded successfully
+#   1  No supported package manager found
+#
+# EXAMPLE
+#   _fish_deps_pm_upgrade ripgrep
 function _fish_deps_pm_upgrade --argument-names pkg
     set -l pm (_fish_deps_detect_pm)
     if test -z "$pm"

functions/_fish_deps_status.fish

@@ -1,7 +1,15 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-# Print colored installed/missing status for all deps, grouped by tier.
+# SYNOPSIS
+#   _fish_deps_status
+#
+# DESCRIPTION
+#   Prints a colored installed/missing status report for all managed fish shell
+#   dependencies, grouped by tier (required, integrations, recommended).
+#
+# EXAMPLE
+#   _fish_deps_status
 function _fish_deps_status
     _fish_deps_catalog
 

functions/_fish_deps_update.fish

@@ -1,8 +1,16 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-# Update all installed deps using their known install method.
-# Priority: cargo > system PM > special (fzf-update, fisher, pipx).
+# SYNOPSIS
+#   _fish_deps_update
+#
+# DESCRIPTION
+#   Updates all currently installed fish shell dependencies using their
+#   preferred method. Priority order: cargo, then system PM, then special
+#   installers (fzf-update, fisher, pipx). Always updates fisher plugins first.
+#
+# EXAMPLE
+#   _fish_deps_update
 function _fish_deps_update
     _fish_deps_catalog
 

functions/_fish_mkdir_p.fish

@@ -1,14 +1,25 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-# mkdir -p with configurable output.
+# SYNOPSIS
+#   _fish_mkdir_p [--path|--tree|--silent] <dir>
 #
-# Flags:
-#   --path / -p   (default) Print "Created: ~/full/path/" on one line
-#   --tree / -t             Tree view: dimmed existing anchor + cyan new dirs
-#   --silent / -s           No output
+# DESCRIPTION
+#   Creates a directory and all missing parents, then reports what was created.
+#   Output mode is configurable: path (default), tree, or silent.
 #
-# Usage: _fish_mkdir_p [--path|--tree|--silent] <dir>
+# ARGUMENTS
+#   -p, --path    Print a single "Created: ~/path/" line (default)
+#   -t, --tree    Show a tree view of the newly created hierarchy
+#   -s, --silent  Suppress all output
+#   dir           The directory path to create
+#
+# RETURNS
+#   0  Directory created or already exists
+#   1  No target directory specified or mkdir failed
+#
+# EXAMPLE
+#   _fish_mkdir_p --tree ~/projects/new/subdir
 function _fish_mkdir_p --description 'mkdir -p with configurable verbose output'
     set -l mode path
     set -l target

functions/_qalc_eval.fish

@@ -1,7 +1,20 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-# Returns the result of a qalc calculation
+# SYNOPSIS
+#   _qalc_eval
+#
+# DESCRIPTION
+#   Reads the current commandline buffer and evaluates it as a qalc
+#   expression, printing the result. Clears the buffer and repaints
+#   after evaluation. No-ops if qalc is not installed or the buffer
+#   is empty. Intended to be bound to a key in key_bindings.fish.
+#
+# RETURNS
+#   1  qalc not found in PATH
+#
+# EXAMPLE
+#   bind \cr _qalc_eval
 function _qalc_eval
     type -q qalc || return 1
 

functions/_replace_command_token.fish

@@ -1,8 +1,17 @@
 # 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 position for replacement.
-# If the command starts with 'sudo', preserves 'sudo' and removes the next token instead.
+# SYNOPSIS
+#   _replace_command_token
+#
+# DESCRIPTION
+#   Removes the first command token from the commandline buffer and
+#   positions the cursor for immediate replacement. If the command starts
+#   with sudo, preserves sudo and removes the token after it instead.
+#   Intended to be bound to a key in key_bindings.fish.
+#
+# EXAMPLE
+#   bind \cx _replace_command_token
 function _replace_command_token --description 'Remove first command token (or first after sudo) and place cursor for replacement'
     set -l cmd (commandline)
 

functions/_scrollback_prune_junk.fish

@@ -1,6 +1,20 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
+# SYNOPSIS
+#   _scrollback_prune_junk [dir]
+#
+# DESCRIPTION
+#   Removes low-value log files from the scrollback history directory:
+#   empty files, files with at most one meaningful line, and Kitty
+#   tab-rename prompt captures. Called by smart_exit.fish on session end.
+#
+# ARGUMENTS
+#   dir  Directory to prune (defaults to $SCROLLBACK_HISTORY_DIR or
+#        ~/.terminal_history)
+#
+# EXAMPLE
+#   _scrollback_prune_junk ~/.terminal_history
 function _scrollback_prune_junk --description 'Remove empty, trivial, and Kitty UI noise logs'
     set -l dir (set -q SCROLLBACK_HISTORY_DIR; and echo $SCROLLBACK_HISTORY_DIR; or echo "$HOME/.terminal_history")
     if set -q argv[1]

functions/_smart_execute.fish

@@ -1,7 +1,17 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-# Executes different functions based on the command line content
+# SYNOPSIS
+#   _smart_execute
+#
+# DESCRIPTION
+#   Bound to Enter, dispatches based on the current commandline buffer.
+#   Buffers ending in = are evaluated as qalc expressions via _qalc_eval.
+#   Empty buffers and all other input fall through to normal execution.
+#   Intended to be bound to a key in key_bindings.fish.
+#
+# EXAMPLE
+#   bind \r _smart_execute
 function _smart_execute --description 'Execute different functions based on the command line content'
     # Get the current command line buffer
     set -l cmd (commandline)

functions/antigravity-ide.fish

@@ -1,7 +1,18 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-# alias antigravity-ide=antigravity
+# SYNOPSIS
+#   antigravity-ide [args...]
+#
+# DESCRIPTION
+#   Wrapper for the antigravity-ide command that filters a known noisy warning
+#   about an unrecognized 'app' option from stderr.
+#
+# ARGUMENTS
+#   args...  Arguments passed through to the antigravity-ide command
+#
+# EXAMPLE
+#   antigravity-ide
 function antigravity-ide --wraps='antigravity-ide' --description 'alias antigravity-ide=antigravity-ide'
     # In fish, we pipe stderr using '2>|' to another command
     command antigravity-ide $argv 2>| grep -v "'app' is not in the list of known options" >&2

functions/antigravity-resume.fish

@@ -1,7 +1,20 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-# Execute antigravity-resume
+# SYNOPSIS
+#   antigravity-resume
+#
+# DESCRIPTION
+#   Resumes an Antigravity (agy) AI session using the session ID saved in
+#   .antigravity_session in the current directory. Falls back to the interactive
+#   session browser if no local session file exists.
+#
+# RETURNS
+#   0  Session resumed or interactive picker opened
+#   1  Required binaries (agy or save_antigravity_session) are not found
+#
+# EXAMPLE
+#   antigravity-resume
 function antigravity-resume --description 'Execute antigravity-resume'
     if not type -q agy
         echo "Error: The 'agy' command is not installed or not in PATH." >&2

functions/antigravity.fish

@@ -1,7 +1,18 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-# alias antigravity=agy
+# SYNOPSIS
+#   antigravity [args...]
+#
+# DESCRIPTION
+#   Wrapper for the agy Antigravity AI CLI that filters a known noisy warning
+#   about an unrecognized 'app' option from stderr.
+#
+# ARGUMENTS
+#   args...  Arguments passed through to the agy command
+#
+# EXAMPLE
+#   antigravity chat
 function antigravity --wraps='agy' --description 'alias antigravity=agy'
     # In fish, we pipe stderr using '2>|' to another command
     command agy $argv 2>| grep -v "'app' is not in the list of known options" >&2

functions/bash.fish

@@ -1,7 +1,18 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-# bash switches to bash shell
+# SYNOPSIS
+#   bash [args...]
+#
+# DESCRIPTION
+#   Switches the current shell session to bash, loading config from the XDG
+#   config directory. Resets $SHELL back to fish on exit.
+#
+# ARGUMENTS
+#   args...  Arguments passed through to the bash command
+#
+# EXAMPLE
+#   bash
 function bash --wraps='bash' --description 'bash switches to bash shell'
     set SHELL $(which bash) # Set shell to bash
     command bash --rcfile "$XDG_CONFIG_HOME/bash/bashrc" $argv # Run bash

functions/bd-pull.fish

@@ -1,7 +1,23 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-# Pull new Gitea issues into local Beads and link them
+# SYNOPSIS
+#   bd-pull <owner/repo>
+#
+# DESCRIPTION
+#   Fetches unlinked issues from a Gitea repository, creates corresponding local
+#   Beads entries, and updates the Gitea issue titles to include the new Bead IDs.
+#   Requires $GITEA_TOKEN and $GITEA_URL to be set.
+#
+# ARGUMENTS
+#   owner/repo  The repository path in owner/name format
+#
+# RETURNS
+#   0  Issues linked and synced (or no unlinked issues found)
+#   1  Missing required argument or environment variables
+#
+# EXAMPLE
+#   bd-pull myuser/myproject
 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

functions/bkg.fish

@@ -1,18 +1,23 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-# Function to run a command in the background, detached from the terminal.
-# This prevents the command from being terminated when the terminal is closed.
-# All output (stdout and stderr) is discarded.
+# SYNOPSIS
+#   bkg <command> [args...]
 #
-# Usage:
-#   bkg <command> [arguments...]
+# DESCRIPTION
+#   Launches a command in the background, fully detached from the terminal
+#   using nohup. All stdout and stderr output is discarded.
 #
-# Example:
+# ARGUMENTS
+#   command  The command to run detached
+#   args...  Additional arguments for the command
+#
+# RETURNS
+#   0  Command launched successfully
+#   1  No command provided
+#
+# EXAMPLE
 #   bkg firefox
-#   bkg code .
-#
-# Execute bkg
 function bkg --description 'Execute bkg'
     # Check if a command was provided as an argument.
     if test -z "$argv[1]"

functions/cat.fish

@@ -1,7 +1,19 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-# Use bat for files and ls for directories when using cat
+# SYNOPSIS
+#   cat [args...]
+#
+# DESCRIPTION
+#   Enhanced cat replacement that uses bat for file display, runs ls when given
+#   a directory, falls back to raw cat for ANSI-colored log files, and finally
+#   falls back to standard cat if bat is not installed.
+#
+# ARGUMENTS
+#   args...  Files or directories to display
+#
+# EXAMPLE
+#   cat README.md
 function cat --wraps='bat' --description 'Use bat for files, ls for directories, and raw cat for ANSI logs'
     # If no arguments are provided, cat usually waits for stdin. 
     # We'll maintain that behavior by skipping the directory check if $argv is empty.

functions/cdi.fish

@@ -1,6 +1,18 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
+# SYNOPSIS
+#   cdi [query]
+#
+# DESCRIPTION
+#   Alias for zi — opens zoxide's interactive directory picker for jumping to
+#   frequently-visited directories using fzf.
+#
+# ARGUMENTS
+#   query  Optional search term to pre-filter the directory list
+#
+# EXAMPLE
+#   cdi myproject
 function cdi --wraps zi --description 'Interactively jump to a directory using zoxide (alias for zi)'
     zi $argv
 end

functions/cffetch.fish

@@ -1,7 +1,18 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-# alias cffetch=clear;fastfetch
+# SYNOPSIS
+#   cffetch [args...]
+#
+# DESCRIPTION
+#   Clears the screen and displays system information using fastfetch with a
+#   custom config if available. Falls back to neofetch if fastfetch is not installed.
+#
+# ARGUMENTS
+#   args...  Additional arguments forwarded to fastfetch or neofetch
+#
+# EXAMPLE
+#   cffetch
 function cffetch --description 'alias cffetch=clear;fastfetch'
     clear
     if which fastfetch >/dev/null 2>&1

functions/cheat.fish

@@ -1,7 +1,19 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-# alias cheat=cheat -c
+# SYNOPSIS
+#   cheat <topic> [args...]
+#
+# DESCRIPTION
+#   Displays colorized cheatsheets using cheat -c. Falls back to tldr, then
+#   man, if cheat is not installed.
+#
+# ARGUMENTS
+#   topic   The command or topic to look up
+#   args... Additional arguments forwarded to cheat, tldr, or man
+#
+# EXAMPLE
+#   cheat tar
 function cheat --wraps='cheat' --description 'alias cheat=cheat -c'
     if type -q cheat
         command cheat -c $argv

functions/check_fish_deps.fish

@@ -1,7 +1,15 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-# Thin wrapper kept for backwards compatibility.
+# SYNOPSIS
+#   check_fish_deps
+#
+# DESCRIPTION
+#   Backwards-compatibility wrapper that delegates to fish-deps status to
+#   report which fish shell dependencies are installed or missing.
+#
+# EXAMPLE
+#   check_fish_deps
 function check_fish_deps --description 'Check all fish-related dependencies'
     fish-deps status
 end

functions/claude-docs.fish

@@ -1,7 +1,16 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-# Update README.md with recent changes using Claude-code
+# SYNOPSIS
+#   claude-docs
+#
+# DESCRIPTION
+#   Invokes Claude Code to analyze recent repository changes and update
+#   README.md, ensuring all features and examples are accurate and pruning
+#   obsolete content.
+#
+# EXAMPLE
+#   claude-docs
 function claude-docs --description 'Claude-code: Sync README with recent changes'
     claude "Analyze the recent changes and update the README.md to ensure all features, setup instructions, and examples are 100% accurate. Prune any obsolete information."
 end

functions/claude-pr.fish

@@ -1,7 +1,16 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-# Create a new git branch, commit, push, and PR using Claude-code
+# SYNOPSIS
+#   claude-pr
+#
+# DESCRIPTION
+#   Invokes Claude Code to perform a full PR workflow: create a kebab-case
+#   branch, write a Conventional Commit, run verification, push, and open a
+#   pull request with a manual verification checklist.
+#
+# EXAMPLE
+#   claude-pr
 function claude-pr --description 'Claude-code: New branch, commit, push, and PR'
     claude "Act as a senior engineer. Execute this sequence: 1. Create a new git branch (kebab-case). 2. Stage changes and write a Conventional Commit message. 3. Self-verify the changes by running relevant build/test commands or linting. 4. Push to remote. 5. Create a PR to 'main' including a summary of changes and a 'Manual Verification' section containing a Markdown checklist (- [ ]) of specific, bite-sized steps required to manually verify the functionality."
 end

functions/claude-resume.fish

@@ -1,7 +1,20 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-# Execute claude-resume
+# SYNOPSIS
+#   claude-resume
+#
+# DESCRIPTION
+#   Resumes a Claude Code session using the ID saved in .claude_session in the
+#   current directory. Falls back to the interactive session picker if no file
+#   exists.
+#
+# RETURNS
+#   0  Session resumed or interactive picker opened
+#   1  Required binaries (claude or save_claude_session) are not found
+#
+# EXAMPLE
+#   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

functions/claude.fish

@@ -1,6 +1,18 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
+# SYNOPSIS
+#   claude [args...]
+#
+# DESCRIPTION
+#   Wrapper for the claude CLI that always injects --remote-control unless it
+#   is already present in the argument list.
+#
+# ARGUMENTS
+#   args...  Arguments passed through to the claude command
+#
+# EXAMPLE
+#   claude "Refactor the auth module"
 function claude --wraps='claude --remote-control' --description 'claude with --remote-control always enabled'
     if contains -- --remote-control $argv
         command claude $argv

functions/cleanup.fish

@@ -1,7 +1,15 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-# Log orphans to ~/.removed_orphans and remove them
+# SYNOPSIS
+#   cleanup
+#
+# DESCRIPTION
+#   Identifies and removes Arch Linux orphan packages using pacman. Logs
+#   package names and versions to ~/.removed_orphans before removal.
+#
+# EXAMPLE
+#   cleanup
 function cleanup --description 'Log orphans to ~/.removed_orphans and remove them'
     set -l orphans (pacman -Qtdq)
     if test -n "$orphans"

functions/clone.fish

@@ -1,7 +1,22 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-# alias clone=clone-in-kitty
+# SYNOPSIS
+#   clone [args...]
+#
+# DESCRIPTION
+#   Alias for clone-in-kitty that clones a repository into a new Kitty terminal
+#   window. Only works inside the Kitty terminal.
+#
+# ARGUMENTS
+#   args...  Arguments forwarded to clone-in-kitty (typically a repo URL)
+#
+# RETURNS
+#   0  Repository cloned
+#   1  Not running inside Kitty terminal
+#
+# EXAMPLE
+#   clone https://github.com/user/repo.git
 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

functions/clonet.fish

@@ -1,7 +1,22 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-# alias clonet=clone-in-kitty --type=tab
+# SYNOPSIS
+#   clonet [args...]
+#
+# DESCRIPTION
+#   Alias for clone-in-kitty --type=tab that clones a repository into a new
+#   Kitty terminal tab. Only works inside the Kitty terminal.
+#
+# ARGUMENTS
+#   args...  Arguments forwarded to clone-in-kitty (typically a repo URL)
+#
+# RETURNS
+#   0  Repository cloned
+#   1  Not running inside Kitty terminal
+#
+# EXAMPLE
+#   clonet https://github.com/user/repo.git
 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,16 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-# Execute code-resume
+# SYNOPSIS
+#   code-resume
+#
+# DESCRIPTION
+#   Resumes the most recent AI coding session in the current directory. Prefers
+#   Claude Code (.claude_session), then Antigravity (.antigravity_session),
+#   falling back to the Claude interactive session picker.
+#
+# EXAMPLE
+#   code-resume
 function code-resume --description 'Execute code-resume'
     if test -f .claude_session
         set -l sid (cat .claude_session)

functions/copy.fish

@@ -1,6 +1,19 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
+# SYNOPSIS
+#   copy <source> <dest>
+#
+# DESCRIPTION
+#   Wrapper for cp that strips trailing slashes from source directories,
+#   preventing unwanted nested copies when the destination already exists.
+#
+# ARGUMENTS
+#   source  Source file or directory
+#   dest    Destination path
+#
+# EXAMPLE
+#   copy ./mydir/ ~/backup
 function copy
     set count (count $argv)
     if test "$count" = 2; and test -d "$argv[1]"

functions/detach.fish

@@ -1,7 +1,25 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-# Execute detach
+# SYNOPSIS
+#   detach [-h] [--version] <command> [args...]
+#
+# DESCRIPTION
+#   Runs a command in the background using nohup, fully detached from the
+#   terminal with all output discarded.
+#
+# ARGUMENTS
+#   -h, --help   Show help message
+#   --version    Show version information
+#   command      The command to run detached
+#   args...      Additional arguments for the command
+#
+# RETURNS
+#   0  Command launched or help/version shown
+#   1  No command provided or unknown option
+#
+# EXAMPLE
+#   detach rsync -a ./data remote:/backup/
 function detach --description 'Execute detach'
     set -l show_help 0
     set -l args

functions/dng2avif.fish

@@ -1,7 +1,27 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-# Convert DNG raw to 10-bit HDR AVIF
+# SYNOPSIS
+#   dng2avif [-h] [-i <file>] [-o <file>] [-q <n>] [-s <n>] [input.dng]
+#
+# DESCRIPTION
+#   Converts a DNG raw image to a 10-bit HDR AVIF using a three-step pipeline:
+#   develop with ImageMagick, encode with ffmpeg+avifenc, sync metadata with
+#   exiftool. Requires magick, ffmpeg, avifenc, and exiftool.
+#
+# ARGUMENTS
+#   -i, --input FILE    Input DNG file
+#   -o, --output FILE   Output AVIF file (defaults to input basename)
+#   -q, --quality N     Encoding quality 0-100 (default: 92)
+#   -s, --speed N       Encoder speed 0-10 (default: 3, 0 = slowest)
+#   -h, --help          Show help message
+#
+# RETURNS
+#   0  Conversion complete
+#   1  File not found, missing dependency, or encode step failed
+#
+# EXAMPLE
+#   dng2avif photo.dng
 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,7 +1,23 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-# Pull and restart docker compose containers
+# SYNOPSIS
+#   dockup [-h] [directory]
+#
+# DESCRIPTION
+#   Pulls the latest Docker images and restarts all services in a Docker Compose
+#   project, then prunes dangling images. Accepts an optional target directory.
+#
+# ARGUMENTS
+#   -h, --help   Show help message
+#   directory    Path to the compose project (defaults to current directory)
+#
+# RETURNS
+#   0  Services updated and running
+#   1  Directory not found or no docker-compose.yml present
+#
+# EXAMPLE
+#   dockup ~/myapp
 function dockup --description 'Pull and restart docker compose containers'
     # Define colors
     set -l clr_error (set_color red)

functions/dops.fish

@@ -1,7 +1,20 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-# Execute docker
+# SYNOPSIS
+#   docker [subcommand] [args...]
+#
+# DESCRIPTION
+#   Wrapper for docker that intercepts the ps subcommand and redirects it to
+#   the dops function for enhanced container listing. All other subcommands are
+#   passed through to the real docker binary.
+#
+# ARGUMENTS
+#   subcommand  Docker subcommand (ps is redirected to dops)
+#   args...     Arguments forwarded to docker or dops
+#
+# EXAMPLE
+#   docker ps
 function docker --description 'Execute docker'
     if test -n "$argv[1]"
         switch $argv[1]

functions/du.fish

@@ -1,7 +1,22 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-# Execute du
+# SYNOPSIS
+#   du [--disk|--dir|--dua] [args...]
+#
+# DESCRIPTION
+#   Smart disk-usage wrapper that routes to duf (disk overview), dust (directory
+#   tree), or dua based on context or explicit flags. Falls back to system du
+#   when the preferred tool is not installed.
+#
+# ARGUMENTS
+#   --disk   Force duf for disk-level overview
+#   --dir    Force dust for directory-level breakdown
+#   --dua    Force dua interactive mode
+#   args...  Files/directories or flags forwarded to the selected tool
+#
+# EXAMPLE
+#   du ~/Downloads
 function du --description 'Execute du'
     set cmd ""
     set args

functions/dusize.fish

@@ -1,7 +1,18 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-# alias dusize=du
+# SYNOPSIS
+#   dusize [dir]
+#
+# DESCRIPTION
+#   Shows a human-readable disk usage summary using du -sh. Defaults to the
+#   current directory if no argument is given.
+#
+# ARGUMENTS
+#   dir  Directory to summarize (defaults to current directory)
+#
+# EXAMPLE
+#   dusize ~/Downloads
 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,7 +1,18 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-# alias edit=nvim
+# SYNOPSIS
+#   edit [args...]
+#
+# DESCRIPTION
+#   Opens files in nvim, falling back to $EDITOR, nano, or vi if nvim is not
+#   installed.
+#
+# ARGUMENTS
+#   args...  Files and options forwarded to the editor
+#
+# EXAMPLE
+#   edit ~/.config/fish/config.fish
 function edit --wraps='nvim' --description 'alias edit=nvim'
     if type -q nvim
         nvim $argv

functions/fast-cli.fish

@@ -1,7 +1,17 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-# Run a speed test using fast.com
+# SYNOPSIS
+#   fast-cli [args...]
+#
+# DESCRIPTION
+#   Runs a network speed test using the fast.com CLI tool.
+#
+# ARGUMENTS
+#   args...  Arguments forwarded to the fast command
+#
+# EXAMPLE
+#   fast-cli
 function fast-cli --description "Run a speed test using fast.com"
     command fast $argv
 end

functions/fast.fish

@@ -23,7 +23,15 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-# Placeholder for a future implementation of a "fast" function
+# SYNOPSIS
+#   fast
+#
+# DESCRIPTION
+#   Displays a styled message indicating that the fast command is unavailable
+#   and suggests using fast-cli instead.
+#
+# EXAMPLE
+#   fast
 function fast --description 'Placeholder for future fast utility'
     # ANSI Escape Codes (Standard 16-color palette)
     set -l bold "\e[1m"

functions/ffetch.fish

@@ -1,7 +1,18 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-# alias ffetch=fastfetch
+# SYNOPSIS
+#   ffetch [args...]
+#
+# DESCRIPTION
+#   Alias for fastfetch that loads a custom config from ~/.fastfetch.jsonc when
+#   present. Falls back to neofetch if fastfetch is not installed.
+#
+# ARGUMENTS
+#   args...  Arguments forwarded to fastfetch or neofetch
+#
+# EXAMPLE
+#   ffetch
 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-deps.fish

@@ -1,6 +1,25 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
+# SYNOPSIS
+#   fish-deps [status|install|update|sync]
+#
+# DESCRIPTION
+#   Manages fish shell dependencies by dispatching to subcommand handlers.
+#   Defaults to status when no subcommand is given.
+#
+# ARGUMENTS
+#   status   Report installed/missing deps (default)
+#   install  Install missing deps interactively
+#   update   Update all installed deps
+#   sync     Install missing deps, then update all
+#
+# RETURNS
+#   0  Subcommand completed
+#   1  Unknown subcommand
+#
+# EXAMPLE
+#   fish-deps sync
 function fish-deps --description 'Manage fish shell dependencies'
     set -l subcmd $argv[1]
 
@@ -27,6 +46,14 @@ function fish-deps --description 'Manage fish shell dependencies'
     end
 end
 
+# SYNOPSIS
+#   __fish_deps_help
+#
+# DESCRIPTION
+#   Prints usage and subcommand reference for the fish-deps command to stdout.
+#
+# EXAMPLE
+#   __fish_deps_help
 function __fish_deps_help
     set_color cyan; echo "fish-deps — manage fish shell dependencies"; set_color normal
     echo ""

functions/fish_right_prompt.fish

@@ -1,7 +1,15 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-# Execute fish_right_prompt
+# SYNOPSIS
+#   fish_right_prompt
+#
+# DESCRIPTION
+#   Renders the right-side prompt showing the active Docker context (in blue,
+#   when non-default) and the current timestamp.
+#
+# EXAMPLE
+#   # Rendered automatically by Fish shell; not called directly.
 function fish_right_prompt --description 'Execute fish_right_prompt'
     # 1. Docker Context in Blue
     set -l docker_ctx (docker context show 2>/dev/null)

functions/fzf-update.fish

@@ -1,7 +1,15 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-# Installs or upgrades fzf from git HEAD into ~/.fzf
+# SYNOPSIS
+#   fzf-update
+#
+# DESCRIPTION
+#   Installs or upgrades fzf from git HEAD into ~/.fzf. Pulls the latest
+#   changes if ~/.fzf already exists, or clones the repository if not.
+#
+# EXAMPLE
+#   fzf-update
 function fzf-update --description 'Install or upgrade fzf from git HEAD'
     if test -d ~/.fzf
         echo "Updating fzf..."

functions/fzf_configure_bindings.fish

@@ -1,8 +1,30 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-# Always installs bindings for insert and default mode for simplicity and b/c it has almost no side-effect
-# https://gitter.im/fish-shell/fish-shell?at=60a55915ee77a74d685fa6b1
+# SYNOPSIS
+#   fzf_configure_bindings [--directory=<key>] [--git_log=<key>] [--git_status=<key>]
+#                          [--history=<key>] [--processes=<key>] [--variables=<key>] [-h]
+#
+# DESCRIPTION
+#   Installs key bindings for fzf.fish in both insert and default vi modes.
+#   Each binding can be overridden with a custom key or disabled by passing an
+#   empty string. Only runs in interactive mode.
+#
+# ARGUMENTS
+#   --directory=key   Override the directory search binding (default: Ctrl-Alt-F)
+#   --git_log=key     Override the git log search binding (default: Ctrl-Alt-L)
+#   --git_status=key  Override the git status binding (default: Ctrl-Alt-S)
+#   --history=key     Override the history search binding (default: Ctrl-R)
+#   --processes=key   Override the processes search binding (default: Ctrl-Alt-P)
+#   --variables=key   Override the variables search binding (default: Ctrl-V)
+#   -h, --help        Show help message
+#
+# RETURNS
+#   0  Bindings installed or help shown
+#   22 Invalid option or positional argument provided
+#
+# EXAMPLE
+#   fzf_configure_bindings --history=ctrl-h
 function fzf_configure_bindings --description "Installs the default key bindings for fzf.fish with user overrides passed as options."
     # no need to install bindings if not in interactive mode or running tests
     status is-interactive || test "$CI" = true; or return

functions/gi.fish

@@ -1,7 +1,29 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-# Generate .gitignore files using the gitignore.io API
+# SYNOPSIS
+#   gi [-h] [-b] [-p] [-s] [targets...]
+#
+# DESCRIPTION
+#   Generates .gitignore content by querying the gitignore.io API. Appends
+#   results to the repository's .gitignore with MD5-based deduplication, or
+#   prints to stdout with -s. Supports boilerplate and interactive prompt modes.
+#
+# ARGUMENTS
+#   -h, --help         Show help message
+#   -d, --description  Show the function description
+#   -l, --list         List all supported targets from the API
+#   -b, --boilerplate  Append boilerplate from $GITIGNORE_BOILERPLATE
+#   -p, --prompt       Prompt for patterns to append
+#   -s, --stdout       Print API output to stdout instead of .gitignore
+#   targets            Comma-separated list of language/tool names
+#
+# RETURNS
+#   0  Patterns appended or printed
+#   1  Not in a git repository or API fetch failed
+#
+# EXAMPLE
+#   gi python,venv
 function gi --description 'Generate .gitignore files using the gitignore.io API'
     argparse h/help d/description l/list b/boilerplate p/prompt s/stdout -- $argv
     or return 1
@@ -163,8 +185,21 @@ function gi --description 'Generate .gitignore files using the gitignore.io API'
     end
 end
 
-# Append API content to .gitignore with MD5-based deduplication.
-# Args: content, label, gitignore_path, readable_path
+# SYNOPSIS
+#   __gi_append_dedup <content> <label> <gitignore_path> <readable_path>
+#
+# DESCRIPTION
+#   Appends gitignore content to a .gitignore file using MD5-based deduplication.
+#   Skips the append if an identical content block is already present.
+#
+# ARGUMENTS
+#   content         The gitignore pattern content to append
+#   label           Human-readable label for the pattern set
+#   gitignore_path  Absolute path to the .gitignore file
+#   readable_path   Home-abbreviated path shown in output messages
+#
+# EXAMPLE
+#   __gi_append_dedup "$content" "python" "$root/.gitignore" "~/.gitignore"
 function __gi_append_dedup
     set -l content $argv[1]
     set -l label $argv[2]

functions/gip.fish

@@ -1,7 +1,15 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-# Show all public IP addresses
+# SYNOPSIS
+#   gip
+#
+# DESCRIPTION
+#   Fetches and prints both the public IPv4 and IPv6 addresses using
+#   icanhazip.com. Shows "Not detected" for any address that times out.
+#
+# EXAMPLE
+#   gip
 function gip --description 'Show all public IP addresses'
     echo -n "IPv4: "
     curl -4 -s --max-time 2 https://icanhazip.com || echo "Not detected"

functions/gip4.fish

@@ -1,7 +1,14 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-# Get public IPv4 address
+# SYNOPSIS
+#   gip4
+#
+# DESCRIPTION
+#   Fetches and prints the machine's public IPv4 address using icanhazip.com.
+#
+# EXAMPLE
+#   gip4
 function gip4 --wraps='curl' --description 'Get public IPv4 address'
     curl -4 -s https://icanhazip.com
 end

functions/gip6.fish

@@ -1,7 +1,19 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-# Get public IPv6 address
+# SYNOPSIS
+#   gip6
+#
+# DESCRIPTION
+#   Fetches and prints the machine's public IPv6 address using icanhazip.com.
+#   Prints an error message if IPv6 is unavailable on the current network.
+#
+# RETURNS
+#   0  IPv6 address printed
+#   1  IPv6 unavailable or not supported on this network
+#
+# EXAMPLE
+#   gip6
 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,7 +1,24 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-# Sync main, prune remotes, and delete orphaned branches
+# SYNOPSIS
+#   git-clean [-h] [-f]
+#
+# DESCRIPTION
+#   Fetches and prunes the remote, updates the current branch, and deletes
+#   local branches whose tracking remote has been deleted. Automatically moves
+#   to main if currently on an orphaned branch.
+#
+# ARGUMENTS
+#   -h, --help   Show help message
+#   -f, --force  Force-delete unmerged orphaned branches (git branch -D)
+#
+# RETURNS
+#   0  Cleanup complete
+#   1  Argument parsing failed
+#
+# EXAMPLE
+#   git-clean --force
 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,18 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-# alias gitui=gitui -t mocha.ron
+# SYNOPSIS
+#   gitui [args...]
+#
+# DESCRIPTION
+#   Launches gitui with the Catppuccin Frappe theme (frappe.ron), passing any
+#   additional arguments through to the gitui command.
+#
+# ARGUMENTS
+#   args...  Arguments forwarded to the gitui command
+#
+# EXAMPLE
+#   gitui
 function gitui --wraps='gitui' --description 'alias gitui=gitui -t mocha.ron'
     command gitui -t frappe.ron $argv
 

functions/hist.fish

@@ -1,7 +1,15 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-# Search fish history and put it in the prompt
+# SYNOPSIS
+#   hist
+#
+# DESCRIPTION
+#   Searches fish history interactively using fzf, inserts the selected command
+#   into the command line, and copies it to the clipboard via wl-copy.
+#
+# EXAMPLE
+#   hist
 function hist --description 'Search fish history and put it in the prompt'
     set -l selected (history | fzf --reverse --height 40% --with-nth 3..)
 

functions/joplin.fish

@@ -1,7 +1,22 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-# Run joplin CLI without Node deprecation warnings
+# SYNOPSIS
+#   joplin [args...]
+#
+# DESCRIPTION
+#   Runs the Joplin CLI with Node deprecation warnings suppressed via
+#   NODE_OPTIONS=--no-deprecation.
+#
+# ARGUMENTS
+#   args...  Arguments forwarded to the joplin command
+#
+# RETURNS
+#   0  Joplin ran successfully
+#   1  joplin binary not found in PATH
+#
+# EXAMPLE
+#   joplin ls
 function joplin --description 'Run Joplin CLI without Node deprecation warnings'
     set -l joplin_path (command -v joplin)
     if test -n "$joplin_path"

functions/lD.fish

@@ -1,7 +1,18 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-# List directories only
+# SYNOPSIS
+#   lD [args...]
+#
+# DESCRIPTION
+#   Lists only directories in long format with icons and hyperlinks. Uses eza,
+#   falls back to lsd, then to system ls.
+#
+# ARGUMENTS
+#   args...  Arguments forwarded to the listing command
+#
+# EXAMPLE
+#   lD ~/projects
 function lD --description 'List directories only'
     if which eza >/dev/null 2>&1
         eza --only-dirs --long --icons --color=auto --hyperlink $argv

functions/ld.fish

@@ -1,7 +1,15 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-# Run lazydocker on the current Docker context
+# SYNOPSIS
+#   ld
+#
+# DESCRIPTION
+#   Launches lazydocker targeting the currently active Docker context by
+#   resolving the host endpoint from docker context inspect.
+#
+# EXAMPLE
+#   ld
 function ld --description 'Run lazydocker on the current Docker context'
     # Fetch the host endpoint of the currently active Docker context
     set -l current_host (docker context inspect --format '{{.Endpoints.docker.Host}}')

functions/less.fish

@@ -1,6 +1,18 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
+# SYNOPSIS
+#   less [args...]
+#
+# DESCRIPTION
+#   Pager wrapper that tries $PAGER, then ov, then less, then more, then cat
+#   as fallbacks in that order.
+#
+# ARGUMENTS
+#   args...  Files or options forwarded to the pager
+#
+# EXAMPLE
+#   less /var/log/syslog
 function less --wraps='ov' --description 'Pager wrapper: $PAGER → ov → less → more → cat'
     if set -q PAGER; and command -q $PAGER
         command $PAGER $argv

functions/limine-edit.fish

@@ -1,7 +1,16 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-# Safely edit and re-verify Limine configuration
+# SYNOPSIS
+#   limine-edit
+#
+# DESCRIPTION
+#   Opens /boot/limine.conf in sudoedit, then re-enrolls the config hash,
+#   runs CachyOS boot hooks (limine-mkinitcpio), and re-signs all Secure Boot
+#   files tracked by sbctl.
+#
+# EXAMPLE
+#   limine-edit
 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,7 +1,14 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-# alias lock=loginctl
+# SYNOPSIS
+#   lock
+#
+# DESCRIPTION
+#   Locks the current desktop session using loginctl lock-session.
+#
+# EXAMPLE
+#   lock
 function lock --wraps='loginctl' --description 'alias lock=loginctl'
     loginctl lock-session
 end

functions/logs.fish

@@ -1,6 +1,23 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
+# SYNOPSIS
+#   logs [-h] [-c <category>]
+#
+# DESCRIPTION
+#   Interactively browses terminal log files (scrollback, paru, yay) sorted
+#   newest-first using fzf. Supports viewing in $PAGER, editing, and deletion.
+#
+# ARGUMENTS
+#   -h, --help           Show help message
+#   -c, --category cat   Filter to one category: scrollback, paru, or yay
+#
+# RETURNS
+#   0  File viewed or no file selected
+#   1  No log files found
+#
+# EXAMPLE
+#   logs -c paru
 function logs --description 'Browse terminal log files interactively with fzf'
     set -l options h/help c/category=
     argparse $options -- $argv

functions/ls.fish

@@ -1,7 +1,18 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-# List all files
+# SYNOPSIS
+#   ls [args...]
+#
+# DESCRIPTION
+#   Lists all files in long format with icons and hyperlinks. Uses eza,
+#   falls back to lsd, then to system ls.
+#
+# ARGUMENTS
+#   args...  Arguments forwarded to the listing command
+#
+# EXAMPLE
+#   ls ~/projects
 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,7 +1,18 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-# Reversed time-sorted listing
+# SYNOPSIS
+#   lsr [args...]
+#
+# DESCRIPTION
+#   Lists files sorted by modification time in reverse (oldest first), one
+#   per line with icons. Uses eza, falls back to lsd, then to system ls.
+#
+# ARGUMENTS
+#   args...  Arguments forwarded to the listing command
+#
+# EXAMPLE
+#   lsr ~/projects
 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,7 +1,18 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-# Size-sorted listing
+# SYNOPSIS
+#   lss [args...]
+#
+# DESCRIPTION
+#   Lists all files sorted by size in long format with gradient color scaling.
+#   Uses eza, falls back to lsd, then to system ls.
+#
+# ARGUMENTS
+#   args...  Arguments forwarded to the listing command
+#
+# EXAMPLE
+#   lss ~/downloads
 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,7 +1,18 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-# Full recursive tree listing
+# SYNOPSIS
+#   lstree [args...]
+#
+# DESCRIPTION
+#   Displays a full recursive tree of the current directory with icons.
+#   Uses eza, falls back to lsd, then to system ls -R.
+#
+# ARGUMENTS
+#   args...  Arguments forwarded to the listing command
+#
+# EXAMPLE
+#   lstree ~/projects/myapp
 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,7 +1,18 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-# Tree listing, depth 2
+# SYNOPSIS
+#   lt [args...]
+#
+# DESCRIPTION
+#   Displays a directory tree limited to depth 2 with icons. Uses eza,
+#   falls back to lsd, then to system ls -R.
+#
+# ARGUMENTS
+#   args...  Arguments forwarded to the listing command
+#
+# EXAMPLE
+#   lt ~/projects
 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,7 +1,19 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-# Reversed time-sorted listing
+# SYNOPSIS
+#   ltr [args...]
+#
+# DESCRIPTION
+#   Lists all files sorted by modification time in reverse (oldest first) in
+#   long format with age-based gradient color scaling. Uses eza, falls back
+#   to lsd, then to system ls.
+#
+# ARGUMENTS
+#   args...  Arguments forwarded to the listing command
+#
+# EXAMPLE
+#   ltr ~/projects
 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,7 +1,18 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-# Extension-sorted listing
+# SYNOPSIS
+#   lx [args...]
+#
+# DESCRIPTION
+#   Lists all files sorted by file extension in long format with icons. Uses
+#   eza, falls back to lsd, then to system ls -lX.
+#
+# ARGUMENTS
+#   args...  Arguments forwarded to the listing command
+#
+# EXAMPLE
+#   lx ~/projects
 function lx --description 'Extension-sorted listing'
     if which eza >/dev/null 2>&1
         eza --long --all --sort=extension --icons --color=auto --hyperlink $argv

functions/mkcd.fish

@@ -1,6 +1,26 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
+# SYNOPSIS
+#   mkcd [-s | --silent] <dir>
+#
+# DESCRIPTION
+#   Creates a directory (including any missing parent directories) and
+#   immediately changes into it. Prints a tree of created directories by
+#   default, or suppresses output with -s. Delegates creation to
+#   _fish_mkdir_p.
+#
+# ARGUMENTS
+#   -h, --help    Show usage help
+#   -s, --silent  Suppress directory creation output
+#   <dir>         Directory to create and enter
+#
+# RETURNS
+#   0  Directory created (or already existed) and entered successfully
+#   1  Directory creation or cd failed
+#
+# EXAMPLE
+#   mkcd ~/projects/myapp
 function mkcd --description 'Create a directory (with parents) and cd into it'
     set -l c_head (set_color --bold cyan)
     set -l c_cmd  (set_color --bold white)

functions/mkdir.fish

@@ -1,7 +1,20 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-# Execute mkdir
+# SYNOPSIS
+#   mkdir [args...]
+#
+# DESCRIPTION
+#   Interactive wrapper around mkdir that calls _fish_mkdir_p for each
+#   directory argument to display created path components. Falls back to
+#   command mkdir -p when flags (e.g. -m 755) are present, and to plain
+#   command mkdir in non-interactive contexts.
+#
+# ARGUMENTS
+#   args...  Directories to create, or flags passed through to command mkdir
+#
+# EXAMPLE
+#   mkdir ~/projects/myapp/src
 function mkdir --description 'Execute mkdir'
     if status is-interactive
         # Fall back to command mkdir -p when flags are present (e.g. -m 755)

functions/p.fish

@@ -1,7 +1,24 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-# Put from clipboard
+# SYNOPSIS
+#   p [args...]
+#
+# DESCRIPTION
+#   Outputs clipboard contents to stdout. Uses wl-paste on Wayland,
+#   falls back to xclip on X11. Supports -h/--help for usage info.
+#
+# ARGUMENTS
+#   -h, --help  Show usage help
+#   args...     Arguments forwarded to the clipboard tool
+#
+# RETURNS
+#   0  Clipboard contents printed successfully
+#   1  No supported clipboard tool found
+#
+# EXAMPLE
+#   p | grep foo
+#   p > file.txt
 function p --description 'Put from clipboard'
     # Check for help flag
     if contains -- -h $argv; or contains -- --help $argv

functions/parur.fish

@@ -1,7 +1,19 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-# Interactively search and remove an installed package using fzf
+# SYNOPSIS
+#   parur
+#
+# DESCRIPTION
+#   Presents an fzf picker of all installed packages (via pacman -Qqs) with
+#   pacman -Qi previews, then removes the selected packages using paru or yay.
+#
+# RETURNS
+#   0  Packages removed or none selected
+#   1  No AUR helper (paru or yay) found
+#
+# EXAMPLE
+#   parur
 function parur --description 'Interactively search and remove an installed package using fzf'
     set -l aur ""
     if type -q paru

functions/paste.fish

@@ -1,7 +1,22 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-# Paste from clipboard
+# SYNOPSIS
+#   paste [args...]
+#
+# DESCRIPTION
+#   Outputs clipboard contents to stdout. Uses wl-paste on Wayland,
+#   falls back to xclip on X11.
+#
+# ARGUMENTS
+#   args...  Arguments forwarded to the clipboard tool
+#
+# RETURNS
+#   0  Clipboard contents printed successfully
+#   1  No supported clipboard tool found
+#
+# EXAMPLE
+#   paste > file.txt
 function paste --description 'Paste from clipboard'
     if type -q wl-paste
         wl-paste $argv

functions/ping.fish

@@ -1,7 +1,21 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-# prettyping with default nolegend
+# SYNOPSIS
+#   ping [args...]
+#
+# DESCRIPTION
+#   Wraps prettyping with --nolegend by default for a cleaner display.
+#   Pass --legend to show the legend. Falls back to system ping if
+#   prettyping is not installed.
+#
+# ARGUMENTS
+#   --legend  Show the prettyping legend (overrides default --nolegend)
+#   args...   Arguments forwarded to prettyping or system ping
+#
+# EXAMPLE
+#   ping google.com
+#   ping --legend google.com
 function ping --description 'prettyping with default nolegend'
     if command -q prettyping
         # Check if the user specifically asked for the legend

functions/pkg.fish

@@ -1,6 +1,25 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
+# SYNOPSIS
+#   pkg [-h] [-i|-u] <package> [package...]
+#
+# DESCRIPTION
+#   Installs or removes Arch Linux packages via paru or yay. In auto mode
+#   (no flag), detects whether each package is installed and toggles it.
+#
+# ARGUMENTS
+#   -h, --help       Show help message
+#   -i, --install    Force install mode
+#   -u, --uninstall  Force uninstall mode
+#   package          One or more package names to install or remove
+#
+# RETURNS
+#   0  Operation completed
+#   1  No AUR helper found, unknown flag, or package operation failed
+#
+# EXAMPLE
+#   pkg firefox
 function pkg --description 'Install or remove packages via paru or yay'
     # ── AUR helper detection ─────────────────────────────────────
     set -l aur ""

functions/poke.fish

@@ -1,6 +1,22 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
+# SYNOPSIS
+#   poke <file> [file...]
+#
+# DESCRIPTION
+#   Creates files using touch, automatically creating any missing parent
+#   directories via _fish_mkdir_p with tree output.
+#
+# ARGUMENTS
+#   file  One or more file paths to create
+#
+# RETURNS
+#   0  Files created
+#   1  No file argument provided
+#
+# EXAMPLE
+#   poke ~/projects/new/src/main.fish
 function poke --description 'touch with automatic parent directory creation'
     if test (count $argv) -eq 0
         echo (set_color red)"poke: no file specified"(set_color normal) >&2

functions/ports.fish

@@ -1,7 +1,15 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-# Show active network listeners
+# SYNOPSIS
+#   ports
+#
+# DESCRIPTION
+#   Lists all active TCP listeners on the system using lsof, showing
+#   port numbers and addresses without hostname resolution.
+#
+# EXAMPLE
+#   ports
 function ports --wraps='sudo' --description 'Show active network listeners'
     sudo lsof -iTCP -sTCP:LISTEN -P -n
 end

functions/qr.fish

@@ -1,7 +1,20 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-# Generate a QR code from text or pipe
+# SYNOPSIS
+#   qr [text...]
+#
+# DESCRIPTION
+#   Generates a UTF-8 QR code from the given text or from stdin if no
+#   argument is provided. Uses qrencode locally if available, otherwise
+#   falls back to the qrenco.de API via curl.
+#
+# ARGUMENTS
+#   text...  Text to encode; reads from stdin if omitted
+#
+# EXAMPLE
+#   qr "https://example.com"
+#   echo "hello" | qr
 function qr --description 'Generate a QR code from text or pipe'
     if type -q qrencode
         if set -q argv[1]

functions/rawfish.fish

@@ -1,7 +1,18 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-# alias rawfish=env NO_TMUX=1 fish
+# SYNOPSIS
+#   rawfish [args...]
+#
+# DESCRIPTION
+#   Launches a Fish shell with NO_TMUX=1 set, bypassing any tmux
+#   auto-attach or session management hooks.
+#
+# ARGUMENTS
+#   args...  Arguments forwarded to fish
+#
+# EXAMPLE
+#   rawfish
 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,24 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-# Run Bash commands replaying changes in Fish
+# SYNOPSIS
+#   replay <commands>
+#
+# DESCRIPTION
+#   Runs the given commands in Bash and replays any resulting environment
+#   variable, alias, and directory changes back into the current Fish
+#   session. Useful for sourcing Bash-only scripts.
+#
+# ARGUMENTS
+#   commands  Bash command string to execute and replay
+#
+# RETURNS
+#   0  Commands ran successfully and changes were replayed
+#   1  Bash command exited with a non-zero status
+#
+# EXAMPLE
+#   replay "source ~/.bashrc"
+#   replay "export FOO=bar"
 function replay --description 'Run Bash commands replaying changes in Fish'
     switch "$argv"
         case -v --version

functions/rg.fish

@@ -1,7 +1,19 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-# alias rg=rg --hyperlink-format=kitty
+# SYNOPSIS
+#   rg [args...]
+#
+# DESCRIPTION
+#   Wraps ripgrep with --hyperlink-format=kitty when running inside Kitty
+#   terminal, enabling clickable file links in search results. Falls back
+#   to plain rg on other terminals.
+#
+# ARGUMENTS
+#   args...  Arguments forwarded to ripgrep
+#
+# EXAMPLE
+#   rg "TODO" src/
 function rg --description 'alias rg=rg --hyperlink-format=kitty'
     if test "$TERM" = xterm-kitty
         command rg --hyperlink-format=kitty $argv

functions/rm.fish

@@ -1,7 +1,31 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-# Ultimate rm: trash, list, empty, and secure-erase
+# SYNOPSIS
+#   rm [-e [options] | -S | args...]
+#
+# DESCRIPTION
+#   Enhanced rm that routes deletions through trash when safe. With no
+#   arguments, lists current trash contents. -e/--empty empties the trash
+#   (with optional trash-empty sub-arguments). -S/--secure permanently
+#   deletes via rm -rf and triggers fstrim. Plain paths and -r/-R are sent
+#   to trash put; any other flags fall back to system rm.
+#
+# ARGUMENTS
+#   (none)              List current trash contents
+#   -e, --empty [opts]  Empty the trash; opts forwarded to trash empty
+#   -S, --secure        Permanently delete targets and run fstrim
+#   -r, -R, --recursive Forwarded to trash put alongside path arguments
+#   args...             Files or paths to trash or remove
+#
+# RETURNS
+#   0  Operation succeeded
+#   1  trash put failed or file not found
+#
+# EXAMPLE
+#   rm file.txt
+#   rm -e
+#   rm -S sensitive_key.pem
 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,19 +1,25 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-###############################################################################
-# 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.
+# SYNOPSIS
+#   sbver [--brief]
 #
-# Arguments:
-#   --brief : Suppresses individual file status and only shows the final summary.
-###############################################################################
-
+# DESCRIPTION
+#   Verifies Secure Boot signatures on all EFI binaries tracked by sbctl,
+#   filtering out "invalid PE header" noise. Color-codes each file as
+#   verified (green ✓) or unsigned (red ✗) and prints a final summary
+#   count.
+#
+# ARGUMENTS
+#   --brief  Suppress per-file output; show only the final summary
+#
+# RETURNS
+#   0  All binaries verified (or summary shown)
+#   1  sbctl is not installed
+#
+# EXAMPLE
+#   sbver
+#   sbver --brief
 function sbver --description 'Verifies Secure Boot status of EFI binaries using sbctl'
   if not type -q sbctl
     echo "Error: 'sbctl' is not installed."

functions/screensleep.fish

@@ -1,7 +1,15 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-# Turn off the display using KDE PowerDevil
+# SYNOPSIS
+#   screensleep
+#
+# DESCRIPTION
+#   Turns off the display after a 1-second delay by invoking the KDE
+#   PowerDevil "Turn Off Screen" global shortcut via busctl.
+#
+# EXAMPLE
+#   screensleep
 function screensleep --description 'Turn off the display using KDE PowerDevil'
     # Optional: 1-second delay to ensure no keystrokes wake it immediately
     sleep 1

functions/scrub.fish

@@ -1,6 +1,29 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
+# SYNOPSIS
+#   scrub [-a] [-d] [-h]
+#
+# DESCRIPTION
+#   Recursively finds and removes OS metadata, editor artifacts, compiler
+#   garbage, and dev caches from the current directory using fd. Routes
+#   deletions through the custom rm function, trashy, trash-cli, or system
+#   rm -rf in that priority order. Aggressive mode adds node_modules, logs,
+#   IDE directories, and AI tool artifacts.
+#
+# ARGUMENTS
+#   -a, --aggressive  Also purge node_modules, *.log, .idea, AI artifacts
+#   -d, --dry-run     Show targets without deleting
+#   -h, --help        Show usage help
+#
+# RETURNS
+#   0  Sweep completed (or dry run shown)
+#   1  fd not found, or unknown argument provided
+#
+# EXAMPLE
+#   scrub
+#   scrub -a
+#   scrub -d
 function scrub --description 'Recursively purge OS, editor, and compiler garbage files/folders from the current directory'
     # Define the base garbage patterns (matches files and directory names)
     set -l garbage_patterns \

functions/search.fish

@@ -1,6 +1,22 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
+# SYNOPSIS
+#   search [args...]
+#
+# DESCRIPTION
+#   Delegates to paru or yay for interactive AUR package search and
+#   installation. Falls back to yay if paru is not installed.
+#
+# ARGUMENTS
+#   args...  Arguments forwarded to paru or yay
+#
+# RETURNS
+#   0  AUR helper ran successfully
+#   1  No AUR helper (paru or yay) found
+#
+# EXAMPLE
+#   search neovim
 function search --description 'Search/install packages interactively via paru or yay'
     set -l aur ""
     if type -q paru

functions/smart_exit.fish

@@ -1,7 +1,24 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-# Function to capture colorized scrollback before exiting, with pruning and safe overrides
+# SYNOPSIS
+#   smart_exit [-h] [-n]
+#
+# DESCRIPTION
+#   Closes the shell session, capturing and archiving the terminal scrollback
+#   log before exit (Kitty only). Automatically prunes junk and excess log
+#   files according to $SCROLLBACK_HISTORY_MAX_FILES.
+#
+# ARGUMENTS
+#   -h, --help    Show help message
+#   -n, --no-log  Exit without saving a scrollback log
+#
+# RETURNS
+#   0  Shell session exited
+#   1  Argument parsing failed
+#
+# EXAMPLE
+#   smart_exit --no-log
 function smart_exit --description 'Capture colorized scrollback before exiting, with pruning and safe overrides'
     set -l options h/help n/no-log
     argparse $options -- $argv

functions/spark.fish

@@ -1,7 +1,24 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-# Sparklines
+# SYNOPSIS
+#   spark [--min=<n>] [--max=<n>] [numbers...]
+#
+# DESCRIPTION
+#   Renders a Unicode sparkline bar chart for a sequence of numbers.
+#   Reads numbers from arguments or from stdin if none are provided.
+#   Optional --min and --max clamp the scale range.
+#
+# ARGUMENTS
+#   --min=<n>   Minimum value for scale (default: list minimum)
+#   --max=<n>   Maximum value for scale (default: list maximum)
+#   numbers...  Space-separated numbers to chart; reads stdin if omitted
+#   -v, --version  Print version
+#   -h, --help     Show usage help
+#
+# EXAMPLE
+#   spark 1 1 2 5 14 42
+#   seq 64 | sort --random-sort | spark
 function spark --description 'Sparklines'
     argparse --ignore-unknown --name=spark v/version h/help m/min= M/max= -- $argv || return
 

functions/split.fish

@@ -1,7 +1,27 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-# Run a command in a new terminal split
+# SYNOPSIS
+#   split [-h | -v] [command...]
+#
+# DESCRIPTION
+#   Opens a new pane split in Kitty or WezTerm, optionally running a
+#   command in it. Defaults to a horizontal (bottom) split. The new pane
+#   inherits the current working directory.
+#
+# ARGUMENTS
+#   -h, --horizontal  Open a horizontal split (default)
+#   -v, --vertical    Open a vertical split
+#   command...        Command to run in the new pane; opens a bare fish
+#                     shell if omitted
+#
+# RETURNS
+#   0  Pane opened successfully
+#   1  Not running inside Kitty or WezTerm
+#
+# EXAMPLE
+#   split
+#   split -v nvim README.md
 function split --description 'Run a command in a new terminal split'
     set -l is_kitty 0
     set -l is_wezterm 0

functions/spwin.fish

@@ -1,7 +1,22 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-# spawn window in kitty or wezterm
+# SYNOPSIS
+#   spwin [args...]
+#
+# DESCRIPTION
+#   Spawns a new terminal OS window in Kitty (via spawn-window.sh if
+#   present, otherwise kitty @ launch) or WezTerm (via wezterm cli spawn).
+#
+# ARGUMENTS
+#   args...  Arguments forwarded to the spawn command
+#
+# RETURNS
+#   0  Window opened successfully
+#   1  Not running inside Kitty or WezTerm
+#
+# EXAMPLE
+#   spwin
 function spwin --wraps='~/.config/kitty/spawn-window.sh' --description 'spawn window in kitty or wezterm'
     if test "$TERM" = xterm-kitty
         if test -x ~/.config/kitty/spawn-window.sh

functions/ssh.fish

@@ -1,7 +1,19 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-# Alias ssh to kitten ssh when using Kitty terminal
+# SYNOPSIS
+#   ssh [args...]
+#
+# DESCRIPTION
+#   Wraps ssh with kitten ssh inside Kitty terminal for better terminal
+#   integration (e.g. terminfo forwarding). Falls back to system ssh on
+#   other terminals.
+#
+# ARGUMENTS
+#   args...  Arguments forwarded to kitten ssh or system ssh
+#
+# EXAMPLE
+#   ssh user@host
 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,7 +1,15 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-# Run Steam while inhibiting system sleep
+# SYNOPSIS
+#   steam-dl
+#
+# DESCRIPTION
+#   Launches Steam with systemd-inhibit to prevent the system from idling
+#   or sleeping during active downloads.
+#
+# EXAMPLE
+#   steam-dl
 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,27 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-# Toggle superpowers extension for antigravity-cli and Claude
+# SYNOPSIS
+#   superpowers [on|off] [-g]
+#
+# DESCRIPTION
+#   Enables or disables the superpowers plugin for both antigravity-cli
+#   (workspace scope) and Claude (project scope). Use -g/--global to apply
+#   at the user scope instead of workspace/project.
+#
+# ARGUMENTS
+#   on            Enable superpowers for both tools
+#   off           Disable superpowers for both tools
+#   -g, --global  Apply at user/global scope instead of workspace/project
+#   -h, --help    Show usage help
+#
+# RETURNS
+#   0  Mode applied successfully
+#   1  No on/off mode specified
+#
+# EXAMPLE
+#   superpowers on
+#   superpowers off -g
 function superpowers --description 'Toggle superpowers extension for antigravity-cli and Claude'
     set -l scope_agy workspace
     set -l scope_claude project

functions/swapstat.fish

@@ -1,7 +1,16 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-# View colorized zRAM and swappiness status
+# SYNOPSIS
+#   swapstat
+#
+# DESCRIPTION
+#   Displays a colorized memory report showing kernel swappiness,
+#   zRAM compression ratio, zRAM device details (via zramctl), and
+#   active swap priority (via swapon).
+#
+# EXAMPLE
+#   swapstat
 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,23 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-# Spawn a new tab in the current terminal
+# SYNOPSIS
+#   tab [args...]
+#
+# DESCRIPTION
+#   Opens a new tab in Kitty, WezTerm, or Konsole using the current
+#   working directory (or $cdto if set). Arguments are forwarded to the
+#   terminal's tab-open command.
+#
+# ARGUMENTS
+#   args...  Arguments forwarded to the terminal's launch command
+#
+# RETURNS
+#   0  Tab opened successfully
+#   1  No supported terminal found
+#
+# EXAMPLE
+#   tab
 function tab --description 'Spawn a new tab in the current terminal'
     set -l dir "$cdto"
     if test -z "$dir"