docs: README — document VAD + YAML plugin schema

README.md

@@ -49,10 +49,51 @@ python main.py
 ## Использование
 
 1. Скажите **«Джарвис»** (или **«jarvis»**) — ассистент даст звуковой сигнал готовности.
-2. В течение 10 секунд произнесите команду:
+2. Произнесите команду — окно записи закрывается само, как только вы замолчите (см. ниже про VAD):
    - либо одну из фраз из `commands.yaml` (открыть браузер, выключить звук и т.д.);
    - либо начните со слова **«скажи …»** — остаток фразы уйдёт в Groq, ответ будет зачитан вслух.
 
+## VAD (определение конца команды)
+
+Окно записи команды закрывается по голосовой активности (webrtcvad), а не по таймеру. Параметры в `config.py`:
+
+- `VAD_AGGRESSIVENESS` (0..3) — насколько агрессивно VAD режет шум; по умолчанию 2.
+- `COMMAND_END_SILENCE_MS` — длительность тишины, после которой окно закрывается (по умолчанию 1200 мс).
+- `COMMAND_MIN_SPEECH_MS` — минимальная длительность речи, иначе тишина не считается концом (500 мс).
+- `COMMAND_MIN_LISTEN_MS` — минимальное время записи, чтобы не закрыться мгновенно (1000 мс).
+- `COMMAND_MAX_LISTEN_MS` — жёсткий потолок (15000 мс).
+
+## Схема commands.yaml
+
+Каждая команда — это пара `phrases` + `action`:
+
+```yaml
+open_browser:
+  phrases:
+    - открой браузер
+    - запусти браузер
+  action: {type: exe, file: "Run browser.exe"}
+```
+
+Типы действий:
+
+- `exe` — запустить `.exe` из `custom-commands/`. Поля: `file` (имя файла), необязательные `wait: true` (ждать завершения), `delay_ms` (пауза после запуска). По умолчанию после `exe` проигрывается звук подтверждения `ok` — отключается через `confirm_sound: null`.
+- `play_sound` — проиграть WAV из `sound/`. Поле `name` (без расширения). Имена `greet` и `ok` проигрываются с рандомным выбором из вариантов `greet1/2/3.wav`, `ok1/2/3.wav`.
+- `system` — встроенные операции. `op: volume_mute`, `volume_unmute`, `exit`.
+- `multi` — последовательность шагов: `steps: [...]`.
+
+Шаги внутри `multi` — тех же типов. Пример:
+
+```yaml
+sound_off:
+  phrases: [выключи звук, отключи звук]
+  action:
+    type: multi
+    steps:
+      - {type: play_sound, name: ok}
+      - {type: system, op: volume_mute}
+```
+
 ## Лицензия
 
 CC BY-NC-SA 4.0 — см. [LICENSE.txt](LICENSE.txt). Авторство оригинала — Abraham Tugalov / Priler. Изменения в этом форке — Bossiara13 (Dmitry Bykov), 2026.