feat: pos media grab — smart URL classifier for auto-download

New tool that classifies URLs by domain and delegates to pos media mp3 (audio) or pos media mp4 (video). Listener gains URL detection step between prefix map and AI bridge — bare URLs auto-download. Domain rules: music.youtube.com/soundcloud/bandcamp → mp3, youtube/vimeo/twitch → mp4 --best, unknown → configurable default. 28 test cases / 70 assertions / 0 failed. make gen && make check green, make lint 0 FAIL / 0 WARN.
2026-09-04 10:48:49 -04:00
parent a4761df3f6
commit 072a8e72c1
7 changed files with 328 additions and 19 deletions
@@ -42,6 +42,8 @@ summary (newest last).

 ## Done

+- **2026-09-04** — `pos media grab` (`bin/pos-media-grab`) — auto-download a URL as audio or video. Classifies by domain (YouTube Music/SoundCloud/Bandcamp → mp3; YouTube/Vimeo/Twitch → mp4) with `--audio`/`--video` overrides and `GRAB_DEFAULT` config (`pos config grab`, default `video`) for unknown domains; `--best` default for video (non-interactive, `--worst` override); all flags (`--output`, `--no-playlist`, `--cookies`, `--dry-run`) forwarded to mp3/mp4; prints a clean summary (🎵/🎬 title, duration, path, size). Telegram listener (`bin/pos-communication-telegram-listener`) gains `url_detect` + a URL routing step between the prefix map and AI bridge — bare http(s) URLs route to `pos media grab --best` (600s timeout). Verified: `/tmp/opencode/media-grab-test/run-tests.sh` 28 cases / 70 assertions green; `bash -n` on both files; `make gen && make check` green; `make lint` 0 FAIL / 0 WARN.
+
 - **2026-08-21** — Share suite interactive layer (`lib/share-lib.sh` + menu modes for all five `pos share *` tools): bare invocation now opens an EOF-safe looping menu instead of printing usage. New `lib/share-lib.sh` (436 lines) owns the shared primitives — `share_menu_guard`/`share_menu_run`/`share_pick`/`share_ask_value` (quit on EOF so non-tty callers can't hang), `share_require_bin`/`share_port_probe`/`share_service_active`/`share_path_probe` rc-only probes, `share_usb_records` (blank-line-record parser for usbsrv listings), `share_smb_shares` (smbclient `-g` Disk enumeration incl. guest→auth retry) + `share_usb_devices`/`share_usb_clients`, `share_nfs_exports` (showmount), `share_folder_candidates` (bounded-probe scan of mounted targets + conventional roots; container overlay/tmpfs/nsfs excluded via findmnt; clients build their own mountpoint pickers on top), and advisories `share_ufw_blocks_ports`+`share_offer_fix`. Tools keep every legacy flag/subcommand byte-compatible (verbatim command bodies, thin menu layer on top): nfs-server gains a client-spec presets picker + inactive-service/UFW offers, nfs-client gains idempotent unmount/unpersist (already-absent = report, rc0) + persist-verify-with-rollback + replace-confirm, smb-server gets UFW offer + menu tree, smb-client gets enumerate→pick→mount with account reuse (`SMB_AUTH_USER` contract), usb-server picker-first with raw-listing manual-entry fallback when the server listing is unreadable. New seams: `EXPORTS_FILE` (nfs-server), `UNIT_DIR` (nfs-client); `bin/pos` INTERACTIVE_CMDS += both stdin-reading share tools; install.sh lib list += share-lib.sh; preinstall.sh += smbclient (smb-client enumeration dep). Docs: POS.md share rows/detail, howto/share.md per-tool Interactive-menu notes, SCRIPTS.md phase table + new `## lib/share-lib.sh` section, DEV.md lib row + env-seam registry, AGENT_Context hand-maintained spots (lib table row 436, Phase-2 prose). Verified: 80-case stub battery vs recaptured deterministic golden — only the 9 documented intentional deltas differ (additive help lines, seam-path strings in messages, missing-dep message delta, unmount-idle FLAGGED→rc0, unpersist round-trip now works, usbs-bare usage→menu guard); 12/12 PTY tests (menus open/quit non-tty, filter/zero-match/default/cancel picker semantics, full nfs-server share flow writes the export line, usb-server share via pickers + down-server fallback, smb-client guest-enumerate→manual-share flow); real `/etc/exports` + `/etc/systemd/system` md5-verified untouched; `make gen && make check` green, `make lint` 0 FAIL / 0 WARN.
 - **2026-08-21** — Refreshed `AGENTS.md` against the codebase: HOWTO category list corrected to match `DOC/howto/*` (ai/share/schedule, no bare "usb"); CI bullet now states only verifiable facts (`lint.yml` job `gates`, push-to-main/PR, `ci-ok/<sha>`/`ci-fail/<sha>` result tags) instead of the uncheckable act-runner naming; new **Doc conflicts** bullet encoding the `MAINTENANCE.md → Phase 0` authority order and `templates/*.sh` as required starting points. Every other claim re-verified against `scripts/{gen-docs,check-sync,lint-conventions}.sh`, `bin/pos` (dispatch loop, INTERACTIVE_CMDS), `.gitignore`/`.gitmodules`, `lib/config-ui.sh`; gates green before and after.
 - **2026-08-15** — `pos docker stack` (`bin/pos-docker-stack`) — containers grouped by their Docker Compose project. Each stack is a section (project name, sorted) with lines `container-name  status  ports`; containers with no compose project land in a `Standalone` section at the end; ends with `Stacks: N  containers: N  standalone: N`. Running only by default, `-a|--all` includes stopped/exited (like `docker ps -a`). Status colored on a terminal (`Up*` green, `Exited*`/`Dead*`/`Created*` red, `Paused*`/`Restarting*` yellow); exit 0 also when no containers. Data via `docker ps` with `--format '{{.Names}}{{"\u001f"}}{{.Label "com.docker.compose.project"}}{{"\u001f"}}{{.Status}}{{"\u001f"}}{{.Ports}}'` (compose v2 sets the project label; `{{"\u001f"}}` escapes in the Go template), parsed with `awk -F'\x1f'` + `IFS=$'\x1f' read` everywhere — tab/pipe delimiters are IFS whitespace or inside values, so `\x1f` (DEV.md:213 gotcha); dash padding via `sed` not `tr` (tr corrupts multi-byte `─`). Deps guard (`docker`) before `--help`; no stdin → not in `INTERACTIVE_CMDS`; `# POS_FLAGS: -a --all`. Docs: POS.md docker row + detail, howto/docker.md table + section, `bin/pos` usage EXAMPLES, AGENT_Context §14 row. Verified: stub-PATH suite `/tmp/opencode/docker-stack-test/run-tests.sh` 23/23 (grouping, sorted stacks, `-a` shows exited, standalone, empty daemon rc=0, colored status, missing docker rc=1, `--help` after deps guard); live runs against the real daemon (affine/audiobookshelf/convertx/gitea stacks, `affine_migration_job Exited (0)` + `lab1 Exited (137)` under `-a`); dispatch via `pos docker stack`; `make gen && make check`, `make lint` 0 FAIL / 0 WARN.
@@ -10,19 +10,19 @@

 <!-- GEN:START docmap -->
 | ## 1. Project Overview | 28–43 |
-| ## 2. Directory Structure | 44–204 |
-| ## 3. Installation Flow | 205–258 |
-| ## 4. The `pos` CLI System | 259–336 |
-| ## 5. Shared Library — `lib/common.sh` | 337–368 |
-| ## 6. Docker Compose / ScaleTail | 369–411 |
-| ## 7. Optional Apps (`apps/`) | 412–441 |
-| ## 8. Entertainment Module | 442–455 |
-| ## 9. Systemd Services | 456–467 |
-| ## 10. Configuration Files | 468–494 |
-| ## 11. Coding Conventions | 495–527 |
-| ## 12. Development Workflow | 528–580 |
-| ## 13. Key File Quick Reference | 581–652 |
-| ## 14. Common Tasks for Agents | 653–686 |
+| ## 2. Directory Structure | 44–205 |
+| ## 3. Installation Flow | 206–259 |
+| ## 4. The `pos` CLI System | 260–338 |
+| ## 5. Shared Library — `lib/common.sh` | 339–370 |
+| ## 6. Docker Compose / ScaleTail | 371–413 |
+| ## 7. Optional Apps (`apps/`) | 414–443 |
+| ## 8. Entertainment Module | 444–457 |
+| ## 9. Systemd Services | 458–469 |
+| ## 10. Configuration Files | 470–496 |
+| ## 11. Coding Conventions | 497–529 |
+| ## 12. Development Workflow | 530–582 |
+| ## 13. Key File Quick Reference | 583–655 |
+| ## 14. Common Tasks for Agents | 656–689 |
 <!-- GEN:END docmap -->

 ## 1. Project Overview
@@ -80,6 +80,7 @@ Linux_post_install/
 │   ├── pos-entertainment-enable            # Enable an auto-trigger for a plugin on a schedule
 │   ├── pos-entertainment-send              # Run a public-API plugin and send its output via the configured notify platforms
 │   ├── pos-entertainment-status            # Show enabled plugins and scheduler state
+│   ├── pos-media-grab                      # Auto-download URL as audio or video (classify + route)
 │   ├── pos-media-mp3                       # Download audio as MP3 (yt-dlp)
 │   ├── pos-media-mp4                       # Download video as MP4 (smart/interactive format select)
 │   ├── pos-media-sync                      # Incremental Music → USB sync (mp3/mp4, add/update only)
@@ -293,6 +294,7 @@ All non-interactive `pos` commands log output to `~/.local/share/linux_post_inst
 | entertainment | enable | `pos-entertainment-enable` | Enable an auto-trigger for a plugin on a schedule |  |  |
 | entertainment | send | `pos-entertainment-send` | Run a public-API plugin and send its output via the configured notify platforms |  |  |
 | entertainment | status | `pos-entertainment-status` | Show enabled plugins and scheduler state |  |  |
+| media | grab | `pos-media-grab` | Auto-download URL as audio or video (classify + route) |  |  |
 | media | mp3 | `pos-media-mp3` | Download audio as MP3 (yt-dlp) |  |  |
 | media | mp4 | `pos-media-mp4` | Download video as MP4 (smart/interactive format select) |  |  |
 | media | sync | `pos-media-sync` | Incremental Music → USB sync (mp3/mp4, add/update only) | lsblk jq | pos media sync --mp3 → Sync only MP3 files to USB · pos media sync --mp4 --dry-run → Preview MP4 sync without copying |
@@ -609,7 +611,7 @@ Use conventional prefixes: `feat:`, `fix:`, `docs:`, `refactor:`, `chore:`
 | `bin/pos-communication-matrix-listener` | 568 | Matrix listener: map /command → bash, run them on room messages |
 | `bin/pos-communication-matrix-sender` | 224 | Send messages to a Matrix room via the client-server API (send, test, login) |
 | `bin/pos-communication-scrcpy` | 254 | Mirror/control an Android device via scrcpy+adb (mirror, devices, record, tcpip, connect, push, pull, screenshot, info) |
-| `bin/pos-communication-telegram-listener` | 782 | Telegram bot listener: map /command → bash and <prefix> → app, run them on chat messages |
+| `bin/pos-communication-telegram-listener` | 805 | Telegram bot listener: map /command → bash and <prefix> → app, run them on chat messages |
 | `bin/pos-communication-telegram-sender` | 221 | Send Telegram messages/files/links/stickers via Bot API (send, test) |
 | `bin/pos-docker-compose` | 487 | Docker Compose service manager (ls/up/down/restart/logs/update/config) |
 | `bin/pos-docker-health` | 107 | One-glance container health dashboard (exits 1 if unhealthy) |
@@ -621,6 +623,7 @@ Use conventional prefixes: `feat:`, `fix:`, `docs:`, `refactor:`, `chore:`
 | `bin/pos-entertainment-enable` | 49 | Enable an auto-trigger for a plugin on a schedule |
 | `bin/pos-entertainment-send` | 95 | Run a public-API plugin and send its output via the configured notify platforms |
 | `bin/pos-entertainment-status` | 62 | Show enabled plugins and scheduler state |
+| `bin/pos-media-grab` | 227 | Auto-download URL as audio or video (classify + route) |
 | `bin/pos-media-mp3` | 86 | Download audio as MP3 (yt-dlp) |
 | `bin/pos-media-mp4` | 132 | Download video as MP4 (smart/interactive format select) |
 | `bin/pos-media-sync` | 219 | Incremental Music → USB sync (mp3/mp4, add/update only) |
@@ -644,7 +647,7 @@ Use conventional prefixes: `feat:`, `fix:`, `docs:`, `refactor:`, `chore:`
 | `bin/pos-ai` | 692 | AI assistant: ask, chat, sessions, capture, models, providers |
 | `bin/pos-config` | 80 | Interactive editor for the tools' runtime config (reads # POS_CONFIG: registry) |
 | `bin/pos-tree` | 118 | Show the pos CLI command tree: categories, commands, and subcommands |
-| `completions/pos.bash` | 308 | Dynamic bash completion |
+| `completions/pos.bash` | 309 | Dynamic bash completion |
 <!-- GEN:END filetable -->
 | `apps/install.sh` | 171 | App install/uninstall picker/orchestrator |

@@ -237,6 +237,7 @@ The standalone `vbox` command still works and forwards to `pos docker vbox` (see
 |---------|------|---------|---------------|
 | `pos media mp3 <url>` | `bin/pos-media-mp3` | Download audio as MP3 via yt-dlp, with thumbnail + metadata | Output to `~/Music/%(title)s.%(ext)s`, `--audio-quality 0` |
 | `pos media mp4 <url>` | `bin/pos-media-mp4` | Download video via yt-dlp with **interactive format selection** | Lists formats (`yt-dlp -F`), asks for a format ID, saves to `~/Videos/` |
+| `pos media grab <url>` | `bin/pos-media-grab` | Auto-download a URL as audio or video (classify + route to mp3/mp4) | Domain-based classification (YouTube Music/SoundCloud/Bandcamp → audio; YouTube/Vimeo/Twitch → video); `--audio`/`--video` force the mode; `--best` default for video (non-interactive); prints a clean summary (🎵/🎬 title, path, size). Config: `GRAB_DEFAULT` (`pos config grab`, default `video`) for unknown domains |
 | `pos media sync [--mp3\|--mp4]` | `bin/pos-media-sync` | Incremental Music → USB sync (add/update only — never deletes) | Copies mp3/mp4 from `$HOME/Music` (or `--source <dir>`) into `<usb>/Music/`, preserving the tree; missing or changed (size/mtime) files are copied, identical ones skipped. Same USB detection as `pos system backup` (lsblk TRAN + lsusb/by-id, mount offer for unmounted sticks, multi-stick picker). `--mp3`/`--mp4` filter by extension, neither = both; `--dry-run` previews. Config: `MEDIA_SYNC_SOURCE`, `MEDIA_SYNC_DEST`, shared `USB_MOUNT_BASE`/`USB_BYID` from `~/.config/linux_post_install/system.env`. Result notified via `lib/notify.sh`. Bare invocation on a terminal (or the `menu` subcommand) opens an interactive menu wrapping these actions (sync now mp3+mp4, dry-run preview, mp3-only, mp4-only, change source folder); flags stay scriptable |
 | `pos media ytsync [add\|sync\|list\|remove]` | `bin/pos-media-ytsync` | Incremental YouTube channel/playlist sync — first run asks for a URL (bare invocation = interactive menu; empty state goes straight to the prompt), repeat runs fetch only new videos | One yt-dlp call per new video (`bestvideo*+bestaudio/best` → MP4, metadata/chapters/thumbnail embedded, `--no-overwrites`, `--windows-filenames --trim-filenames 120`); per-source `--download-archive` (`~/.local/share/linux_post_install/ytsync/archive/<slug>.txt`) makes runs crash-safe and idempotent; registry tracks slug/type/url/subdir. Verbs never prompt (scheduler/timer safe); non-tty interactive entry prints a guard line and exits 0. `--dry-run` probes + plans with zero writes. Notify digest only when new>0 or failed>0 via `lib/notify.sh`. Config: `YTSYNC_VIDEOS_DIR`, `YTSYNC_EXTRA_ARGS` via `pos config ytsync`; automate with `pos system schedule` (`COMMAND=pos media ytsync sync`, `NOTIFY=never`) |

@@ -1,11 +1,13 @@
 # How-To: `pos media`

-Download audio and video from the web via `yt-dlp`, sync your library to a
-USB stick, and keep YouTube channels incrementally up to date.
-Tools: `mp3`, `mp4`, `sync`, `ytsync`.
+Download audio and video from the web via `yt-dlp`, auto-classify URLs,
+sync your library to a USB stick, and keep YouTube channels incrementally
+up to date.
+Tools: `grab`, `mp3`, `mp4`, `sync`, `ytsync`.

 | Tool | What it does |
 |------|--------------|
+| `pos media grab` | Auto-classify URL and download as audio or video |
 | `pos media mp3` | Download audio, convert to MP3 |
 | `pos media mp4` | Download video with smart/interactive format selection |
 | `pos media sync` | Incrementally copy `~/Music` onto a USB stick (mp3/mp4) |
@@ -88,6 +90,56 @@ video+audio and merges them.

 ---

+## `pos media grab` — auto-classify URL and download
+
+```bash
+pos media grab <url>
+```
+
+Smart URL classifier that routes to `pos media mp3` or `pos media mp4`
+automatically based on the domain. Send a URL from your phone via Telegram and
+the bot downloads it to the right place without you thinking about it.
+
+**Classification rules:**
+
+| Domain | Routes to | Why |
+|--------|-----------|-----|
+| `music.youtube.com` | mp3 | Audio streaming |
+| `soundcloud.com` | mp3 | Audio-first platform |
+| `bandcamp.com` | mp3 | Audio-first platform |
+| `youtube.com` / `youtu.be` | mp4 | Video content |
+| `vimeo.com` / `twitch.tv` | mp4 | Video platforms |
+| Everything else | mp4 (default) | Safe fallback |
+
+Override the classification with `--audio` or `--video`. The default for
+unrecognized domains is `video` — change it with `pos config grab` or set
+`GRAB_DEFAULT=audio` in `~/.config/linux_post_install/grab.env`.
+
+```bash
+pos media grab https://music.youtube.com/watch?v=abc          # → ~/Music
+pos media grab https://youtube.com/watch?v=xyz                # → ~/Videos
+pos media grab --audio https://vimeo.com/123                  # force mp3
+pos media grab --worst https://youtu.be/abc                   # lowest quality
+pos media grab --dry-run https://soundcloud.com/artist/track  # preview only
+```
+
+Non-interactive by design — `pos media mp4` receives `--best` by default so it
+never prompts for a format (critical for Telegram bot context where there's no
+TTY). Pass `--worst` if you want the smallest file.
+
+| Flag | Meaning |
+|------|---------|
+| `--audio` | Force audio (mp3) download |
+| `--video` | Force video (mp4) download |
+| `--best` | Best quality for video (default) |
+| `--worst` | Lowest quality for video |
+| `-o, --output <dir>` | Output directory (passed to mp3/mp4) |
+| `--no-playlist` | Download only the single video |
+| `--cookies <file>` | Netscape cookies.txt for age-gated content |
+| `--dry-run` | Print the command that would run, don't execute |
+
+---
+
 ## `pos media sync` — music onto a USB stick

 ```bash
@@ -655,6 +655,22 @@ strip_markdown() {
    printf '%s' "$t"
 }

+# Detect a bare URL in message text. Extracts the first http(s) URL.
+# Returns 0 + prints the URL on success, 1 if no URL found.
+url_detect() {
+    local text="$1"
+    local url=""
+    if [[ "$text" =~ (https?://[^[:space:]]+) ]]; then
+        url="${BASH_REMATCH[1]}"
+        url="${url%%[,.\)!?:;]}"
+        url="${url%%\>*}"
+        [ -n "$url" ] || return 1
+        printf '%s' "$url"
+        return 0
+    fi
+    return 1
+}
+
 handle_message() {
    local text="$1" msg_id="$2" reply_text="${3:-}" value quiet=0
    case "$text" in
@@ -681,6 +697,13 @@ handle_message() {
        run_and_reply "$cmd $qtext" "$msg_id" 120 "$quiet"
        return
    fi
+    # URL detect: bare HTTP(S) URLs → pos media grab
+    local grab_url
+    if grab_url="$(url_detect "$text")"; then
+        log "grab: $grab_url"
+        run_and_reply "pos media grab --best \"$grab_url\"" "$msg_id" 600
+        return
+    fi
    # AI bridge: non-command text starting with "<prefix> " (default "ai",
    # case-insensitive, configurable via TELEGRAM_AI_PREFIX in 'pos config
    # telegram') is forwarded to Gemini; the model's answer is replied
@@ -0,0 +1,227 @@
+#!/usr/bin/env bash
+set -euo pipefail
+# POS: media grab — Auto-download URL as audio or video (classify + route)
+# POS_FLAGS: --audio --video --best --worst --output --no-playlist --cookies --dry-run
+# POS_CONFIG: grab | grab.env | GRAB_DEFAULT=:Default mode for unknown domains (video or audio, default video)
+
+source "$(dirname "$0")/../lib/common.sh" 2>/dev/null || source "$(dirname "$0")/common.sh"
+
+# Load grab.env config (env-seam: GRAB_DEFAULT)
+load_grab_config() {
+    local f="$HOME/.config/linux_post_install/grab.env" k v
+    [ -f "$f" ] || return 0
+    while IFS='=' read -r k v; do
+        [ -n "$k" ] || continue
+        case "$k" in
+            \#*) continue ;;
+        esac
+        v="${v%\"}"; v="${v#\"}"; v="${v%\'}"; v="${v#\'}"
+        if [ -z "${!k:-}" ]; then
+            export "$k"="$v"
+        fi
+    done < <(grep -E '^[A-Z_]+=' "$f" || true)
+}
+
+load_grab_config
+
+# ── URL classification ─────────────────────────────────────────
+classify_url() {
+    local url="$1" mode="${GRAB_DEFAULT:-video}"
+    case "$url" in
+        *music.youtube.com*)  echo "audio" ;;
+        *soundcloud.com*)     echo "audio" ;;
+        *bandcamp.com*)       echo "audio" ;;
+        *youtube.com*|*youtu.be*) echo "video" ;;
+        *vimeo.com*)          echo "video" ;;
+        *twitch.tv*)          echo "video" ;;
+        *)                    echo "$mode" ;;
+    esac
+}
+
+usage() {
+    cat <<EOF
+Usage: pos media grab [options] <url>
+
+Auto-download a URL as audio or video. Classifies the domain and delegates
+to 'pos media mp3' (audio) or 'pos media mp4' (video).
+
+Options:
+  --audio               Force audio (mp3) download
+  --video               Force video (mp4) download
+  --best                Best quality for video (default for non-interactive)
+  --worst               Lowest quality for video
+  -o, --output <dir>    Output directory (passed to mp3/mp4)
+  --no-playlist         Download only the single video
+  --cookies <file>      Netscape cookies.txt for age-gated content
+  --dry-run             Print the command that would run, don't execute
+  -h, --help            This help
+
+Examples:
+  pos media grab https://music.youtube.com/watch?v=abc
+  pos media grab https://youtube.com/watch?v=xyz
+  pos media grab --audio https://vimeo.com/123
+  pos media grab --worst https://youtu.be/abc
+  pos media grab --dry-run https://soundcloud.com/artist/track
+EOF
+    exit 0
+}
+
+# ── Arg parsing ────────────────────────────────────────────────
+URL=""
+FORCE_AUDIO=0
+FORCE_VIDEO=0
+BEST=0
+WORST=0
+DRY_RUN=0
+EXTRA_ARGS=()
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        -h|--help) usage ;;
+        --audio) FORCE_AUDIO=1; shift ;;
+        --video) FORCE_VIDEO=1; shift ;;
+        --best)  BEST=1; shift ;;
+        --worst) WORST=1; shift ;;
+        -o|--output)
+            [ $# -ge 2 ] || err "pos media grab: --output needs a value"
+            EXTRA_ARGS+=(--output "$2"); shift 2 ;;
+        --no-playlist) EXTRA_ARGS+=(--no-playlist); shift ;;
+        --cookies)
+            [ $# -ge 2 ] || err "pos media grab: --cookies needs a value"
+            EXTRA_ARGS+=(--cookies "$2"); shift 2 ;;
+        --dry-run) DRY_RUN=1; shift ;;
+        -*) err "pos media grab: Unknown option: $1 (see --help)" ;;
+        *)
+            [ -z "$URL" ] && URL="$1" && shift || err "pos media grab: Unexpected argument: $1" ;;
+    esac
+done
+
+[ -n "$URL" ] || usage
+
+# Validate URL scheme
+case "$URL" in
+    http://*|https://*) ;;
+    *) err "pos media grab: not a valid URL: $URL (must start with http:// or https://)" ;;
+esac
+
+# Validate mutually exclusive overrides
+[ "$FORCE_AUDIO" -eq 1 ] && [ "$FORCE_VIDEO" -eq 1 ] && \
+    err "pos media grab: --audio and --video are mutually exclusive"
+[ "$BEST" -eq 1 ] && [ "$WORST" -eq 1 ] && \
+    err "pos media grab: --best and --worst are mutually exclusive"
+
+# ── Classification ─────────────────────────────────────────────
+mode=""
+if [ "$FORCE_AUDIO" -eq 1 ]; then
+    mode="audio"
+elif [ "$FORCE_VIDEO" -eq 1 ]; then
+    mode="video"
+else
+    mode="$(classify_url "$URL")"
+fi
+
+# ── Build delegated command ────────────────────────────────────
+DELEGATE_ARGS=()
+
+if [ "$mode" = "audio" ]; then
+    DELEGATE_ARGS=(pos media mp3 "${EXTRA_ARGS[@]}")
+else
+    # mp4 route: --best by default (non-interactive), --worst if user passes it
+    if [ "$WORST" -eq 1 ]; then
+        DELEGATE_ARGS=(pos media mp4 --worst "${EXTRA_ARGS[@]}")
+    else
+        DELEGATE_ARGS=(pos media mp4 --best "${EXTRA_ARGS[@]}")
+    fi
+fi
+
+# ── Dry run ────────────────────────────────────────────────────
+if [ "$DRY_RUN" -eq 1 ]; then
+    echo "${DELEGATE_ARGS[*]} $URL"
+    exit 0
+fi
+
+# ── Execute ────────────────────────────────────────────────────
+output=""
+rc=0
+if output=$("${DELEGATE_ARGS[@]}" "$URL" 2>&1); then
+    rc=0
+else
+    rc=$?
+fi
+
+if [ "$rc" -ne 0 ]; then
+    # Summarize stderr for the user
+    summary="$(printf '%s' "$output" | grep -i 'error\|fail' | head -1 || true)"
+    [ -z "$summary" ] && summary="exit code $rc"
+    err "pos media grab: ❌ Download failed: $summary"
+fi
+
+# ── Metadata + summary ────────────────────────────────────────
+title=""
+duration=""
+file_path=""
+
+# Determine expected output directory
+if [ "$mode" = "audio" ]; then
+    out_dir="$HOME/Music"
+    for (( i=0; i<${#EXTRA_ARGS[@]}; i++ )); do
+        if [ "${EXTRA_ARGS[$i]}" = "--output" ] && [ $(( i + 1 )) -lt ${#EXTRA_ARGS[@]} ]; then
+            out_dir="${EXTRA_ARGS[$(( i + 1 ))]}"
+            break
+        fi
+    done
+    file_ext="mp3"
+else
+    out_dir="$HOME/Videos"
+    for (( i=0; i<${#EXTRA_ARGS[@]}; i++ )); do
+        if [ "${EXTRA_ARGS[$i]}" = "--output" ] && [ $(( i + 1 )) -lt ${#EXTRA_ARGS[@]} ]; then
+            out_dir="${EXTRA_ARGS[$(( i + 1 ))]}"
+            break
+        fi
+    done
+    file_ext="mp4"
+fi
+
+# Fetch metadata (fast, no download)
+if command -v yt-dlp &>/dev/null; then
+    meta="$(yt-dlp --print title --print duration_string --no-warnings "$URL" 2>/dev/null || true)"
+    title="$(printf '%s' "$meta" | sed -n '1p')"
+    duration="$(printf '%s' "$meta" | sed -n '2p')"
+fi
+
+# Find the downloaded file (most recent matching extension in out_dir)
+if [ -d "$out_dir" ]; then
+    file_path="$(find "$out_dir" -maxdepth 1 -name "*.$file_ext" -printf '%T@ %p\n' 2>/dev/null \
+        | sort -rn | head -1 | cut -d' ' -f2- || true)"
+fi
+
+# Build summary
+[ -z "$title" ] && title="$(basename "$URL" | sed 's/[?#].*//')"
+[ -z "$duration" ] && duration="?"
+
+if [ "$mode" = "audio" ]; then
+    emoji="🎵"
+else
+    emoji="🎬"
+fi
+
+echo "$emoji Downloaded: $title ($duration)"
+
+if [ -n "$file_path" ] && [ -f "$file_path" ]; then
+    file_size="$(stat --printf='%s' "$file_path" 2>/dev/null || echo "0")"
+    # Format size in human-readable form
+    if [ "$file_size" -ge 1073741824 ]; then
+        size_human="$(awk "BEGIN { printf \"%.1f GB\", $file_size / 1073741824 }")"
+    elif [ "$file_size" -ge 1048576 ]; then
+        size_human="$(awk "BEGIN { printf \"%.1f MB\", $file_size / 1048576 }")"
+    elif [ "$file_size" -ge 1024 ]; then
+        size_human="$(awk "BEGIN { printf \"%.1f KB\", $file_size / 1024 }")"
+    else
+        size_human="${file_size} B"
+    fi
+    # Show path relative to HOME
+    rel_path="${file_path/#$HOME/\~}"
+    echo "📁 $rel_path ($size_human)"
+else
+    echo "📁 $out_dir/ ($file_ext)"
+fi
@@ -9,6 +9,7 @@ _pos_flags[communication-telegram-sender]="--type --caption --parse-mode --no-pr
 _pos_flags[docker-stack]="-a --all"
 _pos_flags[docker-vbox]="--dir --gpu --device --port --cpus --memory --network"
 _pos_flags[entertainment-send]="--print --markdown"
+_pos_flags[media-grab]="--audio --video --best --worst --output --no-playlist --cookies --dry-run"
 _pos_flags[media-mp3]="--output --no-playlist --cookies --by-artist --dry-run"
 _pos_flags[media-mp4]="--format --best --worst --output --no-playlist --cookies --dry-run"
 _pos_flags[media-sync]="--mp3 --mp4 --source --dry-run"
@@ -46,7 +47,7 @@ _pos_subcmds[system-schedule]="run list config enable disable status migrate men
 _pos_subcmds[ai]="ask chat sessions capture models providers alias gemini openrouter"
 # GEN:END possubcmds
 # GEN:START posconfigscopes
-declare -a _pos_config_scopes=(ai compose entertainment matrix notify scrcpy system telegram ytsync)
+declare -a _pos_config_scopes=(ai compose entertainment grab matrix notify scrcpy system telegram ytsync)
 # GEN:END posconfigscopes

 _pos() {