diff --git a/home/-shrc b/home/-shrc
index 28a4d5d..1e41c3a 100644
--- a/home/-shrc
+++ b/home/-shrc
@@ -125,6 +125,8 @@ alias curls="curl -sS" ### @- invoke curl with less noise.
 
 alias get="git clone --single-branch --depth 1" ### @- retrieve the most recent files from the default branch of a git repository, and not much else.
 alias gs='git status' ### @- invoke git's status subcommand.
+###
+### **TODO:** consider renaming because gs(1) already exists.
 alias gd='git diff -U2' ### @- invoke git's diff subcommand with fewer lines of context.
 alias gds='git --no-pager diff --stat' ### @- display difference stats from git.
 alias gl='git log --oneline' ### @- invoke git's log subcommand with a single line per commit.
@@ -132,6 +134,9 @@ alias glo='git log --graph --decorate --pretty=oneline --abbrev-commit --all' ##
 alias g1='git log --pretty=oneline --abbrev-commit --color=always | head -1' ### @- display the most recent git commit.
 alias gr='git remote -v' ### @- display remote git repositories verbosely.
 alias gb='git --no-pager branch' ### @- display the current git branch.
+###
+### **NOTE:** there also exists a gb(1) program provided by
+### the *gb* package that i don't use.
 
 # being specific {{{2
 
@@ -166,6 +171,8 @@ lol() { ### @ ll - list files verbosely, fancily, ordered, but not recursively.
 
 alias diff="git diff --color=auto --no-ext-diff --no-index --no-prefix" ### @- use git's diff subcommand for general diffing.
 alias gc="git column --mode=dense --padding=2" ### @- columnize text by using git's column subcommand.
+###
+### **TODO:** consider renaming because gc(1) already exists.
 alias counts='find . | wc -l' ### @- count files in the current directory, including files found recursively.
 alias exts="find -type f | grep -o '\\.[^/.]*$' | sort | uniq -c | sort -n" ### @- count and sort file extensions in the current directory, including files found recursively.
 alias nocom='grep -Ev --line-buffered --color=never "^[[:space:]]*(//|#)"' ### @- strip single-line C-like and shell-like comments.
@@ -175,6 +182,9 @@ alias bomb='uconv -f utf-8 -t utf-8 --add-signature' ### @- add a Byte-Order Mar
 alias cleanse='tr -cd "\11\12\15\40-\176"' ### @- strip unprintable and non-ASCII characters.
 alias unwrap='awk '\''BEGIN{RS="\n\n";FS="\n"}{for(i=1;i<=NF;i++)printf "%s ",$i;print "\n"}'\' ### @- join paragraphs into one line each.
 alias double='awk "{print;print}"' ### @- print every line twice. <br/> print every line twice.
+###
+### **NOTE:** there also exists a double(1) program provided by
+### the *plotutils* package that i don't use.
 alias join2='paste -d" " - -' ### @- join every other line.
 alias katagana='perlu -MUnicode::Normalize -pe'"'"'$_=NFKD($_)=~y/ァ-ヶ /ぁ-ゖ　/r'"'" ### @- convert katakana codepoints to their equivalent hiragana.
 ### useful for translating [debug text from ancient games.](https://tcrf.net/)
diff --git a/sh/ff b/sh/ff
index 08ceb0f..818ed81 100644
--- a/sh/ff
+++ b/sh/ff
@@ -4,7 +4,8 @@
 # YES_DASH
 
 ff() { ### @-
-    ### select a file from a given or current directory using `fzy`.
+    ### select a file from a given or current directory using
+    ### [`fzy`.](https://github.com/jhawthorn/fzy)
     [ $# -le 1 ] || { printf "%s\n" "$0: too many arguments" >&2; return 1; }
     find "${1:-.}" -type f | fzy
 }
diff --git a/sh/hex b/sh/hex
index 6f43822..5dfebce 100755
--- a/sh/hex
+++ b/sh/hex
@@ -15,6 +15,9 @@ hex() { ### @-
     ### $ hex 0x221EA8-0x212020
     ### 0000FE88
     ### ```
+    ###
+    ### **NOTE:** there also exists a hex(1) program provided by
+    ### the *basez* package that i don't use.
     printf "%08X\n" "$(($@))"
 }
 
diff --git a/sh/isup b/sh/isup
index a05a230..61585c9 100755
--- a/sh/isup
+++ b/sh/isup
@@ -5,6 +5,13 @@
 
 isup() { ### @-
     ### return 0 if a given website returns a 2xx HTTP code.
+    ###
+    ### ```
+    ### $ isup google.com && echo yay || echo nay
+    ### yay
+    ### $ isup fdhafdslkjgfjs.com && echo yay || echo nay
+    ### nay
+    ### ```
     local c="$(curl -sLI -w '%{http_code}' -o /dev/null "$1")"
     [ -z "${c#2[0-9][0-9]}" ]
 }
diff --git a/sh/monitor b/sh/monitor
index b4f1315..7a1a922 100755
--- a/sh/monitor
+++ b/sh/monitor
@@ -8,6 +8,9 @@ monitor() { ### @-
     ### ```
     ### usage: monitor [-fs] [-n {period}] {command} [{args...}]
     ### ```
+    ###
+    ### **NOTE:** there also exists monitor(1) programs provided by
+    ### the *389-ds-base* and *dmucs* packages that i don't use.
     local bottom=0 strip=0 interval=2 opt=
     while getopts 'fsn:h' opt; do
         case $opt in
diff --git a/sh/note b/sh/note
index a7db472..5acaa94 100644
--- a/sh/note
+++ b/sh/note
@@ -5,6 +5,9 @@
 
 note() { ### @-
     ### act like [`echo2`,](#echo2) but use a bright color to stand out more.
+    ###
+    ### **NOTE:** there also exists a [note(1)](https://www.daemon.de/projects/note/)
+    ### program provided by the *note* package that i don't use.
     local IFS=" "
     printf "\033[1m%s\033[0m\n" "$*" >&2
 }
diff --git a/sh/rot13 b/sh/rot13
index 81e4ea8..35f6aea 100644
--- a/sh/rot13
+++ b/sh/rot13
@@ -10,6 +10,9 @@ rot13() { ### @-
     ### $ rot13 <<< abc123
     ### nop678
     ### ```
+    ###
+    ### **NOTE:** there also exists rot13(1) programs provided by
+    ### the *bsdgames* and *hxtools* packages that i don't use.
     tr -- A-Za-z0-9 N-ZA-Mn-za-m5-90-4
 }
 
diff --git a/sh/rs b/sh/rs
index a2d755f..87dabac 100644
--- a/sh/rs
+++ b/sh/rs
@@ -5,6 +5,8 @@ rs() { ### @-
     ### record screen. does not record audio.
     ### currently only works on Windows (gdigrab).
     ### i'm sure there's something equivalent for Linux.
+    ###
+    ### **TODO:** consider renaming because rs(1) already exists.
     set -e
 
     local o_overwrite= o_rate=30 o_duration=0
diff --git a/sh/sc b/sh/sc
index 78622fb..3f1a408 100755
--- a/sh/sc
+++ b/sh/sc
@@ -41,6 +41,8 @@ sc() { ### @-
     ### upload given files to a webserver and return a direct link for sharing them.
     ### you'll want to tweak this if you use it yourself.
     ### this contains some extra logic for screenshots created by `scropt`.
+    ###
+    ### **TODO:** consider renaming because sc(1) already exists.
     if [ -n "${ZSH_VERSION:-}" ]; then
         # syntax is too different to bother tbh
         echo "please run with bash"
diff --git a/sh/scramble b/sh/scramble
index 148597d..837d75b 100755
--- a/sh/scramble
+++ b/sh/scramble
@@ -7,6 +7,8 @@ scramble() { ### @-
     ### scrambles text in a predictable way using regex.
     ###
     ### sacbremls ttex in a pdrceailtbe way unsig reegx.
+    ###
+    ### **TODO:** consider renaming because scramble(1) already exists.
     [ $# -eq 0 ] || { printf "%s\n" "$0: does not take arguments" >&2; return 1; }
     local eggs='s/@\(\w\)\(\w\)\(\w\)/@\3\1@\2/g'
     sed \
diff --git a/sh/screeny b/sh/screeny
index 67f61d9..ecb330e 100755
--- a/sh/screeny
+++ b/sh/screeny
@@ -2,7 +2,8 @@
 # YES_ZSH
 
 screeny() { ### @-
-    ### i don't use this anymore~
+    ### handle GNU screens.
+    ### these days, i typically use tmux instead.
     local user="${1:?needs arg for user name}"
     shift
     home="/home/$user"
diff --git a/sh/scropt b/sh/scropt
index 89e1ff7..2a7cf64 100755
--- a/sh/scropt
+++ b/sh/scropt
@@ -8,7 +8,9 @@
 scropt() { ### @-
     ### run `scrot` through `optipng` and save the result to `~/play/$(now).png`.
     ###
-    ### `$ ~/sh/sc $(~/sh/scropt -s -d0.5)`
+    ### ```
+    ### $ ~/sh/sc $(~/sh/scropt -s -d0.5)
+    ### ```
     local now=$(now)
     [ $? -eq 0 ] || return $?
     local fn="$HOME/play/$now.png"
diff --git a/sh/streamcrap b/sh/streamcrap
index 7597fba..fb3d962 100644
--- a/sh/streamcrap
+++ b/sh/streamcrap
@@ -97,6 +97,9 @@ yt() { ### @-
     ### remaining arguments are passed to mpv.
     ###
     ### there exist several variants for more specific use cases.
+    ###
+    ### **NOTE:** there also exists a yt(1) program provided by
+    ### the *python3-yt* package that i don't use.
     argc -ge 1 "$0" "$@" || return
     local vid="$1"; shift
     [ -e "$vid" ] || [ "$vid" != "${vid#http}" ] || vid="ytdl://$vid"
diff --git a/sh/unscreen b/sh/unscreen
index 4aae7d7..2116ca5 100755
--- a/sh/unscreen
+++ b/sh/unscreen
@@ -4,7 +4,8 @@
 # NO_DASH
 
 unscreen() { ### @-
-    ### i don't use this anymore~
+    ### handle closing of screens — this works alongside [`screeny`](#screeny).
+    ### these days, i typically use tmux instead.
     local pids="$(screen -ls | fgrep "$1" | cut -d. -f1)"
     for pid in $=pids; do
         local ppid="$(ps h --ppid "$pid" -o pid)"