fix(using-yt-tools): add pipx-shim probe + anti-recreate-venv guard v0.3.1

Bug surfaced in field: agent in another session probed only legacy venv
location, found empty (post-pipx-migration), then took install-hint
verbatim and started recreating the venv we just deleted — destructive
cleanup paradox.

Three fixes:
- Add `~/.local/bin/yt-frames.exe` as known location #2 in probe chain
  (between PATH and legacy venv). pipx is now recommended install per
  yt-tools README; shim lives there.
- Rewrite install-hint to pipx-first (pip install --user pipx; pipx
  ensurepath; pipx install --editable ~/projects/.common/lib/yt-tools).
- Add explicit 'NOT to do' rule: do NOT recreate deleted venv if
  pipx-shim exists. Empty .venv/ + present pipx-shim means PATH issue
  (run pipx ensurepath + restart shell), not missing package.

Failure-modes table updated to reflect three-step probe chain and the
recreate-venv anti-pattern.

skills/using-yt-tools/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: using-yt-tools
-version: 0.3.0
+version: 0.3.1
 description: Two flows for YouTube content. **Iterative-watch** (summary/exploration): transcript with [mm:ss] anchors → pick moments → extract frames. **Targeted-frames** (specific timestamps): extract frames directly, no transcript. Triggers: "что в ролике", "о чём видео", "video summary", "youtube transcript", "покажи кадр на N", или любой youtube.com URL. CLI в `~/projects/.common/lib/yt-tools/`. YouTube-only; для Vimeo/Twitch/local — другие тулзы.
 ---
 
@@ -30,13 +30,22 @@ Iterative-watching YouTube для агента: clean-markdown транскри
 
 Скил ничего не предполагает про активный PATH. **Step 0 каждого flow** — резолв путей для `yt-frames`/`yt-transcript` и `ffmpeg` (+ `yt-dlp`, поставляется в том же venv). Если резолвится через fallback — используй PATH-prepend в каждом вызове (см. Invoke pattern ниже). Abort'ить **только** если бинаря нет ни на PATH, ни в известных install-локациях.
 
-**yt-tools CLI** (один venv даёт все четыре: `yt-frames`, `yt-transcript`, `yt-watch`, `yt-tools`; туда же ставится `yt-dlp`):
+**yt-tools CLI** (любая из локаций даёт все четыре: `yt-frames`, `yt-transcript`, `yt-watch`, `yt-tools` + бонусом `yt-dlp`):
 
-1. PATH: `Get-Command yt-frames` (pwsh) / `command -v yt-frames` (bash)
+1. **PATH**: `Get-Command yt-frames` (pwsh) / `command -v yt-frames` (bash)
-2. Project-local venv:
+2. **pipx-shim** (recommended install — см. install-hint ниже):
+   - Windows: `~/.local/bin/yt-frames.exe`
+   - Linux/macOS: `~/.local/bin/yt-frames`
+3. **Legacy project-venv** (для машин до миграции на pipx):
    - Windows: `~/projects/.common/lib/yt-tools/.venv/Scripts/yt-frames.exe`
    - Linux/macOS: `~/projects/.common/lib/yt-tools/.venv/bin/yt-frames`
-3. Если ни PATH, ни venv — install hint: `python -m venv ~/projects/.common/lib/yt-tools/.venv && ~/projects/.common/lib/yt-tools/.venv/{Scripts,bin}/pip install -e ~/projects/.common/lib/yt-tools/`; стоп.
+4. **Если ни одна локация не сработала** — install hint, потом стоп. **НЕ воссоздавай старый venv** даже если пустой `.venv/` отсутствует — это означает машина либо на pipx (probe #2 должен был сработать; если нет — у юзера `pipx ensurepath` не пройден, скажи запустить), либо вообще без yt-tools (свежая инсталляция per README):
+   ```
+   python -m pip install --user pipx
+   python -m pipx ensurepath              # one-time; restart shell after
+   python -m pipx install --editable ~/projects/.common/lib/yt-tools
+   ```
+   Полный README — `~/projects/.common/lib/yt-tools/README.md`.
 
 **ffmpeg**:
 
@@ -51,17 +60,19 @@ Iterative-watching YouTube для агента: clean-markdown транскри
 
 `yt-frames` сам спавнит `yt-dlp` и `ffmpeg` через `subprocess.run([..., "ffmpeg", ...])` — full-path к самому `yt-frames.exe` **не хватит**, нужен PATH-prepend, чтобы child процессы тоже их видели.
 
+`$YTBIN` подставляй той локацией, где нашёл `yt-frames` на шаге probe (`~/.local/bin/` если pipx-shim, или `.venv/Scripts/`|`/bin/` если legacy venv).
+
 ```bash
 # bash / git-bash — после резолва через fallback
 FFDIR=$(dirname "$(ls ~/AppData/Local/Microsoft/WinGet/Packages/Gyan.FFmpeg_*/ffmpeg-*-full_build/bin/ffmpeg.exe 2>/dev/null | head -1)")
-YTBIN=~/projects/.common/lib/yt-tools/.venv/Scripts  # /bin на Linux/macOS
+YTBIN=~/.local/bin                       # pipx-shim (recommended); legacy: ~/projects/.common/lib/yt-tools/.venv/{Scripts,bin}
 PATH="$FFDIR:$YTBIN:$PATH" yt-frames <url> --timestamps 1:23,4:56
 ```
 
 ```powershell
 # pwsh — glob по плавающей версии ffmpeg
 $ff = (Get-ChildItem "$HOME\AppData\Local\Microsoft\WinGet\Packages\Gyan.FFmpeg_*\ffmpeg-*-full_build\bin\ffmpeg.exe" -ErrorAction SilentlyContinue | Select-Object -First 1).DirectoryName
-$ytbin = "$HOME\projects\.common\lib\yt-tools\.venv\Scripts"
+$ytbin = "$HOME\.local\bin"              # pipx-shim (recommended); legacy: "$HOME\projects\.common\lib\yt-tools\.venv\Scripts"
 $env:PATH = "$ff;$ytbin;" + $env:PATH
 yt-frames <url> --timestamps 1:23,4:56
 ```
@@ -115,8 +126,8 @@ Warnings и errors уходят в stderr (`warning: …`, `error: …`); stdout
 
 | Symptom | Cause | Action |
 |---|---|---|
-| `yt-transcript` / `yt-frames` not on PATH | yt-tools pkg не pip-installed **либо** venv создан, но не на PATH | Прогнать резолв per Prerequisites → Locating binaries. Abort только если и venv-локация пуста — тогда install-hint, стоп |
+| `yt-transcript` / `yt-frames` not on PATH | Не yt-tools отсутствуют, а PATH сессии не подхватил pipx-shim dir или venv не активен | Прогнать **всю** probe-цепочку (PATH → `~/.local/bin/` → legacy venv). Abort и install-hint **только** если ни одна локация ничего не дала. **НЕ воссоздавай venv по install-hint, если pipx-shim есть** — это означает PATH-проблема, а не отсутствие пакета (см. What NOT to do) |
-| `yt-dlp not found on PATH` (от child процесса) | `yt-dlp` есть в venv, но PATH-prepend не собран | Пересобери PATH-prepend (Prerequisites → Invoke pattern); `yt-dlp` ставится тем же `pip install -e` что и `yt-frames` |
+| `yt-dlp not found on PATH` (от child процесса) | `yt-dlp` есть в той же install-локации, что и `yt-frames`, но PATH-prepend не собран | Пересобери PATH-prepend (Prerequisites → Invoke pattern) — `$YTBIN` указать на ту же папку где нашёлся `yt-frames` |
 | `ffmpeg not found on PATH` (от child процесса) | ffmpeg установлен, но в winget-кэше/Homebrew/etc., не на PATH сессии | Прогнать ffmpeg-резолв per Prerequisites, prepend в PATH. Abort только если ни одна локация не нашла бинаря — install per ОС. **Не** требовать restart CC session — резолв решает |
 | `yt-dlp source download failed (exit N) \| stderr: …` | Network / private / age-gated / region-locked / malformed URL | Выведи captured stderr verbatim; не retry |
 | `yt-dlp --dump-json failed` | То же, но на metadata step | То же |
@@ -137,6 +148,7 @@ Cache hygiene: `yt-tools cache list` показывает usage, `yt-tools cache
 
 ## What NOT to do
 
+- **Не воссоздавай удалённый venv по install-hint.** Если `~/projects/.common/lib/yt-tools/.venv/` не существует — **сначала** проверь `~/.local/bin/yt-frames.exe` (pipx-shim). Пустой `.venv/` ≠ «yt-tools не установлен»: машина могла мигрировать на pipx и старый venv осознанно снести. Install-hint в скиле — для **полностью свежей** машины (без pipx, без venv). Воссоздание venv поверх работающего pipx-инсталла — destructive cleanup paradox (тратит ~200MB+ и создаёт две параллельные инсталляции). Если pipx-shim существует, но `Get-Command yt-frames` пуст — нужен `pipx ensurepath` + restart shell, не новый venv.
 - **Не запускай Flow A когда юзер уже дал таймкоды.** «Посмотри 1:23 и 4:56» → сразу Flow B. Fetching transcript first — чистая трата.
 - **Не bulk-extract «на всякий случай».** Flow A берёт кадры из транскрипта, Flow B — из явного user input. Никогда `--mode interval --interval 5s` «to be safe».
 - **Не используй `yt-watch` как default Flow A renderer.** `yt-watch` комбинирует transcript + scene-frames в один doc — тяжелее (требует ffmpeg scene-detect pass на source.mp4). Бери только когда юзер хочет один self-contained document.