fix: guard and document the external tools PR #168 flagged as unguarded

PR #168's Notes section named several functions with a real
external-tool dependency that no `type -q`/`command -q`/`command -v`/
`which` guard covers anywhere in the tree, deliberately left out of
DEPENDENCIES to avoid breaking test_dependencies_resolve. Adds the
guard each was missing, then declares the dependency now that it
resolves:

- bkg, detach: nohup
- gitui: gitui (self-shadow; type -q -f to skip the function itself)
- play-media: mpv, vlc -- already guarded via `type -q -f $p` in a
  loop, just never recognized as one (see next point)
- steam-dl: systemd-inhibit, steam
- wake-lock: systemd-inhibit
- split, spwin, tab: wezterm, konsole (kitty already declared)

docs/verify-manual.py's guard-detection regex only matched `type -q
<name>` immediately, so `type -q -f $p` (the `-f` flag excludes
functions from the match, needed wherever a wrapper shadows a binary
of its own name) was invisible to it -- both as a direct guard and
through the loop-variable indirection. Broadened both patterns to
skip over any flags between `-q` and the name/variable.

split/spwin/tab dispatch on $TERM/$TERM_PROGRAM/$KONSOLE_VERSION to
pick which terminal-specific binary to call, per this repo's C4
convention -- but those env vars only prove the terminal type, not
that its CLI binary is on $PATH: they propagate over ssh, so sshing
out from Kitty/WezTerm inherits the var on a remote host that never
installed the binary. Same latent gap in clone/clonet, whose
clone-in-kitty is a function Kitty's own shell integration injects,
not present on a remote shell that only inherited $TERM. All five now
check the actual thing they are about to call, not just the env var
that selects it.

Also guards and documents three more real, previously-undeclared
dependencies found by the same audit, unrelated to PR #168's named
list but the identical pattern: fast-cli (fast), lock (loginctl),
ports (lsof), screensleep (busctl).

docs/fish-config.md regenerated to match.

docs/fish-config.md

@@ -1026,11 +1026,13 @@ functions). They are active in all interactive sessions.
 
     Exit Status:
       0  Repository cloned
-      1  Not running inside Kitty terminal
+      1  Not running inside Kitty terminal, or clone-in-kitty isn't available
 
     Example:
     clone https://github.com/user/repo.git
 
+**Dependencies:** `clone-in-kitty`
+
 ### clonet
 
     Synopsis:  clonet [args...]
@@ -1043,11 +1045,13 @@ functions). They are active in all interactive sessions.
 
     Exit Status:
       0  Repository cloned
-      1  Not running inside Kitty terminal
+      1  Not running inside Kitty terminal, or clone-in-kitty isn't available
 
     Example:
     clonet https://github.com/user/repo.git
 
+**Dependencies:** `clone-in-kitty`
+
 ## 5.3 Editors and Viewers
 
 ### edit
@@ -1335,9 +1339,17 @@ functions). They are active in all interactive sessions.
     Arguments:
       args...  Arguments forwarded to the gitui command
 
+    Exit Status:
+      1  gitui is not installed
+      *  Exit status of gitui otherwise
+
     Example:
     gitui
 
+**Dependencies:** `gitui`
+
+**Used by:** `gitui`
+
 ### gitup
 
     Synopsis:  gitup [args...]
@@ -1758,11 +1770,14 @@ functions). They are active in all interactive sessions.
     Locks the current desktop session using loginctl lock-session.
 
     Exit Status:
-      Exit status of loginctl lock-session
+      1  loginctl is not installed
+      *  Exit status of loginctl lock-session otherwise
 
     Example:
     lock
 
+**Dependencies:** `loginctl`
+
 ### ports
 
     Synopsis:  ports
@@ -1771,11 +1786,14 @@ functions). They are active in all interactive sessions.
     port numbers and addresses without hostname resolution.
 
     Exit Status:
-      Exit status of lsof
+      1  lsof is not installed
+      *  Exit status of lsof otherwise
 
     Example:
     ports
 
+**Dependencies:** `lsof`
+
 ### sbver
 
     Synopsis:  sbver [--brief]
@@ -1808,11 +1826,14 @@ functions). They are active in all interactive sessions.
     PowerDevil "Turn Off Screen" global shortcut via busctl.
 
     Exit Status:
-      Exit status of busctl
+      1  busctl is not installed
+      *  Exit status of busctl otherwise
 
     Example:
     screensleep
 
+**Dependencies:** `busctl`
+
 ### sudo-toggle
 
     Synopsis:  sudo-toggle
@@ -1880,6 +1901,8 @@ functions). They are active in all interactive sessions.
     Example:
     bkg firefox
 
+**Dependencies:** `nohup`
+
 **Used by:** `md`
 
 ### detach
@@ -1903,6 +1926,8 @@ functions). They are active in all interactive sessions.
     Example:
     detach rsync -a ./data remote:/backup/
 
+**Dependencies:** `nohup`
+
 ### fish_mode_prompt
 
     Synopsis:  fish_mode_prompt
@@ -2035,7 +2060,7 @@ functions). They are active in all interactive sessions.
     split
     split -v nvim README.md
 
-**Dependencies:** `kitty`
+**Dependencies:** `kitty`, `wezterm`
 
 ### spwin
 
@@ -2054,7 +2079,7 @@ functions). They are active in all interactive sessions.
     Example:
     spwin
 
-**Dependencies:** `kitty`
+**Dependencies:** `kitty`, `wezterm`
 
 ### ssh
 
@@ -2093,7 +2118,7 @@ functions). They are active in all interactive sessions.
     Example:
     tab
 
-**Dependencies:** `kitty`
+**Dependencies:** `kitty`, `wezterm`, `konsole`
 
 ## 5.9 Clipboard
 
@@ -2181,6 +2206,8 @@ functions). They are active in all interactive sessions.
     Example:
     fast
 
+**Used by:** `fast-cli`
+
 ### fast-cli
 
     Synopsis:  fast-cli [args...]
@@ -2190,9 +2217,15 @@ functions). They are active in all interactive sessions.
     Arguments:
       args...  Arguments forwarded to the fast command
 
+    Exit Status:
+      1  fast is not installed
+      *  Exit status of fast otherwise
+
     Example:
     fast-cli
 
+**Dependencies:** `fast`
+
 ### gip
 
     Synopsis:  gip
@@ -2992,7 +3025,7 @@ functions). They are active in all interactive sessions.
     play-media
     play-media --player mpv
 
-**Dependencies:** `_fzf_preview_media`, `_fzf_wrapper`, `fd`, `fdfind`, `file`, `xdg-mime`
+**Dependencies:** `_fzf_preview_media`, `_fzf_wrapper`, `fd`, `fdfind`, `file`, `xdg-mime`, `mpv`, `vlc`
 
 ### spark
 
@@ -3022,11 +3055,14 @@ functions). They are active in all interactive sessions.
     or sleeping during active downloads.
 
     Exit Status:
-      Exit status of steam (via systemd-inhibit)
+      1  systemd-inhibit or steam is not installed
+      *  Exit status of steam (via systemd-inhibit) otherwise
 
     Example:
     steam-dl
 
+**Dependencies:** `systemd-inhibit`, `steam`
+
 ### yt-dlp
 
     Synopsis:  yt-dlp [args...] URL [URL...]
@@ -3615,11 +3651,13 @@ functions). They are active in all interactive sessions.
 
     Exit Status:
       0  Command ran and completed
-      1  No command provided
+      1  No command provided, or systemd-inhibit is not installed
 
     Example:
     wake-lock rsync -avz src/ dest/
 
+**Dependencies:** `systemd-inhibit`
+
 # 6. DEPENDENCY CATALOG
 
 `fish-deps` manages these tools. Run `fish-deps` to check status,

docs/verify-manual.py

@@ -211,12 +211,15 @@ def test_dependencies_resolve():
     repo = Path(__file__).parent.parent
     functions = _parsed_functions()
     known = {p.stem for p in (repo / "functions").glob("*.fish")} | set(functions)
-    guard_re = re.compile(r"(?:type -q|command -q|command -v|which)\s+([\w.\-]+)")
+    # `type` takes its own flags (e.g. `-f` to exclude functions from the
+    # match, as in `type -q -f $p`) that can sit between `-q` and the name
+    # -- skip over any of those so the guard is still recognized.
+    guard_re = re.compile(r"(?:type -q(?:\s+-\w+)*|command -q|command -v|which)\s+([\w.\-]+)")
     for path in list(repo.glob("conf.d/*.fish")) + list((repo / "functions").glob("*.fish")):
         text = path.read_text(encoding="utf-8")
         known |= set(guard_re.findall(text))
         for var, names in re.findall(r"for\s+(\w+)\s+in\s+([^\n;]+)", text):
-            if re.search(rf"type -q\s+\$\{{?{re.escape(var)}\}}?\b", text):
+            if re.search(rf"type -q(?:\s+-\w+)*\s+\$\{{?{re.escape(var)}\}}?\b", text):
                 known |= set(names.split())
     dangling = []
     for name, fn in functions.items():

functions/bkg.fish

@@ -4,6 +4,9 @@
 # CATEGORY
 #   08-terminal-management
 #
+# DEPENDENCIES
+#   nohup
+#
 # SYNOPSIS
 #   bkg <command> [args...]
 #
@@ -32,6 +35,11 @@ function bkg --description 'Execute bkg'
         return 1
     end
 
+    if not type -q nohup
+        echo (set_color red)"Error: nohup is not installed."(set_color normal) >&2
+        return 1
+    end
+
     # Run the command using nohup to make it immune to hangups (like closing the terminal).
     # Redirect both stdout and stderr to /dev/null to discard all output.
     # The final ampersand (&) sends the entire process to the background.

functions/clone.fish

@@ -4,6 +4,9 @@
 # CATEGORY
 #   02-navigation
 #
+# DEPENDENCIES
+#   clone-in-kitty
+#
 # SYNOPSIS
 #   clone [args...]
 #
@@ -16,7 +19,7 @@
 #
 # EXIT STATUS
 #   0  Repository cloned
-#   1  Not running inside Kitty terminal
+#   1  Not running inside Kitty terminal, or clone-in-kitty isn't available
 #
 # EXAMPLE
 #   clone https://github.com/user/repo.git
@@ -25,5 +28,12 @@ function clone --wraps='clone-in-kitty' --description 'alias clone=clone-in-kitt
         echo "Error: The 'clone' command requires Kitty terminal." >&2
         return 1
     end
+    # $TERM only proves the terminal type -- clone-in-kitty is a function
+    # Kitty's own shell integration injects, which doesn't happen over an
+    # ssh session that merely inherits $TERM from the local Kitty.
+    if not type -q clone-in-kitty
+        echo "Error: 'clone' detected Kitty but clone-in-kitty isn't available (shell integration not loaded)." >&2
+        return 1
+    end
     clone-in-kitty $argv
 end

functions/clonet.fish

@@ -4,6 +4,9 @@
 # CATEGORY
 #   02-navigation
 #
+# DEPENDENCIES
+#   clone-in-kitty
+#
 # SYNOPSIS
 #   clonet [args...]
 #
@@ -16,7 +19,7 @@
 #
 # EXIT STATUS
 #   0  Repository cloned
-#   1  Not running inside Kitty terminal
+#   1  Not running inside Kitty terminal, or clone-in-kitty isn't available
 #
 # EXAMPLE
 #   clonet https://github.com/user/repo.git
@@ -25,5 +28,12 @@ function clonet --wraps='clone-in-kitty --type=tab' --description 'alias clonet=
         echo "Error: The 'clonet' command requires Kitty terminal." >&2
         return 1
     end
+    # $TERM only proves the terminal type -- clone-in-kitty is a function
+    # Kitty's own shell integration injects, which doesn't happen over an
+    # ssh session that merely inherits $TERM from the local Kitty.
+    if not type -q clone-in-kitty
+        echo "Error: 'clonet' detected Kitty but clone-in-kitty isn't available (shell integration not loaded)." >&2
+        return 1
+    end
     clone-in-kitty --type=tab $argv
 end

functions/detach.fish

@@ -4,6 +4,9 @@
 # CATEGORY
 #   08-terminal-management
 #
+# DEPENDENCIES
+#   nohup
+#
 # SYNOPSIS
 #   detach [-h] [--version] <command> [args...]
 #
@@ -66,5 +69,10 @@ function detach --description 'Execute detach'
         return 1
     end
 
+    if not type -q nohup
+        echo (set_color red)"Error: nohup is not installed."(set_color normal) >&2
+        return 1
+    end
+
     nohup $args >/dev/null 2>&1 &
 end

functions/fast-cli.fish

@@ -4,6 +4,9 @@
 # CATEGORY
 #   10-network
 #
+# DEPENDENCIES
+#   fast
+#
 # SYNOPSIS
 #   fast-cli [args...]
 #
@@ -13,8 +16,16 @@
 # ARGUMENTS
 #   args...  Arguments forwarded to the fast command
 #
+# EXIT STATUS
+#   1  fast is not installed
+#   *  Exit status of fast otherwise
+#
 # EXAMPLE
 #   fast-cli
 function fast-cli --description "Run a speed test using fast.com"
+    if not type -q -f fast
+        echo (set_color red)"Error: fast is not installed."(set_color normal) >&2
+        return 1
+    end
     command fast $argv
 end

functions/gitui.fish

@@ -4,6 +4,9 @@
 # CATEGORY
 #   04-git-and-version-control
 #
+# DEPENDENCIES
+#   gitui
+#
 # SYNOPSIS
 #   gitui [args...]
 #
@@ -14,9 +17,17 @@
 # ARGUMENTS
 #   args...  Arguments forwarded to the gitui command
 #
+# EXIT STATUS
+#   1  gitui is not installed
+#   *  Exit status of gitui otherwise
+#
 # EXAMPLE
 #   gitui
 function gitui --wraps='gitui' --description 'alias gitui=gitui -t mocha.ron'
+    if not type -q -f gitui
+        echo (set_color red)"Error: gitui is not installed."(set_color normal) >&2
+        return 1
+    end
+
     command gitui -t frappe.ron $argv
-
 end

functions/lock.fish

@@ -4,6 +4,9 @@
 # CATEGORY
 #   07-system-and-monitoring
 #
+# DEPENDENCIES
+#   loginctl
+#
 # SYNOPSIS
 #   lock
 #
@@ -11,12 +14,18 @@
 #   Locks the current desktop session using loginctl lock-session.
 #
 # EXIT STATUS
-#   Exit status of loginctl lock-session
+#   1  loginctl is not installed
+#   *  Exit status of loginctl lock-session otherwise
 #
 # EXAMPLE
 #   lock
 function lock --wraps='loginctl' --description 'alias lock=loginctl'
     __fish_help_header (status current-function) $argv; and return 0
 
+    if not type -q loginctl
+        echo (set_color red)"Error: loginctl is not installed."(set_color normal) >&2
+        return 1
+    end
+
     loginctl lock-session
 end

functions/play-media.fish

@@ -5,7 +5,7 @@
 #   13-media-and-utilities
 #
 # DEPENDENCIES
-#   _fzf_preview_media, _fzf_wrapper, fd, fdfind, file, xdg-mime
+#   _fzf_preview_media, _fzf_wrapper, fd, fdfind, file, xdg-mime, mpv, vlc
 #
 # SYNOPSIS
 #   play-media [-p|--player <cmd>]

functions/ports.fish

@@ -4,6 +4,9 @@
 # CATEGORY
 #   07-system-and-monitoring
 #
+# DEPENDENCIES
+#   lsof
+#
 # SYNOPSIS
 #   ports
 #
@@ -12,12 +15,18 @@
 #   port numbers and addresses without hostname resolution.
 #
 # EXIT STATUS
-#   Exit status of lsof
+#   1  lsof is not installed
+#   *  Exit status of lsof otherwise
 #
 # EXAMPLE
 #   ports
 function ports --wraps='sudo' --description 'Show active network listeners'
     __fish_help_header (status current-function) $argv; and return 0
 
+    if not type -q lsof
+        echo (set_color red)"Error: lsof is not installed."(set_color normal) >&2
+        return 1
+    end
+
     sudo lsof -iTCP -sTCP:LISTEN -P -n
 end

functions/screensleep.fish

@@ -4,6 +4,9 @@
 # CATEGORY
 #   07-system-and-monitoring
 #
+# DEPENDENCIES
+#   busctl
+#
 # SYNOPSIS
 #   screensleep
 #
@@ -12,13 +15,19 @@
 #   PowerDevil "Turn Off Screen" global shortcut via busctl.
 #
 # EXIT STATUS
-#   Exit status of busctl
+#   1  busctl is not installed
+#   *  Exit status of busctl otherwise
 #
 # EXAMPLE
 #   screensleep
 function screensleep --description 'Turn off the display using KDE PowerDevil'
     __fish_help_header (status current-function) $argv; and return 0
 
+    if not type -q busctl
+        echo (set_color red)"Error: busctl is not installed."(set_color normal) >&2
+        return 1
+    end
+
     # Optional: 1-second delay to ensure no keystrokes wake it immediately
     sleep 1
     busctl --user call \

functions/split.fish

@@ -8,7 +8,7 @@
 #   integrations/window-mgmt
 #
 # DEPENDENCIES
-#   kitty
+#   kitty, wezterm
 #
 # SYNOPSIS
 #   split [-h | -v] [command...]
@@ -55,6 +55,17 @@ function split --description 'Run a command in a new terminal split'
         return 1
     end
 
+    # $TERM/$TERM_PROGRAM only prove the terminal type, not that its CLI
+    # binary is on $PATH -- e.g. sshing out from Kitty/WezTerm inherits the
+    # env var on the remote host without the binary. Check explicitly.
+    if test $is_kitty -eq 1; and not type -q kitty
+        echo "Error: 'split' detected Kitty but the kitty binary is not installed." >&2
+        return 1
+    else if test $is_wezterm -eq 1; and not type -q wezterm
+        echo "Error: 'split' detected WezTerm but the wezterm binary is not installed." >&2
+        return 1
+    end
+
     set -l kitty_loc hsplit
     set -l wez_loc --bottom
 

functions/spwin.fish

@@ -8,7 +8,7 @@
 #   integrations/window-mgmt
 #
 # DEPENDENCIES
-#   kitty
+#   kitty, wezterm
 #
 # SYNOPSIS
 #   spwin [args...]
@@ -36,13 +36,23 @@ function spwin --wraps='~/.config/kitty/spawn-window.sh' --description 'spawn wi
         return 1
     end
 
+    # $TERM/$TERM_PROGRAM only prove the terminal type, not that its CLI
+    # binary is on $PATH -- e.g. sshing out from Kitty/WezTerm inherits the
+    # env var on the remote host without the binary. Check explicitly.
     if test "$TERM" = xterm-kitty
         if test -x ~/.config/kitty/spawn-window.sh
             ~/.config/kitty/spawn-window.sh $argv
-        else
+        else if type -q kitty
             kitty @ launch --type=window $argv
+        else
+            echo "Error: 'spwin' detected Kitty but neither spawn-window.sh nor the kitty binary is available." >&2
+            return 1
         end
     else if test "$TERM_PROGRAM" = WezTerm
+        if not type -q wezterm
+            echo "Error: 'spwin' detected WezTerm but the wezterm binary is not installed." >&2
+            return 1
+        end
         wezterm cli spawn $argv
     else
         echo "Error: The 'spwin' command requires Kitty or WezTerm." >&2

functions/steam-dl.fish

@@ -4,6 +4,9 @@
 # CATEGORY
 #   13-media-and-utilities
 #
+# DEPENDENCIES
+#   systemd-inhibit, steam
+#
 # SYNOPSIS
 #   steam-dl
 #
@@ -12,13 +15,21 @@
 #   or sleeping during active downloads.
 #
 # EXIT STATUS
-#   Exit status of steam (via systemd-inhibit)
+#   1  systemd-inhibit or steam is not installed
+#   *  Exit status of steam (via systemd-inhibit) otherwise
 #
 # EXAMPLE
 #   steam-dl
 function steam-dl --description 'Run Steam while inhibiting system sleep'
     __fish_help_header (status current-function) $argv; and return 0
 
+    for cmd in systemd-inhibit steam
+        if not type -q $cmd
+            echo (set_color red)"Error: $cmd is not installed."(set_color normal) >&2
+            return 1
+        end
+    end
+
     echo "Inhibiting sleep while Steam downloads..."
     systemd-inhibit --why="Active Download" --who="User" --what=idle:sleep steam
 end

functions/tab.fish

@@ -8,7 +8,7 @@
 #   integrations/window-mgmt
 #
 # DEPENDENCIES
-#   kitty
+#   kitty, wezterm, konsole
 #
 # SYNOPSIS
 #   tab [args...]
@@ -42,11 +42,27 @@ function tab --description 'Spawn a new tab in the current terminal'
         set dir "$PWD"
     end
 
+    # $TERM/$TERM_PROGRAM/$KONSOLE_VERSION only prove the terminal type,
+    # not that its CLI binary is on $PATH -- e.g. sshing out from one of
+    # these inherits the env var on the remote host without the binary.
+    # Check explicitly.
     if test "$TERM" = xterm-kitty
+        if not type -q kitty
+            echo "Error: 'tab' detected Kitty but the kitty binary is not installed." >&2
+            return 1
+        end
         kitty @ launch --type=tab --cwd="$dir" $argv
     else if test "$TERM_PROGRAM" = WezTerm
+        if not type -q wezterm
+            echo "Error: 'tab' detected WezTerm but the wezterm binary is not installed." >&2
+            return 1
+        end
         wezterm cli spawn --cwd "$dir" $argv
     else if set -q KONSOLE_VERSION
+        if not type -q konsole
+            echo "Error: 'tab' detected Konsole but the konsole binary is not installed." >&2
+            return 1
+        end
         konsole --new-tab --workdir "$dir" $argv
     else
         echo "Error: No supported terminal found. Try Kitty, WezTerm, or Konsole." >&2

functions/wake-lock.fish

@@ -4,6 +4,9 @@
 # CATEGORY
 #   14-miscellaneous
 #
+# DEPENDENCIES
+#   systemd-inhibit
+#
 # SYNOPSIS
 #   wake-lock <command> [args...]
 #
@@ -17,7 +20,7 @@
 #
 # EXIT STATUS
 #   0  Command ran and completed
-#   1  No command provided
+#   1  No command provided, or systemd-inhibit is not installed
 #
 # EXAMPLE
 #   wake-lock rsync -avz src/ dest/
@@ -30,6 +33,11 @@ function wake-lock --description 'Run a command while inhibiting system sleep'
         return 1
     end
 
+    if not type -q systemd-inhibit
+        echo (set_color red)"Error: systemd-inhibit is not installed."(set_color normal) >&2
+        return 1
+    end
+
     echo "Running '$argv' with sleep inhibition active..."
 
     # --what=idle:sleep prevents the system from auto-sleeping or being suspended