docs: command builder README + user-facing README section + run_builder.bat

tools/command_builder/README.md

@@ -0,0 +1,68 @@
+# Конструктор команд (developer notes)
+
+GUI-надстройка для редактирования `commands.yaml` без ручной правки YAML. Запускается отдельным процессом, не зависит от рантайма Jarvis.
+
+## Запуск
+
+```
+python -m tools.command_builder
+```
+
+или из корня репо `run_builder.bat`.
+
+## Стек
+
+- `pywebview` (бэкенд EdgeWebView2 на Windows) — оборачивает локальный HTML.
+- Frontend — vanilla JS + CSS, без сборки. Vendored `js-yaml` только для предпросмотра YAML на стороне UI.
+- `ruamel.yaml` — чтение/запись `commands.yaml` с сохранением комментариев и форматирования.
+- `pyautogui` — рантайм для action-типа `keys`.
+
+## Структура
+
+```
+tools/command_builder/
+  __main__.py        точка входа python -m
+  app.py             pywebview bootstrap + Python bridge (js_api)
+  schema.py          dataclass-схема action-блоков и валидация
+  yaml_writer.py     atomic write + .bak бэкап перед каждой записью
+  llm_suggest.py     Groq/OpenAI SDK 1.x, response_format=json_object
+  web/               frontend
+  tests/             pytest для schema + writer
+```
+
+## Bridge API (методы класса `Bridge` в `app.py`)
+
+Все методы возвращают сериализуемые структуры. Ошибки идут как `{"ok": false, "error": "..."}`.
+
+| метод | назначение |
+|-------|-----------|
+| `list_existing_commands()` | список ключей верхнего уровня в `commands.yaml` |
+| `list_exes()` | basename'ы `*.exe` из `custom-commands/` |
+| `list_sound_names()` | разрешённые имена для `play_sound` (из `schema.VALID_SOUND_NAMES`) |
+| `preview_sound(name)` | проигрывает звук в фоновом потоке через `simpleaudio` |
+| `slugify(phrase)` | транслит для генерации `cmd_id` |
+| `validate_draft(json_str)` | прогон через `command_from_dict` |
+| `save_command(json_str)` | append/upsert + бэкап (`overwrite: true` чтобы перезаписать) |
+| `llm_suggest(prompt)` | Groq → JSON → провалидированный action-блок |
+
+## Расширение схемы (новый тип action)
+
+1. В `schema.py`: добавить dataclass с полем `type` и методом `to_dict()`. Включить в Union `Action`. Расширить `action_from_dict()`.
+2. В `tests/test_schema.py`: добавить roundtrip + negative-case тесты.
+3. В `web/app.js`:
+   - карточка в `#action-grid` (`index.html`);
+   - ветка в `renderActionForm()`;
+   - ветка в `updateAction()`;
+   - ветка в `renderInlineEditor()` для использования внутри multi.steps.
+4. В `main.py` → `run_action()`: обработчик нового `type`.
+5. В `llm_suggest.py` → `_ACTION_SCHEMA_DOC`: описание для LLM.
+
+## Бэкапы
+
+`yaml_writer.append_command` / `upsert_command` перед записью копируют `commands.yaml` в `commands.yaml.bak` (через `shutil.copy2`). При запуске `app.py` вызывается `_check_yaml_health()` — если основной файл не парсится, в stderr печатается путь к `.bak` для ручного восстановления.
+
+## Тесты
+
+```
+.venv\Scripts\python.exe -m pytest tools/command_builder/tests/
+```