docs(search): правило ast-index vs vex (когда что) + ссылки в CLAUDE.md

- .claude/rules/search-tools.md — матрица: ast-index (символы/usages/callers/outline),
  vex (semantic/similar/pattern/duplicates/show)
- usages/callers по JS — только ast-index (vex пропускает)
- CLAUDE.md и ast-index.md ссылаются на новое правило

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

.claude/rules/ast-index.md

@@ -1,5 +1,8 @@
 # ast-index Rules
 
+> Семантический поиск / AST-паттерны / дубликаты — это **vex**, см. `search-tools.md`.
+> Это правило — про ast-index (дефолт для символов, usages, callers, outline).
+
 ## Mandatory Search Rules
 
 1. **ALWAYS use ast-index FIRST** for any code search task

.claude/rules/search-tools.md

@@ -0,0 +1,46 @@
+# Search Tools — когда ast-index, когда vex
+
+Два инструмента поиска по коду. **Grep по-прежнему запрещён** (см. `ast-index.md`).
+
+## Правило одной строкой
+
+- Знаешь имя символа / нужны **usages / callers** / outline → **ast-index**
+- Ищешь **по смыслу** / **похожее** / **дубликаты** / **AST-паттерн** / компактное тело → **vex**
+
+## ast-index — дефолт
+
+Быстрее (1–10 мс) и точнее на этом **vanilla-JS** проекте. ВСЕГДА первым для:
+
+| Задача | Команда |
+|--------|---------|
+| Класс / функция по имени | `ast-index class "X"` · `ast-index symbol "x"` |
+| Использования | `ast-index usages "X"` |
+| Кто вызывает / иерархия | `ast-index callers "x"` · `ast-index call-tree "x"` |
+| Структура файла | `ast-index outline "path"` |
+| Поиск в файле | `ast-index search "kw" --in-file "f"` |
+
+⚠️ **usages / callers на чистом JS — ТОЛЬКО ast-index.** vex их пропускает (JS у vex не
+binder-язык). Проверено: `vex usages "audit"` → пусто, `ast-index usages "audit"` → все 10.
+
+## vex — по смыслу и структуре
+
+Для того, чего ast-index не умеет. Бинарник: `C:\Users\Home\bin\vex.exe` (в новых терминалах — `vex`).
+Индекс собран с `--semantic`.
+
+| Задача | Команда |
+|--------|---------|
+| Поиск по смыслу (имя неизвестно) | `vex search "что делает код" --semantic` |
+| Семантически похожие символы | `vex similar "Name"` |
+| AST-паттерн (как ast-grep) | `vex pattern --lang js 'function $NAME($$$)'` |
+| Near-дубликаты | `vex duplicates --threshold 0.95` |
+| Компактное тело символа (экономия токенов) | `vex show "Name"` |
+| Всё про символ за 1 вызов | `vex bundle --mode symbol --symbol Name` |
+
+Особенности CLI: `search` / `usages` / `show` берут индекс **текущей папки** и НЕ принимают `--path`;
+`pattern` требует `--lang` + `--path`.
+
+## Поддержание индексов
+
+- **ast-index**: `ast-index update` (после pull) · `ast-index rebuild` (после новых файлов)
+- **vex**: `vex update` (инкрементально, сохраняет semantic из манифеста) · `vex index --semantic` (полный)
+- Обновить сам бинарник vex: `vex self-update`

CLAUDE.md

@@ -2,9 +2,13 @@
 
 ## Поиск по коду
 
-**ВСЕГДА использовать `ast-index` ПЕРВЫМ** для любого поиска по коду.
+**ast-index — дефолт.** ВСЕГДА первым для «найти символ по имени / usages / callers / outline».
 Grep/Read — только если ast-index вернул пустой результат.
 
+**vex** — для поиска **по смыслу**, AST-паттернов, дубликатов, компактного тела символа:
+`vex search "..." --semantic`, `vex similar`, `vex pattern`, `vex duplicates`, `vex show`.
+Что и когда — подробно в `.claude/rules/search-tools.md`. (usages/callers по JS — только ast-index.)
+
 ```bash
 # Найти класс/функцию/символ
 ast-index class "ClassName"