feat(using-wiki-graph): thin trigger skill for the wiki-graph MCP [v0.1.0]

skills/using-wiki-graph/SKILL.md — triggers on relational/structural wiki
questions («что связывает X и Y», path/neighbors/backlinks/orphans), routes to
mcp__wiki-graph__* instead of single-page reads (the 0%-recall failure mode).
Precondition: dense corpora only (modulair yes, sparse meta-wiki no).

hermes/mapping.yaml: registered as `pending` (intended auto/mcp, mirrors
using-vds-ops) — NOT promoted to auto; promotion gated on a
using-wiki-graph-test-trigger behavioral audit (instrument-touch).

Installed scoped via scripts/install.sh. Closes [wiki-graph-skill].
NOTE: build-hermes currently red on pre-existing unmapped skill 'meta-host-routing' (not this change).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

.tasks/STATUS.md

@@ -1,5 +1,5 @@
 # Task Board
-_Updated: 2026-05-25 (closed yt-listen-path-shim-investigate as wontfix — machine-local transient)_
+_Updated: 2026-05-31 (added using-yt-tools-rate-limit-guard ⚪)_
 
 <!--
   Canonical layout. One block per task. Per-task deep context lives in
@@ -14,6 +14,32 @@ _Updated: 2026-05-25 (closed yt-listen-path-shim-investigate as wontfix — mach
     🔵 Blocked    — waiting on external input
 -->
 
+## ⚪ [using-yt-tools-rate-limit-guard] — Add explicit "don't batch requests at YouTube" rule to `skills/using-yt-tools/SKILL.md` (avoid HTTP 429 IP-block).
+
+**Эмпирика (2026-05-31, modulair-wiki ingest, DESKTOP).** Владелец кинул подборку из 10 YouTube URL. Агент выстрелил залпом ~21 запрос подряд: `yt-dlp --dump-json` ×10 (метаданные — прошли) + `yt-transcript` ×10 (transcript-api). Первый transcript-вызов достучался (вернул список языков), **со второго пошёл `HTTP 429 / "YouTube is blocking requests from your IP"`**. Блок IP-wide и держится минутами — упёрлись **оба** пути: `youtube-transcript-api` (yt-transcript) И `yt-dlp` timedtext-subtitle endpoint (метаданные при этом ещё проходили, а субтитры — нет). Что разблокировало: ~4-мин cooldown + запросы **по одному** с паузами 25–35с + ранний abort если первый не прошёл (чтобы не жечь cooldown впустую).
+
+Второй, смежный баг той же сессии: `yt-transcript` по умолчанию просит `--lang en` и **промахивается мимо ручных `en-US` субтитров** (видео с manually-created `en-US` и без `en` отдаёт "no transcript"). Лечится `--lang en-US,en` (или вообще автоопределением).
+
+**Что добавить в SKILL.md:**
+
+1. **What NOT to do** — новый буллет: «**Не пулять в YouTube пачкой запросов.** Несколько URL подряд (или metadata+transcript залпом) → `HTTP 429`, IP-block на минуты, бьёт оба пути (transcript-api и yt-dlp). Обрабатывай по одному, с паузой ≥25–35с между; при пакете из N URL — последовательно, не параллельно. Если уже словил 429 — cooldown ~3–5 мин перед повтором, проверяй первый запрос и не продолжай залп если он упал.»
+
+2. **Failure modes** — новая строка: симптом `HTTP 429 Too Many Requests` / `"blocking requests from your IP"` → причина: слишком много запросов подряд (rate-limit, не приватность/регион) → действие: cooldown + по одному с паузами; НЕ retry в цикле без задержки. Отличать от `yt-dlp source download failed` (это реальная недоступность видео).
+
+3. (опц.) **Inputs / Flow A** — упомянуть `--lang en-US,en` как дефолт-страховку для ручных не-`en` субтитров (видео NE/прочие с `en-US`-only).
+
+**Bump:** PATCH (поверхностное расширение guidance, не breaking).
+**TDD:** не применим (markdown-документ). Behavioral-смок опционален: «дай 5 URL» → агент обрабатывает последовательно с паузами, не залпом.
+**Дисциплина:** после правки — bump version в frontmatter, commit `feat(using-yt-tools): rate-limit guard (no-batch) vX.Y.Z`; install/hermes-mapping/push — отдельно, как в прошлых yt-tools-тасках (для PATCH достаточно reload-plugins).
+
+**Status:** ready
+**Where I stopped:** (not started) — баг и фикс зафиксированы по живой сессии 2026-05-31; правка скила отложена в задачу (владелец просил не лезть в глобальный скил из проекта modulair-wiki).
+**Next action:** Открыть `skills/using-yt-tools/SKILL.md`, внести пункты 1–3, bump PATCH, commit. Свериться, нет ли дубля с существующим "Не retry на yt-dlp failures" — расширить его, а не плодить.
+**Branch:** master
+<!-- created-by: vitya@DESKTOP / from: modulair-wiki ingest session / 2026-05-31 -->
+
+---
+
 ## 🟡 [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

hermes/mapping.yaml

@@ -154,6 +154,13 @@ skills:
       category: mcp
     reason: "Calls mcp__vds-ops__* tools (read-only, but touches infrastructure). Behavioral audit via using-vds-ops-test-trigger required before promotion to auto."
 
+  using-wiki-graph:
+    mode: pending
+    intended:
+      mode: auto
+      category: mcp
+    reason: "Calls mcp__wiki-graph__* tools (read-only, parses a .wiki/ corpus server-side). Behavioral audit via using-wiki-graph-test-trigger required before promotion to auto."
+
   session-handoff:
     mode: pending
     intended:

skills/using-wiki-graph/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: using-wiki-graph
+version: 0.1.0
+description: "Use when a question is RELATIONAL about a wiki — «что связывает X и Y», «как связаны X и Y», «путь между X и Y», «через что X выходит на Y», «what connects X and Y», «how is X related to Y», «shortest path between pages» — or about wiki STRUCTURE/HEALTH — «что ссылается на X», «кто линкует X», «соседи страницы X», «сироты в вики», «битые/dangling ссылки», «сколько связных компонент», «backlinks of X», «orphan pages». Triggers the `wiki-graph` MCP server (`mcp__wiki-graph__path|neighbors|backlinks|orphans|stats`), which runs a deterministic BFS over `[[wikilinks]]` server-side. The failure-mode this guards: on a relational question the agent does a semantic read of one page and STOPS, never walking the multi-hop link chain (0% recall on such queries vs 67% for graph BFS). Precondition: only DENSE corpora (e.g. modulair-wiki, 150 linked pages) — skip on sparse wikis (the shared meta-wiki has ~1 link total, graph is empty). Each tool needs `corpus` = absolute path to the `.wiki/` dir. Read-only, no grant needed. Skip for content/semantic questions answerable by reading a single page, and for wikis with no `[[links]]`."
+---
+
+# using-wiki-graph
+
+Stop and call the graph. On a **relational** or **structural** wiki question, do not answer from reading one page — the links form a graph the LLM does not traverse reliably by reading. The `wiki-graph` MCP server walks `[[wikilinks]]` deterministically and returns the answer in a few lines; the corpus never enters context.
+
+## When to use
+
+Trigger when the question is about **connections between pages** or **wiki structure**, not about the content of a single page:
+
+- relational — "what connects X and Y", "how are X and Y related", "path between X and Y", «что связывает», «как связаны», «путь между»;
+- neighbourhood — "neighbours of X", "what does X reach in 2 hops", «соседи X», «что рядом с X»;
+- incoming — "what links to X", "who references X", «кто ссылается на X», «backlinks»;
+- health — "orphan pages", "dangling/broken links", "how many components", «сироты», «битые ссылки», «здоровье вики».
+
+## Precondition — dense corpus only
+
+The graph is useful only when the wiki is actually linked. modulair-wiki (~150 linked pages, ~715 edges) — **yes**. The shared meta-wiki (`~/projects/.wiki/`, ~1 link total) — **no**, the graph is empty; answer by reading instead. If unsure, run `stats` first: near-zero `edges` ⇒ fall back to reading.
+
+## Inputs
+
+- `corpus` — **absolute** path to the wiki's `.wiki/` directory (e.g. `C:/Users/vitya/projects/modulair-wiki/.wiki`). Every tool requires it. Provenance dirs (`raw/`, `sources/`, `assets/`) are excluded automatically; the graph is the canonical concept/entity network.
+- page references are **slugs** (the `.md` basename, kebab-case), case-insensitive — e.g. `euclidean-rhythms`, not a title or path.
+
+## Steps
+
+1. Pick the tool from the question shape:
+   - relational / "what connects" → `mcp__wiki-graph__path` (`from`, `to`) — shortest undirected chain.
+   - neighbourhood → `mcp__wiki-graph__neighbors` (`node`, `depth` default 1) — outgoing within N hops.
+   - "who links to" → `mcp__wiki-graph__backlinks` (`node`) — incoming references.
+   - health → `mcp__wiki-graph__orphans` (unlinked pages + dangling targets) or `mcp__wiki-graph__stats` (counts).
+2. Pass `corpus` + the slugs. Report the returned chain/list directly; don't re-derive it by reading pages.
+3. Empty `path` result = genuinely no link chain — say so, don't invent one from prose proximity.
+
+## Failure modes
+
+- Slug typo / page not under a canonical dir → `path` returns empty or the node is unknown. Verify the slug is a real `.md` basename.
+- Sparse corpus → empty/near-empty graph. Don't force it; read instead (see Precondition).
+- `wiki-graph` server not registered → tools absent in session. Then read manually and note the server needs registering in `~/.claude.json`.
+
+## Side effects
+
+None. Read-only; parses files server-side. No writes, no grant, no network.
+
+## What NOT to do
+
+- Don't answer a relational question from a single-page read — that's the exact 0%-recall failure this skill exists to prevent.
+- Don't paste the whole wiki into context to "trace" links by hand — the server does it at zero token cost.
+- Don't invoke on dense-content questions ("what is euclidean-rhythms about") — that's a read, not a graph walk.
+- Don't pass titles or relative paths — only absolute `corpus` + basename slugs.