.gitignore

@@ -298,3 +298,4 @@ AGENTS/
 #   agents-init --plugins
 docs/devlogs
 #   ────────────────────────────────────────────────────────
+/.cache_ggshield

docs/fish-config.index

@@ -151,6 +151,7 @@ superpowers=### superpowers
 media=## 5.13 Media and Utilities
 dng2avif=### dng2avif
 spark=### spark
+yt-dlp=### yt-dlp
 miscfns=## 5.14 Miscellaneous
 config-help=### config-help
 config-update=### config-update

docs/fish-config.md

@@ -923,7 +923,7 @@ Add -i (interactive confirmation) to destructive commands:
       Integrations  wakatime, tailscale
       Recommended   cargo, starship, uv, direnv, paru, yay, eza, lsd, bat,
                     btop, dust, duf, prettyping, ov, ripgrep, lazygit,
-                    lazydocker, trash, kitty, wezterm, python3
+                    lazydocker, trash, kitty, wezterm, python3, yt-dlp
 
     fish-deps
     fish-deps install
@@ -1277,6 +1277,21 @@ Add -i (interactive confirmation) to destructive commands:
     spark 1 1 2 5 14 42
     echo "3 7 2 9 1" | spark
 
+### yt-dlp
+
+    Synopsis:  yt-dlp [args...] URL [URL...]
+    Wraps yt-dlp, prepending sane defaults: --sponsorblock-remove all,
+    --embed-subs, --embed-metadata, and --embed-thumbnail. Each default
+    is suppressed when you already pass that flag, its alias, or its
+    negation (e.g. --no-embed-thumbnail drops the thumbnail default;
+    --no-sponsorblock or your own --sponsorblock-remove drops ours). All
+    other arguments pass through unchanged, and --help falls through to
+    real yt-dlp. Opinionated component (C1 aliases); when disabled it
+    passes straight through to the system yt-dlp.
+
+    yt-dlp dQw4w9WgXcQ
+    yt-dlp --no-embed-thumbnail dQw4w9WgXcQ
+
 ---
 
 ## 5.14 Miscellaneous
@@ -1522,6 +1537,9 @@ fish-deps manages these tools. Run `fish-deps` to check status, or
                 Note: uv does not provide python3 on PATH, and Arch's base
                 does not include it, so it is listed separately. All
                 consumers degrade gracefully without it.
+    yt-dlp      Video/media downloader; backs the yt-dlp wrapper function.
+                Optional — the wrapper falls back to the system yt-dlp and
+                the rest of the config works without it.
 
 ## Install Methods
 

functions/_fish_deps_catalog.fish

@@ -16,27 +16,27 @@ function _fish_deps_catalog
     set -g _fdc_bins \
         uv cargo fish starship fzf zoxide direnv paru yay \
         wakatime tailscale \
-        eza lsd bat btop dust duf prettyping ov rg lazygit lazydocker trash kitty wezterm python3
+        eza lsd bat btop dust duf prettyping ov rg lazygit lazydocker trash kitty wezterm python3 yt-dlp
 
     set -g _fdc_tiers \
         rec rec req rec req req rec rec rec \
         int int \
-        rec rec rec rec rec rec rec rec rec rec rec rec rec rec rec
+        rec rec rec rec rec rec rec rec rec rec rec rec rec rec rec rec
 
     set -g _fdc_cargo \
         "" "" "" starship "" zoxide "" "" "" \
         "" "" \
-        eza lsd bat "" du-dust "" "" ov ripgrep "" "" trashy "" "" ""
+        eza lsd bat "" du-dust "" "" ov ripgrep "" "" trashy "" "" "" ""
 
     set -g _fdc_pm \
         uv cargo fish starship fzf zoxide direnv "" yay \
         wakatime tailscale \
-        eza lsd bat btop dust duf prettyping ov ripgrep lazygit lazydocker trash kitty wezterm python
+        eza lsd bat btop dust duf prettyping ov ripgrep lazygit lazydocker trash kitty wezterm python yt-dlp
 
     set -g _fdc_special \
         curl-uv rustup-installer git-cargo-fish curl-installer fzf-update "" "" paru-build yay-build \
         wakatime-binary "" \
-        "" "" "" "" "" "" "" "" "" "" curl-lazydocker "" "" "" ""
+        "" "" "" "" "" "" "" "" "" "" curl-lazydocker "" "" "" "" ""
 end
 
 # SYNOPSIS

functions/_fish_deps_install.fish

@@ -22,7 +22,9 @@ function _fish_deps_install
         # Determine if this dep needs attention: missing, or fish < 4.0
         set -l needs_install 0
         set -l upgrade_label Install
-        if not type -q $bin
+        # command -q (not type -q): a wrapper function shadowing the name
+        # (rg, rm, yt-dlp) must not be mistaken for the installed binary.
+        if not command -q $bin
             set needs_install 1
         else if test "$bin" = fish
             set -l _major (fish --version 2>&1 | string match -r 'version (\d+)')[2]

functions/_fish_deps_status.fish

@@ -14,7 +14,9 @@ function _fish_deps_status
     _fish_deps_catalog
 
     function __fds_print_dep --argument-names bin tier
-        if type -q $bin
+        # command -q (not type -q): probe PATH only, so wrapper functions that
+        # shadow a tool name (rg, rm, yt-dlp) don't mask a missing binary.
+        if command -q $bin
             # Special version check: fish < 4.0 is functionally incompatible
             if test "$bin" = fish
                 set -l _major (fish --version 2>&1 | string match -r 'version (\d+)')[2]
@@ -28,7 +30,7 @@ function _fish_deps_status
             end
             set_color green; echo -n " ✓ "; set_color normal
             echo -n "$bin "
-            set_color brblack; echo "(Found at "(type -p $bin)")"; set_color normal
+            set_color brblack; echo "(Found at "(command -s $bin)")"; set_color normal
         else if test "$tier" = rec
             set_color yellow; echo -n " ⚠ "; set_color normal
             echo -n "$bin "

functions/_fish_deps_update.fish

@@ -26,8 +26,9 @@ function _fish_deps_update
 
     set -l i 1
     for bin in $_fdc_bins
-        # Skip fisher itself (handled above) and tools that aren't installed
-        if test "$bin" = fisher; or not type -q $bin
+        # Skip fisher itself (handled above) and tools that aren't installed.
+        # command -q (not type -q): ignore wrapper functions shadowing the name.
+        if test "$bin" = fisher; or not command -q $bin
             set i (math $i + 1)
             continue
         end

functions/yt-dlp.fish

@@ -0,0 +1,61 @@
+# Copyright (C) 2026 Rootiest
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+# SYNOPSIS
+#   yt-dlp [args...] URL [URL...]
+#
+# DESCRIPTION
+#   Wraps yt-dlp, injecting sane embedding + SponsorBlock defaults
+#   (--sponsorblock-remove all, --embed-subs, --embed-metadata,
+#   --embed-thumbnail). Each default is suppressed if the user already
+#   passes that flag, its alias, or its negation (e.g. --no-embed-thumbnail
+#   drops our --embed-thumbnail). All other arguments pass through
+#   untouched. --help and friends fall through to real yt-dlp.
+#
+# ARGUMENTS
+#   args...  Arguments forwarded to yt-dlp (defaults prepended)
+#
+# EXAMPLE
+#   yt-dlp dQw4w9WgXcQ
+#   yt-dlp --no-embed-thumbnail dQw4w9WgXcQ   # drops our thumbnail default
+function yt-dlp --description 'yt-dlp with embedding + SponsorBlock defaults'
+    # Opinionated guard (C1): fall back to bare command yt-dlp when disabled.
+    if not __fish_config_op_enabled __fish_config_op_aliases
+        command yt-dlp $argv
+        return $status
+    end
+
+    set -l extra
+
+    # --embed-subs (skip if set or negated)
+    if not contains -- --embed-subs $argv
+        and not contains -- --no-embed-subs $argv
+        set -a extra --embed-subs
+    end
+
+    # --embed-thumbnail (skip if set or negated)
+    if not contains -- --embed-thumbnail $argv
+        and not contains -- --no-embed-thumbnail $argv
+        set -a extra --embed-thumbnail
+    end
+
+    # --embed-metadata (aliases: --add-metadata / --no-add-metadata)
+    if not contains -- --embed-metadata $argv
+        and not contains -- --add-metadata $argv
+        and not contains -- --no-embed-metadata $argv
+        and not contains -- --no-add-metadata $argv
+        set -a extra --embed-metadata
+    end
+
+    # --sponsorblock-remove all
+    # Skip if the user set their own remove (bare or --opt=value form), or
+    # disabled SponsorBlock entirely with --no-sponsorblock.
+    if not string match -q -- '--sponsorblock-remove' $argv
+        and not string match -q -- '--sponsorblock-remove=*' $argv
+        and not contains -- --no-sponsorblock $argv
+        set -a extra --sponsorblock-remove all
+    end
+
+    # User args last so an explicit flag wins any store_true/false precedence.
+    command yt-dlp $extra $argv
+end