From 31f4121737cf20febe26704dc60c68381e630bb6 Mon Sep 17 00:00:00 2001
From: Hermes Agent <hermes@local>
Date: Sat, 3 Oct 2026 21:33:22 +0200
Subject: [PATCH] docs: make Matebook sync preserve build paths and verify
 hashes

---
 IDEA.md      | 15 ++++++++++-----
 KNOWLEDGE.md |  7 +++++++
 2 files changed, 17 insertions(+), 5 deletions(-)

diff --git a/IDEA.md b/IDEA.md
index e566925..18a6861 100644
--- a/IDEA.md
+++ b/IDEA.md
@@ -35,11 +35,16 @@
 
 ## Рабочий флоу (Hello World проверен)
 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` и `.git`, папку `build/` ОБЯЗАТЕЛЬНО включать** — иначе плагин не запустится, см. KNOWLEDGE.md)
-5. В Figma: Plugins → Development → Import plugin from manifest → выбрать `manifest.json` из папки Matebook
-6. Запуск плагина для теста
+2. Перед сборкой обновляешь patch-версию в `package.json` и `src/ui.tsx` (`PLUGIN_VERSION`)
+3. `npm run build` — сборка должна пройти успешно
+4. `git push` → Gitea (`admin/figma-ai-plugin`)
+5. Собираешь архив из корня проекта, исключая только `node_modules` и `.git`; обязательно включаешь `build/` и сохраняешь структуру каталогов. Проверка перед отправкой: `unzip -l /tmp/figma-ai-plugin.tar.gz` должна показывать `build/main.js`, `build/ui.js`, `manifest.json` — не `main.js` и `ui.js` в корне архива.
+6. Передаёшь архив/файлы на Matebook в staging-папку, затем распаковываешь в `D:\Figma Plugins\figma-ai-plugin\` с сохранением путей. Не отправляй flat ZIP (`zip -j`): он кладёт `main.js`/`ui.js` рядом с манифестом, а Figma загружает `build/main.js`/`build/ui.js`.
+7. После синхронизации обязательно сверяешь SHA-256 удалённых `build/main.js`, `build/ui.js`, `manifest.json` с локальными. Проверяешь в `build/ui.js` маркер новой версии (`0.1.N`). Успешный `scp`/распаковка сами по себе не доказывают, что обновилась папка, из которой загружает Figma.
+8. В Figma: Plugins → Development → Import plugin from manifest → выбрать `manifest.json` из папки Matebook; если уже импортирован — выполнить Reload.
+9. Запустить плагин и проверить версию в статус-баре.
+
+**Важно:** не заканчивай sync на наличии ZIP в `Downloads`. Цель — именно `D:\Figma Plugins\figma-ai-plugin\build\`, откуда Figma читает entrypoints. Подробная проверенная процедура — KNOWLEDGE.md, раздел «Синхронизация билда на Matebook».
 
 ## Правила ведения репозитория
 
diff --git a/KNOWLEDGE.md b/KNOWLEDGE.md
index d2e8da4..9f4b6cb 100644
--- a/KNOWLEDGE.md
+++ b/KNOWLEDGE.md
@@ -6,6 +6,13 @@
 
 ## Сборка / окружение
 
+### Синхронизация билда на Matebook: архив должен сохранять `build/`
+- **Симптом:** архив на Matebook есть, но Figma продолжает показывать старую версию.
+- **Причина:** flat-архив, созданный через `zip -j`, складывает `main.js` и `ui.js` в корень. Распаковка обновляет `manifest.json`, но не заменяет `D:\Figma Plugins\figma-ai-plugin\build\main.js` и `build\ui.js`, на которые ссылается манифест.
+- **Решение:** архивировать из корня проекта с путями (`tar czf /tmp/figma-ai-plugin.tar.gz --exclude=node_modules --exclude=.git .`), проверить список файлов, затем распаковать в целевую папку. Для zip использовать `zip -r`, не `zip -j`. После распаковки сверить SHA-256 локальных и удалённых `build/main.js`, `build/ui.js`, `manifest.json`; дополнительно проверить маркер `0.1.N` в удалённом `build/ui.js`.
+- **Проверка цели:** наличие архива в `C:\Users\risow\Downloads` не является успешным деплоем. Успешный deploy подтверждается только файлами в `D:\Figma Plugins\figma-ai-plugin\build\`.
+- **Ссылка:** IDEA.md, раздел «Рабочий флоу».
+
 ### TypeScript 7.x ломает `@create-figma-plugin/build`
 - **Симптом:** `TypeError: Cannot read properties of undefined (reading 'getCurrentDirectory')` при `build-figma-plugin`.
 - **Причина:** `build-figma-plugin` ожидает `ts.sys`, которого нет в TS 7.