From 330a3ba0b40a5d1bb7eb68dfecab8ee4c1822ebe Mon Sep 17 00:00:00 2001
From: Your Name <you@example.com>
Date: Wed, 5 Aug 2026 14:23:03 +0000
Subject: [PATCH] fix: add yt-dlp dep guard to pos-media-mp3/mp4 (clean error
 instead of raw command-not-found)

---
 DOC/AGENT_Context_Project.md | 6 +++---
 bin/pos-media-mp3            | 4 ++++
 bin/pos-media-mp4            | 4 ++++
 3 files changed, 11 insertions(+), 3 deletions(-)

diff --git a/DOC/AGENT_Context_Project.md b/DOC/AGENT_Context_Project.md
index 3bd1d52..55d957f 100644
--- a/DOC/AGENT_Context_Project.md
+++ b/DOC/AGENT_Context_Project.md
@@ -259,7 +259,7 @@ source "$(dirname "$0")/../lib/common.sh"
 
 **Scripts that do NOT source common.sh** (self-contained):
 <!-- GEN:START selfcontained -->
-`pos`, `pos-communication-telegram`, `pos-media-mp3`, `pos-media-mp4`, `pos-network-checkport`, `pos-network-hotspot`, `pos-network-ip`, `pos-network-scan`, `pos-ssh-load-keys`, `pos-system-firewall`.
+`pos`, `pos-communication-telegram`, `pos-network-checkport`, `pos-network-hotspot`, `pos-network-ip`, `pos-network-scan`, `pos-ssh-load-keys`, `pos-system-firewall`.
 <!-- GEN:END selfcontained -->
 
 ---
@@ -476,8 +476,8 @@ Use conventional prefixes: `feat:`, `fix:`, `docs:`, `refactor:`, `chore:`
 | `bin/pos-docker-health` | 110 | One-glance container health dashboard (exits 1 if unhealthy) |
 | `bin/pos-docker-ps` | 128 | Enhanced container overview (health, IPs, ports, uptime) |
 | `bin/pos-docker-vbox` | 157 | Disposable Docker-based VMs (create/enter/start/stop/rm/ls) |
-| `bin/pos-media-mp3` | 31 | Download audio as MP3 (yt-dlp) |
-| `bin/pos-media-mp4` | 34 | Download video as MP4 (interactive format select) |
+| `bin/pos-media-mp3` | 35 | Download audio as MP3 (yt-dlp) |
+| `bin/pos-media-mp4` | 38 | Download video as MP4 (interactive format select) |
 | `bin/pos-network-checkport` | 45 | Check TCP port connectivity |
 | `bin/pos-network-hotspot` | 93 | Wi-Fi hotspot via create_ap + wihotspot-gui |
 | `bin/pos-network-ip` | 69 | Show interfaces, routes, public IP + location |
diff --git a/bin/pos-media-mp3 b/bin/pos-media-mp3
index e3a6b7d..6017355 100755
--- a/bin/pos-media-mp3
+++ b/bin/pos-media-mp3
@@ -2,6 +2,8 @@
 set -euo pipefail
 # POS: media mp3 — Download audio as MP3 (yt-dlp)
 
+source "$(dirname "$0")/../lib/common.sh" 2>/dev/null || source "$(dirname "$0")/common.sh"
+
 usage() {
     cat <<EOF
 Usage: pos media mp3 <url>
@@ -18,6 +20,8 @@ case "${1:-}" in
     -h|--help|"") usage ;;
 esac
 
+command -v yt-dlp &>/dev/null || err "yt-dlp not found — install it with: sudo apt install yt-dlp"
+
 url="$1"
 
 yt-dlp \
diff --git a/bin/pos-media-mp4 b/bin/pos-media-mp4
index 295864e..b0b8bfa 100755
--- a/bin/pos-media-mp4
+++ b/bin/pos-media-mp4
@@ -2,6 +2,8 @@
 set -euo pipefail
 # POS: media mp4 — Download video as MP4 (interactive format select)
 
+source "$(dirname "$0")/../lib/common.sh" 2>/dev/null || source "$(dirname "$0")/common.sh"
+
 usage() {
     cat <<EOF
 Usage: pos media mp4 <url>
@@ -18,6 +20,8 @@ case "${1:-}" in
     -h|--help|"") usage ;;
 esac
 
+command -v yt-dlp &>/dev/null || err "yt-dlp not found — install it with: sudo apt install yt-dlp"
+
 url="$1"
 
 yt-dlp -F "$url"