diff --git a/IDEA.md b/IDEA.md
index 725307f..3a17370 100644
--- a/IDEA.md
+++ b/IDEA.md
@@ -37,6 +37,12 @@
 1. Пишешь код на VPS в `/root/.hermes/projects/figma plugins/figma-ai-plugin/`
 2. `npm install` + `npm run build` (проверка сборки)
 3. `git push` → Gitea (`admin/figma-ai-plugin`)
-4. Копия на Matebook: `D:\Figma Plugins\figma-ai-plugin\` (через tar-архив по SSH, без node_modules/build)
+4. Копия на Matebook: `D:\Figma Plugins\figma-ai-plugin\` (через tar-архив по SSH: **исключать только `node_modules` и `.git`, папку `build/` ОБЯЗАТЕЛЬНО включать** — иначе плагин не запустится, см. KNOWLEDGE.md)
 5. В Figma: Plugins → Development → Import plugin from manifest → выбрать `manifest.json` из папки Matebook
 6. Запуск плагина для теста
+
+## Правила ведения KNOWLEDGE.md
+
+- KNOWLEDGE.md — живая копилка gotcha/решений. Hermes (агент) **имеет право дописывать и править KNOWLEDGE.md самостоятельно, без вопросов к пользователю**, когда находит новую проблему и её решение по ходу работы над проектом.
+- Формат записи: `### Заголовок` + блоки **Симптом / Причина / Решение / Ссылка** (как в текущих записях).
+- Если правишь рабочий флоу здесь (IDEA.md), продублируй связанное gotcha в KNOWLEDGE.md (напр. ловушка с `--exclude build`).
diff --git a/KNOWLEDGE.md b/KNOWLEDGE.md
index 024d7ca..45400c5 100644
--- a/KNOWLEDGE.md
+++ b/KNOWLEDGE.md
@@ -2,6 +2,7 @@
 
 > Копилка находок и решений по проекту. Не наступай на грабли дважды.
 > Пополняется по ходу разработки. Формат: проблема → решение (+ контекст/ссылка).
+> Hermes имеет право править и дополнять этот файл самостоятельно (см. IDEA.md).
 
 ## Сборка / окружение
 
@@ -22,14 +23,22 @@
 - **Решение:** для приглушённого текста брать компонент `<Muted>` из `@create-figma-plugin/ui`, а не проп `muted` у `<Text>`.
 - **Ссылка:** src/ui.tsx
 
+### Плагин не запускается в Figma — нет папки `build/` на Matebook
+- **Симптом:** плагин не открывается / Figma молча ничего не делает при Run (ошибка не всегда видна).
+- **Причина:** `manifest.json` указывает `main: build/main.js` и `ui: build/ui.js`, но в скопированной на Matebook папке папки `build/` нет (старая команда синхронизации исключала её через `--exclude build`).
+- **Решение:** пересобрать на VPS (`npm run build`) и залить на Matebook ВЕСЬ проект вместе с `build/` — исключать только `node_modules` и `.git` (они для запуска в Figma не нужны, Figma исполняет собранные `build/*.js`). После распаковки проверить наличие `build/main.js` и `build/ui.js`.
+- **Ссылка:** IDEA.md (раздел «Рабочий флоу», шаг 4), этот файл (раздел синхронизации через tar).
+
 ## Рабочий флоу (VPS → Matebook → Figma)
 
 ### Копия на Matebook через tar (rsync/scp с пробелами в пути падают)
 - **Симптом:** `rsync: command not found` (на Windows), `scp: ambiguous target` (пробел в пути).
 - **Решение:**
-  1. На VPS: `tar czf /tmp/x.tar.gz --exclude node_modules --exclude build .`
-  2. `scp /tmp/x.tar.gz risow@10.200.201.5:D:/x.tar.gz`
-  3. На Matebook (PowerShell): `Set-Location 'D:\Figma Plugins\figma-ai-plugin'; tar xzf 'D:\x.tar.gz'`
+  1. На VPS: `npm run build` (обязательно — иначе нет папки `build/`)
+  2. На VPS: `tar czf /tmp/x.tar.gz --exclude node_modules --exclude .git .`  ← `build/` НЕ исключать!
+  3. `scp /tmp/x.tar.gz risow@10.200.201.5:D:/x.tar.gz`
+  4. На Matebook (PowerShell): `Set-Location 'D:/Figma Plugins/figma-ai-plugin'; tar xzf 'D:/x.tar.gz'`
+- **Ловушка:** старая команда исключала `--exclude build` → в папке плагина на Matebook не было `build/`, и Figma не находила `build/main.js`/`build/ui.js` → плагин не запускался. См. gotcha «Плагин не запускается — нет `build/`».
 - **Ссылка:** IDEA.md (раздел «Рабочий флоу»)
 
 ### Gitea push через токен в URL