From 15b04ddb4a0b25dcb7cbf3a26f8138934f4db437 Mon Sep 17 00:00:00 2001
From: yage <yage@yage.io>
Date: Fri, 14 Aug 2026 08:12:39 -0600
Subject: [PATCH] various updates and configs

---
 config/local/altaria/bin/xorg.zsh             |   2 +-
 config/local/pikachu/misc/pulseaudio.patch    |   4 +-
 config/rofi.theme.rasi                        |   4 +-
 .../local.pikachu.dotwryn.env.yaml            |   2 +-
 .../environments/local.scwrypts.env.yaml      |   3 -
 config/scwrypts/vundle.zsh                    |   2 +-
 config/user/pgcli/config                      |   2 +-
 config/user/polybar/config.ini                |   2 +-
 .../{ => apps}/alacritty.module.zsh           |   4 +-
 .../desktop/colorscheme/apps/apps.module.zsh  |   9 +
 .../{ => apps}/flameshot.module.zsh           |   0
 .../colorscheme/{ => apps}/getty.module.zsh   |   4 +-
 .../colorscheme/{ => apps}/gtk.module.zsh     |   2 +-
 .../{ => apps}/hyprland.module.zsh            |  10 +-
 .../colorscheme/{ => apps}/kitty.module.zsh   |   2 +-
 .../colorscheme/{ => apps}/polybar.module.zsh |   2 +-
 .../{ => apps}/quickshell.module.zsh          |   2 +-
 .../colorscheme/{ => apps}/rofi.module.zsh    |   6 +-
 .../colorscheme/colorscheme.module.zsh        | 270 +-----------------
 .../desktop/colorscheme/get-hex.module.zsh    | 151 ++++++++++
 .../dotwryn/desktop/colorscheme/get-theme     |   4 +-
 .../dotwryn/desktop/colorscheme/set-theme     |  52 +---
 .../desktop/colorscheme/set-theme.module.zsh  | 185 ++++++++++++
 scwrypts/dotwryn/desktop/xorg/backlight       |  40 ++-
 .../xorg/i3/generate-config.module.zsh        |  12 +-
 .../dotwryn/desktop/xorg/i3/set-background    |  23 +-
 .../desktop/xorg/i3/set-background.module.zsh | 114 ++++++++
 .../dotwryn/desktop/xorg/xrandr.module.zsh    |   2 +-
 .../office/vim/vundle/update.module.zsh       |   2 +-
 .../system/symlinks/get-all.module.zsh        |   4 +-
 scwrypts/media/audio/play-sfx.module.zsh      |  11 +-
 .../media/cloud/synchronize-target.module.zsh |   4 +-
 scwrypts/media/cloud/synchronize.module.zsh   |   2 +-
 .../media/cloud/zshparse/actions.module.zsh   |   4 +-
 .../get-audio-clip-from-video.module.zsh      |  26 +-
 .../get-video-length-seconds.module.zsh       |   2 +-
 .../media/mscore/zshparse/filename.module.zsh |   6 +-
 scwrypts/media/youtube/download.module.zsh    |   6 +-
 scwrypts/remote/tmux/omni                     |   2 +-
 zsh/rc.d/15.plugins-scwrypts.zsh              |   1 +
 zsh/rc.d/80.frog.zsh                          |  15 +-
 41 files changed, 568 insertions(+), 432 deletions(-)
 rename scwrypts/dotwryn/desktop/colorscheme/{ => apps}/alacritty.module.zsh (90%)
 create mode 100644 scwrypts/dotwryn/desktop/colorscheme/apps/apps.module.zsh
 rename scwrypts/dotwryn/desktop/colorscheme/{ => apps}/flameshot.module.zsh (100%)
 rename scwrypts/dotwryn/desktop/colorscheme/{ => apps}/getty.module.zsh (87%)
 rename scwrypts/dotwryn/desktop/colorscheme/{ => apps}/gtk.module.zsh (99%)
 rename scwrypts/dotwryn/desktop/colorscheme/{ => apps}/hyprland.module.zsh (88%)
 rename scwrypts/dotwryn/desktop/colorscheme/{ => apps}/kitty.module.zsh (96%)
 rename scwrypts/dotwryn/desktop/colorscheme/{ => apps}/polybar.module.zsh (98%)
 rename scwrypts/dotwryn/desktop/colorscheme/{ => apps}/quickshell.module.zsh (97%)
 rename scwrypts/dotwryn/desktop/colorscheme/{ => apps}/rofi.module.zsh (85%)
 create mode 100644 scwrypts/dotwryn/desktop/colorscheme/get-hex.module.zsh
 create mode 100644 scwrypts/dotwryn/desktop/colorscheme/set-theme.module.zsh
 create mode 100644 scwrypts/dotwryn/desktop/xorg/i3/set-background.module.zsh

diff --git a/config/local/altaria/bin/xorg.zsh b/config/local/altaria/bin/xorg.zsh
index 5293351..472ab26 100644
--- a/config/local/altaria/bin/xorg.zsh
+++ b/config/local/altaria/bin/xorg.zsh
@@ -176,7 +176,7 @@ XRANDR_SET() {
 	# disabling for a moment since the latest X11/NVIDIA drivers are causing some issues after "disconnect all"
 	#scwrypts desktop xrandr disconnect all
 
-	xrandr ${XRANDR_ARGS[@]} 
+	xrandr ${XRANDR_ARGS[@]}
 
 	sleep 1
 
diff --git a/config/local/pikachu/misc/pulseaudio.patch b/config/local/pikachu/misc/pulseaudio.patch
index 02fdd18..a0d576c 100644
--- a/config/local/pikachu/misc/pulseaudio.patch
+++ b/config/local/pikachu/misc/pulseaudio.patch
@@ -1,14 +1,14 @@
 --- a/analog-output-speaker.conf
 +++ b/analog-output-speaker.conf
 @@ -71,12 +71,14 @@
- 
+
  [Element Hardware Master]
  switch = mute
 -volume = merge
 -override-map.1 = all
 -override-map.2 = all-left,all-right
 +volume = ignore
- 
+
  [Element Master]
  switch = mute
 +volume = ignore
diff --git a/config/rofi.theme.rasi b/config/rofi.theme.rasi
index 7fdb10b..73791b0 100644
--- a/config/rofi.theme.rasi
+++ b/config/rofi.theme.rasi
@@ -2,7 +2,7 @@
  *
  * Author : Aditya Shakya (adi1090x)
  * Github : @adi1090x
- * 
+ *
  * Rofi Theme File
  * Rofi Version: 1.7.3
  **/
@@ -132,7 +132,7 @@ listview {
     reverse:                     false;
     fixed-height:                true;
     fixed-columns:               true;
-    
+
     spacing:                     0px;
     margin:                      0px;
     padding:                     0px;
diff --git a/config/scwrypts/environments/local.pikachu.dotwryn.env.yaml b/config/scwrypts/environments/local.pikachu.dotwryn.env.yaml
index ac798ec..c411fb0 100644
--- a/config/scwrypts/environments/local.pikachu.dotwryn.env.yaml
+++ b/config/scwrypts/environments/local.pikachu.dotwryn.env.yaml
@@ -1,4 +1,4 @@
 ---  # local.pikachu > dotwryn
 desktop:
   backlight-device:
-    value: amdgpu_bl1
+    value: xrandr-fake-brightness
diff --git a/config/scwrypts/environments/local.scwrypts.env.yaml b/config/scwrypts/environments/local.scwrypts.env.yaml
index ff6be82..5e64349 100644
--- a/config/scwrypts/environments/local.scwrypts.env.yaml
+++ b/config/scwrypts/environments/local.scwrypts.env.yaml
@@ -15,9 +15,6 @@ directus:
 discord:
   content-header:
     value: '<@380809228450922507> '
-media-sync:
-  s3-bucket:
-    value: yage
 twilio:
   account-sid:
     value: ACac926b109b3cd8a78685a2a0994d0271
diff --git a/config/scwrypts/vundle.zsh b/config/scwrypts/vundle.zsh
index bc9af58..929eaea 100644
--- a/config/scwrypts/vundle.zsh
+++ b/config/scwrypts/vundle.zsh
@@ -3,6 +3,6 @@
 #
 
 VUNDLE__BUILD__vim-hexokinase() {
-	# ... build steps from /home/w0ryn/.vim/vim-hexokinase 
+	# ... build steps from /home/w0ryn/.vim/vim-hexokinase
 	make hexokinase
 }
diff --git a/config/user/pgcli/config b/config/user/pgcli/config
index eea4308..2f3b4cf 100644
--- a/config/user/pgcli/config
+++ b/config/user/pgcli/config
@@ -144,7 +144,7 @@ null_string = '<null>'
 # manage pager on startup
 enable_pager = True
 
-# Use keyring to automatically save and load password in a secure manner 
+# Use keyring to automatically save and load password in a secure manner
 keyring = True
 
 # Custom colors for the completion menu, toolbar, etc.
diff --git a/config/user/polybar/config.ini b/config/user/polybar/config.ini
index 62b88e8..4f23350 100644
--- a/config/user/polybar/config.ini
+++ b/config/user/polybar/config.ini
@@ -41,7 +41,7 @@ enable-ipc = true
 #####################################################################
 
 [bar/i3]
-modules-left = xworkspaces 
+modules-left = xworkspaces
 
 [module/xworkspaces]
 type = internal/xworkspaces
diff --git a/scwrypts/dotwryn/desktop/colorscheme/alacritty.module.zsh b/scwrypts/dotwryn/desktop/colorscheme/apps/alacritty.module.zsh
similarity index 90%
rename from scwrypts/dotwryn/desktop/colorscheme/alacritty.module.zsh
rename to scwrypts/dotwryn/desktop/colorscheme/apps/alacritty.module.zsh
index 419ccff..932b57e 100644
--- a/scwrypts/dotwryn/desktop/colorscheme/alacritty.module.zsh
+++ b/scwrypts/dotwryn/desktop/colorscheme/apps/alacritty.module.zsh
@@ -2,7 +2,7 @@ _COLORSCHEME_FILE__alacritty="${DOTWRYN}/config/user/alacritty/theme.toml"
 
 _GENERATE_THEME__alacritty() {
 	echo "# do not edit; generated by scwrypts
-# theme : ${THEME_NAME}
+# theme : ${theme_name}
 [colors.cursor]
 cursor = '0x$(_GET_HEX .alacritty.cursor cursor)'
 
@@ -31,7 +31,7 @@ cyan    = '0x$(_GET_HEX .ansi.cyan.bright)'
 white   = '0x$(_GET_HEX .ansi.gray.bright)'
 " | sed '$d' > "${_COLORSCHEME_FILE__alacritty}"
 
-	local TRANSPARENCY_OVERRIDE=$(cat "${SOURCE_THEME}" | utils.yq -r '.alacritty.transparency' | grep -v '^null$')
+	local TRANSPARENCY_OVERRIDE=$(sed 's/--- *#.*/---/' "${theme_source}" | utils.yq -r '.alacritty.transparency' | grep -v '^null$')
 	[ ${TRANSPARENCY_OVERRIDE} ] && {
 		printf "[window]\nopacity = ${TRANSPARENCY_OVERRIDE}\n" >> "${_COLORSCHEME_FILE__alacritty}"
 	}
diff --git a/scwrypts/dotwryn/desktop/colorscheme/apps/apps.module.zsh b/scwrypts/dotwryn/desktop/colorscheme/apps/apps.module.zsh
new file mode 100644
index 0000000..e68d979
--- /dev/null
+++ b/scwrypts/dotwryn/desktop/colorscheme/apps/apps.module.zsh
@@ -0,0 +1,9 @@
+use --group dotwryn desktop/colorscheme/apps/alacritty
+use --group dotwryn desktop/colorscheme/apps/flameshot
+use --group dotwryn desktop/colorscheme/apps/getty
+use --group dotwryn desktop/colorscheme/apps/gtk
+use --group dotwryn desktop/colorscheme/apps/hyprland
+use --group dotwryn desktop/colorscheme/apps/kitty
+use --group dotwryn desktop/colorscheme/apps/polybar
+use --group dotwryn desktop/colorscheme/apps/quickshell
+use --group dotwryn desktop/colorscheme/apps/rofi
diff --git a/scwrypts/dotwryn/desktop/colorscheme/flameshot.module.zsh b/scwrypts/dotwryn/desktop/colorscheme/apps/flameshot.module.zsh
similarity index 100%
rename from scwrypts/dotwryn/desktop/colorscheme/flameshot.module.zsh
rename to scwrypts/dotwryn/desktop/colorscheme/apps/flameshot.module.zsh
diff --git a/scwrypts/dotwryn/desktop/colorscheme/getty.module.zsh b/scwrypts/dotwryn/desktop/colorscheme/apps/getty.module.zsh
similarity index 87%
rename from scwrypts/dotwryn/desktop/colorscheme/getty.module.zsh
rename to scwrypts/dotwryn/desktop/colorscheme/apps/getty.module.zsh
index 168a378..024677d 100644
--- a/scwrypts/dotwryn/desktop/colorscheme/getty.module.zsh
+++ b/scwrypts/dotwryn/desktop/colorscheme/apps/getty.module.zsh
@@ -1,9 +1,9 @@
-_COLORSCHEME_FILE__getty="${ACTIVE_THEME_PATH}/getty.sh"
+_COLORSCHEME_FILE__getty="$(dotwryn.config colorscheme.active.path)/getty.sh"
 
 _GENERATE_THEME__getty() {
 	echo "#!/bin/sh
 # do not edit; generated by scwrypts
-# theme : ${THEME_NAME}
+# theme : ${theme_name}
 #
 # source this file to apply colorscheme to linux getty
 #
diff --git a/scwrypts/dotwryn/desktop/colorscheme/gtk.module.zsh b/scwrypts/dotwryn/desktop/colorscheme/apps/gtk.module.zsh
similarity index 99%
rename from scwrypts/dotwryn/desktop/colorscheme/gtk.module.zsh
rename to scwrypts/dotwryn/desktop/colorscheme/apps/gtk.module.zsh
index c0645e9..9307802 100644
--- a/scwrypts/dotwryn/desktop/colorscheme/gtk.module.zsh
+++ b/scwrypts/dotwryn/desktop/colorscheme/apps/gtk.module.zsh
@@ -10,7 +10,7 @@ _COLORSCHEME_FILE__gtk4="${DOTWRYN}/config/user/gtk-4.0/gtk.css"
 # only bg/fg pairs are the material ones (accent + status colors)
 _GENERATE_THEME__gtk() {
 	local css="/* do not edit; generated by scwrypts
- * theme : ${THEME_NAME}
+ * theme : ${theme_name}
  */
 
 @define-color view_bg_color          #$(_GET_HEX .gtk.view.bg .background);
diff --git a/scwrypts/dotwryn/desktop/colorscheme/hyprland.module.zsh b/scwrypts/dotwryn/desktop/colorscheme/apps/hyprland.module.zsh
similarity index 88%
rename from scwrypts/dotwryn/desktop/colorscheme/hyprland.module.zsh
rename to scwrypts/dotwryn/desktop/colorscheme/apps/hyprland.module.zsh
index 4256466..d822e45 100644
--- a/scwrypts/dotwryn/desktop/colorscheme/hyprland.module.zsh
+++ b/scwrypts/dotwryn/desktop/colorscheme/apps/hyprland.module.zsh
@@ -1,11 +1,11 @@
-_COLORSCHEME_FILE__hyprland_hyprlock="${ACTIVE_THEME_PATH}/hyprlock.conf"
-_COLORSCHEME_FILE__hyprland_hyprtoolkit="${ACTIVE_THEME_PATH}/hyprtoolkit.conf"  # linked to ~/.config/hypr by system/symlinks/get-all
+_COLORSCHEME_FILE__hyprland_hyprlock="$(dotwryn.config colorscheme.active.path)/hyprlock.conf"
+_COLORSCHEME_FILE__hyprland_hyprtoolkit="$(dotwryn.config colorscheme.active.path)/hyprtoolkit.conf"  # linked to ~/.config/hypr by system/symlinks/get-all
 
 _GENERATE_THEME__hyprland() {
 	# (hyprland itself reads the colorscheme through colorscheme.lua; see config/desktop/hyprland/config.d/99-dwindle.lua)
 
 	echo "# do not edit; generated by scwrypts
-# theme : ${THEME_NAME}
+# theme : ${theme_name}
 \$background     = rgb($(_GET_HEX .hyprland.hyprlock.background .background))
 \$foreground     = rgb($(_GET_HEX .hyprland.hyprlock.foreground .foreground))
 \$accent         = rgb($(_GET_HEX .hyprland.hyprlock.accent     .material.secondary.500 .ansi.green.bright))
@@ -18,7 +18,7 @@ _GENERATE_THEME__hyprland() {
 
 	# shared theme for hyprland-ecosystem GUI apps (hyprland-guiutils dialogs, hyprpm prompts, ...)
 	echo "# do not edit; generated by scwrypts
-# theme : ${THEME_NAME}
+# theme : ${theme_name}
 background       = rgb($(_GET_HEX .hyprland.hyprtoolkit.background       .material.secondary.900            .ansi.gray.black))
 base             = rgb($(_GET_HEX .hyprland.hyprtoolkit.base             .material.secondary.900            .ansi.gray.black))
 alternate_base   = rgb($(_GET_HEX .hyprland.hyprtoolkit.alternate-base   .background))
@@ -45,6 +45,6 @@ _SET_THEME__hyprland() {
 	[[ "${HYPRLAND_INSTANCE_SIGNATURE}" ]] || return 0  # hyprland isn't running
 
 	hyprctl reload &>/dev/null
-	scwrypts --group dotwryn --type zsh --name desktop/wayland/hyprland/set-background -- theme "${THEME_NAME}" &>/dev/null  # name.txt is written after this hook
+	scwrypts --group dotwryn --type zsh --name desktop/wayland/hyprland/set-background -- theme "${theme_name}" &>/dev/null  # name.txt is written after this hook
 	return 0
 }
diff --git a/scwrypts/dotwryn/desktop/colorscheme/kitty.module.zsh b/scwrypts/dotwryn/desktop/colorscheme/apps/kitty.module.zsh
similarity index 96%
rename from scwrypts/dotwryn/desktop/colorscheme/kitty.module.zsh
rename to scwrypts/dotwryn/desktop/colorscheme/apps/kitty.module.zsh
index 462eee6..0416a09 100644
--- a/scwrypts/dotwryn/desktop/colorscheme/kitty.module.zsh
+++ b/scwrypts/dotwryn/desktop/colorscheme/apps/kitty.module.zsh
@@ -2,7 +2,7 @@ _COLORSCHEME_FILE__kitty="${DOTWRYN}/config/user/kitty/theme.conf"
 
 _GENERATE_THEME__kitty() {
 	echo "# do not edit; generated by scwrypts
-# theme : ${THEME_NAME}
+# theme : ${theme_name}
 color0 #${BLACK}
 color1 #${RED}
 color2 #${GREEN}
diff --git a/scwrypts/dotwryn/desktop/colorscheme/polybar.module.zsh b/scwrypts/dotwryn/desktop/colorscheme/apps/polybar.module.zsh
similarity index 98%
rename from scwrypts/dotwryn/desktop/colorscheme/polybar.module.zsh
rename to scwrypts/dotwryn/desktop/colorscheme/apps/polybar.module.zsh
index 709cd4c..069866c 100644
--- a/scwrypts/dotwryn/desktop/colorscheme/polybar.module.zsh
+++ b/scwrypts/dotwryn/desktop/colorscheme/apps/polybar.module.zsh
@@ -2,7 +2,7 @@ _COLORSCHEME_FILE__polybar="${DOTWRYN}/config/user/polybar/theme.ini"
 
 _GENERATE_THEME__polybar() {
 	echo "# do not edit; generated by scwrypts
-# theme : ${THEME_NAME}
+# theme : ${theme_name}
 [colors]
 background     = #$(_GET_HEX .polybar.background .background)
 foreground     = #$(_GET_HEX .polybar.foreground .foreground)
diff --git a/scwrypts/dotwryn/desktop/colorscheme/quickshell.module.zsh b/scwrypts/dotwryn/desktop/colorscheme/apps/quickshell.module.zsh
similarity index 97%
rename from scwrypts/dotwryn/desktop/colorscheme/quickshell.module.zsh
rename to scwrypts/dotwryn/desktop/colorscheme/apps/quickshell.module.zsh
index 0548794..cf61531 100644
--- a/scwrypts/dotwryn/desktop/colorscheme/quickshell.module.zsh
+++ b/scwrypts/dotwryn/desktop/colorscheme/apps/quickshell.module.zsh
@@ -2,7 +2,7 @@ _COLORSCHEME_FILE__quickshell="${DOTWRYN}/config/user/quickshell/colors.json"
 
 _GENERATE_THEME__quickshell() {
 	echo "{
-	\"theme\"         : \"${THEME_NAME}\",
+	\"theme\"         : \"${theme_name}\",
 	\"background\"    : \"#$(_GET_HEX .quickshell.background     .background)\",
 	\"foreground\"    : \"#$(_GET_HEX .quickshell.foreground     .foreground)\",
 	\"backgroundAlt\" : \"#$(_GET_HEX .quickshell.background-alt .selection.background)\",
diff --git a/scwrypts/dotwryn/desktop/colorscheme/rofi.module.zsh b/scwrypts/dotwryn/desktop/colorscheme/apps/rofi.module.zsh
similarity index 85%
rename from scwrypts/dotwryn/desktop/colorscheme/rofi.module.zsh
rename to scwrypts/dotwryn/desktop/colorscheme/apps/rofi.module.zsh
index a17bcce..3572f37 100644
--- a/scwrypts/dotwryn/desktop/colorscheme/rofi.module.zsh
+++ b/scwrypts/dotwryn/desktop/colorscheme/apps/rofi.module.zsh
@@ -1,9 +1,9 @@
-_COLORSCHEME_FILE__rofi="${ACTIVE_THEME_PATH}/rofi.rasi"
+_COLORSCHEME_FILE__rofi="$(dotwryn.config colorscheme.active.path)/rofi.rasi"
 
 _GENERATE_THEME__rofi() {
 	echo "/**
  * do not edit; generated by scwrypts
- * theme : ${THEME_NAME}
+ * theme : ${theme_name}
  **/
 
 *{
@@ -15,7 +15,7 @@ _GENERATE_THEME__rofi() {
 	active:         #$(_GET_HEX .rofi.active          .material.base.primary   .ansi.green.regular);
 	urgent:         #$(_GET_HEX .rofi.urgent          .material.base.error     .ansi.red.regular  );
 }
-" | sed '$d' > "$_COLORSCHEME_FILE__rofi"
+" | sed '$d' > "${_COLORSCHEME_FILE__rofi}"
 }
 
 _SET_THEME__rofi() {
diff --git a/scwrypts/dotwryn/desktop/colorscheme/colorscheme.module.zsh b/scwrypts/dotwryn/desktop/colorscheme/colorscheme.module.zsh
index 5424c06..72cc396 100644
--- a/scwrypts/dotwryn/desktop/colorscheme/colorscheme.module.zsh
+++ b/scwrypts/dotwryn/desktop/colorscheme/colorscheme.module.zsh
@@ -1,272 +1,6 @@
 #####################################################################
 
-_COLORSCHEME_DIR="${DOTWRYN}/config/colorschemes"
-
-ACTIVE_THEME_PATH="${_COLORSCHEME_DIR}/active"
-ACTIVE_THEME_SOURCE="${ACTIVE_THEME_PATH}/source.yaml"
-
-use --group dotwryn desktop/colorscheme/alacritty
-use --group dotwryn desktop/colorscheme/flameshot
-use --group dotwryn desktop/colorscheme/getty
-use --group dotwryn desktop/colorscheme/gtk
-use --group dotwryn desktop/colorscheme/hyprland
-use --group dotwryn desktop/colorscheme/kitty
-use --group dotwryn desktop/colorscheme/polybar
-use --group dotwryn desktop/colorscheme/quickshell
-use --group dotwryn desktop/colorscheme/rofi
-
-COLORSCHEME__SUPPORTED_CONFIG_TYPES=($(typeset -f + | sed -n 's/^_GENERATE_THEME__//p'))
-
-DEFAULT_MATERIAL_REFERENCES="${ACTIVE_THEME_PATH}/default.yaml"
-
-DEPENDENCIES+=(sed yq)
-
-utils.environment.check DESKTOP__WALLPAPER_PATH --optional
+use --group dotwryn desktop/colorscheme/get-hex
+use --group dotwryn desktop/colorscheme/set-theme
 
 #####################################################################
-
-MAX_LOOKUP_RECURSION=10
-${scwryptsmodule}.get-hex() {
-	[ ! ${USAGE} ] && USAGE="
-		usage: ...args... [...options...]
-
-		options:
-		  -t, --theme          get the colorscheme value for the indicated theme source
-		  -l, --list-themes    show available color themes and exit
-
-		args:
-		  An ordered list of colorscheme lookup terms. The first term is preferred, and
-		  subsequent lookup terms are used as fallback.
-
-		  Some special terms are allowed (typically for compatibility); however,
-		  these should be simple yq queries from the 'colorscheme/\$THEME_NAME.yaml'
-		     (e.g. '.ansi.red.bright')
-
-		  Special terms:
-		    [0-15]        : lookup by ANSI color number
-			compatibility : foreground | background | cursor | selection_foreground | selection_background
-	"
-
-	local THEME_NAME='current active theme'
-	local THEME_SOURCE="${ACTIVE_THEME_SOURCE}"
-	local ARGS=()
-	local LOOKUPS=()
-	while [[ $# -gt 0 ]]
-	do
-		case $1 in
-			-t | --theme )
-				THEME_NAME=$2; shift 1
-				THEME_SOURCE="${_COLORSCHEME_DIR}/${THEME_NAME}.yaml"
-				[ -f "${THEME_SOURCE}" ] \
-					|| echo.error "no such theme '${THEME_NAME}' exists"
-				;;
-
-			-l | --list-themes ) _LIST_THEMES; return 0 ;;
-
-			[0-9] | 1[0-5] ) LOOKUPS+=($(_GET_YAML_LOOKUP_FOR_ANSI_COLOR $1)) ;;
-
-			foreground           ) LOOKUPS+=(.foreground           .ansi.gray.black) ;;
-			background           ) LOOKUPS+=(.background           .ansi.gray.white) ;;
-			cursor               ) LOOKUPS+=(.cursor               .ansi.gray.white) ;;
-			selection_foreground ) LOOKUPS+=(.selection.foreground .background     ) ;;
-			selection_background ) LOOKUPS+=(.selection.background .foreground     ) ;;
-
-			* ) LOOKUPS+=("$1") ;;
-		esac
-		shift 1
-	done
-
-	[[ ${#LOOKUPS[@]} -gt 0 ]] \
-		|| echo.error 'must provide at least one color lookup'
-
-	utils.check-errors || return 1
-
-	##########################################
-
-	local LOOKUP VALUE
-	local I INIT
-	for LOOKUP in ${LOOKUPS[@]}
-	do
-		I=0 INIT=${LOOKUP}
-		while true
-		do
-			((I+=1))
-			VALUE=$(utils.yq eval-all '. as $item ireduce ({}; . * $item)' "${DEFAULT_MATERIAL_REFERENCES}" "${THEME_SOURCE}" | utils.yq -r ${LOOKUP})
-			case ${VALUE} in
-				.* ) LOOKUP=${VALUE} ;;
-				* ) break ;;
-			esac
-			[[ ${I} -ge ${MAX_LOOKUP_RECURSION} ]] && {
-				VALUE=null
-				WARNING "max recursive depth reached for '${INIT}'"
-				break
-			}
-		done
-
-		[[ ${VALUE} =~ null ]] && continue
-		[[ ${VALUE} =~ ^$   ]] && continue
-		break
-	done
-
-	[[ ${VALUE} =~ null ]] && {
-		echo.error "color lookup error for '${LOOKUPS}'"
-		return 1
-	}
-
-	echo ${VALUE} | sed 's/^#//'
-}
-
-SET_THEME() {
-	[ ! ${USAGE} ] && USAGE="
-		usage: [...options...]
-
-		options:
-		  -t, --theme          one of the available color themes
-		  -l, --list-themes    show available color themes and exit
-
-		  --only   only set the theme for a specific terminal/application
-                   (${COLORSCHEME__SUPPORTED_CONFIG_TYPES})
-
-		  -h, --help   show this dialogue and exit
-
-		args:
-		  \$1   shorthand for '--theme \$1'
-
-		generate all source-controlled theme files then link them to the
-		appropriate local theme file to immediately update terminal themes
-
-		Note : 'i3wm colorscheme' configuration is supported but must be performed
-		       through the 'desktop/xorg/i3 --group dotwryn' module due to
-			   some odd complexity
-	"
-	local THEME_NAME CONFIG_TYPE
-	local UPDATE_ACTIVE_THEME=true
-	while [[ $# -gt 0 ]]
-	do
-		case $1 in
-			-t | --theme       ) THEME_NAME=$2; shift 1 ;;
-			-l | --list-themes ) _LIST_THEMES; return 0 ;;
-
-			--only )
-				UPDATE_ACTIVE_THEME=false
-				CONFIG_TYPE=$2; shift 1
-				command -v _SET_THEME__${CONFIG_TYPE} >/dev/null 2>&1 \
-					|| echo.error "configuration for '${CONFIG_TYPE}' not supported"
-				;;
-
-			-h | --help ) USAGE; return 0 ;;
-
-			* ) [ ! ${THEME_NAME} ] \
-					&& THEME_NAME=$1 \
-					|| echo.error "unknown argument '$1'" \
-					;
-		esac
-		shift 1
-	done
-
-	utils.check-errors --no-fail || return 1
-
-	##########################################
-
-	[ ${THEME_NAME} ] || THEME_NAME=$(_LIST_THEMES | utils.fzf 'select a theme')
-	[ ${THEME_NAME} ] || ABORT
-
-	local SOURCE_THEME="${_COLORSCHEME_DIR}/${THEME_NAME}.yaml"
-	[ -f "${SOURCE_THEME}" ] \
-		|| echo.error "no such theme '${THEME_NAME}'" \
-		|| return 1
-
-	##########################################
-
-	[[ ${UPDATE_ACTIVE_THEME} =~ true ]] && {
-		mkdir -p "${ACTIVE_THEME_PATH}" &>/dev/null
-		echo.status "updating active theme" \
-			&& ( cd -- "${ACTIVE_THEME_PATH}"; ln -sf -- "../$(basename -- "${SOURCE_THEME}")" "./$(basename -- "${ACTIVE_THEME_SOURCE}")"; ) \
-			&& echo.success "active theme set to '${THEME_NAME}'" \
-			|| echo.error "unable to set active theme to '${THEME_NAME}'" \
-			|| return 2
-	}
-
-	local CONFIG_TYPES=()
-	[ ${CONFIG_TYPE} ] \
-		&& CONFIG_TYPES=(${CONFIG_TYPE}) \
-		|| CONFIG_TYPES=(${COLORSCHEME__SUPPORTED_CONFIG_TYPES}) \
-		;
-
-	_GET_HEX() { dotwryn.desktop.colorscheme.get-hex --theme ${THEME_NAME} $@; }
-	# allow simple ANSI-color reference
-	local          BLACK=$(_GET_HEX .ansi.gray.black     )
-	local   BRIGHT_BLACK=$(_GET_HEX .ansi.gray.regular   )
-	local            RED=$(_GET_HEX .ansi.red.regular    )
-	local     BRIGHT_RED=$(_GET_HEX .ansi.red.bright     )
-	local          GREEN=$(_GET_HEX .ansi.green.regular  )
-	local   BRIGHT_GREEN=$(_GET_HEX .ansi.green.bright   )
-	local         YELLOW=$(_GET_HEX .ansi.yellow.regular )
-	local  BRIGHT_YELLOW=$(_GET_HEX .ansi.yellow.bright  )
-	local           BLUE=$(_GET_HEX .ansi.blue.regular   )
-	local    BRIGHT_BLUE=$(_GET_HEX .ansi.blue.bright    )
-	local        MAGENTA=$(_GET_HEX .ansi.magenta.regular)
-	local BRIGHT_MAGENTA=$(_GET_HEX .ansi.magenta.bright )
-	local           CYAN=$(_GET_HEX .ansi.cyan.regular   )
-	local    BRIGHT_CYAN=$(_GET_HEX .ansi.cyan.bright    )
-	local          WHITE=$(_GET_HEX .ansi.gray.white     )
-	local   BRIGHT_WHITE=$(_GET_HEX .ansi.gray.bright    )
-	local     FOREGROUND=$(_GET_HEX .foreground          )
-	local     BACKGROUND=$(_GET_HEX .background          )
-	local         CURSOR=$(_GET_HEX .cursor              )
-
-	for CONFIG_TYPE in ${CONFIG_TYPES[@]}
-	do
-		echo.status "updating ${CONFIG_TYPE} theme" \
-			&& _GENERATE_THEME__${CONFIG_TYPE} \
-			&& _SET_THEME__${CONFIG_TYPE} \
-			&& echo.success "emulator ${CONFIG_TYPE} successfully updated to ${THEME_NAME}" \
-			|| echo.error "error setting theme ${THEME_NAME} for ${CONFIG_TYPE}"
-
-		[[ ${CONFIG_TYPE} =~ ^getty$ ]] && [[ ${TERM} =~ ^linux$ ]] && {
-			echo.status 'loading getty theme now' \
-				&& NO_CLEAR=1 source "${ACTIVE_THEME_PATH}/getty.sh" \
-				&& echo.success 'getty theme loaded' \
-				|| echo.error 'getty theme loading error (see above)'
-			}
-	done
-
-	local WALLPAPER="$(find "${DESKTOP__WALLPAPER_PATH}" -type f -name ${THEME_NAME}.\* 2>/dev/null | head -n1)"
-	[ "${WALLPAPER}" ] && command -v feh &>/dev/null \
-		&& feh --no-fehbg --bg-fill "${WALLPAPER}"
-
-	utils.check-errors --no-usage || return 1
-
-	# --only regenerates one config type; the active theme (and its name) is unchanged
-	[[ ${UPDATE_ACTIVE_THEME} =~ true ]] \
-		&& echo "${THEME_NAME}" > "${ACTIVE_THEME_PATH}/name.txt"
-
-	return 0
-}
-
-#####################################################################
-
-_LIST_THEMES() {
-	ls "${_COLORSCHEME_DIR}" | sed -n 's/.yaml$//p'
-}
-
-_GET_YAML_LOOKUP_FOR_ANSI_COLOR() {
-	echo "
-0: .ansi.gray.black
-1: .ansi.red.regular
-2: .ansi.green.regular
-3: .ansi.yellow.regular
-4: .ansi.blue.regular
-5: .ansi.magenta.regular
-6: .ansi.cyan.regular
-7: .ansi.gray.white
-8: .ansi.gray.regular
-9: .ansi.red.bright
-10: .ansi.green.bright
-11: .ansi.yellow.bright
-12: .ansi.blue.bright
-13: .ansi.magenta.bright
-14: .ansi.cyan.bright
-15: .ansi.gray.bright
-" | utils.yq -r ".$1"
-}
diff --git a/scwrypts/dotwryn/desktop/colorscheme/get-hex.module.zsh b/scwrypts/dotwryn/desktop/colorscheme/get-hex.module.zsh
new file mode 100644
index 0000000..45af637
--- /dev/null
+++ b/scwrypts/dotwryn/desktop/colorscheme/get-hex.module.zsh
@@ -0,0 +1,151 @@
+#####################################################################
+
+${scwryptsmodule}() {
+	local PARSERS=() DESCRIPTION='
+		provides a literal hex code for the target theme based on
+		the provided lookup key(s)
+	'
+	eval "$(utils.parse.autosetup)"
+	##########################################
+
+	theme.yq() { echo "${theme_yaml}" | utils.yq -r "${@}" | grep -v ^null$; }
+
+	local previously_searched_keys=()
+
+	local lookup_key value
+	for lookup_key in "${yaml_lookup_array[@]}"
+	do
+		while [[ "${previously_searched_keys[(Ie)${lookup_key}]}" -le 1 ]]
+		do
+			value="$(theme.yq "${lookup_key}")"
+			case "${value}" in
+				( .* )  # value resembles another key
+					previously_searched_keys+=("${lookup_key}")
+					lookup_key="${value}"
+					;;
+
+				( * ) break ;;
+			esac
+			value=null
+		done
+
+		[[ "${value}" =~ '^#' ]] && break
+	done
+
+	case "${value}" in
+		( #* ) echo "${value/\#/}" ;;
+		( null | '' ) echo.error "color lookup error for ${(q)yaml_lookup_array[@]}" ;;
+
+	esac
+}
+
+${scwryptsmodule}.parse.locals() {
+	local ARGS=()
+	local theme_name='current active theme'
+	local theme_source
+	local theme_yaml
+	local yaml_lookup_array=()
+}
+
+${scwryptsmodule}.parse() {
+	local parsed=0
+
+	case "${1}" in
+		( -t | --theme ) parsed=2; theme_name="${2}" ;;
+	esac
+
+	return "${parsed}"
+}
+
+${scwryptsmodule}.parse.usage() {
+	USAGE__options+='
+		-t, --theme          get the colorscheme value for the indicated theme source
+		-l, --list-themes    show available color themes and exit
+	'
+
+	USAGE__args+='
+		$1..$N   lookup keys for hex color codes
+		An ordered list of colorscheme lookup terms. The first term is preferred, and
+		subsequent lookup terms are used as fallback.
+
+		Some special terms are allowed (typically for compatibility); however, in
+		general, these should be simple jq-style queries to pull values from the
+		associated colorscheme.yaml file
+		  (e.g. .ansi.red.bright)
+
+		Special terms:
+		  [0-15]        : lookup by ANSI color number
+		  compatibility : foreground | background | cursor | selection_foreground | selection_background
+	'
+}
+
+${scwryptsmodule}.parse.validate() {
+	local _a
+	for _a in "${ARGS[@]}"
+	do
+		case "${_a}" in
+			# --- ANSI color numbers -------------------
+			(  0 ) yaml_lookup_array+=(.ansi.gray.black)      ;;
+			(  1 ) yaml_lookup_array+=(.ansi.red.regular)     ;;
+			(  2 ) yaml_lookup_array+=(.ansi.green.regular)   ;;
+			(  3 ) yaml_lookup_array+=(.ansi.yellow.regular)  ;;
+			(  4 ) yaml_lookup_array+=(.ansi.blue.regular)    ;;
+			(  5 ) yaml_lookup_array+=(.ansi.magenta.regular) ;;
+			(  6 ) yaml_lookup_array+=(.ansi.cyan.regular)    ;;
+			(  7 ) yaml_lookup_array+=(.ansi.gray.white)      ;;
+			(  8 ) yaml_lookup_array+=(.ansi.gray.regular)    ;;
+			(  9 ) yaml_lookup_array+=(.ansi.red.bright)      ;;
+			( 10 ) yaml_lookup_array+=(.ansi.green.bright)    ;;
+			( 11 ) yaml_lookup_array+=(.ansi.yellow.bright)   ;;
+			( 12 ) yaml_lookup_array+=(.ansi.blue.bright)     ;;
+			( 13 ) yaml_lookup_array+=(.ansi.magenta.bright)  ;;
+			( 14 ) yaml_lookup_array+=(.ansi.cyan.bright)     ;;
+			( 15 ) yaml_lookup_array+=(.ansi.gray.bright)     ;;
+
+			# --- special keys -------------------------
+			( foreground           ) yaml_lookup_array+=(.foreground           .ansi.gray.black) ;;
+			( selection_foreground ) yaml_lookup_array+=(.selection.foreground .background     ) ;;
+
+			( background           ) yaml_lookup_array+=(.background           .ansi.gray.white) ;;
+			( selection_background ) yaml_lookup_array+=(.selection.background .foreground     ) ;;
+
+			( cursor               ) yaml_lookup_array+=(.cursor .ansi.gray.white) ;;
+
+			( '' ) ;;
+
+			# --- literal lookup keys ------------------
+			( * ) yaml_lookup_array+=("${_a}") ;;
+		esac
+	done
+	unset _a
+
+	[[ "${#yaml_lookup_array[@]}" -gt 0 ]] \
+		|| echo.error "must provide at least one yaml lookup key"
+
+	case "${theme_name}" in
+		( 'current active theme' )
+			theme_source="$(dotwryn.config colorscheme.active.source)"
+			;;
+
+		( * )
+			theme_source="$(dotwryn.config colorscheme.path)/${theme_name}.yaml"
+			;;
+	esac
+
+	[[ -f "${theme_source}" ]] \
+		|| echo.error "invalid or missing theme '${theme_name}'" -v theme_source
+
+	theme_yaml="$(
+		for yamlfile in \
+			"$(dotwryn.config colorscheme.active.default-material-references)" \
+			"${theme_source}" \
+			;
+		do
+			[[ "$(head -n1 "${yamlfile}")" =~ ^--- ]] || echo '---'
+			sed 's/---\s*#.*$/---/' "${yamlfile}"
+		done | utils.yq.combine-files
+	)"
+
+	[[ "${theme_yaml}" ]] && [[ "$(echo "${theme_yaml}" | utils.yq -r . 2>/dev/null)" ]] \
+		|| echo.error "yaml theme '${theme_name}' produced invalid yaml"
+}
diff --git a/scwrypts/dotwryn/desktop/colorscheme/get-theme b/scwrypts/dotwryn/desktop/colorscheme/get-theme
index 7c5964c..02a796c 100755
--- a/scwrypts/dotwryn/desktop/colorscheme/get-theme
+++ b/scwrypts/dotwryn/desktop/colorscheme/get-theme
@@ -9,6 +9,6 @@ USAGE__description+='
 #####################################################################
 
 MAIN() {
-	cat "${ACTIVE_THEME_PATH}/name.txt" 2>/dev/null \
-		|| ERROR 'theme name not available'
+	cat "$(dotwryn.config colorscheme.active.path)/name.txt" 2>/dev/null \
+		|| echo.error 'theme name not available'
 }
diff --git a/scwrypts/dotwryn/desktop/colorscheme/set-theme b/scwrypts/dotwryn/desktop/colorscheme/set-theme
index 1825225..553f95a 100755
--- a/scwrypts/dotwryn/desktop/colorscheme/set-theme
+++ b/scwrypts/dotwryn/desktop/colorscheme/set-theme
@@ -1,56 +1,14 @@
 #!/bin/zsh
-use desktop/colorscheme --group dotwryn
-use desktop/xorg/i3 --group dotwryn
 #####################################################################
 
-USAGE__options+="
-	-t, --theme          one of the available color themes
-	-l, --list-themes    show available color themes and exit
-
-	--only   only set the theme for a specific terminal/application
-	         (${COLORSCHEME__SUPPORTED_CONFIG_TYPES})
-"
-
-USAGE__args+='
-	\$1   shorthand for "--theme \$1"
-'
-
-USAGE__description+='
-	Generates source-controlled config files for the selected theme.
-	By default, generates all possible config types to provide a
-	consistent, system-wide theme.
-
-	Due to complexities with i3wm colorscheme management, it is not
-	possible to update i3wm colorscheme files when using the "--only"
-	flag.
-'
+use --group dotwryn desktop/colorscheme
 
+dotwryn.desktop.colorscheme.set-theme.parse.usage
 
 #####################################################################
 
 MAIN() {
-	local ARGS=() UPDATE_I3_CONFIG=true
-
-	while [[ $# -gt 0 ]]
-	do
-		case $1 in
-			--only )
-				ARGS+=($1)
-				UPDATE_I3_CONFIG=false
-				;;
-
-			* ) ARGS+=($1) ;;
-		esac
-		shift 1
-	done
-
-	SET_THEME ${ARGS[@]} \
-		|| ERROR 'failed to set theme (see above)' \
-		|| return 1
-
-	[[ ${UPDATE_I3_CONFIG} =~ true ]] || return 0
-
-	dotwryn.desktop.xorg.i3.generate-config \
-		|| ERROR 'failed to update i3 config (see above)' \
-		|| return 1
+	#dotwryn.config colorscheme.path
+	#dotwryn.config colorscheme.supported-apps
+	dotwryn.desktop.colorscheme.set-theme "${@}"
 }
diff --git a/scwrypts/dotwryn/desktop/colorscheme/set-theme.module.zsh b/scwrypts/dotwryn/desktop/colorscheme/set-theme.module.zsh
new file mode 100644
index 0000000..96331a4
--- /dev/null
+++ b/scwrypts/dotwryn/desktop/colorscheme/set-theme.module.zsh
@@ -0,0 +1,185 @@
+#####################################################################
+
+use --group dotwryn desktop/colorscheme/get-hex
+use --group dotwryn desktop/xorg/i3/set-background
+
+use --group dotwryn desktop/colorscheme/apps
+
+#####################################################################
+
+DOTWRYN_COLORSCHEME__SUPPORTED_CONFIG_TYPES=()
+dotwryn.config colorscheme.supported-apps DOTWRYN_COLORSCHEME__SUPPORTED_CONFIG_TYPES
+
+
+${scwryptsmodule}() {
+	local PARSERS=() DESCRIPTION='
+		generate source-controlled theme files and link them to the
+		appropriate applications
+	'
+
+	eval "$(utils.parse.autosetup)"
+
+	local DEBUG_ARGS=(-v theme_name -v theme_source -v config_types)
+	local TRACE_ARGS=("${DEBUG_ARGS[@]}" -v update_active_theme)
+
+	##########################################
+
+	local colorscheme_active_path="$(dotwryn.config colorscheme.active.path)"
+	local colorscheme_active_source="$(dotwryn.config colorscheme.active.source)"
+
+	echo.trace 'starting colorscheme update'
+
+	case "${update_active_theme}" in
+		( false ) ;;
+		( true )
+			echo.status "updating active theme" \
+				&& (
+					cd -- "${colorscheme_active_path}"
+					ln -sf -- "../$(basename -- "${theme_source}")" "./$(basename -- "$(dotwryn.config colorscheme.active.source)")"
+				) \
+				&& echo.success "active theme set to '${theme_name}'" \
+				|| echo.error "unable to set active theme to '${theme_name}'" \
+				;
+			;;
+	esac
+
+	_GET_HEX() { dotwryn.desktop.colorscheme.get-hex --theme "${theme_name}" "${@}"; }
+
+	_GET_HEX . | utils.yq >/dev/null \
+		|| echo.error "error loading colorscheme file; aborting" \
+		|| return 1
+
+	# allow simple ANSI-color reference
+	local \
+		         BLACK="$( _GET_HEX .ansi.gray.black      )" \
+		  BRIGHT_BLACK="$( _GET_HEX .ansi.gray.regular    )" \
+		           RED="$( _GET_HEX .ansi.red.regular     )" \
+		    BRIGHT_RED="$( _GET_HEX .ansi.red.bright      )" \
+		         GREEN="$( _GET_HEX .ansi.green.regular   )" \
+		  BRIGHT_GREEN="$( _GET_HEX .ansi.green.bright    )" \
+		        YELLOW="$( _GET_HEX .ansi.yellow.regular  )" \
+		 BRIGHT_YELLOW="$( _GET_HEX .ansi.yellow.bright   )" \
+		          BLUE="$( _GET_HEX .ansi.blue.regular    )" \
+		   BRIGHT_BLUE="$( _GET_HEX .ansi.blue.bright     )" \
+		       MAGENTA="$( _GET_HEX .ansi.magenta.regular )" \
+		BRIGHT_MAGENTA="$( _GET_HEX .ansi.magenta.bright  )" \
+		          CYAN="$( _GET_HEX .ansi.cyan.regular    )" \
+		   BRIGHT_CYAN="$( _GET_HEX .ansi.cyan.bright     )" \
+		         WHITE="$( _GET_HEX .ansi.gray.white      )" \
+		  BRIGHT_WHITE="$( _GET_HEX .ansi.gray.bright     )" \
+		    FOREGROUND="$( _GET_HEX .foreground           )" \
+		    BACKGROUND="$( _GET_HEX .background           )" \
+		        CURSOR="$( _GET_HEX .cursor               )" \
+		;
+
+
+	for config_type in "${config_types[@]}"
+	do
+		case "${config_type}" in
+			( i3-background )
+				dotwryn.desktop.xorg.i3.set-background "${theme_name}"
+				;;
+
+			( i3 )
+				dotwryn.desktop.xorg.i3.generate-config \
+				;;
+
+			( * )
+				echo.status "updating ${config_type} theme" \
+					&& "_GENERATE_THEME__${config_type}" \
+					&& "_SET_THEME__${config_type}" \
+					&& echo.success "emulator ${config_type} successfully updated to ${theme_name}" \
+					|| echo.error "error setting theme ${theme_name} for ${config_type}" \
+				;;
+		esac || continue
+
+		# handle special 
+		case "${config_type}" in
+			( getty )
+				[[ "${TERM}" == linux ]] || continue
+				echo.status 'loading getty theme now' \
+					&& NO_CLEAR=1 source "${colorscheme_active_path}/getty.sh" \
+					&& echo.success 'getty theme loaded' \
+					|| echo.error 'getty theme loading error (see above)' \
+				;;
+		esac
+	done
+
+	# --only regenerates one config type; the active theme (and its name) is unchanged
+	[[ "${ERRORS}" -eq 0 ]] && [[ "${update_active_theme}" =~ true ]] \
+		&& echo "${theme_name}" > "${colorscheme_active_path}/name.txt"
+
+	return "${ERRORS}"
+}
+
+${scwryptsmodule}.parse.locals() {
+	local ARGS=()
+	local theme_name theme_source
+	local update_active_theme=true
+	local config_type config_types=()
+}
+
+${scwryptsmodule}.parse() {
+	local parsed=0
+
+	case "${1}" in
+		( -t | --theme ) parsed=2
+			theme_name="${2}"
+			;;
+
+		( -l | --list-themes ) parsed=1
+			dotwryn.config colorscheme.themes
+			EARLY_ESCAPE_CODE=0
+			;;
+
+		( --only ) parsed=2
+			update_active_theme=false
+			config_type="${2}"
+			;;
+	esac
+
+	return "${parsed}"
+}
+
+${scwryptsmodule}.parse.usage() {
+	[[ "${#DOTWRYN_COLORSCHEME__SUPPORTED_CONFIG_TYPES[@]}" -eq 0 ]] \
+
+	USAGE__options+="
+		-t, --theme          one of the available color themes
+		-l, --list-themes    show available color themes and exit
+
+		--only   only set the theme for a specific terminal/application
+		         (${DOTWRYN_COLORSCHEME__SUPPORTED_CONFIG_TYPES[@]})
+	"
+
+	USAGE__args+='
+		$1   theme name (can be used instead of -t / --theme)
+	'
+}
+
+${scwryptsmodule}.parse.validate() {
+	[[ "${theme_name}" ]] && [[ "${ARGS[1]}" ]] \
+		&& echo.error "unknown argument '${ARGS[1]}'"
+
+	[[ "${theme_name}" ]] || theme_name="${ARGS[1]}"
+	[[ "${theme_name}" ]] || theme_name="$(dotwryn.config colorscheme.themes | utils.fzf 'select a theme')"
+	[[ "${theme_name}" ]] \
+		|| echo.error 'must provide theme name'
+
+	theme_source="$(dotwryn.config colorscheme.path)/${theme_name}.yaml"
+	[[ -f "${theme_source}" ]] \
+		|| echo.error "no such theme '${theme_name}'"
+
+	[[ "${#ARGS[@]}" -le 1 ]] \
+		|| echo.error "unknown argument(s) ${(q)ARGS[@]:1}"
+
+	case "${config_type}" in
+		( '' ) config_types=("${DOTWRYN_COLORSCHEME__SUPPORTED_CONFIG_TYPES[@]}") ;;
+		( * )
+			[[ "$(zsh.is-in-array DOTWRYN_COLORSCHEME__SUPPORTED_CONFIG_TYPES "${config_type}")" ]] \
+				|| echo.error "invalid config type '${config_type}' (supported: ${(q)DOTWRYN_COLORSCHEME__SUPPORTED_CONFIG_TYPES[@]})"
+
+			config_types=("${config_type}")
+			;;
+	esac
+}
diff --git a/scwrypts/dotwryn/desktop/xorg/backlight b/scwrypts/dotwryn/desktop/xorg/backlight
index 8e4089d..e656443 100755
--- a/scwrypts/dotwryn/desktop/xorg/backlight
+++ b/scwrypts/dotwryn/desktop/xorg/backlight
@@ -7,18 +7,26 @@ utils.environment.check DESKTOP__BACKLIGHT_DEVICE --optional
 
 MAIN() {
 	local SCWRYPTS_NOTIFICATION_ENGINES=(echo notify.desktop)
-	local UTIL
-
-	for UTIL in enlighten gmux_backlight xbacklight
+	local controller
+	for controller in brightnessctl enlighten gmux_backlight xbacklight
 	do
-		command -v ${UTIL} >/dev/null 2>&1 && break
+		command -v ${controller} >/dev/null 2>&1 && break
 	done
 
-	case ${DESKTOP__BACKLIGHT_DEVICE} in
-		( xrandr-fake-brightness ) UTIL=xrandr ;;
+	c() { "${controller}" "${controller__args[@]}" "${@}"; }
+	
+	local controller__args=()
+	case "${controller}" in
+		( brightnessctl )
+			[[ "${DESKTOP__BACKLIGHT_DEVICE}" ]] && controller__args+=(-d "${DESKTOP__BACKLIGHT_DEVICE}")
+			;;
 	esac
 
-	[[ ${UTIL} =~ ^enlighten$ ]] && {
+	case ${DESKTOP__BACKLIGHT_DEVICE} in
+		( xrandr-fake-brightness ) controller=xrandr ;;
+	esac
+
+	[[ ${controller} =~ ^enlighten$ ]] && {
 		CURRENT_PERCENT=$(BACKLIGHT_DEVICE=${DESKTOP__BACKLIGHT_DEVICE} enlighten | sed 's/.*(//;s/%.*//')
 		[[ ${CURRENT_PERCENT} -gt 60 ]] && DELTA=40
 		[[ ${CURRENT_PERCENT} -le 60 ]] && DELTA=20
@@ -27,7 +35,7 @@ MAIN() {
 	}
 
 	local UP DOWN
-	[[ ${UTIL} =~ ^xrandr$ ]] && {
+	[[ ${controller} =~ ^xrandr$ ]] && {
 		[[ "${XRANDR_TARGET[@]}" ]] \
 			|| XRANDR_TARGET=$(xrandr | grep ' connected' | awk '{print $1;}')
 
@@ -44,7 +52,8 @@ MAIN() {
 
 	case $1 in
 		up )
-			case ${UTIL} in
+			case ${controller} in
+				( brightnessctl ) c set 20%+ ;;
 				xbacklight     ) xbacklight -inc 10 ;;
 				gmux_backlight ) gmux_backlight +100 ;;
 
@@ -57,7 +66,10 @@ MAIN() {
 			esac
 			;;
 		down )
-			case ${UTIL} in
+			case ${controller} in
+				( brightnessctl )
+					brightnessctl "${controller__args[@]}" set 20%-
+					;;
 				xbacklight     )
 					[[ $(xbacklight -get) -le 10 ]] \
 						&& xbacklight -set 1 \
@@ -78,24 +90,24 @@ MAIN() {
 			;;
 		set )
 			[ ! $2 ] && FAIL 1 'no value provided to set'
-			case ${UTIL} in
+			case ${controller} in
 				xbacklight     ) xbacklight -set $2 ;;
 				gmux_backlight ) gmux_backlight $2  ;;
 				enlighten      ) BACKLIGHT_DEVICE=${DESKTOP__BACKLIGHT_DEVICE} enlighten "=$2"    ;;
 			esac
 			;;
 		min | minimum )
-			case ${UTIL} in
+			case ${controller} in
 				enlighten ) BACKLIGHT_DEVICE=${DESKTOP__BACKLIGHT_DEVICE} enlighten '=1%' ;;
 			esac
 			;;
 		max | maximum )
-			case ${UTIL} in
+			case ${controller} in
 				enlighten ) BACKLIGHT_DEVICE=${DESKTOP__BACKLIGHT_DEVICE} enlighten '=100%' ;;
 			esac
 			;;
 		query | '' )
-			case ${UTIL} in
+			case ${controller} in
 				enlighten ) notify.success "current brightness : $(BACKLIGHT_DEVICE=${DESKTOP__BACKLIGHT_DEVICE} enlighten)" ;;
 			esac
 			;;
diff --git a/scwrypts/dotwryn/desktop/xorg/i3/generate-config.module.zsh b/scwrypts/dotwryn/desktop/xorg/i3/generate-config.module.zsh
index e972fc5..c35510a 100644
--- a/scwrypts/dotwryn/desktop/xorg/i3/generate-config.module.zsh
+++ b/scwrypts/dotwryn/desktop/xorg/i3/generate-config.module.zsh
@@ -20,7 +20,7 @@ ${scwryptsmodule}() {
 
 	local CONFIG="$(utils.yq eval-all '. as $item ireduce ({}; . * $item)' "$CONFIG_DEFAULT_FILE" "$CONFIG_OVERRIDE_FILE")"
 	[ $CONFIG ] \
-		|| ERROR "unable to retrieve i3 config yaml (see above)" \
+		|| echo.error "unable to retrieve i3 config yaml (see above)" \
 		|| return 1 \
 		;
 
@@ -100,7 +100,7 @@ ${scwryptsmodule}() {
 		&& rm "$I3_CONFIG.temp2" \
 		&& echo.status "validating config" \
 		&& i3 -C -c "$I3_CONFIG.temp" \
-		|| ERROR "unable to produce config, or produced an invalid config (see above or '$I3_CONFIG.temp')" \
+		|| echo.error "unable to produce config, or produced an invalid config (see above or '$I3_CONFIG.temp')" \
 		|| return 1
 
 	[[ $SAFE =~ true ]] && [ -f "$I3_CONFIG" ] && {
@@ -122,7 +122,7 @@ ${scwryptsmodule}() {
 	: \
 		&& mv "$I3_CONFIG.temp" "$I3_CONFIG" \
 		&& echo.success "successfully generated i3 config" \
-		|| ERROR "something went wrong when moving config (check '$(dirname $I3_CONFIG)')" \
+		|| echo.error "something went wrong when moving config (check '$(dirname $I3_CONFIG)')" \
 		|| return 1 \
 		;
 
@@ -144,7 +144,7 @@ ${scwryptsmodule}.parse() {
 	case $1 in
 		--safe ) SAFE=true ;;
 		--override-file )
-			[ -f "$2" ] || ERROR "no file '$2' can be found"
+			[ -f "$2" ] || echo.error "no file '$2' can be found"
 			CONFIG_OVERRIDE_FILE="$2"
 			;;
 	esac
@@ -161,12 +161,12 @@ ${scwryptsmodule}.parse.usage() {
 		--safe            preserve old config (or fail if old conf does not exist)
 		--override-file   fully qualified path to the override yaml file (default ~/.config/i3/local.yaml)
 	"
-	
+
 	USAGE__description+="
 		Since i3wm does not provide a way to load config values dynamically,
 		I run this script to generate colorscheme values and other per-machine
 		overrides.
-	
+
 		Uses the current, active colorscheme and local overrides specified in
 		~/.config/i3/local.yaml
 	"
diff --git a/scwrypts/dotwryn/desktop/xorg/i3/set-background b/scwrypts/dotwryn/desktop/xorg/i3/set-background
index bd88a36..b670222 100755
--- a/scwrypts/dotwryn/desktop/xorg/i3/set-background
+++ b/scwrypts/dotwryn/desktop/xorg/i3/set-background
@@ -1,23 +1,10 @@
 #!/bin/zsh
-REQUIRED_ENV+=(DESKTOP__WALLPAPER_PATH)
+#####################################################################
+
+use --group dotwryn desktop/xorg/i3/set-background
+
 #####################################################################
 
 MAIN() {
-	[ ! -d $WALLPAPER_PATH ] \
-		&& FAIL 1 "no such directory for DESKTOP__WALLPAPER_PATH='$DESKTOP__WALLPAPER_PATH'"
-
-	SELECTION="$1"
-	[ ! $SELECTION ] && SELECTION=random
-
-	case $SELECTION in
-		random )
-			feh --no-fehbg --recursive --randomize --bg-fill $WALLPAPER_PATH
-			;;
-		* )
-			[ ! -f $DESKTOP__WALLPAPER_PATH/$SELECTION ] \
-				&& FAIL 2 "no such wallpaper '$SELECTION' in wallpaper path"
-
-			feh --no-fehbg --bg-fill $DESKTOP__WALLPAPER_PATH/$SELECTION
-			;;
-	esac
+	dotwryn.desktop.xorg.i3.set-background "${@}"
 }
diff --git a/scwrypts/dotwryn/desktop/xorg/i3/set-background.module.zsh b/scwrypts/dotwryn/desktop/xorg/i3/set-background.module.zsh
new file mode 100644
index 0000000..c46acf0
--- /dev/null
+++ b/scwrypts/dotwryn/desktop/xorg/i3/set-background.module.zsh
@@ -0,0 +1,114 @@
+#####################################################################
+
+use scwrypts/get-realpath
+
+#####################################################################
+
+${scwryptsmodule}() {
+	local ERRORS=0
+	local feh_args=(--no-fehbg --bg-fill)
+
+	local selection="${1}"
+
+	local configured_wallpaper_path_required mode
+	case "${selection}" in
+		( random | --random )
+			[[ "${selection}" == random ]] && echo.warning.deprecation 'desktop' 'flag "random" has been replaced with "--random"'
+			mode=random
+			configured_wallpaper_path_required=true
+			;;
+
+		( /* | ~/* | .* )
+			mode=explicit-filepath
+			configured_wallpaper_path_required=false
+			;;
+
+		( '' )
+			mode=interactive
+			configured_wallpaper_path_required=true
+			;;
+
+		( * )
+			mode=basename
+			configured_wallpaper_path_required=true
+			;;
+	esac
+
+	local desktop_wallpaper_realpath
+	case "${configured_wallpaper_path_required}" in
+		( false ) ;;
+		( true )
+			utils.environment.check DESKTOP__WALLPAPER_PATH \
+				|| return 1
+
+			desktop_wallpaper_realpath="$(scwrypts.get-realpath "${DESKTOP__WALLPAPER_PATH}")"
+
+			[[ "${desktop_wallpaper_realpath}" ]] && [[ -d "${desktop_wallpaper_realpath}" ]] \
+				|| echo.error "wallpaper path missing or invalid" -v DESKTOP__WALLPAPER_PATH -v desktop_wallpaper_realpath \
+				|| return 1
+			;;
+	esac
+
+	local background background_type=file
+	case "${mode}" in
+		( random )
+			background="${desktop_wallpaper_realpath}"
+			background_type=directory
+			feh_args+=(--recursive --randomize)
+			;;
+
+		( interactive )
+			background="$(utils.fzf.file-select --prompt 'select a background' "${desktop_wallpaper_realpath}")"
+			;;
+
+		( explicit-filepath )
+			background="$(scwrypts.get-realpath "${selection}")"
+			;;
+
+		( basename )
+			local selection_has_filetype \
+				&& [[ "${selection:e}" ]] \
+				&& selection_has_filetype=true \
+				|| selection_has_filetype=false \
+				;
+
+			case "${selection_has_filetype}" in
+				( true )
+					background="${desktop_wallpaper_realpath}/${selection}"
+					[[ -f "${background}" ]] \
+						|| echo.error "missing or invalid file '${selection}'" -v desktop_wallpaper_realpath
+					;;
+
+				( false )
+					local file_type file_types=(png jpg jpeg)
+					for file_type in "${file_types[@]}" "${file_types[@]:u}"
+					do
+						background="${desktop_wallpaper_realpath}/${selection}.${file_type}"
+						[[ -f "${background}" ]] && break
+						file_type=''
+					done
+
+					[[ "${file_type}" ]] \
+						|| echo.error "no image files matched '${selection}'" -v desktop_wallpaper_realpath \
+						|| return 1
+				;;
+			esac
+			;;
+	esac
+
+	case "${background_type}" in
+		( file )
+			[[ "${background}" ]] && [[ -f "${background}" ]] \
+				|| echo.error "missing or invalid wallpaper file '${selection}'" -v background \
+				|| return 1
+			;;
+
+		( directory )
+			[[ "${background}" ]] && [[ -d "${background}" ]] \
+				|| echo.error "missing or invalid wallpaper directory '${selection}'" -v background \
+				|| return 1
+			;;
+	esac
+
+	feh "${feh_args[@]}" "${background}"
+}
diff --git a/scwrypts/dotwryn/desktop/xorg/xrandr.module.zsh b/scwrypts/dotwryn/desktop/xorg/xrandr.module.zsh
index d0635a1..f97e86b 100644
--- a/scwrypts/dotwryn/desktop/xorg/xrandr.module.zsh
+++ b/scwrypts/dotwryn/desktop/xorg/xrandr.module.zsh
@@ -12,5 +12,5 @@ XRANDR__DISCONNECT_ALL_DISPLAYS() {
 		&& xrandr $(xrandr | grep ' connected' | awk '{print "--output "$1" --off"}') \
 		&& sleep 1 \
 		&& echo.success 'all displays disconnected' \
-		|| { ERROR 'unable to disconnect displays'; return 1; }
+		|| { echo.error 'unable to disconnect displays'; return 1; }
 }
diff --git a/scwrypts/dotwryn/office/vim/vundle/update.module.zsh b/scwrypts/dotwryn/office/vim/vundle/update.module.zsh
index 34d3950..f69705d 100644
--- a/scwrypts/dotwryn/office/vim/vundle/update.module.zsh
+++ b/scwrypts/dotwryn/office/vim/vundle/update.module.zsh
@@ -10,7 +10,7 @@ DEPENDENCIES+=(git)
 ${scwryptsmodule}() {
 	eval "$(utils.parse.autosetup)"
 	##########################################
-	
+
 	local VIM_PLUGIN_DIR="$(config.vim.get-plugin-dir)"
 	[ "${VIM_PLUGIN_DIR}" ] \
 		|| echo.error "cannot determine vim plugin dir (see above)" \
diff --git a/scwrypts/dotwryn/system/symlinks/get-all.module.zsh b/scwrypts/dotwryn/system/symlinks/get-all.module.zsh
index d65a4fb..0ad6898 100644
--- a/scwrypts/dotwryn/system/symlinks/get-all.module.zsh
+++ b/scwrypts/dotwryn/system/symlinks/get-all.module.zsh
@@ -38,10 +38,10 @@ ${scwryptsmodule}() {
 
 		local GROUP_MATCH_REGEX="\\($(printf '\|%s' ${SCWRYPTS_GROUP_ENVS[@]} | sed 's/^\\|//')\\)"
 		local LOCAL_MATCH_REGEX='\(\.'${DOTWRYN_HOSTNAME}'\(\..*\+\)*\)\?'
-	
+
 		local LOCAL_DIR="${SCWRYPTS_CONFIG_PATH}/environments"
 		local SOURCE_DIR="${DOTWRYN}/config/scwrypts/environments"
-	
+
 		find "${DOTWRYN}/config/scwrypts/environments" -mindepth 1 -maxdepth 1 -name \*.env.yaml \
 			| sed -n "s^.*/\(local${LOCAL_MATCH_REGEX}\.${GROUP_MATCH_REGEX}.env.yaml\)$${SOURCE_DIR}/\1^${LOCAL_DIR}/\1^p" \
 			| grep -v '\.secret\.' \
diff --git a/scwrypts/media/audio/play-sfx.module.zsh b/scwrypts/media/audio/play-sfx.module.zsh
index e02bee3..df501a6 100644
--- a/scwrypts/media/audio/play-sfx.module.zsh
+++ b/scwrypts/media/audio/play-sfx.module.zsh
@@ -10,6 +10,7 @@ REQUIRED_ENV+=(DESKTOP__SFX_PATH)
 
 ${scwryptsmodule}() {
 	local SCWRYPTS_NOTIFICATION_ENGINES=(echo notify.desktop)
+	local DESCRIPTION='plays a sound effect'
 
 	eval "$(utils.parse.autosetup)"
 
@@ -47,6 +48,10 @@ ${scwryptsmodule}.parse.locals() {
 ${scwryptsmodule}.parse.usage() {
 	USAGE__description='
 		play the indicated sound effect by mapped name or filename
+	'
+
+	USAGE__args='
+		\$1   mapped name or filename
 
 		mapped names :
 		  backlight  notify
@@ -54,10 +59,6 @@ ${scwryptsmodule}.parse.usage() {
 		  mute       volume
 		  gamedock   homedock  undock
 	'
-
-	USAGE__args='
-		\$1   mapped name or filename
-	'
 }
 
 ${scwryptsmodule}.parse.validate() {
@@ -67,6 +68,6 @@ ${scwryptsmodule}.parse.validate() {
 		;
 
 	[ -f "${SFX_FILE}" ] \
-		|| notify.error "unable to locate sfx file '$1'" \
+		|| notify.error "unable to locate sfx file '${SFX_FILE}'" \
 		|| return 1
 }
diff --git a/scwrypts/media/cloud/synchronize-target.module.zsh b/scwrypts/media/cloud/synchronize-target.module.zsh
index ef30486..fb17004 100644
--- a/scwrypts/media/cloud/synchronize-target.module.zsh
+++ b/scwrypts/media/cloud/synchronize-target.module.zsh
@@ -54,7 +54,7 @@ ${scwryptsmodule}() {
 	echo.status "${ACTION}ing ${TARGET}"
 	cloud.aws s3 sync $A $B \
 		&& echo.success "${TARGET} up-to-date" \
-		|| { ERROR "unable to sync ${TARGET} (see above)"; return 1; }
+		|| { echo.error "unable to sync ${TARGET} (see above)"; return 1; }
 }
 
 #####################################################################
@@ -81,7 +81,7 @@ ${scwryptsmodule}.parse.usage() {
 
 ${scwryptsmodule}.parse.validate() {
 	[ "${TARGET}" ] \
-		|| ERROR 'must specify a target'
+		|| echo.error 'must specify a target'
 
 	TARGET_LOCAL="${HOME}/${TARGET}"
 	TARGET_CLOUD="s3://${MEDIA_SYNC__S3_BUCKET}/${TARGET}"
diff --git a/scwrypts/media/cloud/synchronize.module.zsh b/scwrypts/media/cloud/synchronize.module.zsh
index 3c135bc..f3a5a37 100644
--- a/scwrypts/media/cloud/synchronize.module.zsh
+++ b/scwrypts/media/cloud/synchronize.module.zsh
@@ -36,7 +36,7 @@ ${scwryptsmodule}() {
 
 	[[ $FAILED_COUNT -eq 0 ]] \
 		&& echo.success "successfully completed ${ACTION} for ${TARGET_COUNT} / ${TARGET_COUNT} target(s)" \
-		||   ERROR "failed ${ACTION} for ${FAILED_COUNT} / ${TARGET_COUNT} target(s)" \
+		||   echo.error "failed ${ACTION} for ${FAILED_COUNT} / ${TARGET_COUNT} target(s)" \
 		;
 }
 
diff --git a/scwrypts/media/cloud/zshparse/actions.module.zsh b/scwrypts/media/cloud/zshparse/actions.module.zsh
index 7c167d6..6b168b3 100644
--- a/scwrypts/media/cloud/zshparse/actions.module.zsh
+++ b/scwrypts/media/cloud/zshparse/actions.module.zsh
@@ -28,10 +28,10 @@ ${scwryptsmodule}.validate() {
 	case "${ACTION}" in
 		( push | pull | pull-first-synchronize | push-first-synchronize ) ;;
 		( '' )
-			ERROR 'must specify a media sync action'
+			echo.error 'must specify a media sync action'
 			;;
 		( * )
-			ERROR "invalid media sync action '${ACTION}'"
+			echo.error "invalid media sync action '${ACTION}'"
 			;;
 	esac
 }
diff --git a/scwrypts/media/ffmpeg/get-audio-clip-from-video.module.zsh b/scwrypts/media/ffmpeg/get-audio-clip-from-video.module.zsh
index c90d77c..11f5787 100644
--- a/scwrypts/media/ffmpeg/get-audio-clip-from-video.module.zsh
+++ b/scwrypts/media/ffmpeg/get-audio-clip-from-video.module.zsh
@@ -42,7 +42,7 @@ ${scwryptsmodule}() {
 		-ss ${START_TIME_SECONDS} -t $((${END_TIME_SECONDS} - ${START_TIME_SECONDS}))\
 		"${OUTPUT_FILENAME}" \
 		&& echo.success "created clip '${OUTPUT_FILENAME}'" \
-		||   ERROR "error creating clip '$(basename -- "${OUTPUT_FILENAME}")' (see above)"
+		||   echo.error "error creating clip '$(basename -- "${OUTPUT_FILENAME}")' (see above)"
 }
 
 #####################################################################
@@ -53,7 +53,7 @@ ${scwryptsmodule}.parse() {
 	# local START_TIME_SECONDS END_TIME_SECONDS    optional
 
 	local PARSED=0
-	
+
 	case $1 in
 		-i | --input-filename  ) PARSED=2;  INPUT_FILENAME="$2" ;;
 		-o | --output-filename ) PARSED=2; OUTPUT_FILENAME="$2" ;;
@@ -84,24 +84,24 @@ ${scwryptsmodule}.parse.validate() {
 		&& [ "${INPUT_FILENAME}" ] \
 		&& [ -f "${INPUT_FILENAME}" ] \
 		&& [ "${OUTPUT_FILENAME}" ] \
-		|| ERROR "must provide a valid input and output filename\ninput  : '${INPUT_FILENAME}\noutput : '${OUTPUT_FILENAME}'" \
+		|| echo.error "must provide a valid input and output filename\ninput  : '${INPUT_FILENAME}\noutput : '${OUTPUT_FILENAME}'" \
 		|| return
 
 	[[ ${OUTPUT_FILENAME} =~ .mp3$ ]] || OUTPUT_FILENAME="${OUTPUT_FILENAME}.mp3"
 
 	local VIDEO_LENGTH_SECONDS=$(media.ffmpeg.get-video-length-seconds "${INPUT_FILENAME}")
 	[ "${VIDEO_LENGTH_SECONDS}" ] && [[ "${VIDEO_LENGTH_SECONDS}" -gt 0 ]] \
-		|| ERROR "unable to determine video length; is '${INPUT_FILENAME}' a video?" \
+		|| echo.error "unable to determine video length; is '${INPUT_FILENAME}' a video?" \
 		|| return
 
 	local CLIP_METHOD=start-time-to-end-time
 	case ${USE_WHOLE_VIDEO} in
 		true )
 			[ ! "${START_TIME_SECONDS}" ] \
-				|| ERROR "conflicting arguments '--start' and '--use-whole-video'"
+				|| echo.error "conflicting arguments '--start' and '--use-whole-video'"
 
 			[ ! "${END_TIME_SECONDS}" ] \
-				|| ERROR "conflicting arguments '--end' and '--use-whole-video'"
+				|| echo.error "conflicting arguments '--end' and '--use-whole-video'"
 			;;
 		false )
 			[ ! "${START_TIME_SECONDS}" ] && [ ! "${END_TIME_SECONDS}" ] \
@@ -118,28 +118,28 @@ ${scwryptsmodule}.parse.validate() {
 		interactive )
 			START_TIME_SECONDS=$(echo 0 | utils.fzf.user-input "enter start time (0 ≤ t < ${VIDEO_LENGTH_SECONDS})")
 			[ "${START_TIME_SECONDS}" ] \
-				|| ERROR 'interactive user abort' \
+				|| echo.error 'interactive user abort' \
 				|| return
 
 			END_TIME_SECONDS=$(echo ${VIDEO_LENGTH_SECONDS} | utils.fzf.user-input "enter end time (${START_TIME_SECONDS} > t ≥ $VIDEO_LENGTH_SECONDS)")
 			[ "${END_TIME_SECONDS}" ] \
-				|| ERROR 'interactive user abort' \
+				|| echo.error 'interactive user abort' \
 				|| return
 			;;
 	esac
 
 	[[ "${START_TIME_SECONDS}" -ge 0 ]] \
-		|| ERROR "cannot use negative start time (start time = ${START_TIME_SECONDS})"
+		|| echo.error "cannot use negative start time (start time = ${START_TIME_SECONDS})"
 
 	[[ "${END_TIME_SECONDS}" -gt 0 ]] \
-		|| ERROR "end time must be after the video starts (end time = ${END_TIME_SECONDS})"
+		|| echo.error "end time must be after the video starts (end time = ${END_TIME_SECONDS})"
 
 	[[ "${START_TIME_SECONDS}" -lt "${VIDEO_LENGTH_SECONDS}" ]] \
-		|| ERROR "start time must be before video ends (start time = ${START_TIME_SECONDS}; video length = ${VIDEO_LENGTH_SECONDS})"
+		|| echo.error "start time must be before video ends (start time = ${START_TIME_SECONDS}; video length = ${VIDEO_LENGTH_SECONDS})"
 
 	[[ "${END_TIME_SECONDS}" -le "${VIDEO_LENGTH_SECONDS}" ]] \
-		|| ERROR "end time cannot go beyond video end (end time = ${END_TIME_SECONDS}; video length = ${VIDEO_LENGTH_SECONDS})"
+		|| echo.error "end time cannot go beyond video end (end time = ${END_TIME_SECONDS}; video length = ${VIDEO_LENGTH_SECONDS})"
 
 	[[ "${START_TIME_SECONDS}" -lt "${END_TIME_SECONDS}" ]] \
-		|| ERROR "start time must come before end time (start time = ${START_TIME_SECONDS}; end time = ${END_TIME_SECONDS})"
+		|| echo.error "start time must come before end time (start time = ${START_TIME_SECONDS}; end time = ${END_TIME_SECONDS})"
 }
diff --git a/scwrypts/media/ffmpeg/get-video-length-seconds.module.zsh b/scwrypts/media/ffmpeg/get-video-length-seconds.module.zsh
index ab8c148..821d78a 100644
--- a/scwrypts/media/ffmpeg/get-video-length-seconds.module.zsh
+++ b/scwrypts/media/ffmpeg/get-video-length-seconds.module.zsh
@@ -8,7 +8,7 @@ ${scwryptsmodule}() {
 	local FILENAME="$1"
 
 	[ "${FILENAME}" ] && [ -f "${FILENAME}" ] \
-		|| ERROR "invalid or missing file '${FILENAME}'" \
+		|| echo.error "invalid or missing file '${FILENAME}'" \
 		|| return 1
 
 	ffprobe \
diff --git a/scwrypts/media/mscore/zshparse/filename.module.zsh b/scwrypts/media/mscore/zshparse/filename.module.zsh
index 0c6dd8e..34bb66f 100644
--- a/scwrypts/media/mscore/zshparse/filename.module.zsh
+++ b/scwrypts/media/mscore/zshparse/filename.module.zsh
@@ -29,14 +29,14 @@ ${scwryptsmodule}.validate() {
 			MSCORE_FILENAME="$(cd "${MSCORE__SCORES_PATH}"; find . -type f | grep '\.msc[zx]$' | utils.fzf 'select a score')"
 
 			[ "${MSCORE_FILENAME}" ] && [ -f "${MSCORE__SCORES_PATH}/${MSCORE_FILENAME}" ] \
-				|| ERROR "invalid score '${MSCORE_FILENAME}'"
+				|| echo.error "invalid score '${MSCORE_FILENAME}'"
 
 			MSCORE_FILENAME="${MSCORE__SCORES_PATH}/${MSCORE_FILENAME}"
 			;;
 
 		( * )
 			[ -f "${MSCORE_FILENAME}" ] \
-				|| ERROR "no score '${MSCORE_FILENAME}' exists"
+				|| echo.error "no score '${MSCORE_FILENAME}' exists"
 			;;
 	esac
 
@@ -65,7 +65,7 @@ ${scwryptsmodule}.validate() {
 
 	[ -f "${TEMP_FILE}" ] \
 		&& MSCORE_FILENAME="${TEMP_FILE}" \
-		|| ERROR "failed to extract '${TEMP_FILE}'" \
+		|| echo.error "failed to extract '${TEMP_FILE}'" \
 		|| MSCORE_FILENAME='' \
 		;
 
diff --git a/scwrypts/media/youtube/download.module.zsh b/scwrypts/media/youtube/download.module.zsh
index 03eb4ad..220b95a 100644
--- a/scwrypts/media/youtube/download.module.zsh
+++ b/scwrypts/media/youtube/download.module.zsh
@@ -20,13 +20,13 @@ ${scwryptsmodule}() {
 	local FILENAME="$(media.youtube.get-filename "${URL}")"
 
 	[ "${FILENAME}" ] \
-		|| ERROR "could not find metadata; cannot proceed with download\n${URL}" \
+		|| echo.error "could not find metadata; cannot proceed with download\n${URL}" \
 		|| return 1
 
 	media.youtube.yt-dlp "${URL}" \
 			--format 'bestvideo[ext=mp4]+bestaudio[ext=m4a]/mp4' \
 		&& echo.success "finished download of ${URL}\n$(media.youtube.get-download-path)/${FILENAME}" \
-		||   ERROR "failed to download '${FILENAME}' (${URL})"
+		||   echo.error "failed to download '${FILENAME}' (${URL})"
 		;
 }
 
@@ -59,5 +59,5 @@ ${scwryptsmodule}.parse.usage() {
 
 ${scwryptsmodule}.parse.validate() {
 	[ "$URL" ] \
-		|| ERROR "must provide download URL"
+		|| echo.error "must provide download URL"
 }
diff --git a/scwrypts/remote/tmux/omni b/scwrypts/remote/tmux/omni
index 4bc40b5..2137714 100755
--- a/scwrypts/remote/tmux/omni
+++ b/scwrypts/remote/tmux/omni
@@ -3,7 +3,7 @@
 
 DEPENDENCIES+=(tmux scwrypts)
 
-use omni --group remote
+use --group remote omni
 
 #####################################################################
 
diff --git a/zsh/rc.d/15.plugins-scwrypts.zsh b/zsh/rc.d/15.plugins-scwrypts.zsh
index f4a98cf..999f030 100644
--- a/zsh/rc.d/15.plugins-scwrypts.zsh
+++ b/zsh/rc.d/15.plugins-scwrypts.zsh
@@ -2,6 +2,7 @@
 
 ZSH_PLUGINS+=(
 	"$(scwrypts --root)/scwrypts.plugin.zsh"
+	"$(scwrypts --root)/zsh/utils/utils.module.zsh"
 	)
 
 () {  # default environment name lookup
diff --git a/zsh/rc.d/80.frog.zsh b/zsh/rc.d/80.frog.zsh
index d5ed03b..1ac7979 100644
--- a/zsh/rc.d/80.frog.zsh
+++ b/zsh/rc.d/80.frog.zsh
@@ -1,16 +1,3 @@
-command -v \
-		echo.error \
-		echo.status \
-		echo.success \
-		echo.success.color \
-		rg \
-		sed \
-		utils.check-errors \
-		utils.colors.green \
-		utils.yN \
-	&>/dev/null || return 0
-
-
 frog() {
 	eval "$(usage.reset)"
 
@@ -136,7 +123,7 @@ frog() {
 	rg -- "${SEARCH_REGEX}" ${FILES_MATCHED[@]}
 
 	echo.status "showing matches from $(utils.colors.green)${#FILES_MATCHED[@]} file(s)$(echo.status.color) in the current directory"
-	utils.yN "replace all matches with '${REPLACE_VALUE}'?" || return 1
+	user.yN "replace all matches with '${REPLACE_VALUE}'?" || return 1
 
 	[[ ${TRIM} =~ true ]] && SEARCH_REGEX='\s\+$'