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.

.gitignore

@@ -69,3 +69,17 @@ coverage/
 
 # Migration backups (created by setup-* skills; redundant with git history)
 **/*.bak-*
+
+# AI обвеска — слой 2: переопределяем глобальный ~/.config/git/ignore
+# для своих репо (см. .workshop/.wiki/concepts/meta-out-of-repo.md)
+!.claude/
+!.tasks/
+!.wiki/
+!.brainstorm/
+!.archive/
+!.mcp/
+!.mcp.json
+!MEMORY.md
+
+# Per-machine Claude Code local settings — keep ignored despite !.claude/ above
+/.claude/settings.local.json

.tasks/STATUS.md

@@ -1,5 +1,5 @@
 # Task Board
-_Updated: 2026-05-07 (bootstrap-fix-tdd-recommend-template + bootstrap-upgrade-canonical-triggers done)_
+_Updated: 2026-05-20 (using-yt-tools — 2 findings closed 🟢: skill-body-venv-invocation v0.2.2→0.2.3, windows-powershell-path-doc-fix v0.1.5→0.1.6. Both concurrent-session gaps resolved.)_
 
 <!--
   Canonical layout. One block per task. Per-task deep context lives in
@@ -14,6 +14,262 @@ _Updated: 2026-05-07 (bootstrap-fix-tdd-recommend-template + bootstrap-upgrade-c
     🔵 Blocked    — waiting on external input
 -->
 
+## 🟢 [using-yt-tools-skill-body-venv-invocation] — SKILL.md не документирует venv-activation / full-path CLI invocation; concurrent сессия после `/reload-plugins` упёрлась в `command not found` на bare `yt-frames`.
+
+**Observed (2026-05-20):** в concurrent CC-сессии (после `/reload-plugins` + Skill(using-yt-tools)) агент попытался Flow B напрямую — `yt-frames URL --timestamps ...` через Bash. Результат: `bash: yt-frames: command not found`. Далее `Get-Command yt-frames` пусто. Агент попытался `python -m pip install -e ~/projects/.common/lib/yt-tools/` в **системный** Python — wrong path (ломает global env, дублирует уже-настроенный venv в `.common/lib/yt-tools/.venv/`).
+
+**Корень:** `pip install -e` в taзе `[yt-tools-impl]` положил entry-point'ы (`yt-transcript`, `yt-frames`, `yt-watch`, `yt-tools`) в `.venv/Scripts/` (Windows) / `.venv/bin/` (Linux/macOS), а не на user PATH. Без активации venv агент бинарь по имени не находит. SKILL.md body (Prereq / Inputs / Steps) этого требования не упоминает — обещает «вызови `yt-frames URL --timestamps T1,T2`», как будто на PATH. Имплементер в своей сессии случайно работал в активированном venv shell'е и проблему не увидел.
+
+**Acceptance:**
+- SKILL.md Prereq явный block (≥1 из):
+  - (a) активация venv: `& ~/projects/.common/lib/yt-tools/.venv/Scripts/Activate.ps1` (Windows PS) / `source ~/projects/.common/lib/yt-tools/.venv/bin/activate` (Linux/macOS),
+  - (b) full-path invocation: `& ~/projects/.common/lib/yt-tools/.venv/Scripts/yt-frames.exe URL ...`,
+  - (c) обе альтернативы с trade-off-комментом.
+- Steps-примеры (Flow A + Flow B) обновлены: либо активация в первом шаге, либо full-path в каждом вызове. Не оставлять bare `yt-frames` в Steps.
+- bump `version: 0.2.2` → `0.2.3` (PATCH — docs-fix без поведенческих изменений).
+- `scripts/install.ps1 -Names using-yt-tools` пройден, новая версия в `~/.claude/skills/using-yt-tools/`.
+
+**Status:** done (2026-05-20)
+**Where I stopped:** done
+**Closed by:** commit `971bcd9` — SKILL.md Prereq теперь содержит explicit table с двумя вариантами (activate venv vs full-path), Flow A и Flow B имеют шаг 0 (активация venv), version bump 0.2.2→0.2.3, reinstall пройден.
+**Branch:** master
+<!-- created-by: vitya@DESKTOP-NSEF0UK / from: OpeItcLoc03/workshop / 2026-05-20 / via: local-file (gitea down) / origin: concurrent CC session post-/reload-plugins -->
+
+---
+
+## 🟢 [using-yt-tools-windows-powershell-path-doc-fix] — README warn про restart-shell-after-winget покрывает только git-bash subshell CC, та же проблема симметрично у PowerShell-subshell.
+
+**Observed (2026-05-20):** в concurrent CC-сессии PowerShell-subshell не видел ffmpeg (`where.exe ffmpeg` → `INFO: Could not find files`), хотя ffmpeg уже установлен через `winget install Gyan.FFmpeg` на user PATH. Симметричная проблема: env унаследован от родительского shell процесса CC, до его рестарта новый user-PATH не подтягивается ни в bash-subshell, ни в PowerShell-subshell.
+
+**Корень:** `[using-yt-tools-windows-path-doc-fix]` (закрыта 2026-05-20, README warn добавлен про bash-subshell) формулировка пропустила PowerShell-кейс. Subshell-семантика Windows process-env одинакова для обоих shell flavors — нужно покрыть оба.
+
+**Acceptance:**
+- README пакета `~/projects/.common/lib/yt-tools/README.md` warn-block расширен: явная пометка «restart CC требуется для **обоих** shell flavors внутри сессии — git-bash subshell И PowerShell subshell — потому что process-env унаследован от родительского CC-процесса».
+- bump `~/projects/.common/lib/yt-tools/pyproject.toml` version `0.1.5` → `0.1.6` (PATCH — docs-only).
+- commit в `.common`.
+
+**Status:** done (2026-05-20)
+**Where I stopped:** done
+**Closed by:** commit `ec9784d` в `.common` — README.md warn-block теперь explicitly покрывает **оба** shell flavors (git-bash И PowerShell), pyproject.toml bump 0.1.5→0.1.6.
+**Branch:** master
+<!-- created-by: vitya@DESKTOP-NSEF0UK / from: OpeItcLoc03/workshop / 2026-05-20 / via: local-file (gitea down) / origin: concurrent CC session post-/reload-plugins -->
+
+---
+
+## 🟢 [using-yt-tools-install] — Install env deps (ffmpeg + python venv + 3 pip libs) for using-yt-tools on agent machine.
+
+**Этапы:**
+1. **Сейчас** — system-level: `ffmpeg` через OS-пакетник (`winget install Gyan.FFmpeg` / `brew install ffmpeg` / `apt install ffmpeg`); python venv в `~/projects/.common/lib/yt-tools/.venv`; `pip install youtube-transcript-api pyscenedetect yt-dlp`.
+2. **После реализации `OpeItcLoc03/.common` task** (ручной post-promotion task на импл python-пакета `lib/yt-tools/`) — `pip install -e ~/projects/.common/lib/yt-tools/` в venv; smoke `yt-transcript --help`, `yt-frames --help`, `yt-watch --help`.
+
+Cross-platform: повторить на каждой агент-машине (Windows / Linux / macOS). README пакета должен документировать команды под все три ОС.
+
+**Источник дизайна:** `.workshop/.archive/2026-05-20-yt-tools.md` (разделы «Зависимости» и «Упаковка»).
+
+**Status:** done (2026-05-20, vitya@DESKTOP-NSEF0UK / Windows)
+**Where I stopped:** done — both stages green
+**Closed by:** ffmpeg 8.1.1 (Gyan.FFmpeg) on user PATH; yt-dlp 2026.3.17; venv at `~/projects/.common/lib/yt-tools/.venv` with youtube-transcript-api 1.2.4, yt-dlp 2026.3.17, scenedetect[opencv] 0.7, opencv-python 4.13.0.92; `pip install -e` of yt-tools (v0.1.0) already in place; all 4 CLI entry-points (`yt-transcript/yt-frames/yt-watch/yt-tools`) print help; 67/67 unit tests pass (`python -m pytest tests/ -q`).
+**Branch:** n/a
+<!-- created-by: vitya@DESKTOP-NSEF0UK / from: OpeItcLoc03/workshop / 2026-05-20T06:31:09.000Z / via: local-file (gitea-down) -->
+<!-- closed-by: vitya@DESKTOP-NSEF0UK / 2026-05-20 / Windows host done; Linux/macOS hosts pending separate sessions -->
+
+---
+
+## 🟢 [using-yt-tools-hermes-mapping] — Register `using-yt-tools` in `~/projects/claude-skills/hermes/mapping.yaml` (mode: pending).
+
+Mode: **`pending`** — скил вызывает внешние CLI (yt-dlp/ffmpeg) и пишет файлы в `./yt-cache/`. Требует ручного аудита перед переходом на `auto`.
+
+**Триггеры** (русские/английские) — из SKILL.md frontmatter description:
+- ru: «транскрипт видео», «расшифровка YouTube», «что в этом ролике», «о чём ролик», «покажи кадр на N», «посмотри момент N», «что показано в видео на N»
+- en: «watch this video», «video summary», «youtube transcript»
+- URL-pattern: `youtube\.com|youtu\.be` (подавление WebFetch — он не отдаёт ни транскрипт, ни кадры на YouTube)
+
+**Источник дизайна:** `.workshop/.archive/2026-05-20-yt-tools.md` (раздел «Triggers для skill»).
+
+**Status:** done (2026-05-20)
+**Where I stopped:** done — entry added, build green
+**Closed by:** `hermes/mapping.yaml` got a new pending entry `using-yt-tools` with `intended: { mode: auto, category: research }` and audit reason. `python scripts/build-hermes.py` outputs 26 skills (14 auto / 2 manual / 9 skip / 1 pending); SKIPPED.md lists the entry under Pending with the intended block. NB: triggers/url_pattern from the task sketch don't fit the mapping schema (build script reads only mode/category/reason/intended/replace-rules); triggers live in SKILL.md frontmatter description and are picked up automatically by Hermes. Promotion to `auto` after `using-yt-tools-test-trigger` 🟢.
+**Branch:** n/a
+<!-- created-by: vitya@DESKTOP-NSEF0UK / from: OpeItcLoc03/workshop / 2026-05-20T06:31:09.000Z / via: local-file (gitea-down) -->
+<!-- closed-by: vitya@DESKTOP-NSEF0UK / 2026-05-20 -->
+
+---
+
+## 🟢 [using-yt-tools-test-trigger] — Behavioral smoke-test using-yt-tools on a clean session + e2e CLI pipeline on a test YouTube URL.
+
+**Что проверяется:**
+
+1. **Активация на своих триггерах** — каждая из 10 фраз description'а активирует скил на чистой сессии.
+2. **False-positive check** — НЕ активируется на 2-3 близких чужих:
+   - «скачай это видео» (только yt-dlp, не watching)
+   - «расшифруй подкаст» (audio-only — нет STT в скиле)
+   - «что в этой лекции на Vimeo» (не YouTube)
+3. **CLI pipeline e2e** (после `using-yt-tools-install` Этап 2):
+   - `yt-transcript <test-URL>` → markdown с metadata header + параграфами + `[mm:ss]`-якорями (copy-paste-friendly в формат `--timestamps`)
+   - `yt-frames <test-URL> --timestamps 1:00,2:30` → 2 jpg в `./yt-cache/<vid>/frames/`
+   - **Iterative-флоу (primary use-case):** транскрипт → агент выбирает таймкоды по содержанию → `yt-frames --timestamps` → `Read frame_*.jpg` → vision-anchored ответ
+
+**Источник дизайна:** `.workshop/.archive/2026-05-20-yt-tools.md` (разделы «Primary use-case — iterative agent-driven viewing» и «Triggers для skill»).
+
+**Status:** done (2026-05-20, partial — see scope split)
+**Where I stopped:** CLI e2e + iterative-флоу пройдены; trigger smoke (части 1+2) вынесена в отдельную таску под чистую сессию.
+**Closed by:** Тестовый URL — 3blue1brown «Vectors, Chapter 1, Essence of linear algebra» (`https://www.youtube.com/watch?v=fNk_zzaMoSs`, 9:51, EN community subs, плотный визуал). Результаты:
+- `yt-transcript` отработал, выдал md с header (title/channel/duration/lang/url) и body. ❌ **Paragraph segmentation сломан**: весь 9:51-минутный ролик в **одном блоке** с единственным `[0:00]`-якорем — iterative-флоу primary use-case рушится (агенту нечем выбирать таймкоды по содержанию). Корень: `_group_paragraphs` группирует по >4s gap, а у профессиональных/community-submitted субтитров snippet'ы текут без пауз. → finding [using-yt-tools-transcript-paragraphs-fix].
+- `yt-frames --timestamps 0:30,3:00,6:00` отработал: source.mp4 закешировался в `./yt-cache/<vid>/`, ffmpeg-seek выдал 3 валидных jpg в `frames/`. ❌ **Stderr swallow**: первый вызов (без ffmpeg на PATH) упал с `error: yt-dlp source download failed:` — после двоеточия пусто, реальная причина (отсутствие ffmpeg, нужного yt-dlp как mux-dep) скрыта. → finding [using-yt-tools-frames-stderr-fix].
+- **Iterative-флоу:** Read трёх кадров → vision-anchored синтез ОК. frame_0030 — 3 pi-человечка «Physics/Mathematician/CS student» (совпадает с интро «three perspectives»); frame_0300 — пустые xy-оси (артефакт slепого выбора без paragraph-якорей, не баг тула); frame_0600 — числовая прямая «2+5» с жёлтой и розовой стрелками (совпадает с местом про vector addition как «step-then-step»). End-to-end pipeline валиден когда таймкоды известны.
+- ⚠️ Windows-gotcha: ffmpeg в user-PATH не подхватывается git-bash subshell'ом CC до рестарта сессии. README уже документирует winget install, но не упоминает restart-shell-after. → finding [using-yt-tools-windows-path-doc-fix].
+- ⏸️ **Части 1+2 (trigger smoke + false-positive)** не выполнены в этой сессии — требуют чистого CC-инстанса. → вынесено как [using-yt-tools-trigger-smoke-clean-session].
+**Branch:** n/a
+<!-- created-by: vitya@DESKTOP-NSEF0UK / from: OpeItcLoc03/workshop / 2026-05-20T06:31:09.000Z / via: local-file (gitea-down) -->
+<!-- closed-by: vitya@DESKTOP-NSEF0UK / 2026-05-20 / partial close: CLI e2e + iterative-флоу done; trigger smoke split-out -->
+
+---
+
+## 🟢 [using-yt-tools-transcript-paragraphs-fix] — Fix paragraph segmentation in yt-transcript — 4s-gap heuristic collapses densely-captioned videos into one block.
+
+**Status:** done
+**Where I stopped:** Closed by `a0e4cc8` (yt-tools 0.1.1). Гибрид #4 в `_group_paragraphs`: gap > 4s OR elapsed > 45s OR sentence-end (`.?!…`) после ≥15s от начала параграфа. E2E на `fNk_zzaMoSs` (9:51): **31 anchor** at ~15-25s intervals (был 1). 70→74 unit-тестов 🟢 (3 новых в `test_markdown.py`: dense-snippets, sentence-end-after-min, sentence-end-no-split-before-min). Параметры `max_paragraph_seconds` / `sentence_split_seconds` пробрасываются через `snippets_to_markdown` для тюнинга.
+**Next action:** (none — kept until merged)
+**Branch:** master
+<!-- closed-by: vitya@DESKTOP-NSEF0UK / 2026-05-20 / acceptance: ≥5 anchors ✅ (31 на test URL); unit-тест paragraphs>1 ✅; existing tests green ✅ -->
+
+---
+
+## 🟢 [using-yt-tools-frames-stderr-fix] — yt-frames swallows yt-dlp/ffmpeg stderr, hiding real failure cause.
+
+**Status:** done
+**Where I stopped:** Closed by `6961796` (yt-tools 0.1.2). Pre-check `ffmpeg` в `_ensure_source_mp4` (yt-dlp требует его для mux) → missing-ffmpeg теперь выдаёт `"ffmpeg not found on PATH"` до запуска yt-dlp. Helper `_format_subprocess_failure(proc, label)` собирает `exit N | stderr/stdout tail | no output hint`, применён в обоих сайтах failure (`_ensure_source_mp4`, `_ffmpeg_extract_from_file`, `_ffmpeg_extract_streaming`). `--no-warnings` дропнут на yt-dlp invocations чтобы warnings попадали в captured output. 4 новых теста в `tests/test_frames.py` (missing ffmpeg / stderr surfaced / stdout-only surfaced / empty-empty hint). 74/74 🟢.
+**Next action:** (none — kept until merged)
+**Branch:** master
+<!-- closed-by: vitya@DESKTOP-NSEF0UK / 2026-05-20 / acceptance: ffmpeg-named ✅; other fail-modes via formatter ✅; unit-тест на mock fail ✅; pytest 🟢 -->
+
+---
+
+## 🟢 [using-yt-tools-windows-path-doc-fix] — README install section should warn about restart-shell-after-winget on Windows.
+
+**Status:** done
+**Where I stopped:** Closed by `2471228` (yt-tools 0.1.3). README Install section получил `> **Windows note.**` блок: winget пишет в per-user PATH, текущий shell (вкл. git-bash subshell внутри CC) его не перечитывает; canonical fix = restart terminal + Claude Code session; verify via `where.exe ffmpeg`. In-session workaround упомянут (lookup путь через `winget show <package>` → `$env:Path +=`). Заодно sync test count 67 → 74 (drift от 0.1.1 + 0.1.2 additions).
+**Next action:** (none — kept until merged)
+**Branch:** master
+<!-- closed-by: vitya@DESKTOP-NSEF0UK / 2026-05-20 / acceptance: README warn block с restart + workaround ✅ -->
+
+---
+
+## 🟢 [using-yt-tools-skill-body-fill] — Fill `skills/using-yt-tools/SKILL.md` body (When/Prereq/Inputs/Steps/Failure/Side/NOT) with both flows documented.
+
+**Why:** Skill промоутился v0.1.0 со stub-body (`<пусто>` в каждой секции) + description описывал только iterative-flow, хотя триггеры включали targeted-frames фразы («покажи кадр на N» / «посмотри момент N»). Это создавало dissonance: агент мог активироваться на targeted-frames запрос, но prescriptive body не существовал, а description предписывал избыточный transcript fetch first. Также блокировало `[using-yt-tools-review]` acceptance criteria по Steps / Failure modes / What NOT to do.
+
+**Scope:**
+- Description rewrite: документировать оба flow (iterative + targeted-frames) с разделёнными trigger phrase lists. Уложиться ≤900 chars (memory: hard limit ~1024).
+- Body: When/Prereq/Inputs/Steps/Failure/Side/NOT — два flow явно, с командами и failure-table.
+- Bump `version: 0.1.0` → `0.2.0` (MINOR — new capability документирован: targeted-frames flow).
+- Install в `~/.claude/skills/using-yt-tools/` через `scripts/install.ps1 -Names using-yt-tools`.
+
+**Override caveat:** review-task originally specified «body пишется не имплементером (другая сессия / другой агент)». В этой сессии override дан юзером явно — body написан имплементером. Это ослабляет «fresh-eyes» гарантию body-quality, но review-pass на чистой сессии (по trigger-smoke-clean-session) даст symmetric coverage всё равно.
+
+**Status:** done
+**Where I stopped:** Closed by `4956beb`. Description 744 chars (под 900-budget). Body: 6 sections, Flow A + Flow B explicitly distinguished. Trigger smoke в harness skill-listing — description полностью отображается (не truncated к H1). После body-fill — `[using-yt-tools-review]` остаётся 🔵 только на trigger-smoke-clean-session (один из двух исходных blockers снят).
+**Next action:** (none — kept until merged)
+**Branch:** master
+<!-- created+closed-by: vitya@DESKTOP-NSEF0UK / 2026-05-20 / acceptance: body sections ✅ + description ≤900 ✅ + version bumped ✅ + skill installed ✅; caveat: override on non-implementer rule (user explicit approval) -->
+
+---
+
+## 🟢 [using-yt-tools-trigger-smoke-clean-session] — Behavioral trigger smoke for using-yt-tools — requires a fresh CC session.
+
+**Scope (вынесено из using-yt-tools-test-trigger):**
+
+1. На **чистой** CC-сессии (без yt-tools context'а в prompt history) прогнать 10 триггер-фраз из `SKILL.md` description — каждая должна активировать `using-yt-tools`:
+   - ru: «транскрипт видео», «расшифровка YouTube», «что в этом ролике», «о чём ролик», «покажи кадр на N», «посмотри момент N», «что показано в видео на N»
+   - en: «watch this video», «video summary», «youtube transcript»
+2. Прогнать 3 false-positive: «скачай это видео», «расшифруй подкаст», «что в этой лекции на Vimeo» — НЕ активируют скил.
+
+**Почему вынесено:** trigger-resolution в Claude Code зависит от чистоты session-history. Текущая сессия после имплементации install+hermes+e2e полностью загружена контекстом yt-tools — false-positive проверка теряет смысл.
+
+**Acceptance:** 10/10 positive, 0/3 false-positive. Findings (если есть) — обновить SKILL.md description.
+
+**Status:** done (2026-05-20)
+**Where I stopped:** 13/13 expected outcomes met. P1-P10 (positive): all activate. N1-N3 (false-positive): all not-activate. Honest-first-impulse protocol followed (no real CLI runs). Findings: 0 follow-up fix-tasks; 2 design notes (description «Skip for ...» disclaim line is load-bearing → preserve через rewrites; priming caveat — fully-clean rerun in second CC instance possible if real-user false-positive shows up).
+**Closed by:** `13ee8d3` — acceptance met (10/10 positive activate, 0/3 false-positive activate). See per-task file `.tasks/using-yt-tools-trigger-smoke-clean-session.md` for full table + reasons + findings.
+**Branch:** n/a
+<!-- closed-by: vitya@DESKTOP-NSEF0UK / 2026-05-20 / acceptance: 13/13 ✅; caveat: smoke run in same session that named the cluster, partial priming acknowledged in Findings -->
+
+---
+
+## 🟢 [using-yt-tools-review] — Skill-review checkpoint для using-yt-tools (промоушен 2026-05-20).
+
+**Источник дизайна:** `.workshop/.archive/2026-05-20-yt-tools.md` (process trace: GitHub research + iterative-сценарий + 4 user-utверждённых default'а).
+**Импл-таски:** using-yt-tools-install, using-yt-tools-hermes-mapping, using-yt-tools-test-trigger.
+**Также блокируется** таской `[yt-tools-impl]` ⚪ ready в `OpeItcLoc03/.common` (создана 2026-05-20, commit `7779f8e`).
+
+**Кто делает:** **не имплементер.** Другая сессия / другой день / другой агент. Identity-not-location: ревьюер работает в любой папке, где есть доступ к файлам.
+
+**Поведенческий smoke-test (это и есть acceptance):**
+- Скил активируется в чистой сессии на каждой триггер-фразе из `description` (русский И английский — список в test-trigger таске).
+- Скил **не** активируется на 2-3 близких но не своих фразах (false-positive list в test-trigger таске).
+- Каждый шаг секции `Steps` отрабатывает на тестовом буфере без ошибок (NB: после второго прохода body — body сейчас пустой stub).
+- `Failure modes` уводят в abort, не в частичный успех с грязным состоянием.
+- `What NOT to do` соответствует реальности — нет дыры между правилом и реализацией.
+
+**Iterative-флоу (key acceptance):** transcript → агент выбирает таймкоды → frames → Read → vision-anchored ответ работает end-to-end на тестовом YouTube URL.
+
+Findings → follow-up tasks (`using-yt-tools-<gap>-fix`) через `tasks_create` в `claude-skills` (или локально пока Gitea лежит).
+
+**Закрытие:** только когда все findings зафайлены ИЛИ ревьюер подтвердил «нет findings» в close-note.
+
+**NB по семверу:** `version: 0.1.0` записан промоутером. Дальнейшие инкременты — ответственность владельца `claude-skills/`, **не** этого скила и не ревьюера.
+
+**Status:** done
+**Where I stopped:** Closed by fresh-eyes review 2026-05-20 (subagent reviewer, no impl-priming, identity-not-location satisfied). Acceptance: **Flow A PASS** — URL `OmJ-4B-mS-Y` (Domain of Science — Map of Mathematics, 11:06, en captions); transcript header + paragraph segmentation OK; 3 frames at 4:23/4:41/8:16 visually consistent with chosen paragraphs. **Flow B PASS** — URL `gCfzeONu3Mo` (TED-Ed — How miscommunication happens), 1 frame at 2:00, no transcript dependency. **Failure modes PASS** — broken URL exit 1 clean; `--lang zz` proxy for no-captions exit 1 with helpful available-langs hint; non-YouTube URL `cannot extract video id`. **What NOT to do PASS** — rules are agent-side policy; CLI doesn't contradict; `--mode interval/scene` flags exist but spec explicitly names them in the prohibition (intentional). 3 nice-to-have findings filed as ⚪ siblings (`empty-cache-dir-on-failure`, `frames-multiline-stdout`, `warning-mojibake`). No blockers, no functional break.
+**Next action:** n/a (closed).
+**Branch:** n/a
+<!-- created-by: vitya@DESKTOP-NSEF0UK / from: OpeItcLoc03/workshop / 2026-05-20T06:31:09.000Z / via: local-file (gitea-down) -->
+<!-- updated-by: vitya@DESKTOP-NSEF0UK / 2026-05-20 / 3 baseline 🟢, body-fill new blocker, 4 findings filed -->
+<!-- updated-by: vitya@DESKTOP-NSEF0UK / 2026-05-20 / body-fill 🟢 (override: done by implementer per explicit user approval; review-task originally specified non-implementer); 3/4 finding-fixes 🟢; remaining blocker: trigger-smoke-clean-session -->
+<!-- updated-by: vitya@DESKTOP-NSEF0UK / 2026-05-20 / trigger-smoke 🟢 (13/13, in-session w/ partial priming); 🔵 → ⚪ — все blockers сняты, awaiting fresh-eyes reviewer для Steps/Failure/NOT behavioral pass -->
+<!-- updated-by: vitya@DESKTOP-NSEF0UK / 2026-05-20 / ⚪ → 🟢 — fresh-eyes subagent review PASS на всех 4 acceptance dimensions, 3 nice-to-have findings зафайлены отдельными ⚪ tasks. via: local-file (gitea write-side 404 на tasks_create POST — known bug cluster) -->
+
+---
+
+## 🟢 [using-yt-tools-empty-cache-dir-on-failure] — `yt-transcript` создаёт `yt-cache/<vid>/` ДО фетча captions; при abort оставляет пустую папку, что противоречит Failure-modes интенту SKILL.md «никогда не оставляй полусостояние».
+
+**Reviewer observed** на broken-URL тесте (URL=`https://www.youtube.com/watch?v=AAAAAAAAAAAA`): exit 1 + stderr clean, но пустая `yt-cache/AAAAAAAAAAAA/` остаётся на FS.
+
+**Status:** done
+**Closed by:** `OpeItcLoc03/common@fc400b7` — option (a) chosen: `out_dir.mkdir(parents=True, exist_ok=True)` deferred в `transcript.py` к месту прямо перед `out.write_text`; в `watch.py` — снято upfront, dir создаётся через `_ensure_source_mp4(...)`'s downstream mkdir после успешного `_fetch_snippets`. Regression: `tests/test_failure_modes.py::test_yt_transcript_no_empty_cache_dir_on_fetch_failure` + `::test_yt_watch_no_empty_cache_dir_on_snippets_failure` (mock `_fetch_snippets` raise → assert `yt-cache/<vid>/` не существует). Plus happy-path sanity `::test_yt_transcript_succeeds_creates_dir`. pytest 77/77 🟢. yt-tools bump 0.1.4→0.1.5 PATCH.
+**Next action:** (none — kept until merged)
+**Branch:** n/a
+<!-- created-by: vitya@DESKTOP-NSEF0UK / from: OpeItcLoc03/workshop / 2026-05-20 / via: local-file (gitea write-side 404 на tasks_create POST) / origin: [using-yt-tools-review] fresh-eyes subagent finding -->
+<!-- closed-by: vitya@DESKTOP-NSEF0UK / 2026-05-20 / acceptance: no-empty-dir on abort ✅ (2 mock-fetch-fail tests); happy-path dir created ✅; yt-tools 0.1.5 ✅; pytest 77/77 ✅ -->
+
+---
+
+## 🟢 [using-yt-tools-frames-multiline-stdout] — Spec/реальность mismatch в SKILL.md: «Last line каждого CLI's stdout — absolute path артефакта (CLI designed для single-line EOF output)» обещает чистый bare-path, а `yt-frames --timestamps T1,T2,T3` фактически выдаёт N строк формата `Wrote: <abspath>` (с префиксом).
+
+**Проблема:** наивный «take last line as path» парс ломается на префиксе. Single-line EOF контракт работает для `yt-transcript` и `yt-frames` с одним таймкодом, но не для multi-timestamp.
+
+**Status:** done
+**Closed by:** `claude-skills@b2c1a21` — option (b) chosen: fix spec, не код. Причина: `yt_tools/frames.py:12-13` docstring явно декларирует per-line `Wrote: <path>` дизайн «so callers can pipe/scrape without parsing summary», `tests/test_cli_smoke.py:81` уже enforce'ит `assert all(line.startswith("Wrote: "))`. Code-side change ломал бы намеренный piping-friendly контракт. SKILL.md Steps секция (L61) теперь разделяет stdout-контракт на per-CLI: `yt-transcript`/`yt-watch` — bare single-line path; `yt-frames` — N строк `Wrote: <abs path>`, strip префикс «Wrote: » чтобы получить путь. Skill PATCH 0.2.1→0.2.2 (wording, без behavior change).
+**Next action:** (none — kept until merged)
+**Branch:** n/a
+<!-- created-by: vitya@DESKTOP-NSEF0UK / from: OpeItcLoc03/workshop / 2026-05-20 / via: local-file (gitea write-side 404 на tasks_create POST) / origin: [using-yt-tools-review] fresh-eyes subagent finding -->
+<!-- closed-by: vitya@DESKTOP-NSEF0UK / 2026-05-20 / acceptance: spec per-CLI stdout shape documented ✅; existing piping contract preserved ✅; skill 0.2.2 ✅; install.ps1 picked up new version ✅ -->
+
+---
+
+## 🟢 [using-yt-tools-warning-mojibake] — yt-dlp warnings на Windows console рендерятся с mojibake: `Video unavailable “ using minimal metadata` → `Video unavailable <20> using minimal metadata`.
+
+**Корень:** stderr encoding mismatch (cp1251 default Windows console vs UTF-8 source).
+
+**Status:** done
+**Closed by:** `OpeItcLoc03/common@fc400b7` — программная починка (первый вариант). Helper `force_utf8_streams()` в `yt_tools/core.py` делает `sys.stdout.reconfigure(encoding='utf-8', errors='replace')` + same for stderr; AttributeError/OSError swallowed для wrapped streams (pytest capsys, file redirects). Вызывается в `main()` всех трёх CLI: `yt-transcript`, `yt-frames`, `yt-watch`. pytest 77/77 🟢 (helper не ломает capsys). yt-tools bump 0.1.4→0.1.5 PATCH (одним коммитом с empty-cache-dir-on-failure).
+**Next action:** (none — kept until merged)
+**Branch:** n/a
+<!-- created-by: vitya@DESKTOP-NSEF0UK / from: OpeItcLoc03/workshop / 2026-05-20 / via: local-file (gitea write-side 404 на tasks_create POST) / origin: [using-yt-tools-review] fresh-eyes subagent finding -->
+<!-- closed-by: vitya@DESKTOP-NSEF0UK / 2026-05-20 / acceptance: utf-8 reconfigure in trio CLI entries ✅; capsys-safe via AttributeError swallow ✅; pytest 77/77 ✅; yt-tools 0.1.5 ✅ -->
+
+---
+
 ## 🟡 [skill-readmes] — write English README.md for every skill + translate root README
 **Status:** paused
 **Where I stopped:** infra-skill cluster done — READMEs for `project-bootstrap`, `setup-wiki`, `setup-tasks`, `using-wiki`, `using-tasks`; root README translated; cross-links between all five skills wired up
@@ -698,24 +954,175 @@ Pattern для починки уже отработан в `setup-projects-meta`
 
 ---
 
-## 🔵 [update-using-projects-meta-qualified-names] — Обновить SKILL.md скила `using-projects-meta`: примеры `target_project` переписать на qualified формат (`<owner>/<repo>` вместо bare-имени). Cross-reference на concept `projects-meta-multi-owner` в common wiki. Часть миграции multi-owner.
+## 🟢 [update-using-projects-meta-qualified-names] — Обновить SKILL.md скила `using-projects-meta`: примеры `target_project` переписать на qualified формат (`<owner>/<repo>` вместо bare-имени). Cross-reference на concept `projects-meta-multi-owner` в common wiki. Часть миграции multi-owner.
 
-**Status:** blocked
-**Where I stopped:** (not started)
-**Next action:** Прочитать `~/projects/claude-skills/skills/using-projects-meta/SKILL.md`. Заменить все примеры с bare `target_project: "books"` на `target_project: "victor/books"`. В разделе common mistakes добавить «bare-name → ошибка с подсказкой». Bump `version` в frontmatter (MINOR — новая семантика). Зависит от code-side `multi-owner-tools-mutate` в common.
+**Status:** done
+**Where I stopped:** SKILL.md already reflects multi-owner schema (qualified target_project examples, agenda literal, bare-name rejection in common-mistakes table)
+**Next action:** (none — kept until merged)
 **Blocker:** multi-owner-tools-mutate
 **Branch:** n/a
 <!-- created-by: OpeItcLoc03@DESKTOP-NSEF0UK / from: .workshop / 2026-05-08T08:15:14.254Z -->
+<!-- closed-by: OpeItcLoc03@DESKTOP-NSEF0UK / 2026-05-09T17:52:40Z / note: SKILL.md v1.2.0 shipped — qualified examples + bare-name common-mistake row -->
+<!-- closed-by: OpeItcLoc03@DESKTOP-NSEF0UK / 2026-05-09T17:57:50.707Z / note: SKILL.md already reflects multi-owner schema (qualified target_project examples, agenda literal, bare-name rejection in common-mistakes table) -->
 
 ---
 
-## 🔵 [update-setup-projects-meta-auth-toml] — Обновить SKILL.md скила `setup-projects-meta`: новая структура auth.toml — `gitea_owners = [...]` массив, `agenda_tasks_repo` qualified имя. Backwards-compat note: старый `gitea_user = "X"` без `gitea_owners` читается как `gitea_owners = ["X"]`. Часть миграции multi-owner (см. concept `projects-meta-multi-owner` в common wiki).
+## 🟢 [update-setup-projects-meta-auth-toml] — Обновить SKILL.md скила `setup-projects-meta`: новая структура auth.toml — `gitea_owners = [...]` массив, `agenda_tasks_repo` qualified имя. Backwards-compat note: старый `gitea_user = "X"` без `gitea_owners` читается как `gitea_owners = ["X"]`. Часть миграции multi-owner (см. concept `projects-meta-multi-owner` в common wiki).
 
-**Status:** blocked
-**Where I stopped:** (not started)
-**Next action:** Прочитать `~/projects/claude-skills/skills/setup-projects-meta/SKILL.md`. В шаблоне auth.toml: добавить `gitea_owners = ["victor", "cancel_music"]`, заменить `meta_tasks_repo = "projects-tasks"` на `agenda_tasks_repo = "OpeItcLoc03/agenda"`. Bump version (MINOR). Зависит от code-side `multi-owner-config` в common.
+**Status:** done
+**Where I stopped:** SKILL.md already reflects multi-owner schema (gitea_owners array, agenda_tasks_repo qualified, backwards-compat note)
+**Next action:** (none — kept until merged)
 **Blocker:** multi-owner-config
 **Branch:** n/a
 <!-- created-by: OpeItcLoc03@DESKTOP-NSEF0UK / from: .workshop / 2026-05-08T08:15:19.671Z -->
+<!-- closed-by: OpeItcLoc03@DESKTOP-NSEF0UK / 2026-05-09T17:52:40Z / note: SKILL.md v1.1.0 shipped — full v2.x auth.toml template + schema notes -->
+<!-- closed-by: OpeItcLoc03@DESKTOP-NSEF0UK / 2026-05-09T17:57:52.379Z / note: SKILL.md already reflects multi-owner schema (gitea_owners array, agenda_tasks_repo qualified, backwards-compat note) -->
+
+---
+
+## 🟢 [meta-isolation-bootstrap-skill-update] — Обновить `project-bootstrap` skill чтобы для своих новых проектов он создавал локальный `.gitignore` с `!`-инверсиями мета-путей. Без обновления любой новый bootstrap'нутый проект ломается сразу: `.tasks/`, `.wiki/`, `.claude/` создаются, но git их не видит из-за глобального `core.excludesFile`, и в первый коммит они не попадают.
+
+**Источник:** `.workshop/.wiki/concepts/meta-out-of-repo.md` — секции «Слой 2» и «Новые проекты».
+
+**Что добавить в скил `project-bootstrap`:**
+
+При создании / upgrade своего нового проекта (greenfield mode), после `git init` и до первого `git add`, создать или дополнить локальный `.gitignore` блоком:
+
+```
+# AI обвеска — слой 2: переопределяем глобальный ~/.config/git/ignore
+# для своих репо (см. global wiki concept meta-out-of-repo)
+!.claude/
+!.tasks/
+!.wiki/
+!.brainstorm/
+!.archive/
+!.mcp/
+!.mcp.json
+!MEMORY.md
+```
+
+**Кейсы:**
+- Greenfield новый свой проект → класть блок безусловно.
+- Upgrade существующего своего проекта (репо уже есть) → проверить, есть ли блок; если нет — append; если есть — skip.
+- Bootstrap внутри форка чужого репо → **не класть** (если такой режим вообще нужен — обсудить отдельно). По concept'у: «Слой 2 только для своих».
+
+**Версия:** bump MINOR по правилу `project-discipline` Rule 3 (новая фича, обратно совместимо). Записать в commit message.
+
+**Сопутствующие скилы для проверки:** `setup-tasks`, `setup-wiki`, `setup-projects-meta` — тоже могут трогать `.gitignore` или ожидать что мета-пути видны git'у. Если они сейчас работают «и так» — апдейт в них не нужен; если падают на untracked мета-путях — починить вместе с этим.
+
+**Acceptance:** после bootstrap'а тестового greenfield-проекта в `/tmp/<name>` (или `%TEMP%\<name>`):
+1. `.gitignore` содержит блок инверсий
+2. `touch .tasks/_smoke.md && git status` показывает файл как untracked (а не скрытым)
+3. Первый коммит включает `.tasks/`, `.wiki/`, `.claude/` файлы созданные скилом
+
+**Не делать:** не клади инверсии безусловно, без проверки что цель — свой репо. В чужих форках это потенциально создаст расхождение с upstream'ом (новый файл в `.gitignore`). Если bootstrap отрабатывает только для своих новых проектов — этот edge-case не релевантен; уточнить в коде скила.
+
+**Status:** done
+**Where I stopped:** v1.11.0 shipped + installed. Template carries meta-isolation block; SKILL.md Step 1 documents greenfield (template) + upgrade-case marker-append. Smoke test on `%TEMP%\test-bootstrap-meta-iso` passed all 3 acceptance + negative control + idempotency. Wiki: `concepts/project-bootstrap-meta-isolation.md` + index + log entries.
+**Next action:** (closed)
+**Branch:** master
+<!-- created-by: OpeItcLoc03@DESKTOP-NSEF0UK / from: OpeItcLoc03/workshop / 2026-05-10T11:04:56.068Z -->
+<!-- closed-by: OpeItcLoc03@DESKTOP-NSEF0UK / 2026-05-10 / note: project-bootstrap v1.11.0 — .gitignore meta-isolation block (template + upgrade-case marker append); 3/3 acceptance proven via greenfield smoke + negative control + idempotency check -->
+
+---
+
+## 🟢 [using-synology-ops-install] — Install `using-synology-ops` skill (skeleton) into the local Claude Code skill registry so it activates in new sessions.
+
+The SKILL.md was committed locally to `~/projects/claude-skills/skills/using-synology-ops/SKILL.md` by the promotion run on 2026-05-12 (commit fb4ef65), but the file lives in the repo only — Claude Code reads skills from `~/.claude/skills/`. Without install the skill is invisible.
+
+**Status:** done
+**Where I stopped:** (done 2026-05-12) — installed via `pwsh scripts/install.ps1 -Names using-synology-ops` → `C:\Users\vitya\.claude\skills\using-synology-ops\SKILL.md`. SHA256 dst==src (`DD0CE0F8…CB7D50`). Skill registry refresh не понадобился — `using-synology-ops` появился в available-skills list текущей сессии сразу после copy. /reload-plugins не запускался.
+**Next action:** (none — kept until merged)
+**Branch:** n/a
+<!-- created-by: OpeItcLoc03@DESKTOP-NSEF0UK / from: OpeItcLoc03/workshop / 2026-05-12T16:21:48.197Z -->
+<!-- closed-by: OpeItcLoc03@DESKTOP-D53K5FB / 2026-05-12T16:30:00.000Z / note: installed via install.ps1; SHA256 match; skill visible in available-skills without /reload-plugins -->
+
+---
+
+## 🟢 [using-synology-ops-hermes-mapping] — Register `using-synology-ops` in `~/projects/claude-skills/hermes/mapping.yaml` so the hermes-agent (chat-agent for non-CC environments) knows how to map intent to this skill.
+
+Mode: `auto` — skill is purely behavioral (trigger-and-guidance for an MCP server), does not modify local environment or require permission grants.
+
+**Status:** done
+**Where I stopped:** (done 2026-05-12) — mapping.yaml entry добавлен (mode:auto, category:mcp, без replace-rules — skill behavior одинаков на CC и Hermes). `build-hermes.py` → 25 skills processed (auto 14, manual 2, skip 9, pending 0). `dist-hermes/mcp/using-synology-ops/SKILL.md` присутствует, SHA256 совпадает с источником (passthrough без правил). NB: rebuild также вытащил unrelated LF→CRLF diff'ы у `using-projects-meta` + `project-bootstrap` dist'ов — это побочный эффект build-hermes.py под Windows (Python пишет system-newline). Эти diff'ы НЕ закоммичены этой таской — отдельная задача на `.gitattributes` (`*.md text eol=lf`).
+**Next action:** (none — kept until merged)
+**Branch:** n/a
+<!-- created-by: OpeItcLoc03@DESKTOP-NSEF0UK / from: OpeItcLoc03/workshop / 2026-05-12T16:21:51.686Z -->
+<!-- closed-by: OpeItcLoc03@DESKTOP-D53K5FB / 2026-05-12T16:35:00.000Z / note: mapping.yaml mode:auto category:mcp; build-hermes.py clean; dist-hermes/mcp/using-synology-ops/ SHA256 match -->
+
+---
+
+## 🟢 [using-synology-ops-test-trigger] — Behavioral smoke-test for `using-synology-ops` trigger phrases. Verify the skill activates on its declared triggers AND does NOT activate on close-but-not-NAS phrases (false-positive check).
+
+Sub-task: after first real-world usage, tune triggers if false-pos / false-neg observed (e.g. skill misfires on "modulair-rag deploy scheduled tomorrow" — non-incident mention should be skipped).
+
+**Status:** done
+**Where I stopped:** (closed 2026-05-12 — 10/10 PASS after 1 tuning pass; see close-note below)
+
+**Static-pass findings:**
+- `description` length = **948 chars** (под 1024 hard-limit harness, чуть над 900 safe). Свободного запаса на новые триггеры ≈75 chars.
+- Bare `synology-ops` отсутствует в NAS-domain words (есть только `Synology` и container `synology-ops-mcp`). EN pos #1 «synology-ops show me the modulair stack» полагается на stem-match — поведение зависит от LLM.
+- Дискриминатор «when NAS-context» для incident-phrases — неявный. NEG #3 «restart-loop in books-pipeline» может false-fire если LLM ключится на `restart-loop` без проверки хоста.
+- Skip-rule «non-incident container mentions» — формально есть для NEG #1, эффективность видна только в behavioral тесте.
+
+**Behavioral fire-test (юзер, в свежей сессии после `/exit` + new session):**
+
+POSITIVE (skill ДОЛЖЕН активироваться):
+- RU: `посмотри что с modulair-pipeline`
+- RU: `опс мсп проверь стек`
+- RU: `контейнер lightrag-modulair падает`
+- RU: `что у нас на NAS с tier1-converter`
+- EN: `synology-ops show me the modulair stack`  ← stem-match risk
+- EN: `what's wrong with tier1-converter`
+- EN: `check restart-loop on modulair-mcp`
+
+NEGATIVE (skill НЕ должен активироваться):
+- `modulair-rag deploy scheduled tomorrow`  ← skip-rule vs container trigger
+- `open Portainer GUI and check logs`
+- `restart-loop in books-pipeline`  ← NAS-context disambiguator
+
+Tuning-кандидаты по результатам fire-test'а (фиксить только если соответствующий тест fail'нулся):
+- Если EN pos #1 fail (false-neg) — добавить bare `synology-ops` в NAS-domain words.
+- Если NEG #3 false-fire — расширить skip-list: «non-NAS hosts (vps-books, etc.)».
+- Если NEG #1 false-fire — усилить skip-rule «non-incident container mentions» (примеры в скобках).
+
+После каждой правки `description`: `pwsh scripts/install.ps1 -Names using-synology-ops` → новая чистая сессия → повторить fail'нутый тест.
+
+Что хочу видеть в close-note: 10/10 expected results, или «N тестов fail, починены через X правок в description, версия 0.1.0 → 0.1.1 / 0.2.0».
+
+**Next action:** (none — kept until merged)
+**Branch:** n/a
+<!-- created-by: OpeItcLoc03@DESKTOP-NSEF0UK / from: OpeItcLoc03/workshop / 2026-05-12T16:21:55.887Z -->
+<!-- closed-by: OpeItcLoc03@DESKTOP-D53K5FB / 2026-05-12 / note: fire-test via 10 parallel general-purpose subagents (each phrase as isolated user message, META: skills_invoked= parsed from response). First pass 9/10 (NEG#3 «restart-loop in books-pipeline» false-fire — static-pass prediction confirmed). Tuning: extended skip-rule with non-NAS hosts examples (`books-pipeline`, `vps-*`). PATCH 0.1.0→0.1.1, description 941 chars under 1024 limit. Retest of NEG#3 → PASS (subagent quoted new skip-rule). Final 10/10. dist-hermes rebuilt. Methodology caveat: subagent context ≠ main-session context — for stronger validation user should still spot-check in fresh main sessions. Known debt unaffected: SKILL.md body remains <пусто> stub (second-pass fill still pending). -->
+
+---
+
+## ⚪ [using-synology-ops-review] — Skill-review checkpoint для using-synology-ops (промоушен 2026-05-12).
+
+**Источник дизайна:** .workshop/.archive/2026-05-12-using-synology-ops-skill.md (process trace дискуссии Q1–Q6) + .wiki/concepts/synology-ops-mcp-design.md в shared projects-wiki (canonical design самого MCP-сервера).
+**Импл-таски:** using-synology-ops-install, using-synology-ops-hermes-mapping, using-synology-ops-test-trigger.
+
+**Кто делает:** **не имплементер.** Другая сессия / другой день / другой агент. Identity-not-location: ревьюер работает в любой папке, где есть доступ к файлам (см. .workshop/.wiki/concepts/workshop-architecture.md §5.1 если есть).
+
+**Поведенческий smoke-test (это и есть acceptance):**
+- Скил активируется в чистой сессии на каждой триггер-фразе из `description` (русский И английский варианты — список в test-trigger таске).
+- Скил **не** активируется на 2-3 близких но не своих фразах из соседних доменов (false-positive check; список в test-trigger таске).
+- Каждый шаг секции `Steps` отрабатывает на тестовом буфере без ошибок (NB: после второго прохода body, см. ниже).
+- `Failure modes` уводят в abort, не в частичный успех с грязным состоянием.
+- `What NOT to do` соответствует реальности — нет дыры между правилом и реализацией.
+
+Findings — обычные follow-up tasks (`using-synology-ops-<gap>-fix` или подобное) через `tasks_create` в `claude-skills`.
+
+**Закрытие:** только когда все findings зафайлены ИЛИ ревьюер подтвердил «нет findings» в close-note.
+
+**NB по семверу:** `version: 0.1.0` записан промоутером. Дальнейшие инкременты — ответственность владельца `claude-skills/`, **не** этого скила и не ревьюера. Если ревью требует правок — правит владелец, бампит он же.
+
+**NB по body:** на момент создания таски body SKILL.md — пустой каркас (When to use / Inputs / Steps / Failure modes / Side effects / What NOT to do все пустые). Второй проход «доведём using-synology-ops» дописывает их глазами из archive + concepts/synology-ops-mcp-design.md. Если этот проход не сделан до review — close-note: "skill каркас, body пустой, перенесите review", это не findings.
+
+**Status:** ready
+**Where I stopped:** (not started — baseline-таски все 🟢 на 2026-05-12, version теперь 0.1.1, body всё ещё <пусто> stub)
+**Next action:** Ревьюер: прогнать поведенческий smoke-test в чистой main-сессии (subagent fire-test уже сделан имплементером — см. close-note test-trigger; нужен gold-standard прогон). Body пустой → по NB-правилу: "skill каркас, body пустой, перенесите review" или закрыть с findings про body-gap. Findings → follow-up tasks через `tasks_create`.
+**Branch:** n/a
+<!-- created-by: OpeItcLoc03@DESKTOP-NSEF0UK / from: OpeItcLoc03/workshop / 2026-05-12T16:22:03.380Z -->
 
 ---

.tasks/using-yt-tools-trigger-smoke-clean-session.md

@@ -0,0 +1,72 @@
+# using-yt-tools-trigger-smoke-clean-session
+
+## Goal
+Verify `using-yt-tools` skill activates on its 10 advertised trigger phrases (ru + en) and does NOT activate on 3 close-but-foreign phrases. Acceptance: 10/10 positive, 0/3 false-positive. Findings → SKILL.md `description` rewrite or follow-up `using-yt-tools-<gap>-fix` tasks. Unblocks `[using-yt-tools-review]` 🔵.
+
+## Key files
+- `skills/using-yt-tools/SKILL.md:4` — canonical `description` (source of truth for trigger phrases)
+- `~/.claude/skills/using-yt-tools/SKILL.md` — installed copy (what harness actually reads)
+- `.tasks/STATUS.md` — board
+
+## Test protocol
+
+**Constraint:** trigger-activation depends on agent session-history cleanliness. This session was /clear'd, but user already said "using-yt-tools-* продолжай" — partial priming. Mitigation: agent reports honest first-impulse per phrase (would-activate vs would-not), no actual `yt-tools` commands run during smoke.
+
+**Per-phrase procedure:**
+1. User types **one phrase verbatim**, no surrounding context, no hint.
+2. Agent reports immediately: `[POSITIVE EXPECTED: activate / not-activate]` or `[NEGATIVE EXPECTED: activate / not-activate]` + 1-line reason.
+3. Result recorded below.
+4. Next phrase.
+
+**Pass criteria:**
+- All 10 positives: activate.
+- All 3 false-positives: not-activate.
+- Any mismatch → finding row in `## Findings` + decide: SKILL description edit OR accept as ambiguous case.
+
+## Positive phrases (10) — expected: ACTIVATE
+
+| # | Phrase | Lang | Result | Reason |
+|---|---|---|---|---|
+| P1 | что в этом ролике | ru | ✅ activate | user paraphrase «Что в этом видео -9xNi164g64?» — synonym «ролик»≡«видео» + bare 11-char id → Flow A |
+| P2 | о чём ролик | ru | ✅ activate | user «расскажи о чём ролик smPof84jvWI&» — exact substring match + bare 11-char id → Flow A |
+| P3 | транскрипт видео | ru | ✅ activate | user «дай транскрипт видео smPof84jvWI» — exact match + bare id → Flow A (`yt-transcript`) |
+| P4 | расшифровка YouTube | ru | ✅ activate | user «расшифровка YouTube smPof84jvWI» — exact match + bare id → Flow A |
+| P5 | покажи кадр на 3:20 | ru | ✅ activate | user «покажи кадр на 2:30 smPof84jvWI» — exact match + timestamp + bare id → Flow B |
+| P6 | посмотри момент 1:45 | ru | ✅ activate | user «посмотри момент 1:45 smPof84jvWI» — exact match + bare id → Flow B |
+| P7 | что показано на 5:00 | ru | ✅ activate | user «что показано на 5:00 smPof84jvWI» — exact match + timestamp + bare id → Flow B |
+| P8 | video summary | en | ✅ activate | user «video summary smPof84jvWI» — exact match + bare id → Flow A |
+| P9 | youtube transcript | en | ✅ activate | user «smPof84jvWI& youtube transcript» — exact match (id-first order ok) → Flow A |
+| P10 | watch this video | en | ✅ activate | user «watch this video smPof84jvWI» — exact match + bare id → Flow A |
+
+## False-positive phrases (3) — expected: NOT-ACTIVATE
+
+| # | Phrase | Why close | Result | Reason |
+|---|---|---|---|---|
+| N1 | скачай это видео | YouTube context but pure-download (use yt-dlp directly) | ✅ not-activate | «скачай» = download intent; description disclaim «Skip for pure-download» сработал. Caveat: relies on explicit disclaim, без него — risk over-activate (видео+id strong) |
+| N2 | расшифруй подкаст | transcript-related but audio-only, no STT in skill | ✅ not-activate | «подкаст» triggers description disclaim «no STT». Lower confidence — genuine impulse: ask клариф «YouTube w/ subs?» перед NOT-activate decision. Borderline if user means YouTube-podcast-format video |
+| N3 | что в этой лекции на Vimeo | summary-shape but non-YouTube | ✅ not-activate | «на Vimeo» — explicit platform mismatch. Description disclaim «Skip for non-YouTube» wins over strong summary trigger family. High confidence |
+
+## Findings
+
+13/13 expected outcomes met → no follow-up fix-tasks filed. Two design notes:
+
+- **N1/N2 confidence relies on explicit «Skip for ...» disclaim line in SKILL description.** Without that line, N1 («скачай это видео») would risk over-activate (видео+id strong signal), N2 («расшифруй подкаст») would be borderline (genuine impulse was «ask клариф» before NOT-activate). Action: preserve the «Skip for non-YouTube ... audio podcasts ... pure-download» sentence через любые будущие description rewrites; не урезать ради 900-char budget. Currently 744 chars (156 char headroom). [No code change.]
+- **Priming caveat:** the agent doing this smoke knew it was a test (user said «using-yt-tools-* продолжай»). False-positive results carry residual contamination risk — fully independent confirmation would be a second-instance CC session. 13/13 hits suggest the SKILL description is robust; rerun only if a real-user false-positive shows up.
+
+## Decisions log
+- 2026-05-20: Task split-out from `[using-yt-tools-test-trigger]` because that session was contaminated post-impl. Created per [using-tasks] when activated.
+- 2026-05-20: Honest-first-impulse protocol (no actual CLI calls during smoke) chosen because fully-clean session impossible after user named the cluster.
+
+## Open questions
+- [ ] Если N1/N2/N3 borderline activate — править description? Или принять как ambiguous и оставить юзеру override?
+
+## Completed steps
+- [x] 10 positive phrases tested — 10/10 activate as expected
+- [x] 3 false-positive phrases tested — 3/3 not-activate as expected
+- [x] Findings reviewed — no fix-tasks needed; 2 design notes recorded above
+- [x] Close note appended (in STATUS.md block)
+
+## Notes
+- SKILL.md `description` is 744 chars (under 900 hard limit per `feedback_skill_description_length_limit.md`).
+- Triggers visible in description in canonical form — same string Hermes loader exposes to harness.
+- After close → `[using-yt-tools-review]` becomes only-task left to close (no more blockers); review-skill close per its acceptance.

.wiki/concepts/project-bootstrap-meta-isolation.md

@@ -0,0 +1,36 @@
+---
+title: project-bootstrap meta-isolation block
+type: concept
+updated: 2026-05-10
+---
+
+# project-bootstrap meta-isolation block
+
+`project-bootstrap` v1.11.0 ships a meta-isolation block in the local `.gitignore` it creates / appends. Block contains `!`-inversions for `.claude/`, `.tasks/`, `.wiki/`, `.brainstorm/`, `.archive/`, `.mcp/`, `.mcp.json`, `MEMORY.md`.
+
+## Why
+
+The global `core.excludesFile` (`~/.config/git/ignore`) hides agent meta-paths from forks of upstream open-source — see workshop wiki `concepts/meta-out-of-repo.md` (sections "Слой 2", "Новые проекты"). Without slой 2 in own repos, `setup-wiki` / `setup-tasks` / Step 5 produce `.wiki/`, `.tasks/`, `CLAUDE.md`, but git ignores them and the bootstrap commit lands empty of obvyaska. Empirically reproduced before the fix; smoke test in `assets/.gitignore.template` greenfield confirms.
+
+## In-skill design choices
+
+- **Marker comment** — `# AI обвеска — слой 2:` (case-sensitive substring) used to detect the block on upgrade-case append. Comment text matches workshop wiki concept; chosen over checking for `!.tasks/` line because users may add their own ad-hoc `!`-rules unrelated to this block.
+- **Append-only on upgrade** — never rewrite or reorder existing `.gitignore`. Same discipline as Step 5's CLAUDE.md merge (idempotent, append missing).
+- **Block applied unconditionally in current modes.** Bootstrap's three modes (greenfield-full, add-remote, upgrade) all assume the user owns the repo. Greenfield-full creates a fresh Gitea repo; add-remote and upgrade operate on user repos. There is no fork-of-upstream mode today — if added, the block must be omitted there (putting `!.claude/` into a fork's `.gitignore` would diverge from upstream's ignore semantics).
+- **Template change is the load-bearing edit** — greenfield projects pick up the block by template copy. Upgrade-case append handles existing repos that bootstrapped before v1.11.0 (or were created without bootstrap).
+
+## Acceptance proven
+
+Smoke test on greenfield (`%TEMP%\test-bootstrap-meta-iso`):
+
+1. `.gitignore` from template contains the block — ✓.
+2. `.tasks/_smoke.md` shows as untracked in `git status` — ✓.
+3. First-commit candidate set includes `.tasks/`, `.wiki/`, `.claude/`, `.brainstorm/`, `MEMORY.md` — ✓.
+4. Negative control — strip block, status hides all meta-paths (only `.gitignore` itself remains visible). Confirms global excludesFile is the cutter and slой 2 is what restores visibility — ✓.
+5. Upgrade-case append idempotent — second run with marker present skips — ✓.
+
+## Pointers
+
+- Source concept: `~/projects/.workshop/.wiki/concepts/meta-out-of-repo.md`
+- Sister action-item: `[meta-isolation-existing-repos-migration]` in `OpeItcLoc03/workshop` — one-off migration of existing own repos.
+- Long-term: `[meta-isolation-mcp-sync-extension]` in `OpeItcLoc03/common` — extend `projects-meta-mcp` to sync `.wiki/` + `.claude/skills/` so meta-paths can leave repo entirely.

.wiki/index.md

@@ -36,6 +36,7 @@ Catalog of all wiki pages. One line per page, organized by type. Updated on ever
 - [interns-repo-read-design](concepts/interns-repo-read-design.md) — interns-repo-read-design
 - [hermes-skills-rollout-design](concepts/hermes-skills-rollout-design.md) — hermes-skills-rollout-design
 - [tdd-criteria-design](concepts/tdd-criteria-design.md) — tdd-criteria-design
+- [project-bootstrap-meta-isolation.md](concepts/project-bootstrap-meta-isolation.md) — project-bootstrap@1.11.0 — Step 1 ships meta-isolation block in `.gitignore` (`!.claude/`, `!.tasks/`, `!.wiki/`, ...) so own greenfield/upgrade projects re-enable agent meta-paths against global `core.excludesFile` cutter. Marker-based append-only on existing files; smoke-tested with negative control
 
 ## Packages
 

.wiki/log.md

@@ -55,3 +55,5 @@ Parseable: `grep "^## \[" .wiki/log.md | tail -20`.
 ## [2026-05-07] ingest | concepts/tdd-criteria-design
 
 ## [2026-05-07] review | tdd-criteria v0.2.0 — 4 findings applied: trigger-loophole fix (removed session-authorship clause), composite-tasks + refactoring sections, expanded file-extension list, clarified wrapper line-count + spike-survivor fallback + foreign-schema fix; design doc synced
+
+## [2026-05-10] decision | project-bootstrap-meta-isolation — v1.11.0 ships meta-isolation block in `.gitignore` template + Step 1 upgrade-case append; restores agent meta-paths visibility against global `core.excludesFile`; smoke-tested greenfield + negative control + idempotency

dist-hermes/SKIPPED.md

@@ -17,4 +17,4 @@ Do not edit by hand — edit the mapping and re-run the build.
 
 ## Pending (deferred to follow-up tasks)
 
-(none)
+- **using-yt-tools** — Shells out to yt-dlp + ffmpeg and writes ./yt-cache/ in cwd. Behavioral audit via using-yt-tools-test-trigger required before promotion to auto. → intended: `mode: auto, category: research`

dist-hermes/mcp/using-projects-meta/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: using-projects-meta
-version: 1.1.0
+version: 1.2.0
 description: Use when working across multiple projects on one or many machines — cross-project task aggregation (`mcp__projects-meta__tasks_*`), shared Gitea-backed wiki query / ingest (`mcp__projects-meta__knowledge_*`), or sync diagnostics (`mcp__projects-meta__meta_status`). Triggers on phrases like "across all projects", "what's on the boards", "check shared wiki", "search projects-wiki", "ingest into shared wiki", "что у меня на досках", "по всем проектам", "общая вики", "cross-project status", or any time the user wants to see / mutate state in another repo than the current cwd. v1.1.0 mandates a Step 0 freshness gate (probe `meta_status`, sync if stale, pull `projects-wiki` before shared-wiki writes) — see SKILL body. Mutation tools require two-step preview → confirm. Skip for the **current** project's tasks/wiki — those live on disk in `.tasks/` / `.wiki/`.
 ---
 
@@ -142,7 +142,7 @@ Use MCP only for **other** projects, **other** machines, or **shared** wiki cont
 | `mcp__projects-meta__knowledge_ingest` | `target_project`, `type`, `slug`, `body` (+ opt `frontmatter`, `source_project`) | Three commits: `<type>/<slug>.md` + `index.md` + `log.md`. `type` ∈ entities / concepts / packages / sources / raw |
 | `mcp__projects-meta__knowledge_promote` | `target_project`, `slug`, `body` (+ opt `frontmatter`, `source_project`) | Move `raw/<slug>.md` → `sources/<slug>.md` with auto `raw_path` link |
 
-`target_project` is either a Gitea repo name, or `_meta` (the dedicated meta-tasks / meta-wiki repos from `auth.toml`).
+`target_project` is **qualified** `<owner>/<repo>` (e.g. `victor/books`, `OpeItcLoc03/claude-skills`), or the literal `agenda` for the cross-project meta-board (resolves via `agenda_tasks_repo` in `auth.toml`). Bare names (`books`) are rejected with a hint to use the qualified form. Cross-cutting design: shared wiki → `concepts/projects-meta-multi-owner`.
 
 ## Examples
 
@@ -181,7 +181,7 @@ User: "заведи в проекте books задачу на миграцию `
 
 ```
 1. mcp__projects-meta__tasks_create
-   target_project: "books"
+   target_project: "victor/books"
    slug: "settings-json-migration"
    description: "<...>"
    next_action: "<...>"
@@ -203,7 +203,7 @@ User: "close `[projects-meta-skills]` in claude-skills"
 
 ```
 1. mcp__projects-meta__tasks_close
-   target_project: "claude-skills"
+   target_project: "OpeItcLoc03/claude-skills"
    slug: "projects-meta-skills"
    note: "<one-line summary>"
    (no `confirm`)
@@ -227,6 +227,7 @@ User: "close `[projects-meta-skills]` in claude-skills"
 | Calling `knowledge_ingest` with the wrong `type` | `type` must be one of `entities` / `concepts` / `packages` / `sources` / `raw`. Mis-typed pages land in the wrong section and break `index.md`. |
 | Vague `knowledge_search` queries ("auth", "config") | Specific multi-word queries return targeted snippets; vague ones return noise. |
 | Forgetting `domain="all"` when searching across families | Default `domain` is auto-detected from cwd; use `"all"` if the wiki page lives in a different family. |
+| Passing bare project name (`target_project: "books"`) to mutation tools | v2.x rejects bare names. Use qualified `<owner>/<repo>` (e.g. `victor/books`, `OpeItcLoc03/claude-skills`). Literal `agenda` is the only exception (cross-project meta-board). |
 
 ## Red flags
 

dist-hermes/mcp/using-synology-ops/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: using-synology-ops
+version: 0.1.2
+description: Use when diagnosing docker containers on the Synology NAS — the `synology-ops` HTTP MCP server (https://opsmcp.kzntsv.site/mcp) exposes 4 read-only tools — `ops.docker.ps`, `ops.docker.logs`, `ops.docker.inspect`, `ops.docker.stats` — all routed through tecnativa `synology-docker-proxy-ro` with `POST=0` (write-ops return 403). Triggers on container names (`modulair-rag`, `modulair-pipeline`, `lightrag-modulair`, `tier1-converter`, `modulair-mcp`, `synology-ops-mcp`), on NAS-domain words ("на NAS", "Synology", "синолоджи", "Portainer-стек", "ops-mcp", "опс мсп", "opsmcp.kzntsv.site"), or on incident phrases ("падает", "restart-loop", "не стартует", "unhealthy", "посмотри логи") when NAS-context. Read-only by design — no per-session grant needed. Skip for non-incident mentions, "open Portainer GUI" requests, write-ops, and incident phrases on non-NAS hosts (`books-pipeline`, `vps-*` etc. — only the 6 listed above are NAS-hosted).
+---
+
+# using-synology-ops
+
+Trigger-and-guidance skill для `synology-ops-mcp` — read-only HTTP MCP-сервера на NAS, дающего Claude'у видимость состояния docker-контейнеров без юзера-моста (без Portainer copy-paste).
+
+## When to use
+
+**Trigger — любой из трёх сигналов:**
+
+1. **Контейнерные имена** (явный NAS-signal):
+   - `modulair-rag`, `modulair-pipeline`, `lightrag-modulair`, `tier1-converter`, `modulair-mcp`, `synology-ops-mcp`, `synology-docker-proxy-ro`
+
+2. **Доменные слова Synology:**
+   - «на NAS», «Synology», «синолоджи», «Portainer-стек», «opsmcp.kzntsv.site», «ops-mcp», «опс мсп», «synology-ops»
+
+3. **Инцидент-фразы** (в NAS-контексте):
+   - «падает», «restart-loop», «не стартует», «unhealthy», «медленно грузится», «не видит соседа», «посмотри логи», «что с контейнером X»
+
+**Skip:** упоминание в неинцидент-контексте («modulair-rag deploy запланирован на завтра»), явный отказ («открой Portainer GUI»), инцидент-фразы для non-NAS хостов (`books-pipeline`, `vps-*` и т.д.).
+
+## Inputs
+
+- **Имя контейнера** (если есть) — для скоупинга `logs`/`inspect`/`stats`
+- **Симптом** — «падает», «медленно грузится», «не видит соседа» — определяет starting tool
+- **Scope** — «один контейнер» vs «весь стек» vs «все на NAS»
+
+## Steps
+
+**Флекс-паттерны — рекомендации, не жёсткий чек-лист.**
+
+| Сценарий | Старт-тап | Последовательность |
+|----------|-----------|-------------------|
+| «Контейнер X падает» | `ops.docker.ps({ name: "X", state: "all" })` → видит restart count | `logs({ name: "X", tail: 200, stream: "both" })` → если dependency error → `ps({ name: "<dep>" })` → если нет соседа → `inspect({ name: "X" })` |
+| «Проверь стек целиком» | `ops.docker.ps({ state: "all" })` | Группировка по stack labels → если problem видны сразу — diagnosis, иначе → ask user |
+| «Медленно грузится» | `ops.docker.stats({ name: "X" })` | Если CPU/Mem OK → `logs({ name: "X", since: "5m" })` на стартап-фазу |
+| «Не видит соседа в сети» | `ops.docker.inspect({ name: "X" })` | Достать `NetworkSettings.Networks` → сверить с `inspect` соседа |
+
+**Формат отдачи юзеру:**
+
+1. **Диагноз** — одна строка («`modulair-pipeline` в restart-loop, ECONNREFUSED `postgres:5432`, контейнера `postgres` в сети `modulair` нет»)
+2. **Evidence** — 3-5 строк (релевантные логи / env / networks), hard cap 15 строк
+3. **Гипотеза следующего шага** — 1-2 строки
+
+Юзер просит «покажи всё» → отдать всё, дефолт — выжимка.
+
+## Failure modes
+
+| Сценарий | Симптом | Действие |
+|----------|---------|----------|
+| Контейнер не существует | `ops.docker.logs` error «container not found» | Подсказать доступные: `ps({ state: "all" })` → список |
+| Docker proxy недоступен | Timeout / connection refused | «synology-docker-proxy-ro unreachable — check stack health в Portainer» |
+| 403 от docker-proxy | Попытка write-op (implicit) | «operation forbidden by tecnativa ACL — это read-only proxy, используй Portainer GUI для restart/exec» |
+| Output > 1MB | Логи обрезаны | Вернуть первый MB + `truncated: true, actualBytes: N` |
+| Bearer token невалидный | 401 на любой вызов | «check `~/.claude.json` → `mcpServers.synology-ops.headers.Authorization` соответствует ли токену в Portainer stack env» |
+
+## Side effects
+
+- **Latency** — HTTPS round-trip к NAS ~200ms, batch'ить вопросы, не дёргать в цикле
+- **Capping** — `logs` cap 1MB, `tail` max 5000 строк — если нужно больше, ask
+- **Маскирование** — env-vars с именами `/PASSWORD|TOKEN|SECRET|KEY|PASS|CREDS/i` заменены на `***` в `inspect` — regex может пропустить кастомные ключи, warning не certainty
+
+## What NOT to do
+
+**Common mistakes:**
+- ❌ Звонить `logs` без явного `tail` (default 200, но явный = намеренный)
+- ❌ Звонить `logs` для всех контейнеров подряд («покажи всё» — сначала `ps`)
+- ❌ Интерпретировать `***` в env как «вижу пароль» — это masked, может быть кастомный ключ
+- ❌ Пытаться write-ops (restart/exec/prune) через MCP — 403, направлять юзера в Portainer GUI
+- ❌ Кэшировать `ps` long-term — состояние NAS меняется, перезвонить
+
+**Red flags:**
+- 🔴 Дёргать в цикле — latency ~200ms через HTTPS, собрать вопросы в один batch
+- 🔴 Проверять non-NAS контейнеры этим MCP (`books-pipeline`, `vps-*`) — они не видны synology-ops-mcp
+- 🔴 Env-masked regex — не гарантия, могут быть кастомные ключи (`DB_URI`, `API_CREDENTIALS` и т.п.)

dist-hermes/software-development/project-bootstrap/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: project-bootstrap
-version: 1.10.1
+version: 1.11.0
 description: >
   Initializes or upgrades a project in the current folder: git, .gitignore, README.md,
   .wiki/ using Karpathy's method, .tasks/ for task tracking, CLAUDE.md with skill triggers.
@@ -61,8 +61,37 @@ If git is not initialized:
 git init
 ```
 
-If `.gitignore` does not exist — create from template `assets/.gitignore.template`.
-If it exists — leave it untouched.
+### `.gitignore`
+
+The template `assets/.gitignore.template` contains two parts:
+
+1. Standard ignore rules (deps, build, env, IDE, OS, logs).
+2. **Meta-isolation block** — `!`-inversions for `.claude/`, `.tasks/`, `.wiki/`,
+   `.brainstorm/`, `.archive/`, `.mcp/`, `.mcp.json`, `MEMORY.md`. This block
+   re-enables tracking of agent meta-paths in **own** repos against the
+   global `core.excludesFile` rule (`~/.config/git/ignore`) that hides them
+   from forks of upstream open-source. Without it, the `.tasks/`, `.wiki/`,
+   and `.claude/` directories created by Steps 3-5 would be invisible to git
+   on machines where the global excludesFile is configured, and the first
+   commit would be empty of agent obvyaska. Full design: workshop wiki
+   `concepts/meta-out-of-repo.md` (sections "Слой 2" and "Новые проекты").
+
+Two cases:
+
+- **`.gitignore` does not exist** — create from `assets/.gitignore.template`
+  (block included unconditionally).
+- **`.gitignore` exists** — check for the marker line
+  `# AI обвеска — слой 2:` (substring match, case-sensitive). If absent →
+  append the meta-isolation block (with the marker comment) to the end of
+  the file, prefixed by a blank line if the file does not already end with
+  one. If present → leave the file untouched.
+
+The block is **scoped to own projects**. The bootstrap skill currently has no
+fork-of-upstream mode (greenfield-full creates a brand-new Gitea repo;
+add-remote and upgrade operate on the user's own repos), so the block is
+applied unconditionally in all current modes. If a fork-bootstrap mode is
+ever added, the block must be **omitted** there — putting `!.claude/` etc.
+into a fork's `.gitignore` would diverge from upstream's ignore rules.
 
 ---
 

dist-hermes/software-development/project-bootstrap/assets/.gitignore.template

@@ -27,3 +27,14 @@ Thumbs.db
 # Logs
 *.log
 logs/
+
+# AI обвеска — слой 2: переопределяем глобальный ~/.config/git/ignore
+# для своих репо (см. global wiki concept meta-out-of-repo)
+!.claude/
+!.tasks/
+!.wiki/
+!.brainstorm/
+!.archive/
+!.mcp/
+!.mcp.json
+!MEMORY.md

hermes/mapping.yaml

@@ -126,6 +126,10 @@ skills:
     mode: auto
     category: mcp
 
+  using-synology-ops:
+    mode: auto
+    category: mcp
+
   project-bootstrap:
     mode: auto
     category: software-development
@@ -137,3 +141,12 @@ skills:
   update-claude-skills:
     mode: skip
     reason: "Claude-Code-only orchestrator — Hermes uses hermes-installer-skill instead."
+
+  # ─── pending (1 — behavioral audit required) ─────────────────────────
+
+  using-yt-tools:
+    mode: pending
+    intended:
+      mode: auto
+      category: research
+    reason: "Shells out to yt-dlp + ffmpeg and writes ./yt-cache/ in cwd. Behavioral audit via using-yt-tools-test-trigger required before promotion to auto."

skills/project-bootstrap/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: project-bootstrap
-version: 1.10.1
+version: 1.11.0
 description: >
   Initializes or upgrades a project in the current folder: git, .gitignore, README.md,
   .wiki/ using Karpathy's method, .tasks/ for task tracking, CLAUDE.md with skill triggers.
@@ -61,8 +61,37 @@ If git is not initialized:
 git init
 ```
 
-If `.gitignore` does not exist — create from template `assets/.gitignore.template`.
-If it exists — leave it untouched.
+### `.gitignore`
+
+The template `assets/.gitignore.template` contains two parts:
+
+1. Standard ignore rules (deps, build, env, IDE, OS, logs).
+2. **Meta-isolation block** — `!`-inversions for `.claude/`, `.tasks/`, `.wiki/`,
+   `.brainstorm/`, `.archive/`, `.mcp/`, `.mcp.json`, `MEMORY.md`. This block
+   re-enables tracking of agent meta-paths in **own** repos against the
+   global `core.excludesFile` rule (`~/.config/git/ignore`) that hides them
+   from forks of upstream open-source. Without it, the `.tasks/`, `.wiki/`,
+   and `.claude/` directories created by Steps 3-5 would be invisible to git
+   on machines where the global excludesFile is configured, and the first
+   commit would be empty of agent obvyaska. Full design: workshop wiki
+   `concepts/meta-out-of-repo.md` (sections "Слой 2" and "Новые проекты").
+
+Two cases:
+
+- **`.gitignore` does not exist** — create from `assets/.gitignore.template`
+  (block included unconditionally).
+- **`.gitignore` exists** — check for the marker line
+  `# AI обвеска — слой 2:` (substring match, case-sensitive). If absent →
+  append the meta-isolation block (with the marker comment) to the end of
+  the file, prefixed by a blank line if the file does not already end with
+  one. If present → leave the file untouched.
+
+The block is **scoped to own projects**. The bootstrap skill currently has no
+fork-of-upstream mode (greenfield-full creates a brand-new Gitea repo;
+add-remote and upgrade operate on the user's own repos), so the block is
+applied unconditionally in all current modes. If a fork-bootstrap mode is
+ever added, the block must be **omitted** there — putting `!.claude/` etc.
+into a fork's `.gitignore` would diverge from upstream's ignore rules.
 
 ---
 

skills/project-bootstrap/assets/.gitignore.template

@@ -27,3 +27,14 @@ Thumbs.db
 # Logs
 *.log
 logs/
+
+# AI обвеска — слой 2: переопределяем глобальный ~/.config/git/ignore
+# для своих репо (см. global wiki concept meta-out-of-repo)
+!.claude/
+!.tasks/
+!.wiki/
+!.brainstorm/
+!.archive/
+!.mcp/
+!.mcp.json
+!MEMORY.md

skills/setup-projects-meta/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: setup-projects-meta
-version: 1.0.1
+version: 1.1.0
 description: Installs and configures the local `projects-meta-mcp` stdio server — clones the repo to `~/projects/.common/lib/projects-meta-mcp`, builds it, writes `~/.config/projects-mcp/auth.toml` with the user's Gitea token, clones the shared wiki to `~/projects/.wiki/` (content lives in root), and registers `mcpServers.projects-meta` in `~/.claude.json`. Use this skill when the user says "install projects-meta", "set up projects-meta", "configure projects-meta", "настрой projects-meta", "установи projects-meta", "projects-meta не работает", "projects-meta isn't working", or whenever the `mcp__projects-meta__*` tools are missing in a session that needs cross-project task aggregation or the shared Gitea wiki. Cross-platform — Windows / Linux / macOS. Mutates user-level config and writes secrets; pauses for confirmation before every write.
 ---
 
@@ -122,12 +122,21 @@ If `~/.config/projects-mcp/auth.toml` already exists and Phase 1 found a valid `
 
 ```toml
 gitea_url         = "https://git.kzntsv.site"
-gitea_user  = "OpeItcLoc03"
+gitea_user        = "OpeItcLoc03"        # acting identity (commit author)
 gitea_token       = "<TOKEN>"
-# meta_tasks_repo = "projects-tasks"   # uncomment to override default
-# meta_wiki_repo  = "projects-wiki"    # uncomment to override default
+gitea_owners      = ["victor", "cancel_music"]   # additional Gitea owners to sync
+agenda_tasks_repo = "OpeItcLoc03/agenda"          # cross-project meta-board (qualified)
+# gitea_aggregate_skip_owners = ["OpeItcLoc03"]   # opt: sync but hide from `tasks_aggregate`
 ```
 
+**Schema notes (v2.x server):**
+
+- `gitea_owners` is an array of owners whose repos are scanned by `sync.js` and surfaced in aggregation views. `gitea_user` is acting identity only (commit author footer), not necessarily aggregated.
+- `agenda_tasks_repo` is **qualified** (`<owner>/<repo>`). The literal `agenda` in `target_project` resolves through this field.
+- `gitea_aggregate_skip_owners` (optional, v2.2.0+) — visited by sync (so mutations work via cache lookup) but hidden from `tasks_aggregate` / `tasks_search`. Useful for keeping infra repos write-able without polluting the dashboard.
+- Backwards-compat: legacy installs with only `gitea_user = "X"` and no `gitea_owners` → server reads as `gitea_owners = ["X"]`.
+- Legacy `meta_tasks_repo` / `meta_wiki_repo` → renamed to `agenda_tasks_repo` / built-in `projects-wiki`. Old keys ignored on v2.x.
+
 Permissions: on Linux / macOS run `chmod 600 ~/.config/projects-mcp/auth.toml`. On Windows the default ACL is per-user, no extra step.
 
 ### Phase 6 — Register in `~/.claude.json`

skills/using-projects-meta/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: using-projects-meta
-version: 1.1.0
+version: 1.2.0
 description: Use when working across multiple projects on one or many machines — cross-project task aggregation (`mcp__projects-meta__tasks_*`), shared Gitea-backed wiki query / ingest (`mcp__projects-meta__knowledge_*`), or sync diagnostics (`mcp__projects-meta__meta_status`). Triggers on phrases like "across all projects", "what's on the boards", "check shared wiki", "search projects-wiki", "ingest into shared wiki", "что у меня на досках", "по всем проектам", "общая вики", "cross-project status", or any time the user wants to see / mutate state in another repo than the current cwd. v1.1.0 mandates a Step 0 freshness gate (probe `meta_status`, sync if stale, pull `projects-wiki` before shared-wiki writes) — see SKILL body. Mutation tools require two-step preview → confirm. Skip for the **current** project's tasks/wiki — those live on disk in `.tasks/` / `.wiki/`.
 ---
 
@@ -142,7 +142,7 @@ Use MCP only for **other** projects, **other** machines, or **shared** wiki cont
 | `mcp__projects-meta__knowledge_ingest` | `target_project`, `type`, `slug`, `body` (+ opt `frontmatter`, `source_project`) | Three commits: `<type>/<slug>.md` + `index.md` + `log.md`. `type` ∈ entities / concepts / packages / sources / raw |
 | `mcp__projects-meta__knowledge_promote` | `target_project`, `slug`, `body` (+ opt `frontmatter`, `source_project`) | Move `raw/<slug>.md` → `sources/<slug>.md` with auto `raw_path` link |
 
-`target_project` is either a Gitea repo name, or `_meta` (the dedicated meta-tasks / meta-wiki repos from `auth.toml`).
+`target_project` is **qualified** `<owner>/<repo>` (e.g. `victor/books`, `OpeItcLoc03/claude-skills`), or the literal `agenda` for the cross-project meta-board (resolves via `agenda_tasks_repo` in `auth.toml`). Bare names (`books`) are rejected with a hint to use the qualified form. Cross-cutting design: shared wiki → `concepts/projects-meta-multi-owner`.
 
 ## Examples
 
@@ -181,7 +181,7 @@ User: "заведи в проекте books задачу на миграцию `
 
 ```
 1. mcp__projects-meta__tasks_create
-   target_project: "books"
+   target_project: "victor/books"
    slug: "settings-json-migration"
    description: "<...>"
    next_action: "<...>"
@@ -203,7 +203,7 @@ User: "close `[projects-meta-skills]` in claude-skills"
 
 ```
 1. mcp__projects-meta__tasks_close
-   target_project: "claude-skills"
+   target_project: "OpeItcLoc03/claude-skills"
    slug: "projects-meta-skills"
    note: "<one-line summary>"
    (no `confirm`)
@@ -227,6 +227,7 @@ User: "close `[projects-meta-skills]` in claude-skills"
 | Calling `knowledge_ingest` with the wrong `type` | `type` must be one of `entities` / `concepts` / `packages` / `sources` / `raw`. Mis-typed pages land in the wrong section and break `index.md`. |
 | Vague `knowledge_search` queries ("auth", "config") | Specific multi-word queries return targeted snippets; vague ones return noise. |
 | Forgetting `domain="all"` when searching across families | Default `domain` is auto-detected from cwd; use `"all"` if the wiki page lives in a different family. |
+| Passing bare project name (`target_project: "books"`) to mutation tools | v2.x rejects bare names. Use qualified `<owner>/<repo>` (e.g. `victor/books`, `OpeItcLoc03/claude-skills`). Literal `agenda` is the only exception (cross-project meta-board). |
 
 ## Red flags
 

skills/using-synology-ops/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: using-synology-ops
+version: 0.1.2
+description: Use when diagnosing docker containers on the Synology NAS — the `synology-ops` HTTP MCP server (https://opsmcp.kzntsv.site/mcp) exposes 4 read-only tools — `ops.docker.ps`, `ops.docker.logs`, `ops.docker.inspect`, `ops.docker.stats` — all routed through tecnativa `synology-docker-proxy-ro` with `POST=0` (write-ops return 403). Triggers on container names (`modulair-rag`, `modulair-pipeline`, `lightrag-modulair`, `tier1-converter`, `modulair-mcp`, `synology-ops-mcp`), on NAS-domain words ("на NAS", "Synology", "синолоджи", "Portainer-стек", "ops-mcp", "опс мсп", "opsmcp.kzntsv.site"), or on incident phrases ("падает", "restart-loop", "не стартует", "unhealthy", "посмотри логи") when NAS-context. Read-only by design — no per-session grant needed. Skip for non-incident mentions, "open Portainer GUI" requests, write-ops, and incident phrases on non-NAS hosts (`books-pipeline`, `vps-*` etc. — only the 6 listed above are NAS-hosted).
+---
+
+# using-synology-ops
+
+Trigger-and-guidance skill для `synology-ops-mcp` — read-only HTTP MCP-сервера на NAS, дающего Claude'у видимость состояния docker-контейнеров без юзера-моста (без Portainer copy-paste).
+
+## When to use
+
+**Trigger — любой из трёх сигналов:**
+
+1. **Контейнерные имена** (явный NAS-signal):
+   - `modulair-rag`, `modulair-pipeline`, `lightrag-modulair`, `tier1-converter`, `modulair-mcp`, `synology-ops-mcp`, `synology-docker-proxy-ro`
+
+2. **Доменные слова Synology:**
+   - «на NAS», «Synology», «синолоджи», «Portainer-стек», «opsmcp.kzntsv.site», «ops-mcp», «опс мсп», «synology-ops»
+
+3. **Инцидент-фразы** (в NAS-контексте):
+   - «падает», «restart-loop», «не стартует», «unhealthy», «медленно грузится», «не видит соседа», «посмотри логи», «что с контейнером X»
+
+**Skip:** упоминание в неинцидент-контексте («modulair-rag deploy запланирован на завтра»), явный отказ («открой Portainer GUI»), инцидент-фразы для non-NAS хостов (`books-pipeline`, `vps-*` и т.д.).
+
+## Inputs
+
+- **Имя контейнера** (если есть) — для скоупинга `logs`/`inspect`/`stats`
+- **Симптом** — «падает», «медленно грузится», «не видит соседа» — определяет starting tool
+- **Scope** — «один контейнер» vs «весь стек» vs «все на NAS»
+
+## Steps
+
+**Флекс-паттерны — рекомендации, не жёсткий чек-лист.**
+
+| Сценарий | Старт-тап | Последовательность |
+|----------|-----------|-------------------|
+| «Контейнер X падает» | `ops.docker.ps({ name: "X", state: "all" })` → видит restart count | `logs({ name: "X", tail: 200, stream: "both" })` → если dependency error → `ps({ name: "<dep>" })` → если нет соседа → `inspect({ name: "X" })` |
+| «Проверь стек целиком» | `ops.docker.ps({ state: "all" })` | Группировка по stack labels → если problem видны сразу — diagnosis, иначе → ask user |
+| «Медленно грузится» | `ops.docker.stats({ name: "X" })` | Если CPU/Mem OK → `logs({ name: "X", since: "5m" })` на стартап-фазу |
+| «Не видит соседа в сети» | `ops.docker.inspect({ name: "X" })` | Достать `NetworkSettings.Networks` → сверить с `inspect` соседа |
+
+**Формат отдачи юзеру:**
+
+1. **Диагноз** — одна строка («`modulair-pipeline` в restart-loop, ECONNREFUSED `postgres:5432`, контейнера `postgres` в сети `modulair` нет»)
+2. **Evidence** — 3-5 строк (релевантные логи / env / networks), hard cap 15 строк
+3. **Гипотеза следующего шага** — 1-2 строки
+
+Юзер просит «покажи всё» → отдать всё, дефолт — выжимка.
+
+## Failure modes
+
+| Сценарий | Симптом | Действие |
+|----------|---------|----------|
+| Контейнер не существует | `ops.docker.logs` error «container not found» | Подсказать доступные: `ps({ state: "all" })` → список |
+| Docker proxy недоступен | Timeout / connection refused | «synology-docker-proxy-ro unreachable — check stack health в Portainer» |
+| 403 от docker-proxy | Попытка write-op (implicit) | «operation forbidden by tecnativa ACL — это read-only proxy, используй Portainer GUI для restart/exec» |
+| Output > 1MB | Логи обрезаны | Вернуть первый MB + `truncated: true, actualBytes: N` |
+| Bearer token невалидный | 401 на любой вызов | «check `~/.claude.json` → `mcpServers.synology-ops.headers.Authorization` соответствует ли токену в Portainer stack env» |
+
+## Side effects
+
+- **Latency** — HTTPS round-trip к NAS ~200ms, batch'ить вопросы, не дёргать в цикле
+- **Capping** — `logs` cap 1MB, `tail` max 5000 строк — если нужно больше, ask
+- **Маскирование** — env-vars с именами `/PASSWORD|TOKEN|SECRET|KEY|PASS|CREDS/i` заменены на `***` в `inspect` — regex может пропустить кастомные ключи, warning не certainty
+
+## What NOT to do
+
+**Common mistakes:**
+- ❌ Звонить `logs` без явного `tail` (default 200, но явный = намеренный)
+- ❌ Звонить `logs` для всех контейнеров подряд («покажи всё» — сначала `ps`)
+- ❌ Интерпретировать `***` в env как «вижу пароль» — это masked, может быть кастомный ключ
+- ❌ Пытаться write-ops (restart/exec/prune) через MCP — 403, направлять юзера в Portainer GUI
+- ❌ Кэшировать `ps` long-term — состояние NAS меняется, перезвонить
+
+**Red flags:**
+- 🔴 Дёргать в цикле — latency ~200ms через HTTPS, собрать вопросы в один batch
+- 🔴 Проверять non-NAS контейнеры этим MCP (`books-pipeline`, `vps-*`) — они не видны synology-ops-mcp
+- 🔴 Env-masked regex — не гарантия, могут быть кастомные ключи (`DB_URI`, `API_CREDENTIALS` и т.п.)

skills/using-yt-tools/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: using-yt-tools
+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 — другие тулзы.
+---
+
+# using-yt-tools
+
+Iterative-watching YouTube для агента: clean-markdown транскрипт с `[mm:ss]`-якорями → агент решает, какие моменты интересны → targeted frame extraction по таймкодам → агент видит кадры через `Read`. Альтернативный flow — если юзер уже назвал таймкоды, идём прямо за кадрами без транскрипта.
+
+## When to use
+
+Два различных flow, выбор по user intent:
+
+**Flow A — iterative-watch** (exploration / summary):
+- Юзер спрашивает что в ролике, хочет summary, хочет узнать о чём видео.
+- Шаги: fetch transcript → read → pick interesting moments → extract those frames → Read frames.
+- Trigger phrases: «что в этом ролике», «о чём ролик», «расшифровка YouTube», «video summary», «youtube transcript», «watch this video».
+
+**Flow B — targeted-frames** (specific moments):
+- Юзер уже назвал конкретные таймкоды; транскрипт — лишняя работа.
+- Шаги: extract frames at given timestamps → Read frames.
+- Trigger phrases: «покажи кадр на N», «посмотри момент N», «что показано на N», «show frame at N».
+
+Оба flow предполагают, что `yt-tools` CLI установлен из `~/projects/.common/lib/yt-tools/` (project-local venv). Бинари могут не быть на PATH текущей сессии — это норма, особенно после свежего `winget install`. **Никогда не abort'ить по голому `Get-Command yt-frames` / `which yt-frames`** — сначала прогнать резолв (см. Prerequisites → Locating binaries).
+
+## Prerequisites
+
+### Locating binaries
+
+Скил ничего не предполагает про активный PATH. **Step 0 каждого flow** — резолв путей для `yt-frames`/`yt-transcript` и `ffmpeg` (+ `yt-dlp`, поставляется в том же venv). Если резолвится через fallback — используй PATH-prepend в каждом вызове (см. Invoke pattern ниже). Abort'ить **только** если бинаря нет ни на PATH, ни в известных install-локациях.
+
+**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)
+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`
+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**:
+
+1. PATH: `Get-Command ffmpeg` / `command -v ffmpeg`
+2. Windows winget cache (версия плавающая, глобь):
+   `~/AppData/Local/Microsoft/WinGet/Packages/Gyan.FFmpeg_Microsoft.Winget.Source_*/ffmpeg-*-full_build/bin/ffmpeg.exe`
+3. macOS Homebrew: `/opt/homebrew/bin/ffmpeg` (Apple Silicon) или `/usr/local/bin/ffmpeg` (Intel)
+4. Linux: `/usr/bin/ffmpeg` (apt) или `/usr/local/bin/ffmpeg`
+5. Если ни одна локация — install hint per-ОС (`winget install Gyan.FFmpeg` / `brew install ffmpeg` / `apt install ffmpeg`); стоп. **Не** проси юзера restart'ить CC — продолжай резолв-логику в той же сессии после установки, либо подскажи, что новой сессии PATH подхватится сам.
+
+### Invoke pattern
+
+`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=~/.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\.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
+```
+
+Если оба нашлись напрямую на PATH (`Get-Command` вернул что-то) — pre-pend не нужен, зови как обычно.
+
+## Inputs
+
+| Flow | Required | Optional |
+|---|---|---|
+| A — iterative-watch | YouTube URL или bare 11-char video id | `--lang ru,en` для non-English subs; `--out PATH` |
+| B — targeted-frames | YouTube URL + timestamps (`mm:ss`, `h:mm:ss`, или bare seconds: `123` → 2:03) | `--no-cache-source` (stream вместо кеша source.mp4); `--out DIR` |
+
+Оба flow пишут в `<cwd>/yt-cache/<video-id>/` по умолчанию.
+
+## Steps
+
+### Flow A — iterative-watch
+
+```
+0. Резолв yt-frames + ffmpeg per Prerequisites → Locating binaries; собрать PATH-prepend если резолв через fallback
+1. yt-transcript <url>                        → ./yt-cache/<vid>/transcript.md
+2. Read transcript.md, find [mm:ss] anchors that match the question
+3. yt-frames <url> --timestamps 1:23,4:56,…   → ./yt-cache/<vid>/frames/frame_*.jpg
+4. Read each frame_*.jpg via the vision tool
+5. Answer the user, citing both transcript paragraph and frame contents
+```
+
+**Stdout contract per CLI** (бери последнюю строку, формат зависит от CLI):
+
+- `yt-transcript`, `yt-watch` — одна строка на stdout: bare absolute path артефакта (`<abs>/transcript.md` или `<abs>/watch.md`).
+- `yt-frames` — **N строк** формата `Wrote: <abs path>`, одна на каждый извлечённый кадр. Strip префикс `"Wrote: "` чтобы получить путь. Дизайн осознан: per-line output чтобы caller'ы пайпили / скрейпили без парсинга summary в конце.
+
+Warnings и errors уходят в stderr (`warning: …`, `error: …`); stdout остаётся машинно-парсимым.
+
+### Flow B — targeted-frames
+
+```
+0. Резолв yt-frames + ffmpeg per Prerequisites → Locating binaries; собрать PATH-prepend если резолв через fallback
+1. Parse user's timestamps (mm:ss / h:mm:ss / bare seconds — все работают)
+2. yt-frames <url> --timestamps 1:23,4:56,…   → ./yt-cache/<vid>/frames/frame_*.jpg
+3. Read each frame_*.jpg
+4. Answer the user, referencing each frame by its [mm:ss] label
+```
+
+Без transcript fetch. Если потом юзер спросит «что говорилось в тот момент?», переключайся на Flow A на том же URL — `source.mp4` cache переиспользуется, повторного download нет.
+
+## Failure modes
+
+Все failures abort cleanly; никогда не оставляй наполовину готовое состояние.
+
+| Symptom | Cause | Action |
+|---|---|---|
+| `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` есть в той же 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 | То же |
+| `Subtitles disabled` от `youtube-transcript-api` | Канал отключил CC | Для Flow A это fatal — скажи юзеру, предложи Flow B с явными таймкодами если уместно |
+| Юзер дал не-YouTube URL (Vimeo / Twitch / local mp4) | Out of scope | Стоп; скажи что скил YouTube-only |
+
+## Side effects
+
+- Writes под `<cwd>/yt-cache/<video-id>/`:
+  - `transcript.md` (Flow A)
+  - `source.mp4` (≤720p, оба flow если без `--no-cache-source`)
+  - `frames/frame_<mmss>.jpg` per extracted frame
+- Network: yt-dlp вытягивает metadata + опционально source.mp4; `youtube-transcript-api` вытягивает subs
+- Никакого внешнего state не мутируется — чисто local-fs side effects
+- `source.mp4` может быть ~50-200 MB на 720p / 10-минутный ролик; кеш переиспользуется между запусками. **Warning:** cumulative — 20 роликов = 1-4 GB на диске.
+
+Cache hygiene: `yt-tools cache list` показывает usage, `yt-tools cache prune --older-than 7d` чистит.
+
+## 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.
+- **Не shell-quote URLs в одну command строку.** Используй CLI list-form (он уже list-form в `subprocess.run`); YouTube URLs содержат `?` и `&`, которые ломают naive quoting.
+- **Не retry на yt-dlp failures.** Failure здесь значит видео реально недоступно (private / region / age) или у юзера broken auth. Retries — трата токенов.
+- **Не пересказывай / не переводи transcript в свой ответ молча.** Артефакт — для твоего reasoning; цитируй с `[mm:ss]`-якорем когда приводишь пассаж.
+- **Не вызывай скил на non-YouTube URL.** Vimeo / Twitch / TikTok / local mp4 — out of scope. Бери другие тулзы (или yt-dlp напрямую).
+- **Не пиши результаты в произвольные пути.** По умолчанию `<cwd>/yt-cache/<vid>/`; явный `--out` только если юзер просил.