diff --git a/AGENT_TODO.md b/AGENT_TODO.md
index d11d089..1bffe8f 100644
--- a/AGENT_TODO.md
+++ b/AGENT_TODO.md
@@ -128,3 +128,4 @@ summary (newest last).
 - **2026-08-14** — `pos system backup` optional encryption (`--no-encrypt` flag + `BACKUP_ENCRYPT=0` env, flag-or-env — user chose "Flag + env only"): plain path keeps a verified `.tar.gz` with no password prompt (headless/cron safe); encrypt path unchanged (prompt → gpg AES-256 → decrypt-verify; the gpg dep-guard moved into the encrypt branch so plain backups no longer require `gnupg`). Arg parsing rewritten as a loop over `"$@"` so `pos system backup <folder> --no-encrypt` works with the flag after the folder; usage() documents all three forms + the plain artifact name; `# POS_FLAGS: --service --no-encrypt`; `config/system.env` template gains `#BACKUP_ENCRYPT=0`; POS.md row + howto/system.md section updated. Verified: stub suite +2 cases (T18 flag / T19 env: plain .tar.gz artifact, gpg never called via `$GPG_CALLED`, USB copy + sha256 of the plain archive, notify wording) — 65/65 green; `bash -n`, `make gen && make check`, `make lint` 0 FAIL / 0 WARN.
 - **2026-08-14** — CI green-check via plain git (no SSH to the runner, no API tokens — user chose "CI tags + git ls-remote" + "scripts/ci-status.sh helper"): `.gitea/workflows/lint.yml` scoped to `on: push: branches: [main]` (tag pushes no longer re-trigger it) and the gate step now reports its own outcome as a lightweight tag — `ci-ok/$GITHUB_SHA` on success / `ci-fail/$GITHUB_SHA` on failure, pushed over HTTP with the jobs automatic `GITEA_TOKEN` to `http://oauth2:${GITEA_TOKEN}@gitea.skink-platy.ts.net:3000/admin/Linux_post_install.git` (runner container already host-maps that hostname to 100.111.241.54); `steps.gates.conclusion` decides ok/fail, `if: always()` (guarded to `push` events) covers failed gate runs, and an existing-tag guard makes re-runs idempotent. New executable `scripts/ci-status.sh [--wait] [<sha>]` reads the tags via `git ls-remote` (origin, `CI_STATUS_REMOTE` override): GREEN (0) / RED (1) / PENDING (2); `--wait` polls every 10s up to 10 min. DEV.md §CI gains a "Checking green without SSH" bullet. Verified: `bash -n`, yaml-parse OK, `make gen && make check`, `make lint` 0 FAIL / 0 WARN; first live-tag verification pending the push (fallback if Gitea clamps token-push: PAT as workflow secret).
 - **2026-08-14** — `pos media sync` (`bin/pos-media-sync`) — incremental Music → USB sync, plus the shared USB layer it builds on. **New lib `lib/usb-lib.sh`** (194 lines, installed by install.sh): `usb_detect` (lsblk JSON, TRAN + lsusb/by-id cross-check → `USB_MOUNTED`/`USB_UNMOUNTED`), `usb_related_present`, `usb_mount_offer` (`/media/<label>` mount-offer, `usb-automount` scheme), `usb_pick_root <prefix> <subfolder> <giveup-msg>` (detect → mount-offer → single/multi picker → `USB_ROOT`); seams `USB_MOUNT_BASE`/`USB_BYID` with `BACKUP_MOUNT_BASE`/`BACKUP_USB_BYID` aliases so existing `system.env` lines keep working; TRAN-fallback warning deduped to once per scan. `pos-system-backup` refactored onto it (216 lines, was 364) — re-ran the backup stub suite: 65/65 green. **Sync tool**: add/update only, never deletes (user choice); `--mp3`/`--mp4` filter (neither = both), `--source <dir>` (default `MEDIA_SYNC_SOURCE`/`$HOME/Music`), `--dry-run` preview with counts; copies missing/changed (size/mtime) files into `<usb>/Music/` (`MEDIA_SYNC_DEST`) preserving the tree via `cp --preserve=timestamps`; result notified via `lib/notify.sh`; `media-sync` added to `INTERACTIVE_CMDS`; deps guards (`lsblk`/`jq`) before `-h|--help`. Docs: POS.md media row, howto/media.md section, SCRIPTS.md lib section + Phase-2 lib list, system.env seams, DEV.md env-seam registry, AGENT_Context Common Tasks + hand-maintained lib row (+usb-lib 194) + gen'd tree/dispatch/filetable/flags. Verified: new stub suite `/tmp/opencode/msync-run.sh` 46/46 green (fresh/no-op/update/filter/dry-run/multi-stick/mount-offer/no-USB skip/never-delete/--source/TRAN-fallback/notify) — caught and fixed an inverted `needs_copy` return; `make gen && make check`, `make lint` 0 FAIL / 0 WARN; dispatch via `pos media sync --help` + `pos media` listing.
+- **2026-08-22** — `pos media ytsync` (`bin/pos-media-ytsync`) — incremental YouTube channel/playlist sync into `~/Videos`, implemented per the Architect decisions D1–D9 + Designer UX contract (`reportAgents/2026-08-22-*.md`). Subcommands `add [url] / sync [name] / list / remove <name>` + `--dry-run`; bare invocation = interactive menu (`/dev/tty` reads, EOF-safe, NOT in INTERACTIVE_CMDS so dispatcher tee logging is kept; empty state goes straight to the URL prompt). One yt-dlp call per new video (`bestvideo*+bestaudio/best` → MP4, metadata/chapters/thumbnail, `--no-overwrites`, `--windows-filenames --trim-filenames 120`, retries 3), per-video `[n/N] title` heartbeat lines, LF-only logs (spinner TTY-gated); probe = `yt-dlp --flat-playlist -J` parsed with jq, new-list diffed against the per-source `--download-archive` BEFORE downloads (exact counts, exact dry-run plans, zero speculative downloads). State machine-owned outside ~/Videos: `$YTSYNC_STATE_DIR/{registry(\x1f-delimited slug⇥type⇥url⇥subdir⇥playlist_title⇥added_ts), archive/<slug>.txt, history.log}`, atomic temp+mv writes; `remove` keeps files AND archive (re-add resumes incrementally); `?v=`+`&list=` URLs download the single video only. Exit codes: 0 incl. no-op/cancel/non-tty-guard; 1 reserved for missing deps, invalid explicit URL, unknown/ambiguous name, wholesale source failure. Notify digest only when new>0 or failed>0 (+ ERR-trap alarm around download passes) via opt-in `lib/notify.sh`. Config scope `ytsync`: `YTSYNC_VIDEOS_DIR` / `YTSYNC_EXTRA_ARGS` (`pos config ytsync`); automation documented as a `pos system schedule` job (`COMMAND=pos media ytsync sync`, `NOTIFY=never`). Deps guards before `-h|--help` with yt-dlp+jq active under `--dry-run` (the preview IS the probe; ffmpeg skipped there). Docs: `tools-docs/ytsync.md` (new dir), POS.md media row + notes, HOWTO.md row, howto/media.md section + troubleshooting, AGENT_Context Common-Tasks row, `bin/pos` EXAMPLES line. Verified: `make gen && make check && make lint` 0 FAIL / 0 WARN; PATH-stub yt-dlp suite (add happy path, incremental 0-new idempotency, playlist NNN numbering, dry-run zero writes, non-tty guard rc0, remove-keeps-archive) with real $HOME byte-untouched via seams.
diff --git a/DOC/AGENT_Context_Project.md b/DOC/AGENT_Context_Project.md
index 754c72b..82ddd28 100644
--- a/DOC/AGENT_Context_Project.md
+++ b/DOC/AGENT_Context_Project.md
@@ -10,19 +10,19 @@
 
 <!-- GEN:START docmap -->
 | ## 1. Project Overview | 28–43 |
-| ## 2. Directory Structure | 44–195 |
-| ## 3. Installation Flow | 196–247 |
-| ## 4. The `pos` CLI System | 248–320 |
-| ## 5. Shared Library — `lib/common.sh` | 321–352 |
-| ## 6. Docker Compose / ScaleTail | 353–395 |
-| ## 7. Optional Apps (`apps/`) | 396–425 |
-| ## 8. Entertainment Module | 426–439 |
-| ## 9. Systemd Services | 440–451 |
-| ## 10. Configuration Files | 452–478 |
-| ## 11. Coding Conventions | 479–511 |
-| ## 12. Development Workflow | 512–564 |
-| ## 13. Key File Quick Reference | 565–628 |
-| ## 14. Common Tasks for Agents | 629–661 |
+| ## 2. Directory Structure | 44–196 |
+| ## 3. Installation Flow | 197–248 |
+| ## 4. The `pos` CLI System | 249–322 |
+| ## 5. Shared Library — `lib/common.sh` | 323–354 |
+| ## 6. Docker Compose / ScaleTail | 355–397 |
+| ## 7. Optional Apps (`apps/`) | 398–427 |
+| ## 8. Entertainment Module | 428–441 |
+| ## 9. Systemd Services | 442–453 |
+| ## 10. Configuration Files | 454–480 |
+| ## 11. Coding Conventions | 481–513 |
+| ## 12. Development Workflow | 514–566 |
+| ## 13. Key File Quick Reference | 567–631 |
+| ## 14. Common Tasks for Agents | 632–665 |
 <!-- GEN:END docmap -->
 
 ## 1. Project Overview
@@ -80,6 +80,7 @@ Linux_post_install/
 │   ├── 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)
+│   ├── pos-media-ytsync                    # Incrementally sync YouTube channels/playlists into ~/Videos
 │   ├── pos-network-checkport               # Check TCP/UDP port reachability (nmap, or bash/nc fallback) + local interface view
 │   ├── pos-network-download                # aria2 RPC daemon + queue control (add/torrent/metalink, watch, limits)
 │   ├── pos-network-hotspot                 # Wi-Fi hotspot via create_ap + wihotspot-gui
@@ -283,6 +284,7 @@ All non-interactive `pos` commands log output to `~/.local/share/linux_post_inst
 | 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) |
+| media | ytsync | `pos-media-ytsync` | Incrementally sync YouTube channels/playlists into ~/Videos |
 | network | checkport | `pos-network-checkport` | Check TCP/UDP port reachability (nmap, or bash/nc fallback) + local interface view |
 | network | download | `pos-network-download` | aria2 RPC daemon + queue control (add/torrent/metalink, watch, limits) |
 | network | hotspot | `pos-network-hotspot` | Wi-Fi hotspot via create_ap + wihotspot-gui |
@@ -583,7 +585,7 @@ Use conventional prefixes: `feat:`, `fix:`, `docs:`, `refactor:`, `chore:`
 | `features/autostart.sh` | 50 | Boot-time feature (moved from `bin/`, flag-gated service) |
 | `features/usb-automount.sh` | 138 | USB automount feature (udev rule + flag-gated service) |
 <!-- GEN:START filetable -->
-| `bin/pos` | 294 | CLI dispatcher with smart arg matching + logging + category help |
+| `bin/pos` | 295 | CLI dispatcher with smart arg matching + logging + category help |
 | `bin/pos-ai-gemini` | 311 | Chat with Google Gemini (ask, chat, models, sessions) |
 | `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) |
@@ -603,6 +605,7 @@ Use conventional prefixes: `feat:`, `fix:`, `docs:`, `refactor:`, `chore:`
 | `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` | 164 | Incremental Music → USB sync (mp3/mp4, add/update only) |
+| `bin/pos-media-ytsync` | 1180 | Incrementally sync YouTube channels/playlists into ~/Videos |
 | `bin/pos-network-checkport` | 496 | Check TCP/UDP port reachability (nmap, or bash/nc fallback) + local interface view |
 | `bin/pos-network-download` | 951 | aria2 RPC daemon + queue control (add/torrent/metalink, watch, limits) |
 | `bin/pos-network-hotspot` | 93 | Wi-Fi hotspot via create_ap + wihotspot-gui |
@@ -610,8 +613,8 @@ Use conventional prefixes: `feat:`, `fix:`, `docs:`, `refactor:`, `chore:`
 | `bin/pos-network-scan` | 272 | Parallel ping sweep of CIDR |
 | `bin/pos-share-nfs-client` | 138 | Mount NFS shares (ephemeral or persistent systemd mount units) |
 | `bin/pos-share-nfs-server` | 134 | Manage the NFS kernel server (status, share/unshare exports, enable/disable) |
-| `bin/pos-share-smb-client` | 217 | Mount SMB/CIFS shares (ephemeral or persistent systemd mount units) |
-| `bin/pos-share-smb-server` | 253 | Manage the Samba server (status, share/unshare exports, users, enable/disable) |
+| `bin/pos-share-smb-client` | 440 | Mount SMB/CIFS shares (ephemeral or persistent systemd mount units) |
+| `bin/pos-share-smb-server` | 311 | Manage the Samba server (status, share/unshare exports, users, enable/disable) |
 | `bin/pos-share-usb-server` | 218 | USB Redirector server control (--ls, --share; prompts when args omitted) |
 | `bin/pos-ssh-load-keys` | 31 | Load all SSH keys into the agent |
 | `bin/pos-system-backup` | 216 | Encrypted (AES-256) folder snapshots (tar + gpg) |
@@ -620,7 +623,7 @@ Use conventional prefixes: `feat:`, `fix:`, `docs:`, `refactor:`, `chore:`
 | `bin/pos-system-schedule` | 81 | Scheduled jobs: run a command on a timer; notify on threshold/change/error/always or silently |
 | `bin/pos-config` | 80 | Interactive editor for the tools' runtime config (reads # POS_CONFIG: registry) |
 | `bin/pos-tree` | 112 | Show the pos CLI command tree: categories, commands, and subcommands |
-| `completions/pos.bash` | 294 | Dynamic bash completion |
+| `completions/pos.bash` | 298 | Dynamic bash completion |
 <!-- GEN:END filetable -->
 | `apps/install.sh` | 171 | App install/uninstall picker/orchestrator |
 
@@ -652,6 +655,7 @@ Use conventional prefixes: `feat:`, `fix:`, `docs:`, `refactor:`, `chore:`
 | Modify SMB share logic | Edit `bin/pos-share-smb-server` / `bin/pos-share-smb-client` |
 | Modify scrcpy mirroring logic | Edit `bin/pos-communication-scrcpy` (config scope `scrcpy` via `pos config scrcpy`; `SCRCPY_*` keys in `~/.config/linux_post_install/scrcpy.env`) |
 | Modify Music→USB sync logic | Edit `bin/pos-media-sync` / shared USB layer `lib/usb-lib.sh` (seams `MEDIA_SYNC_SOURCE`/`MEDIA_SYNC_DEST`/`USB_MOUNT_BASE`/`USB_BYID` in `~/.config/linux_post_install/system.env`) |
+| Modify YouTube channel sync logic | Edit `bin/pos-media-ytsync` (state in `~/.local/share/linux_post_install/ytsync`; config scope `ytsync` via `pos config ytsync`; research notes `tools-docs/ytsync.md`) |
 | Modify the scheduler / scheduled jobs | Edit `bin/pos-system-schedule` / `lib/scheduler-lib.sh` (jobs in `~/.config/linux_post_install/schedule.d/`) |
 | Modify AI/Gemini logic | Edit `bin/pos-ai-gemini` (config scope `ai` via `pos config ai`; `AI_GEMINI_API_KEY`/`AI_GEMINI_MODEL` in `~/.config/linux_post_install/ai.env`) |
 | Modify UFW/firewall logic | Edit `bin/pos-system-firewall` |
diff --git a/DOC/HOWTO.md b/DOC/HOWTO.md
index d43776c..b968b6d 100644
--- a/DOC/HOWTO.md
+++ b/DOC/HOWTO.md
@@ -12,7 +12,7 @@ authoritative one-line reference (every command + flag), see
 | `pos ai` | Chat with Google Gemini from CLI or Telegram | [ai](howto/ai.md) |
 | `pos network` | IP info, hotspot, scan, port check, aria2 download daemon | [network](howto/network.md) |
 | `pos docker` | Compose services, container dashboards, disposable VMs | [docker](howto/docker.md) |
-| `pos media` | Download audio/video via yt-dlp | [media](howto/media.md) |
+| `pos media` | Download audio/video via yt-dlp; incremental YouTube channel sync | [media](howto/media.md) |
 | `pos system` | Backups, firewall, health dashboard | [system](howto/system.md) |
 | `pos system schedule` | Scheduled jobs: run a command on a timer, notify on threshold/change/error or silently | [schedule](howto/schedule.md) |
 | `pos ssh` | Load keys into the agent | [ssh](howto/ssh.md) |
diff --git a/DOC/POS.md b/DOC/POS.md
index 9cd53e9..fd6771f 100644
--- a/DOC/POS.md
+++ b/DOC/POS.md
@@ -210,6 +210,17 @@ 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 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` |
+| `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`) |
+
+A watch link carrying **both** `?v=` and `&list=` downloads only that single video
+(`--no-playlist`) — nobody accidentally backfills a 500-video playlist from a watch
+link; a pure playlist link becomes a tracked playlist source with numbered
+`<NNN> - <title>.mp4` files. `pos media ytsync remove <name>` stops tracking but
+keeps the downloaded files AND the archive — re-adding the same source later
+resumes incrementally instead of re-downloading. Members-only/age-gated videos are
+reported as "N videos require sign-in — skipped" (escape hatch:
+`YTSYNC_EXTRA_ARGS="--cookies …"` in `ytsync.env`). Research details:
+`tools-docs/ytsync.md`.
 
 ### system
 
diff --git a/DOC/howto/media.md b/DOC/howto/media.md
index c4e9f7c..4c8608e 100644
--- a/DOC/howto/media.md
+++ b/DOC/howto/media.md
@@ -1,13 +1,15 @@
 # How-To: `pos media`
 
-Download audio and video from the web via `yt-dlp`, and sync your library to a
-USB stick. Tools: `mp3`, `mp4`, `sync`.
+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`.
 
 | Tool | What it does |
 |------|--------------|
 | `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) |
+| `pos media ytsync` | Track YouTube channels/playlists and download only new videos into `~/Videos` |
 
 Requires `yt-dlp` and `ffmpeg` (`sudo apt install yt-dlp ffmpeg`); the tools
 fail with a clean error message instead of a raw `command not found` if either
@@ -147,6 +149,85 @@ Config (all in `~/.config/linux_post_install/system.env` or exported):
 
 ---
 
+## `pos media ytsync` — incremental YouTube channel sync
+
+```bash
+pos media ytsync                                  # interactive
+pos media ytsync add https://youtube.com/@SomeChannel
+pos media ytsync sync                             # fetch new videos from every source
+pos media ytsync list
+pos media ytsync remove "Some Channel"
+```
+
+The first run asks for a channel or playlist URL, shows what was resolved
+(`Resolved : Linus Tech Tips (channel · 2140 videos)` + the target library path),
+and downloads everything. Every later run probes the same URL, diffs it against a
+per-source download archive, and fetches **only new videos** — one yt-dlp call per
+video (`bestvideo*+bestaudio/best` merged to MP4 with metadata, chapters and the
+thumbnail embedded; existing files are never overwritten).
+
+Where files land:
+
+```
+~/Videos/<channel>/<title>.mp4                              # channels & single videos
+~/Videos/<channel>/<playlist>/<NNN> - <title>.mp4           # playlist sources (playlist order)
+```
+
+| Command | Meaning |
+|---------|---------|
+| `add [url]` | Register a source + first download (asks for the URL if omitted) |
+| `sync [name]` | Incremental pass — all tracked sources, or one by slug/display name |
+| `list` | Tracked sources table: type, archived count, last sync date, destination |
+| `remove <name>` | Stop tracking. Downloaded files AND the archive are kept |
+
+Notes:
+
+- A watch link with **both** `?v=` and `&list=` downloads only that single video,
+  never the whole playlist.
+- Retitled/renamed videos keep their local filenames (the archive is keyed by video
+  id); inserting a video mid-playlist shifts future numbering only.
+- Members-only / age-gated videos are skipped with a count ("N videos require
+  sign-in"). Escape hatch: put `YTSYNC_EXTRA_ARGS=--cookies-from-browser firefox`
+  (or `--cookies <file>`) into the config file below.
+- State lives outside `~/Videos`, in `~/.local/share/linux_post_install/ytsync/`
+  (registry, per-source archives, run history) — the media tree stays pure media.
+
+**Recipe: daily automation** — no built-in timers; use the shared scheduler:
+
+```bash
+pos system schedule config     # name: ytsync
+#   INTERVAL=daily            (or hourly / weekly / OnCalendar=…)
+#   NOTIFY=never              # ytsync sends its own digest; don't double-notify
+#   MSG="ytSync"
+#   COMMAND=pos media ytsync sync
+pos system schedule enable ytsync
+pos system schedule run ytsync # test once, right now
+```
+
+ytsync never prompts on `sync`, so the job is timer-safe by construction. It
+notifies via `lib/notify.sh` only when something happened (new videos or failures);
+a scheduled no-op run stays silent — hence `NOTIFY=never` on the job to avoid
+double alerts.
+
+**Previewing:** `--dry-run` works on `add` and `sync` — real probe + plan block
+(`New : 12 would be downloaded (800 already present)` + example filenames), zero
+writes anywhere:
+
+```bash
+pos media ytsync sync --dry-run
+pos media ytsync add https://youtube.com/@SomeChannel --dry-run
+```
+
+Config (`~/.config/linux_post_install/ytsync.env`, chmod 600 — materialize/edit via
+`pos config ytsync`; exported environment wins):
+
+| Key | Default | Meaning |
+|-----|---------|---------|
+| `YTSYNC_VIDEOS_DIR` | `$HOME/Videos` | Videos root for synced sources |
+| `YTSYNC_EXTRA_ARGS` | *(empty)* | Extra yt-dlp flags appended to every download call (cookies, format overrides, …) |
+
+---
+
 ## Troubleshooting
 
 - Format list is empty / download fails → the site or age-gate requires
@@ -157,6 +238,15 @@ Config (all in `~/.config/linux_post_install/system.env` or exported):
   it falls back to the uploader name in the artist slot.
 - Very large downloads: ensure free space; files land in `~/Music`/`~/Videos`
   (or your `-o` directory).
+- ytsync: "could not reach YouTube" at add → connectivity/DNS; the interactive
+  flow re-prompts up to 3×. "source not found or private" → wrong handle or a
+  deleted/private source.
+- ytsync: many "exists, kept" warnings after a YouTube-side change → the
+  channel's internal id changed, so re-adding computed a new archive. Rename the
+  old archive file (`~/.local/share/linux_post_install/ytsync/archive/<old>.txt`)
+  to the new slug before syncing (see `tools-docs/ytsync.md`).
+- ytsync: "disk full — stopping … mid-run" → free space on the videos volume and
+  run `pos media ytsync sync` again; unfetched videos simply stay "new".
 
 ---
 
diff --git a/bin/pos b/bin/pos
index 9a41370..29e0a1b 100755
--- a/bin/pos
+++ b/bin/pos
@@ -153,6 +153,7 @@ EXAMPLES
 
   pos media mp3 <url>                     Download audio as MP3
   pos media mp4 <url>                     Download video as MP4
+  pos media ytsync sync                   Incremental YouTube channel sync
 
   pos system firewall                     Interactive UFW manager
   pos system backup /srv/project          Encrypted (AES-256) folder snapshot
diff --git a/bin/pos-media-ytsync b/bin/pos-media-ytsync
new file mode 100755
index 0000000..bc7974d
--- /dev/null
+++ b/bin/pos-media-ytsync
@@ -0,0 +1,1180 @@
+#!/usr/bin/env bash
+set -euo pipefail
+# POS: media ytsync — Incrementally sync YouTube channels/playlists into ~/Videos
+# POS_SUBCMDS: add sync list remove
+# POS_FLAGS: --dry-run
+# POS_CONFIG: ytsync | ytsync.env | YTSYNC_VIDEOS_DIR=:Videos root for synced channels (default ~/Videos) | YTSYNC_EXTRA_ARGS=:Extra yt-dlp flags appended verbatim to every yt-dlp call (advanced)
+
+source "$(dirname "$0")/../lib/common.sh" 2>/dev/null || source "$(dirname "$0")/common.sh"
+source "$(dirname "$0")/../lib/notify.sh" 2>/dev/null || source "$(dirname "$0")/notify.sh"
+if ! command -v notify_send >/dev/null 2>&1; then
+    notify_send() { return 0; }   # notify.sh absent → silent no-op (opt-in by design)
+fi
+
+# ── Global flag pre-scan ────────────────────────────────────────────
+DRY_RUN=0
+for _arg in "$@"; do
+    if [ "$_arg" = "--dry-run" ]; then DRY_RUN=1; fi
+done
+
+# ── Deps guards (before -h|--help; yt-dlp+jq active EVEN under --dry-run,
+#    because the preview IS the probe — deliberate divergence from mp3/mp4) ──
+command -v yt-dlp >/dev/null 2>&1 || err "yt-dlp not found — installed by preinstall.sh (GitHub release → /usr/local/bin); run ./preinstall.sh or see DOC/howto/media.md"
+command -v jq >/dev/null 2>&1 || err "jq not found (needed to parse yt-dlp probe output) — install it with: sudo apt install jq"
+if [ "$DRY_RUN" -eq 0 ]; then
+    command -v ffmpeg >/dev/null 2>&1 || err "ffmpeg not found (needed for MP4 merge) — install it with: sudo apt install ffmpeg"
+fi
+
+# ── Runtime config (~/.config/linux_post_install/ytsync.env) ────────
+# Exported environment wins over the file; defaults come last.
+_YTSYNC_CFG="$CONFIG_DIR/ytsync.env"
+if [ -f "$_YTSYNC_CFG" ]; then
+    while IFS= read -r _line || [ -n "$_line" ]; do
+        case "$_line" in ''|\#*) continue ;; esac
+        case "$_line" in
+            YTSYNC_VIDEOS_DIR=*)
+                _v="${_line#*=}"
+                _v="${_v%\"}"; _v="${_v#\"}"; _v="${_v%\'}"; _v="${_v#\'}"
+                : "${YTSYNC_VIDEOS_DIR:=$_v}"
+                ;;
+            YTSYNC_EXTRA_ARGS=*)
+                _v="${_line#*=}"
+                _v="${_v%\"}"; _v="${_v#\"}"; _v="${_v%\'}"; _v="${_v#\'}"
+                : "${YTSYNC_EXTRA_ARGS:=$_v}"
+                ;;
+        esac
+    done <"$_YTSYNC_CFG"
+fi
+
+# ── Env seams (all written VAR="${VAR:-default}") ───────────────────
+YTSYNC_VIDEOS_DIR="${YTSYNC_VIDEOS_DIR:-$HOME/Videos}"   # user key AND test seam
+YTSYNC_STATE_DIR="${YTSYNC_STATE_DIR:-${XDG_STATE_HOME:-$HOME/.local/share}/linux_post_install/ytsync}"
+
+REG_FILE="$YTSYNC_STATE_DIR/registry"
+ARCHIVE_DIR="$YTSYNC_STATE_DIR/archive"
+HIST_FILE="$YTSYNC_STATE_DIR/history.log"
+
+BAD_URL_MSG="Not a YouTube URL — expected a channel (@handle, /c/, /user/), a playlist (?list=…), or a video link"
+
+usage() {
+    cat <<'EOF'
+Usage: pos media ytsync [command] [args]
+
+Incrementally download YouTube channels/playlists into ~/Videos.
+First run asks for a channel URL; repeat runs fetch only new videos.
+
+Commands:
+  add [url]         Register a source and download it (asks for URL if omitted)
+  sync [name]       Incremental sync of tracked sources (all, if no name given)
+  list              Show tracked sources and their status
+  remove <name>     Stop tracking a source (keeps downloaded files)
+
+Options:
+  --dry-run         Show what would be downloaded, fetch nothing
+  -h, --help        This help
+
+Layout:
+  Videos/<channel>/<playlist>/<NNN> - <title>.<ext>   (playlist sources)
+  Videos/<channel>/<title>.<ext>                      (channel/video sources)
+
+Notes:
+  Existing files are never overwritten; renamed/retitled videos keep their
+  local filename. Unattended/scheduled use: 'pos media ytsync sync'.
+  A watch link carrying BOTH ?v= and &list= downloads only that single video
+  (--no-playlist), never the whole playlist. 'remove' keeps the downloaded
+  files AND the archive — re-adding the same source later resumes
+  incrementally instead of re-downloading.
+
+Examples:
+  pos media ytsync                                  # interactive
+  pos media ytsync add https://youtube.com/@SomeChannel
+  pos media ytsync sync                             # cron/timer entry point
+  pos media ytsync sync --dry-run                   # preview only
+  pos media ytsync list
+
+Environment:
+  YTSYNC_VIDEOS_DIR   Videos root (default: $HOME/Videos)
+  YTSYNC_EXTRA_ARGS   Extra yt-dlp flags appended to every download call
+  Both editable via 'pos config ytsync'.
+EOF
+    exit 0
+}
+
+# ── Small shared helpers ────────────────────────────────────────────
+_tmpfiles=()
+cleanup() {
+    if [ "${#_tmpfiles[@]}" -gt 0 ]; then
+        rm -f "${_tmpfiles[@]}" >/dev/null 2>&1 || true
+    fi
+}
+trap cleanup EXIT
+
+newtmp() {
+    local t
+    t="$(mktemp)"
+    _tmpfiles+=("$t")
+    printf '%s' "$t"
+}
+
+_pretty() {   # collapse a $HOME prefix to ~ for display only
+    local p="$1"
+    case "$p" in
+        "$HOME") printf '~' ;;
+        "$HOME"/*) printf '~%s' "${p#"$HOME"}" ;;
+        *) printf '%s' "$p" ;;
+    esac
+}
+
+fmt_dur() {   # seconds → "4m12s" / "37s" / "1h05m"
+    local s="$1"
+    if [ "$s" -ge 3600 ]; then
+        printf '%dh%02dm' $((s / 3600)) $(((s % 3600) / 60))
+    elif [ "$s" -ge 60 ]; then
+        printf '%dm%02ds' $((s / 60)) $((s % 60))
+    else
+        printf '%ss' "$s"
+    fi
+}
+
+secs_since() {   # nanosecond start stamp → whole seconds elapsed
+    local end
+    end=$(_nano_now)
+    echo $(((end - $1) / 1000000000))
+}
+
+is_youtube_url() {
+    local u="$1"
+    case "$u" in
+        http://*youtube.com/* | https://*youtube.com/* | \
+            http://*youtu.be/* | https://*youtu.be/* | \
+            www.youtube.com/* | m.youtube.com/* | music.youtube.com/* | \
+            youtube.com/* | youtu.be/* | @*)
+            return 0 ;;
+    esac
+    return 1
+}
+
+classify_url() {   # list= without v= → playlist; v= → single video; else channel
+    local u="$1"
+    if [[ "$u" == *list=* && "$u" != *v=* ]]; then
+        printf 'playlist\n'
+    elif [[ "$u" == *v=* ]]; then
+        printf 'video\n'
+    else
+        printf 'channel\n'
+    fi
+}
+
+sanitize_component() {   # safe directory component from a resolved name
+    local s="$1"
+    s="${s//\//-}"
+    s="$(printf '%s' "$s" | sed -E 's/^[[:space:].]+//; s/[[:space:].]+$//')"
+    s="${s:0:80}"
+    if [ -z "$s" ]; then s="YouTube"; fi
+    printf '%s' "$s"
+}
+
+slugify() {   # unique internal key [a-z0-9][a-z0-9_-]*
+    local s
+    s="$(printf '%s' "$1" | tr '[:upper:]' '[:lower:]')"
+    s="$(printf '%s' "$s" | sed -E 's/[^a-z0-9]+/-/g; s/^-+//; s/-+$//' | cut -c1-60)"
+    if [ -z "$s" ]; then s="source"; fi
+    case "$s" in
+        [a-z0-9]*) ;;
+        *) s="c$s" ;;
+    esac
+    printf '%s' "$s"
+}
+
+# ── Registry (machine-owned state; \x1f-delimited records) ──────────
+# slug ⇥ type ⇥ url ⇥ subdir ⇥ playlist_title ⇥ added_ts
+registry_entries() {
+    if [ -f "$REG_FILE" ]; then
+        cat "$REG_FILE"
+    fi
+    return 0
+}
+
+registry_count() {
+    local n=""
+    if [ -f "$REG_FILE" ]; then
+        n="$(grep -c . "$REG_FILE" 2>/dev/null || true)"
+    fi
+    printf '%s' "${n:-0}"
+}
+
+registry_has_slug() {
+    local s="$1" line f1
+    while IFS= read -r line; do
+        [ -n "$line" ] || continue
+        f1="${line%%$'\x1f'*}"
+        if [ "$f1" = "$s" ]; then return 0; fi
+    done < <(registry_entries)
+    return 1
+}
+
+unique_slug() {   # numeric -2 suffix on collision (checks registry slugs only)
+    local base="$1" cand n=2
+    cand="$base"
+    while registry_has_slug "$cand"; do
+        cand="${base}-${n}"
+        n=$((n + 1))
+    done
+    printf '%s' "$cand"
+}
+
+registry_add_line() {   # atomic append (temp+mv)
+    local line="$1" tmp
+    mkdir -p "$YTSYNC_STATE_DIR"
+    tmp="$(mktemp "$YTSYNC_STATE_DIR/.registry.XXXXXX")"
+    _tmpfiles+=("$tmp")
+    {
+        if [ -f "$REG_FILE" ]; then cat "$REG_FILE"; fi
+        printf '%s\n' "$line"
+    } >"$tmp"
+    mv "$tmp" "$REG_FILE"
+}
+
+registry_remove_slug() {   # atomic rewrite without the slug's line
+    local slug="$1" tmp line f1
+    mkdir -p "$YTSYNC_STATE_DIR"
+    tmp="$(mktemp "$YTSYNC_STATE_DIR/.registry.XXXXXX")"
+    _tmpfiles+=("$tmp")
+    while IFS= read -r line || [ -n "$line" ]; do
+        [ -n "$line" ] || continue
+        f1="${line%%$'\x1f'*}"
+        if [ "$f1" = "$slug" ]; then continue; fi
+        printf '%s\n' "$line"
+    done < <(registry_entries) >"$tmp"
+    mv "$tmp" "$REG_FILE"
+}
+
+# ── Archive + history ───────────────────────────────────────────────
+is_archived() {   # native yt-dlp archive format "<extractor> <id>"; exact-field match
+    local id="$1" f="$2"
+    [ -f "$f" ] || return 1
+    awk -v want="$id" '$2 == want { found=1; exit } END { exit(found ? 0 : 1) }' "$f"
+}
+
+archive_count() {
+    local slug="$1" n=""
+    if [ -f "$ARCHIVE_DIR/$slug.txt" ]; then
+        n="$(wc -l <"$ARCHIVE_DIR/$slug.txt")"
+        n="$(printf '%s' "$n" | tr -d '[:space:]')"
+    fi
+    printf '%s' "${n:-0}"
+}
+
+append_history() {   # <date> · <name> · N new · M skipped · K failed
+    mkdir -p "$YTSYNC_STATE_DIR"
+    printf '%s · %s · %s new · %s skipped · %s failed\n' \
+        "$(date '+%Y-%m-%d %H:%M')" "$1" "$2" "$3" "$4" >>"$HIST_FILE"
+}
+
+append_history_failed() {
+    mkdir -p "$YTSYNC_STATE_DIR"
+    printf '%s · %s · FAILED (probe)\n' "$(date '+%Y-%m-%d %H:%M')" "$1" >>"$HIST_FILE"
+}
+
+last_sync_of() {   # newest history line naming <display name>, date field only
+    local name="$1" last=""
+    if [ -f "$HIST_FILE" ]; then
+        last="$(grep -F " · $name · " "$HIST_FILE" 2>/dev/null | tail -n 1 | cut -d'·' -f1 || true)"
+        last="${last% }"
+    fi
+    printf '%s' "${last:--}"
+}
+
+last_run_overall() {
+    local last=""
+    if [ -f "$HIST_FILE" ]; then
+        last="$(tail -n 1 "$HIST_FILE" | cut -d'·' -f1 || true)"
+        last="${last% }"
+    fi
+    printf '%s' "$last"
+}
+
+# ── Probe (yt-dlp --flat-playlist -J, parsed with jq) ───────────────
+# spawn()-shaped UX but RETURNS failure instead of exiting: the interactive add
+# flow re-prompts up to 3× and a failing source during sync must not kill the
+# others' passes (spawn() exits the process on failure — unusable here).
+# Spinner frames are TTY-only so no \r bytes ever reach the dispatcher tee log.
+PROBE_JSON=""
+PROBE_ERR=""
+
+run_probe() {   # run_probe <url>
+    local url="$1"
+    PROBE_JSON="$(newtmp)"
+    PROBE_ERR="$(newtmp)"
+    local msg="Resolving source …" start rc pid elapsed i
+    start=$(_nano_now)
+    yt-dlp --flat-playlist -J --no-warnings -- "$url" >"$PROBE_JSON" 2>"$PROBE_ERR" &
+    pid=$!
+    if [ -t 1 ]; then
+        local spin=('⠋' '⠙' '⠹' '⠸' '⠼' '⠴' '⠦' '⠧' '⠇' '⠏')
+        i=0
+        while kill -0 "$pid" 2>/dev/null; do
+            printf '\r%s  %s%s %s' "$CYAN" "${spin[$i]}" "$RESET" "$msg"
+            i=$(((i + 1) % ${#spin[@]}))
+            sleep 0.1
+        done
+    else
+        printf '%s\n' "$msg"
+    fi
+    rc=0
+    wait "$pid" || rc=$?
+    elapsed=$(_elapsed "$start")
+    if [ "$rc" -eq 0 ]; then
+        if [ -t 1 ]; then
+            printf '\r%s  OK%s %s (%s)\n' "$GREEN" "$RESET" "$msg" "$elapsed"
+        else
+            printf '%s  OK %s (%s)\n' "$GREEN" "$msg" "$elapsed"
+        fi
+    else
+        if [ -t 1 ]; then
+            printf '\r%s  FAIL%s %s (%s)\n' "$RED" "$RESET" "$msg" "$elapsed"
+        else
+            printf '%s  FAIL %s (%s)\n' "$RED" "$msg" "$elapsed"
+        fi
+    fi
+    return "$rc"
+}
+
+probe_fail_reason() {   # echoes "notfound" | "unreachable" (reads $PROBE_ERR)
+    if grep -qiE 'not found|private|does not exist|404|unavailable|removed' "$PROBE_ERR" 2>/dev/null; then
+        printf 'notfound\n'
+    else
+        printf 'unreachable\n'
+    fi
+}
+
+parse_probe() {   # sets P_NAME P_OWNER P_TITLE P_KEY from $PROBE_JSON
+    jq -e 'type == "object"' "$PROBE_JSON" >/dev/null 2>&1 || return 1
+    P_NAME="$(jq -r '.channel // .uploader // .uploader_id // .title // ""' "$PROBE_JSON")"
+    P_OWNER="$(jq -r '.channel // .uploader // .uploader_id // ""' "$PROBE_JSON")"
+    P_TITLE="$(jq -r '.title // ""' "$PROBE_JSON")"
+    P_KEY="$(jq -r '.uploader_id // .channel_id // .id // ""' "$PROBE_JSON")"
+    return 0
+}
+
+ENTRY_IDS=()
+ENTRY_TITLES=()
+
+collect_entries() {   # flat .entries[] or a single video object (?v= URLs)
+    ENTRY_IDS=()
+    ENTRY_TITLES=()
+    local n p id t
+    n="$(jq -r '((.entries // []) | length)' "$PROBE_JSON")"
+    if [ "$n" -gt 0 ]; then
+        local -a pairs=()
+        mapfile -t pairs < <(jq -r '.entries[] | ((.id // "") + "\u001f" + (.title // ""))' "$PROBE_JSON")
+        for p in "${pairs[@]}"; do
+            id="${p%%$'\x1f'*}"
+            t="${p#*$'\x1f'}"
+            ENTRY_IDS+=("$id")
+            ENTRY_TITLES+=("$t")
+        done
+    else
+        ENTRY_IDS+=("$(jq -r '.id // ""' "$PROBE_JSON")")
+        ENTRY_TITLES+=("$(jq -r '.title // ""' "$PROBE_JSON")")
+    fi
+}
+
+NEW_IDS=()
+NEW_TITLES=()
+NEW_POS=()
+NEW_TOTAL=0
+SIGNIN_COUNT=0
+TOTAL_VALID=0
+
+is_signin_skipped() {   # empty id OR "[Private"/"[Deleted"/"[Unavailable" titles
+    if [ -z "$1" ]; then return 0; fi
+    case "$2" in
+        "[Private"* | "[Deleted"* | "[Unavailable"*) return 0 ;;
+    esac
+    return 1
+}
+
+compute_new_list() {   # $1 = archive file; diff entry ids against it BEFORE downloads
+    local archive="$1"
+    NEW_IDS=()
+    NEW_TITLES=()
+    NEW_POS=()
+    NEW_TOTAL=0
+    SIGNIN_COUNT=0
+    TOTAL_VALID=0
+    local i n id t pos=0
+    n="${#ENTRY_IDS[@]}"
+    for ((i = 0; i < n; i++)); do
+        id="${ENTRY_IDS[$i]}"
+        t="${ENTRY_TITLES[$i]}"
+        pos=$((pos + 1))
+        if is_signin_skipped "$id" "$t"; then
+            SIGNIN_COUNT=$((SIGNIN_COUNT + 1))
+            continue
+        fi
+        TOTAL_VALID=$((TOTAL_VALID + 1))
+        if ! is_archived "$id" "$archive"; then
+            NEW_IDS+=("$id")
+            NEW_TITLES+=("$t")
+            NEW_POS+=("$pos")
+            NEW_TOTAL=$((NEW_TOTAL + 1))
+        fi
+    done
+    return 0
+}
+
+# ── Per-video download (NEVER wrapped in spawn(): hours-long batches need a
+#    live heartbeat; spawn captures output until completion) ────────────────
+DL_ERRCAP=""
+DL_RC=0
+
+download_video() {   # <archive> <template> <video_id> <type>; stderr→$DL_ERRCAP
+    local archive="$1" tpl="$2" vid="$3" vtype="$4"
+    local -a dl=(
+        yt-dlp
+        -f "bestvideo*+bestaudio/best"
+        --merge-output-format mp4
+        --embed-metadata --embed-chapters
+        --embed-thumbnail
+        --no-overwrites
+        --download-archive "$archive"
+        --windows-filenames
+        --trim-filenames 120
+        --retries 3 --fragment-retries 3
+    )
+    if [ "$vtype" = "video" ]; then dl+=(--no-playlist); fi
+    dl+=(--quiet --no-warnings)
+    if [ -t 1 ]; then dl+=(--progress); fi
+    if [ -n "${YTSYNC_EXTRA_ARGS:-}" ]; then
+        local -a extra=()
+        read -r -a extra <<<"$YTSYNC_EXTRA_ARGS" || true
+        if [ "${#extra[@]}" -gt 0 ]; then dl+=("${extra[@]}"); fi
+    fi
+    dl+=(-o "$tpl" "https://www.youtube.com/watch?v=$vid")
+    DL_ERRCAP="$(newtmp)"
+    DL_RC=0
+    "${dl[@]}" 2>"$DL_ERRCAP" || DL_RC=$?
+}
+
+# ── Failure-alarm trap (media-sync precedent), armed per pass ───────
+CURRENT_SOURCE=""
+arm_fail_alarm() {
+    CURRENT_SOURCE="$1"
+    trap 'notify_send "⚠️ ytSync FAILED for ${CURRENT_SOURCE}"' ERR
+}
+disarm_fail_alarm() {
+    trap - ERR
+    CURRENT_SOURCE=""
+}
+
+# ── Run-result accumulators ─────────────────────────────────────────
+G_NEW=0
+G_PRESENT=0
+G_FAILED=0
+G_WHOLEFAIL=0
+G_SOURCES=0
+NOTIFY_TITLES=()
+NOTIFY_MORE=0
+NOTIFY_NAMES_NEW=()
+NOTIFY_NAMES_FAIL=()
+NOTIFY_SRC_NEW=0
+NOTIFY_DEST=""
+PASS_ROWS=()
+
+reset_globals() {
+    G_NEW=0
+    G_PRESENT=0
+    G_FAILED=0
+    G_WHOLEFAIL=0
+    G_SOURCES=0
+    NOTIFY_TITLES=()
+    NOTIFY_MORE=0
+    NOTIFY_NAMES_NEW=()
+    NOTIFY_NAMES_FAIL=()
+    NOTIFY_SRC_NEW=0
+    NOTIFY_DEST=""
+    PASS_ROWS=()
+}
+
+join_comma() {   # join_comma <array-name>
+    local -n arr="$1"
+    local out="" el
+    for el in "${arr[@]}"; do
+        if [ -z "$out" ]; then out="$el"; else out="${out}, ${el}"; fi
+    done
+    printf '%s' "$out"
+}
+
+send_digest() {   # noteworthy-only: new>0 or failed>0 (silent noop runs)
+    if [ "$DRY_RUN" -eq 1 ]; then return 0; fi
+    if [ "$G_NEW" -gt 0 ]; then
+        local msg t dest
+        msg="📺 ytSync — ${G_NEW} new videos: $(join_comma NOTIFY_NAMES_NEW)"
+        for t in "${NOTIFY_TITLES[@]}"; do
+            msg+=$'\n• '"${t}"
+        done
+        if [ "$NOTIFY_MORE" -gt 0 ]; then
+            msg+=$'\n…and '"${NOTIFY_MORE}"' more'
+        fi
+        if [ "$NOTIFY_SRC_NEW" -eq 1 ]; then
+            dest="$NOTIFY_DEST"
+        else
+            dest="$YTSYNC_VIDEOS_DIR"
+        fi
+        msg+=$'\n→ '"$(_pretty "$dest")"
+        notify_send "$msg"
+    fi
+    if [ "$G_FAILED" -gt 0 ]; then
+        notify_send "⚠️ ytSync — ${G_FAILED} videos failed: $(join_comma NOTIFY_NAMES_FAIL) (run 'pos media ytsync sync' to retry)"
+    elif [ "$G_WHOLEFAIL" -gt 0 ]; then
+        notify_send "⚠️ ytSync — ${G_WHOLEFAIL} sources failed: $(join_comma NOTIFY_NAMES_FAIL) (check connectivity; run 'pos media ytsync sync' to retry)"
+    fi
+    return 0
+}
+
+# ── Per-source pass engine ──────────────────────────────────────────
+S_SLUG="" S_TYPE="" S_URL="" S_SUBDIR="" S_TITLE=""
+R_NEW=0 R_PRESENT=0 R_FAILED=0 R_EXISTS=0 R_SIGNIN=0 R_STOPPED=""
+
+pass_prepare() {   # fresh probe + diff; rc 0 ok / 1 wholesale failure
+    R_NEW=0
+    R_PRESENT=0
+    R_FAILED=0
+    R_EXISTS=0
+    R_SIGNIN=0
+    R_STOPPED=""
+    CURRENT_SOURCE="${S_SUBDIR##*/}"
+    if ! run_probe "$S_URL"; then
+        if [ "$(probe_fail_reason)" = "notfound" ]; then
+            warn "source not found or private: $S_URL — skipping"
+        else
+            warn "could not reach YouTube — check your connection and try again (${CURRENT_SOURCE})"
+        fi
+        return 1
+    fi
+    if ! parse_probe; then
+        warn "unexpected yt-dlp probe output for ${CURRENT_SOURCE} — skipping"
+        return 1
+    fi
+    collect_entries
+    compute_new_list "$ARCHIVE_DIR/$S_SLUG.txt"
+    R_SIGNIN="$SIGNIN_COUNT"
+    R_PRESENT=$((TOTAL_VALID - NEW_TOTAL))
+    return 0
+}
+
+print_dry_plan_for_current() {
+    if [ "$R_SIGNIN" -gt 0 ]; then
+        warn "${R_SIGNIN} videos require sign-in — skipped"
+    fi
+    printf 'Source   : %s\n' "$S_URL"
+    printf 'Resolved : %s (%s · %s videos)\n' "${P_NAME:-${S_SUBDIR##*/}}" "$S_TYPE" "$TOTAL_VALID"
+    printf 'Library  : %s/\n' "$(_pretty "$YTSYNC_VIDEOS_DIR/$S_SUBDIR")"
+    printf 'New      : %s would be downloaded (%s already present)\n' "$NEW_TOTAL" "$R_PRESENT"
+    local i shown=0 ex
+    for ((i = 0; i < NEW_TOTAL; i++)); do
+        if [ "$shown" -ge 5 ]; then break; fi
+        if [ "$S_TYPE" = "playlist" ]; then
+            ex="$(printf '%03d - %s.mp4' "${NEW_POS[$i]}" "${NEW_TITLES[$i]}")"
+        else
+            ex="${NEW_TITLES[$i]}.mp4"
+        fi
+        printf '  %s\n' "$ex"
+        shown=$((shown + 1))
+    done
+    if [ "$NEW_TOTAL" -gt "$shown" ]; then
+        printf '  … %s more\n' "$((NEW_TOTAL - shown))"
+    fi
+    printf 'DRY RUN complete — %s new would be fetched → %s/%s\n' \
+        "$NEW_TOTAL" "$(_pretty "$YTSYNC_VIDEOS_DIR")" "$S_SUBDIR"
+    return 0
+}
+
+pass_execute() {
+    local name="${S_SUBDIR##*/}"
+    local archive="$ARCHIVE_DIR/$S_SLUG.txt"
+    local destdir="$YTSYNC_VIDEOS_DIR/$S_SUBDIR"
+
+    if [ "$DRY_RUN" -eq 1 ]; then
+        print_dry_plan_for_current
+        G_SOURCES=$((G_SOURCES + 1))
+        G_NEW=$((G_NEW + NEW_TOTAL))
+        G_PRESENT=$((G_PRESENT + R_PRESENT))
+        PASS_ROWS+=("${name} — ${NEW_TOTAL} new · ${R_PRESENT} present")
+        return 0
+    fi
+
+    if [ "$R_SIGNIN" -gt 0 ]; then
+        warn "${R_SIGNIN} videos require sign-in — skipped"
+    fi
+    log "${name} — ${NEW_TOTAL} new of ${TOTAL_VALID}"
+
+    if [ "${#NEW_IDS[@]}" -eq 0 ]; then
+        ok "Sync complete: 0 new, ${R_PRESENT} already present, 0 failed → ${destdir}"
+        append_history "$name" 0 "$R_PRESENT" 0
+        G_SOURCES=$((G_SOURCES + 1))
+        G_PRESENT=$((G_PRESENT + R_PRESENT))
+        PASS_ROWS+=("${name} — 0 new · ${R_PRESENT} present · 0 failed")
+        return 0
+    fi
+    mkdir -p "$destdir" "$ARCHIVE_DIR"
+
+    arm_fail_alarm "$name"
+    local i total idx vid vt tpl pos tstart rc
+    total="${#NEW_IDS[@]}"
+    idx=0
+    for ((i = 0; i < total; i++)); do
+        vid="${NEW_IDS[$i]}"
+        vt="${NEW_TITLES[$i]}"
+        pos="${NEW_POS[$i]}"
+        idx=$((idx + 1))
+        echo "  [$idx/$total] $vt"
+        if [ "$S_TYPE" = "playlist" ]; then
+            tpl="${destdir}/$(printf '%03d' "$pos") - %(title)s.%(ext)s"
+        else
+            tpl="${destdir}/%(title)s.%(ext)s"
+        fi
+        tstart=$(_nano_now)
+        download_video "$archive" "$tpl" "$vid" "$S_TYPE"
+        rc="$DL_RC"
+        if [ "$rc" -eq 0 ]; then
+            ok "[$idx/$total] $vt ($(fmt_dur "$(secs_since "$tstart")"))"
+            R_NEW=$((R_NEW + 1))
+            G_NEW=$((G_NEW + 1))
+            if [ "${#NOTIFY_TITLES[@]}" -lt 5 ]; then
+                NOTIFY_TITLES+=("$vt")
+            else
+                NOTIFY_MORE=$((NOTIFY_MORE + 1))
+            fi
+        elif grep -qE 'No space left on device|Errno 28' "$DL_ERRCAP" 2>/dev/null; then
+            warn "disk full — stopping '${name}' mid-run"
+            sed -n '1,3p' "$DL_ERRCAP" | sed 's/^/    /'
+            R_STOPPED="yes"
+            break
+        elif grep -qiE 'has already been downloaded|already been recorded' "$DL_ERRCAP" 2>/dev/null; then
+            warn "exists, kept: $vt"
+            ok "[$idx/$total] $vt ($(fmt_dur "$(secs_since "$tstart")"))"
+            R_EXISTS=$((R_EXISTS + 1))
+        else
+            warn "unavailable: $vt"
+            sed -n '1,3p' "$DL_ERRCAP" | sed 's/^/    /'
+            R_FAILED=$((R_FAILED + 1))
+            G_FAILED=$((G_FAILED + 1))
+        fi
+    done
+    disarm_fail_alarm
+
+    local present_total=$((R_PRESENT + R_EXISTS))
+    ok "Sync complete: ${R_NEW} new, ${present_total} already present, ${R_FAILED} failed → ${destdir}"
+    append_history "$name" "$R_NEW" "$present_total" "$R_FAILED"
+    G_SOURCES=$((G_SOURCES + 1))
+    G_PRESENT=$((G_PRESENT + present_total))
+    local row="${name} — ${R_NEW} new · ${present_total} present · ${R_FAILED} failed"
+    if [ -n "$R_STOPPED" ]; then row+=" · STOPPED (disk full)"; fi
+    PASS_ROWS+=("$row")
+
+    if [ "$R_NEW" -gt 0 ]; then
+        NOTIFY_NAMES_NEW+=("$name")
+        NOTIFY_SRC_NEW=$((NOTIFY_SRC_NEW + 1))
+        NOTIFY_DEST="$destdir"
+    fi
+    if [ "$R_FAILED" -gt 0 ]; then
+        NOTIFY_NAMES_FAIL+=("$name")
+    fi
+    return 0
+}
+
+# ── Add flow ────────────────────────────────────────────────────────
+DERIVED_SLUG=""
+DERIVED_SUBDIR=""
+
+derive_source_fields() {   # $1=vtype $2=url; needs parsed probe globals
+    local vtype="$1" url="$2"
+    local name="$P_NAME" key="$P_KEY" base subdir title
+    if [ -z "$name" ]; then name="$url"; fi
+    if [ -n "$key" ]; then
+        base="$(slugify "$key")"
+    else
+        base="$(slugify "$name")"
+    fi
+    DERIVED_SLUG="$(unique_slug "$base")"
+    case "$vtype" in
+        playlist)
+            title="$(sanitize_component "${P_TITLE:-Playlist}")"
+            if [ -n "$P_OWNER" ]; then
+                subdir="$(sanitize_component "$P_OWNER")/${title}"
+            else
+                subdir="$title"
+            fi
+            ;;
+        *)
+            subdir="$(sanitize_component "$name")"
+            ;;
+    esac
+    DERIVED_SUBDIR="$subdir"
+}
+
+show_resolution_screen() {   # $1=vtype $2=subdir
+    printf 'Resolved : %s (%s · %s videos)\n' "${P_NAME:-unknown}" "$1" "$TOTAL_VALID"
+    printf 'Library  : %s/\n' "$(_pretty "$YTSYNC_VIDEOS_DIR/$2")"
+    case "$1" in
+        playlist) printf '          └── numbered: <NNN> - <title>.<ext>\n' ;;
+        *) printf '          └── flat videos: <title>.<ext>\n' ;;
+    esac
+}
+
+finish_add() {   # $1=vtype $2=url $3=confirm|explicit — probe already done
+    local vtype="$1" url="$2" mode="$3"
+    collect_entries
+    derive_source_fields "$vtype" "$url"
+    local slug="$DERIVED_SLUG" subdir="$DERIVED_SUBDIR"
+    local name="${subdir##*/}"
+
+    if registry_has_slug "$slug"; then
+        log "'$name' is already tracked — nothing to add (run 'pos media ytsync sync')"
+        return 0
+    fi
+
+    compute_new_list "$ARCHIVE_DIR/$slug.txt"
+    # mirror pass_prepare's counters so pass_execute's summary/digest are
+    # correct on the add path too (archive may hold ids from a previous
+    # tracking period — remove/re-add resume)
+    R_SIGNIN="$SIGNIN_COUNT"
+    R_PRESENT=$((TOTAL_VALID - NEW_TOTAL))
+    show_resolution_screen "$vtype" "$subdir"
+
+    if [ "$DRY_RUN" -eq 0 ]; then
+        if [ "$mode" = "confirm" ]; then
+            local ans=""
+            if ! read -rp "Start download? [Y/n] " ans </dev/tty; then
+                log "Cancelled — nothing changed"
+                return 0
+            fi
+            case "$ans" in
+                n | N | no | NO)
+                    log "Cancelled — nothing changed"
+                    return 0
+                    ;;
+            esac
+        fi
+        mkdir -p "$YTSYNC_STATE_DIR" "$ARCHIVE_DIR"
+        registry_add_line "$(printf '%s\x1f%s\x1f%s\x1f%s\x1f%s\x1f%s' \
+            "$slug" "$vtype" "$url" "$subdir" "${P_TITLE:-}" "$(date '+%Y-%m-%d %H:%M')")"
+    fi
+
+    S_SLUG="$slug"
+    S_TYPE="$vtype"
+    S_URL="$url"
+    S_SUBDIR="$subdir"
+    S_TITLE="${P_TITLE:-}"
+    if [ "$DRY_RUN" -eq 1 ]; then
+        log "DRY RUN — nothing will be downloaded"
+        print_dry_plan_for_current
+        return 0
+    fi
+    pass_execute
+    send_digest
+    return 0
+}
+
+require_tty() {
+    if [ ! -t 0 ]; then
+        printf "%s\n" "[!] ytSync needs a terminal for its prompt — use 'pos media ytsync sync' for unattended runs." >&2
+        return 1
+    fi
+    return 0
+}
+
+ASKED_URL=""
+ATTEMPT=1
+
+attempt_exhausted() {   # bumps ATTEMPT; rc 0 → exhausted (cancel), 1 → keep asking
+    ATTEMPT=$((ATTEMPT + 1))
+    [ "$ATTEMPT" -gt 3 ]
+}
+
+ask_url_interactive() {   # sets ASKED_URL; rc 1 = cancelled/EOF
+    ATTEMPT=1
+    ASKED_URL=""
+    local u prompt vtype
+    while :; do
+        if [ "$ATTEMPT" -eq 1 ]; then
+            prompt="Channel or playlist URL: "
+        else
+            prompt="Try again (${ATTEMPT} of 3), or press Enter to cancel: "
+        fi
+        u=""
+        if ! read -rp "$prompt" u </dev/tty; then
+            log "Cancelled — nothing changed"
+            return 1
+        fi
+        if [ -z "$u" ]; then
+            if attempt_exhausted; then
+                log "Cancelled — nothing changed"
+                return 1
+            fi
+            continue
+        fi
+        if ! is_youtube_url "$u"; then
+            warn "$BAD_URL_MSG"
+            if attempt_exhausted; then
+                log "Cancelled — nothing changed"
+                return 1
+            fi
+            continue
+        fi
+        vtype="$(classify_url "$u")"
+        if ! run_probe "$u"; then
+            if [ "$(probe_fail_reason)" = "notfound" ]; then
+                warn "source not found or private: $u"
+            else
+                warn "could not reach YouTube — check your connection and try again"
+            fi
+            if attempt_exhausted; then
+                log "Cancelled — nothing changed"
+                return 1
+            fi
+            continue
+        fi
+        if ! parse_probe; then
+            warn "unexpected yt-dlp probe output"
+            if attempt_exhausted; then
+                log "Cancelled — nothing changed"
+                return 1
+            fi
+            continue
+        fi
+        ASKED_URL="$u"
+        return 0
+    done
+}
+
+cmd_add() {
+    local url="${1:-}"
+    reset_globals
+    if [ -z "$url" ]; then
+        if ! require_tty; then exit 0; fi
+        if ! ask_url_interactive; then return 0; fi
+        url="$ASKED_URL"
+    fi
+    if ! is_youtube_url "$url"; then
+        warn "$BAD_URL_MSG"
+        exit 1
+    fi
+    if ! run_probe "$url"; then
+        if [ "$(probe_fail_reason)" = "notfound" ]; then
+            err "source not found or private: $url"
+        fi
+        warn "could not reach YouTube — check your connection and try again"
+        exit 1
+    fi
+    if ! parse_probe; then
+        err "could not parse yt-dlp probe output for: $url"
+    fi
+    local mode="explicit"
+    if [ -z "${1:-}" ]; then mode="confirm"; fi
+    finish_add "$(classify_url "$url")" "$url" "$mode"
+}
+
+# ── Sync flow ───────────────────────────────────────────────────────
+SYNC_LINES=()
+MATCHING_SLUGS=()
+
+resolve_sources() {   # $1=token-or-empty → SYNC_LINES[]; rc 0 ok / 1 none / 2 ambiguous
+    SYNC_LINES=()
+    MATCHING_SLUGS=()
+    local token="$1" line slug sub
+    if [ -z "$token" ]; then
+        mapfile -t SYNC_LINES < <(registry_entries)
+        if [ "${#SYNC_LINES[@]}" -eq 0 ]; then return 1; fi
+        return 0
+    fi
+    while IFS= read -r line; do
+        [ -n "$line" ] || continue
+        IFS=$'\x1f' read -r slug _ _ sub _ _ <<<"$line"
+        if [ "$token" = "$slug" ] || [ "$token" = "${sub##*/}" ]; then
+            SYNC_LINES+=("$line")
+            MATCHING_SLUGS+=("$slug")
+        fi
+    done < <(registry_entries)
+    if [ "${#SYNC_LINES[@]}" -eq 0 ]; then return 1; fi
+    if [ "${#SYNC_LINES[@]}" -gt 1 ]; then return 2; fi
+    return 0
+}
+
+run_sync_set() {   # iterates SYNC_LINES[]; roll-up + digest; rc 1 iff wholesale failure
+    if [ "$DRY_RUN" -eq 1 ]; then
+        log "DRY RUN — nothing will be downloaded"
+    fi
+    local line
+    for line in "${SYNC_LINES[@]}"; do
+        IFS=$'\x1f' read -r S_SLUG S_TYPE S_URL S_SUBDIR S_TITLE rest <<<"$line"
+        if pass_prepare; then
+            pass_execute
+        else
+            G_WHOLEFAIL=$((G_WHOLEFAIL + 1))
+            NOTIFY_NAMES_FAIL+=("${S_SUBDIR##*/}")
+            if [ "$DRY_RUN" -eq 0 ]; then
+                append_history_failed "${S_SUBDIR##*/}"
+            fi
+        fi
+    done
+    if [ "${#PASS_ROWS[@]}" -gt 1 ]; then
+        printf 'Sync summary\n'
+        local row
+        for row in "${PASS_ROWS[@]}"; do
+            printf '  %s\n' "$row"
+        done
+    fi
+    send_digest
+    if [ "$G_WHOLEFAIL" -gt 0 ]; then
+        return 1
+    fi
+    return 0
+}
+
+cmd_sync() {
+    local token="${1:-}"
+    reset_globals
+    local rs=0
+    resolve_sources "$token" || rs=$?
+    if [ "$rs" -eq 1 ]; then
+        if [ -z "$token" ]; then
+            log "nothing tracked yet — add a source with 'pos media ytsync add'"
+            return 0
+        fi
+        err "unknown source '${token}' — see 'pos media ytsync list'"
+    fi
+    if [ "$rs" -eq 2 ]; then
+        err "ambiguous '${token}' — candidates: $(join_comma MATCHING_SLUGS)"
+    fi
+    local src_rc=0
+    run_sync_set || src_rc=$?
+    return "$src_rc"
+}
+
+# ── List flow ───────────────────────────────────────────────────────
+cmd_list() {
+    local count
+    count="$(registry_count)"
+    if [ "$count" -eq 0 ]; then
+        log "nothing tracked yet — add a source with 'pos media ytsync add'"
+        return 0
+    fi
+    printf 'Tracked sources (%s)\n\n' "$count"
+    local wname=4 line slug stype surl ssub stitle sts rest
+    local dn dest vids last
+    local -a names=() types=() vids_last=() dests=()
+    while IFS= read -r line; do
+        [ -n "$line" ] || continue
+        IFS=$'\x1f' read -r slug stype surl ssub stitle sts rest <<<"$line"
+        dn="${ssub##*/}"
+        dest="$(_pretty "$YTSYNC_VIDEOS_DIR/$ssub")"
+        vids="$(archive_count "$slug")"
+        last="$(last_sync_of "$dn")"
+        last="${last:0:10}"
+        names+=("$dn")
+        types+=("$stype")
+        vids_last+=("${vids}|${last}")
+        dests+=("$dest")
+        if [ "${#dn}" -gt "$wname" ]; then wname="${#dn}"; fi
+    done < <(registry_entries)
+
+    printf '  %-*s  %-8s  %6s  %-10s  %s\n' "$wname" "NAME" "TYPE" "VIDEOS" "LAST SYNC" "DESTINATION"
+    local i n vl
+    for ((i = 0; i < ${#names[@]}; i++)); do
+        n="${names[$i]}"
+        vl="${vids_last[$i]}"
+        printf '  %-*s  %-8s  %6s  %-10s  %s\n' \
+            "$wname" "$n" "${types[$i]}" "${vl%%|*}" "${vl#*|}" "${dests[$i]}"
+    done
+    printf '\nState: %s (registry · archive/ · history.log)\n' "$(_pretty "$YTSYNC_STATE_DIR")"
+    return 0
+}
+
+# ── Remove flow ─────────────────────────────────────────────────────
+remove_by_line() {   # $1=registry line — drops tracking, keeps files AND archive
+    local line="$1" slug stype surl ssub stitle sts rest
+    IFS=$'\x1f' read -r slug stype surl ssub stitle sts rest <<<"$line"
+    local name="${ssub##*/}"
+    if [ "$DRY_RUN" -eq 1 ]; then
+        log "would stop tracking '${name}' — files and archive stay"
+        return 0
+    fi
+    registry_remove_slug "$slug"
+    ok "Stopped tracking '${name}' — files kept in $(_pretty "$YTSYNC_VIDEOS_DIR/$ssub")"
+    log "Archive kept — re-adding this source later resumes incrementally"
+    return 0
+}
+
+cmd_remove() {
+    local token="${1:-}"
+    if [ -z "$token" ]; then
+        err "usage: pos media ytsync remove <name>"
+    fi
+    reset_globals
+    local rs=0
+    resolve_sources "$token" || rs=$?
+    if [ "$rs" -eq 1 ]; then
+        err "unknown source '${token}' — see 'pos media ytsync list'"
+    fi
+    if [ "$rs" -eq 2 ]; then
+        err "ambiguous '${token}' — candidates: $(join_comma MATCHING_SLUGS)"
+    fi
+    remove_by_line "${SYNC_LINES[0]}"
+}
+
+# ── Interactive front door ──────────────────────────────────────────
+menu_render() {
+    {
+        printf '════════════════════════════════════════════\n'
+        printf '  ytSync — YouTube channel sync\n'
+        printf '════════════════════════════════════════════\n'
+        local lr suffix
+        lr="$(last_run_overall)"
+        suffix=""
+        if [ -n "$lr" ]; then suffix=" · last run ${lr}"; fi
+        printf '  1) Sync all channels now   (%s tracked%s)\n' "$(registry_count)" "$suffix"
+        printf '  2) Add a channel or playlist\n'
+        printf '  3) List channels\n'
+        printf '  4) Remove a channel\n'
+        printf '  0) Exit\n'
+        printf '--------------------------------------------\n'
+    } >&2
+}
+
+menu_remove_flow() {
+    local -a lines=() dnames=()
+    mapfile -t lines < <(registry_entries)
+    if [ "${#lines[@]}" -eq 0 ]; then
+        log "nothing tracked yet"
+        return 0
+    fi
+    local line slug stype surl ssub stitle sts rest i pick ans target rs=0
+    for line in "${lines[@]}"; do
+        IFS=$'\x1f' read -r slug stype surl ssub stitle sts rest <<<"$line"
+        dnames+=("${ssub##*/}")
+    done
+    for i in "${!dnames[@]}"; do
+        printf '  %s) %s\n' "$((i + 1))" "${dnames[$i]}" >&2
+    done
+    pick=""
+    if ! read -rp "Remove which channel? [1-${#dnames[@]}], 0=cancel " pick </dev/tty; then
+        log "Cancelled — nothing changed"
+        return 0
+    fi
+    case "$pick" in
+        0 | "" | q | Q)
+            log "Cancelled — nothing changed"
+            return 0
+            ;;
+    esac
+    if [[ ! "$pick" =~ ^[0-9]+$ ]] || [ "$pick" -lt 1 ] || [ "$pick" -gt "${#dnames[@]}" ]; then
+        warn "invalid choice: $pick"
+        return 0
+    fi
+    target="${dnames[$((pick - 1))]}"
+    ans=""
+    if ! read -rp "Stop tracking '${target}'? Files stay in ~/Videos. [y/N]: " ans </dev/tty; then
+        log "Cancelled — nothing changed"
+        return 0
+    fi
+    case "$ans" in
+        y | Y | yes | YES)
+            resolve_sources "$target" || rs=$?
+            if [ "$rs" -ne 0 ]; then
+                warn "could not uniquely resolve '${target}'"
+                return 0
+            fi
+            remove_by_line "${SYNC_LINES[0]}"
+            ;;
+        *)
+            log "Cancelled — nothing changed"
+            ;;
+    esac
+    return 0
+}
+
+interactive_empty_state() {   # zero sources → straight to the URL prompt
+    while :; do
+        if ! ask_url_interactive; then
+            return 0
+        fi
+        finish_add "$(classify_url "$ASKED_URL")" "$ASKED_URL" confirm
+    done
+}
+
+interactive_menu() {
+    if ! require_tty; then exit 0; fi
+    if [ "$(registry_count)" -eq 0 ]; then
+        interactive_empty_state
+        return 0
+    fi
+    local choice rs=0
+    while :; do
+        menu_render
+        choice=""
+        if ! read -rp "Choose: " choice </dev/tty; then
+            return 0
+        fi
+        case "$choice" in
+            1)
+                reset_globals
+                resolve_sources "" || rs=$?
+                if [ "$rs" -eq 0 ]; then
+                    run_sync_set || true
+                fi
+                rs=0
+                ;;
+            2)
+                reset_globals
+                if ask_url_interactive; then
+                    finish_add "$(classify_url "$ASKED_URL")" "$ASKED_URL" confirm
+                fi
+                ;;
+            3) cmd_list ;;
+            4) menu_remove_flow ;;
+            0 | q | Q) return 0 ;;
+            *) : ;;   # unknown choice → redraw
+        esac
+    done
+}
+
+# ── Argument dispatch ───────────────────────────────────────────────
+VERB=""
+TARGET=""
+while [ "$#" -gt 0 ]; do
+    case "$1" in
+        --dry-run) DRY_RUN=1 ;;
+        -h | --help) usage ;;
+        --*) err "unknown option: $1 (see 'pos media ytsync --help')" ;;
+        *)
+            if [ -z "$VERB" ]; then
+                VERB="$1"
+            elif [ -z "$TARGET" ]; then
+                TARGET="$1"
+            else
+                err "too many arguments: $* (see 'pos media ytsync --help')"
+            fi
+            ;;
+    esac
+    shift
+done
+
+if [ -z "$VERB" ]; then
+    if [ "$DRY_RUN" -eq 1 ]; then
+        printf "[!] use 'add --dry-run' or 'sync --dry-run'\n" >&2
+        exit 1
+    fi
+    interactive_menu
+    exit 0
+fi
+
+case "$VERB" in
+    add) cmd_add "$TARGET" ;;
+    sync) cmd_sync "$TARGET" ;;
+    list) cmd_list ;;
+    remove) cmd_remove "$TARGET" ;;
+    *) err "unknown command: $VERB (see 'pos media ytsync --help')" ;;
+esac
diff --git a/completions/pos.bash b/completions/pos.bash
index fee6e61..cb6ddb1 100644
--- a/completions/pos.bash
+++ b/completions/pos.bash
@@ -12,6 +12,7 @@ _pos_flags[entertainment-send]="--print --markdown"
 _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"
+_pos_flags[media-ytsync]="--dry-run"
 _pos_flags[network-checkport]="--tcp --udp --ping --no-banner --versions --timeout"
 _pos_flags[network-download]="--dir --out --split --seed --force --upload --gid --tmux"
 _pos_flags[network-hotspot]="--foreground"
@@ -28,11 +29,14 @@ _pos_subcmds[communication-scrcpy]="devices record tcpip connect push pull scree
 _pos_subcmds[communication-telegram-sender]="send test"
 _pos_subcmds[docker-compose]="ls installed up down restart logs update config"
 _pos_subcmds[docker-vbox]="create enter stop start rm ls"
+_pos_subcmds[media-ytsync]="add sync list remove"
 _pos_subcmds[network-download]="start stop status add torrent metalink list info files peers pause resume remove purge move limit set watch restart retry replace"
+_pos_subcmds[share-smb-client]="mount unmount list persist unpersist"
+_pos_subcmds[share-smb-server]="status share unshare list adduser deluser reload enable disable"
 _pos_subcmds[system-schedule]="run list config enable disable status migrate"
 # GEN:END possubcmds
 # GEN:START posconfigscopes
-declare -a _pos_config_scopes=(ai compose entertainment matrix notify scrcpy system telegram)
+declare -a _pos_config_scopes=(ai compose entertainment matrix notify scrcpy system telegram ytsync)
 # GEN:END posconfigscopes
 
 _pos() {
diff --git a/tools-docs/ytsync.md b/tools-docs/ytsync.md
new file mode 100644
index 0000000..c2a4918
--- /dev/null
+++ b/tools-docs/ytsync.md
@@ -0,0 +1,129 @@
+# `pos media ytsync` — implementation research notes
+
+Internal reference for maintainers touching `bin/pos-media-ytsync`. The user-facing
+docs live in `DOC/POS.md → media` and `DOC/howto/media.md`; the behavioral contract
+is `reportAgents/2026-08-22-designer-ytsync.md` + the Architect decisions D1–D9 in
+`reportAgents/2026-08-22-architect-ytsync.md`.
+
+## Probe mechanics
+
+One fast call per source per run:
+
+```
+yt-dlp --flat-playlist -J --no-warnings -- <url>
+```
+
+- `--flat-playlist` keeps entries as stubs, so cost is 1–2 HTTP round trips
+  regardless of library size (seconds even for 2000-video channels).
+- `-J` dumps a single JSON object. Parsed with `jq`:
+  - display name: `.channel // .uploader // .uploader_id // .title`
+  - owner (for playlist subdirs): `.channel // .uploader // .uploader_id` — no title
+    fallback (avoids `Playlist Title/Playlist Title` doubling when a playlist probe
+    has no channel fields)
+  - key (slug source): `.uploader_id // .channel_id // .id`
+  - entries: `.entries[] | (.id) + "\x1f" + (.title)`; a `?v=` URL returns a bare
+    video object with **no** `.entries`, handled as a one-entry list.
+- The new-list is computed BEFORE any download by diffing entry ids against
+  `archive/<slug>.txt` — exact `[n/N]` counts, exact dry-run plans, zero speculative
+  downloads.
+- Sign-in-skipped bucket: entries with an empty id OR titles starting with
+  `[Private` / `[Deleted` / `[Unavailable`. Reported as "N videos require sign-in —
+  skipped"; never counted as failures.
+
+### Why probes don't use spawn()
+
+`lib/common.sh spawn()` **exits the process on failure** and captures output until
+completion. ytsync needs recoverable probes (interactive add re-prompts ≤3×; sync
+must continue other sources after one bad probe) and never wraps the download batch
+(hours of silence behind a spinner). `_probe_run` mirrors spawn's OK/FAIL line UX but
+returns rc, and its braille spinner frames are emitted only on a TTY so no `\r`
+bytes ever reach the dispatcher's tee'd logs.
+
+## Classification (URL shape, deterministic)
+
+| URL contains | Type | Behavior |
+|---|---|---|
+| `list=` without `v=` | `playlist` | tracked source; files land as `<videos>/<owner>/<playlist>/<NNN> - <title>.<ext>` |
+| `v=` present (with or without `list=`) | `video` | single video, downloaded with `--no-playlist`; nobody backfills a 500-video playlist by pasting a watch link |
+| neither | `channel` | flat source; `<videos>/<channel>/<title>.<ext>` |
+
+## Download invocation (one yt-dlp call PER NEW VIDEO)
+
+```
+yt-dlp -f "bestvideo*+bestaudio/best"
+       --merge-output-format mp4        # parity with pos media mp4
+       --embed-metadata --embed-chapters --embed-thumbnail
+       --no-overwrites                  # parity; collisions become "exists, kept" warnings
+       --download-archive <state>/archive/<slug>.txt   # crash-safe per-video recording
+       --windows-filenames              # USB/Samba/TV-safe names
+       --trim-filenames 120             # headroom for the NNN prefix under 255-byte limits
+       --retries 3 --fragment-retries 3
+       [--no-playlist]                  # only for type=video sources
+       ${YTSYNC_EXTRA_ARGS}             # appended last — user override hatch
+       -o "<template>" "https://www.youtube.com/watch?v=<id>"
+```
+
+- Templates are COMPUTED from stored registry fields (`subdir`), never from yt-dlp
+  placeholders like `%(playlist_title)s` — a stored subdir cannot be NA and cannot
+  drift mid-library.
+- Playlist template gets a LITERAL zero-padded index injected by the tool (from the
+  probe's entry position), because standalone watch URLs have no live
+  `%(playlist_index)s`. Caveat: inserting a video mid-playlist shifts FUTURE
+  numbering; existing files are never renamed.
+- Deliberate divergences from mp4: no `--embed-subs --sub-langs all` (library bloat;
+  re-add per-source via `YTSYNC_EXTRA_ARGS`, appended-last wins); `--quiet
+  --no-warnings` plus `--progress` only on a TTY (yt-dlp auto-simplifies progress
+  when piped, keeping `\r` out of logs).
+- Sequential downloads; batching is the listed future optimization (accepted v1
+  cost: one extra extraction round trip per video).
+
+## State layout (machine-owned, outside ~/Videos)
+
+```
+${YTSYNC_STATE_DIR:-~/.local/share/linux_post_install/ytsync}/
+├── registry            # \x1f-delimited: slug⇥type⇥url⇥subdir⇥playlist_title⇥added_ts
+├── archive/<slug>.txt  # native yt-dlp archive format ("<extractor> <id>"), one per source
+└── history.log         # append-only: "<YYYY-MM-DD HH:MM> · <name> · N new · M skipped · K failed"
+```
+
+- `slug`: `[a-z0-9][a-z0-9_-]*`, derived from probed uploader_id/handle; numeric
+  `-2` suffix on collision, checking registry slugs only.
+- Registry/archive writes are atomic (mktemp inside the state dir + mv).
+- `remove` drops only the registry line. Keeping the orphaned archive makes a future
+  re-add of the same source an incremental resume instead of a full re-download that
+  would collide with existing files under `--no-overwrites`.
+- History grammar note: a wholesale probe failure appends `<date> · <name> · FAILED
+  (probe)` instead of the numeric triple — the pass did not complete, and faking
+  zeros would hide it from `grep`.
+
+## Edge cases
+
+- **Mid-playlist inserts** shift future numbering only (see above).
+- **Title renames on YouTube** never rename local files — the archive is keyed by
+  video id; local files are immutable once written.
+- **Same-title collision** (`--no-overwrites` refusal): stderr is matched for
+  "already been downloaded" → `[!] exists, kept: <file>`, counted into the
+  "already present" tally of the summary (the fixed summary grammar has three
+  buckets; tools-docs records this folding).
+- **Disk full (ENOSPC)**: stderr matched for "No space left on device"/Errno 28 →
+  prominent warning, that source stops mid-run (unfetched videos simply stay "new"
+  next run since the archive was untouched), other channels continue.
+- **Per-video generic failure**: `[!] unavailable: <title>` + first 3 stderr lines,
+  continue, counted as failed. Per-video failures never flip the exit code; rc 1 is
+  reserved for missing deps, invalid explicit URL, unknown/ambiguous `<name>`, or
+  ≥1 requested source failing wholesale during sync.
+- **Slug stability**: the slug derives from the probed `uploader_id`. If YouTube
+  ever changes that id for a channel, a re-add computes a different slug whose
+  archive starts empty → existing files would be "re-downloaded", hitting
+  `--no-overwrites` and spamming `exists, kept` warnings. Manual mitigation if it
+  ever bites: rename the old `archive/<old-slug>.txt` to the new slug before
+  syncing. Accepted v1 limitation (Architect §Remaining uncertainty #4).
+
+## Testing seams
+
+- `YTSYNC_STATE_DIR`, `YTSYNC_VIDEOS_DIR` — every written path honors them
+  (written `VAR="${VAR:-default}"`). Fake `yt-dlp` arrives via stub PATH emitting
+  canned `-J` JSON; fake notify via a stubbed sender appending to `sends.log`.
+- Interactive reads all come from `/dev/tty` (NOT stdin), so the tool is NOT in
+  `bin/pos`'s INTERACTIVE_CMDS and dispatched runs keep full tee logging; non-tty
+  interactive entry points print the guard line and exit 0.