docs(functions): merge manual-only examples and notes into headers

Folds the examples Section 5 carried but the headers did not into each
function's `# EXAMPLE`, and moves the three lines that only looked like
examples -- the two typo-abbreviation notes and rm's /usr/bin/rm fallback --
into `# NOTES`, the label already in use.

Also corrects gi's synopsis, which omitted -l, and documents yt-dlp's
--no-embed-thumbnail in `# ARGUMENTS`.

functions/bd-pull.fish

@@ -21,6 +21,7 @@
 #
 # EXAMPLE
 #   bd-pull myuser/myproject
+#   bd-pull rootiest/fish-config
 function bd-pull --description 'Pull new Gitea issues into local Beads and link them'
     if not set -q argv[1]; echo "Need repo owner/name"; return 1; end
     if not set -q GITEA_TOKEN; echo "\$GITEA_TOKEN not set"; return 1; end

functions/cat.fish

@@ -17,6 +17,7 @@
 #
 # EXAMPLE
 #   cat README.md
+#   cat ~/projects/myapp
 function cat --wraps='bat' --description 'Use bat for files, ls for directories, and raw cat for ANSI logs'
     # Opinionated guard (C1): fall back to bare command cat when disabled.
     if not __fish_config_op_enabled __fish_config_op_aliases

functions/cheat.fish

@@ -17,6 +17,7 @@
 #
 # EXAMPLE
 #   cheat tar
+#   cheat git
 function cheat --wraps='cheat' --description 'alias cheat=cheat -c'
     if type -q cheat
         command cheat -c $argv

functions/config-help.fish

@@ -42,6 +42,7 @@
 #   config-help --man
 #   config-help keys --man
 #   config-help --help
+#   config-help pkg --man
 #
 # NOTES
 #   The preferred invocation is `help config [...]` — this function is

functions/copy.fish

@@ -17,6 +17,7 @@
 #
 # EXAMPLE
 #   copy ./mydir/ ~/backup
+#   copy ./mydir/ ~/backup    # copies mydir INTO backup, not backup/mydir/
 function copy
     set count (count $argv)
     if test "$count" = 2; and test -d "$argv[1]"

functions/dng2avif.fish

@@ -25,6 +25,7 @@
 #
 # EXAMPLE
 #   dng2avif photo.dng
+#   dng2avif -q 85 -s 5 -i shot.dng -o out.avif
 function dng2avif --description 'Convert DNG raw to 10-bit HDR AVIF'
     set -l options (fish_opt -s h -l help)
     set -a options (fish_opt -s i -l input -r)

functions/du.fish

@@ -20,6 +20,7 @@
 #
 # EXAMPLE
 #   du ~/Downloads
+#   du --disk
 function du --description 'Execute du'
     # Opinionated guard (C1): fall back to bare command du when disabled.
     if not __fish_config_op_enabled __fish_config_op_aliases

functions/dusize.fish

@@ -16,6 +16,7 @@
 #
 # EXAMPLE
 #   dusize ~/Downloads
+#   dusize ~/Videos
 function dusize --wraps='du' --description 'alias dusize=du'
     du -sh (test -n "$argv[1]"; and echo $argv[1]; or echo .)
 end

functions/edit.fish

@@ -41,6 +41,8 @@
 #   edit --terminal --new todo.md
 #   edit --editor=code --clipboard
 #   edit --text="hello world"
+#   edit ~/.config/fish/config.fish
+#   edit --visual notes.txt
 function edit --description 'Open files in a terminal or GUI editor with fallbacks'
     set -l c_head (set_color --bold cyan)
     set -l c_cmd (set_color --bold white)

functions/fish-deps.fish

@@ -23,6 +23,9 @@
 #
 # EXAMPLE
 #   fish-deps sync
+#   fish-deps
+#   fish-deps install
+#   fish-deps update
 function fish-deps --description 'Manage fish shell dependencies'
     set -l subcmd $argv[1]
 

functions/gi.fish

@@ -5,7 +5,7 @@
 #   04-git-and-version-control
 #
 # SYNOPSIS
-#   gi [-h] [-b] [-p] [-s] [targets...]
+#   gi [-h] [-b] [-p] [-s] [-l] [targets...]
 #
 # DESCRIPTION
 #   Generates .gitignore content by querying the gitignore.io API. Appends
@@ -27,6 +27,8 @@
 #
 # EXAMPLE
 #   gi python,venv
+#   gi -b -p
+#   gi -s node > .gitignore
 function gi --description 'Generate .gitignore files using the gitignore.io API'
     argparse h/help d/description l/list b/boilerplate p/prompt s/stdout -- $argv
     or return 1

functions/git-clean.fish

@@ -22,6 +22,7 @@
 #
 # EXAMPLE
 #   git-clean --force
+#   git-clean
 function git-clean --description 'Sync main, prune remotes, and delete orphaned branches'
     set -l options h/help f/force
     argparse $options -- $argv

functions/logs.fish

@@ -21,6 +21,8 @@
 #
 # EXAMPLE
 #   logs -c paru
+#   logs
+#   logs -c scrollback
 function logs --description 'Browse terminal log files interactively with fzf'
     # Opinionated guard (C4): integrations disabled
     if not __fish_config_op_enabled __fish_config_op_integrations

functions/ls.fish

@@ -16,6 +16,8 @@
 #
 # EXAMPLE
 #   ls ~/projects
+#   ls
+#   ls -a ~/projects
 function ls --description 'List all files'
     # Opinionated guard (C1): fall back to bare command ls when disabled.
     if not __fish_config_op_enabled __fish_config_op_aliases

functions/mkcd.fish

@@ -24,6 +24,7 @@
 #
 # EXAMPLE
 #   mkcd ~/projects/myapp
+#   mkcd ~/projects/newapp/src
 function mkcd --description 'Create a directory (with parents) and cd into it'
     set -l c_head (set_color --bold cyan)
     set -l c_cmd  (set_color --bold white)

functions/open-url.fish

@@ -36,6 +36,9 @@
 # EXAMPLE
 #   open-url https://git.rootiest.dev/rootiest/fish-config
 #   open-url -v https://fish-config-docs.pages.dev/
+#
+# NOTES
+#   Typo abbreviation: url-open (expands to open-url on space/enter).
 function open-url --description 'Open a URL in the best available web browser'
     argparse h/help s/silent v/verbose -- $argv
     or return 1

functions/repo-open.fish

@@ -42,6 +42,12 @@
 #   repo-open              # open current branch (+ subdir) in browser
 #   repo-open --print      # just print the URL
 #   repo-open --root       # repo home page for the current branch
+#   repo-open
+#   repo-open --print
+#   repo-open --root
+#
+# NOTES
+#   Typo abbreviation: open-repo (expands to repo-open on space/enter).
 function repo-open --description 'Open the origin remote of the current repo in a browser'
     argparse -X 0 h/help p/print r/root -- $argv
     or return 1

functions/rg.fish

@@ -17,6 +17,8 @@
 #
 # EXAMPLE
 #   rg "TODO" src/
+#   rg "fish_greeting" ~/.config/fish/
+#   rg -l "TODO" ~/projects/myapp
 function rg --description 'alias rg=rg --hyperlink-format=kitty'
     # Opinionated guard (C1): fall back to bare command rg when disabled.
     if not __fish_config_op_enabled __fish_config_op_aliases

functions/rm.fish

@@ -33,6 +33,9 @@
 #   rm file.txt
 #   rm -e
 #   rm -S sensitive_key.pem
+#
+# NOTES
+#   Falls back to /usr/bin/rm when trash is unavailable.
 function rm --description 'Ultimate rm: trash, list, empty, and secure-erase'
     # Opinionated guard (C1): fall back to bare command rm when disabled.
     if not __fish_config_op_enabled __fish_config_op_aliases

functions/spark.fish

@@ -22,6 +22,7 @@
 # EXAMPLE
 #   spark 1 1 2 5 14 42
 #   seq 64 | sort --random-sort | spark
+#   echo "3 7 2 9 1" | spark
 function spark --description 'Sparklines'
     argparse --ignore-unknown --name=spark v/version h/help m/min= M/max= -- $argv || return
 

functions/y.fish

@@ -20,6 +20,8 @@
 #
 # EXAMPLE
 #   y "hello world"
+#   ls | y
+#   cat file.txt | y
 function y --description 'Yank to clipboard'
     # Check for help flag
     if contains -- -h $argv; or contains -- --help $argv

functions/yt-dlp.fish

@@ -17,6 +17,7 @@
 #
 # ARGUMENTS
 #   args...  Arguments forwarded to yt-dlp (defaults prepended)
+#   --no-embed-thumbnail  Skip thumbnail embedding for this run
 #
 # EXAMPLE
 #   yt-dlp dQw4w9WgXcQ