verbalcoding 0.2.6 → 0.2.8

package/docs/i18n/CONFIGURATION.ko.md

@@ -1,48 +1,40 @@
-# VerbalCoding 설정 가이드
+# VerbalCoding 설정
 
 ## 설정 마법사
 
-Discord 봇/애플리케이션 생성 절차는 여기에서 처음부터 반복 설명하지 않습니다. Discord 쪽 설정은 아래 상위 문서를 보고 진행한 뒤 VerbalCoding 설정으로 돌아오세요.
+Discord 봇/애플리케이션 설정은 여기서 처음부터 다시 설명하지 않습니다. Discord 쪽 단계는 다음 업스트림 가이드를 사용한 뒤 VerbalCoding 설정으로 돌아오세요:
 
 - Hermes Agent Discord 메시징 가이드: <https://hermes-agent.nousresearch.com/docs/user-guide/messaging/discord>
 - Discord 공식 봇 개요: <https://docs.discord.com/developers/bots/overview>
-- Discord 공식 시작 가이드: <https://docs.discord.com/developers/quick-start/getting-started>
-
-npm으로 설치한 경우:
-
-```bash
-vc setup --yes
-```
-
-GitHub 클론에서 직접 실행하는 경우:
+- Discord 공식 빠른 시작: <https://docs.discord.com/developers/quick-start/getting-started>
 
 ```bash
-./scripts/install.sh --yes
+./scripts/install.sh
 ```
 
-설치기는 Discord 토큰, 허용 사용자, 자동 입장 음성 채널 이름, transcript 채널/스레드, CLI 하네스 백엔드, 기본 음성 언어, TTS 설정, wake word 동작을 묻습니다. 결과는 권한 `0600`의 `.env`에 저장되며, `.env`는 git에서 무시됩니다. 클론 설치에서는 짧은 셸 명령 `vc`도 연결합니다.
+설치 프로그램은 Discord 토큰, 허용 사용자, 자동 참가 음성 채널 이름, 전사 채널/스레드, CLI 하네스 백엔드, 기본 음성 언어, TTS 설정, 웨이크워드 동작을 묻습니다. mode `0600`으로 `.env`를 작성하며, `.env`는 git에서 무시됩니다. 또한 짧은 셸 명령 `vc`도 연결합니다.
 
-수동 설치 후 셸 명령만 연결하려면:
+수동 설치 후 셸 명령만 필요하다면:
 
 ```bash
 npm link
 ```
 
-## 지원 에이전트 백엔드
+## 지원되는 에이전트 백엔드
 
-`.env`에서 `AGENT_BACKEND`를 설정합니다.
+`.env`에서 `AGENT_BACKEND`를 설정하세요.
 
-| 백엔드 | 기본 명령 | 메모 |
+| 백엔드 | 기본 명령 | 참고 |
 |---|---|---|
-| `hermes` | `hermes chat -Q -q` | 기본값. `.verbalcoding-session` resume 동작을 유지합니다. |
-| `claude-code` / `claude` | `claude -p` | `CLAUDE_COMMAND` 또는 `AGENT_COMMAND`로 재정의 가능 |
-| `codex` | `codex exec` | `CODEX_COMMAND` 또는 `AGENT_COMMAND`로 재정의 가능 |
-| `gemini` | `gemini -p` | `GEMINI_COMMAND` 또는 `AGENT_COMMAND`로 재정의 가능 |
-| `opencode` | `opencode run` | `OPENCODE_COMMAND` 또는 `AGENT_COMMAND`로 재정의 가능 |
-| `openclaw` | `openclaw run` | `OPENCLAW_COMMAND` 또는 `AGENT_COMMAND`로 재정의 가능 |
-| `custom` | `AGENT_COMMAND` 필수 | 사용자 prompt가 마지막 argv 인자로 붙습니다. |
+| `hermes` | `hermes chat -Q -q` | 기본값. `.verbalcoding-session` 이어받기 동작을 보존합니다. |
+| `claude-code` / `claude` | `claude -p` | `CLAUDE_COMMAND` 또는 `AGENT_COMMAND`로 재정의. |
+| `codex` | `codex exec` | `CODEX_COMMAND` 또는 `AGENT_COMMAND`로 재정의. |
+| `gemini` | `gemini -p` | `GEMINI_COMMAND` 또는 `AGENT_COMMAND`로 재정의. |
+| `opencode` | `opencode run` | `OPENCODE_COMMAND` 또는 `AGENT_COMMAND`로 재정의. |
+| `openclaw` | `openclaw run` | `OPENCLAW_COMMAND` 또는 `AGENT_COMMAND`로 재정의. |
+| `custom` | 필수 `AGENT_COMMAND` | 프롬프트가 마지막 argv 인자로 추가됩니다. |
 
-공통 override 예시:
+일반 재정의:
 
 ```bash
 AGENT_BACKEND=custom
@@ -57,16 +49,16 @@ LATENCY_LOG_PATH=./.logs/latency.jsonl
 
 ## 에이전트 어댑터 계약
 
-음성 브릿지는 모든 백엔드와 하나의 어댑터 계약으로 통신합니다.
+음성 브리지는 하나의 어댑터 계약을 통해 모든 백엔드와 통신합니다:
 
-- `run({ text }, signal, plan)`은 상태, 최종 답변 텍스트, 백엔드 라벨, elapsed time, 선택적 세션 metadata를 반환합니다.
-- `ask(text, signal, plan)`은 호환용 단축 함수이며 최종 답변 텍스트만 반환합니다.
-- `capabilities`는 해당 백엔드가 session resume, streaming progress, cancellation을 지원하는지 선언합니다.
-- Hermes는 기준 어댑터입니다. resume, verbose progress streaming, cancellation, Hermes 세션 파일에서 최종 답변 복구를 지원합니다.
+- `run({ text }, signal, plan)`은 상태, 최종 답변 텍스트, 백엔드 라벨, 경과 시간, 선택적 세션 메타데이터를 반환합니다.
+- `ask(text, signal, plan)`은 최종 답변 텍스트만 반환하는 호환성 단축 함수입니다.
+- `capabilities`는 백엔드가 세션 이어받기, 스트리밍 진행, 취소를 지원하는지 선언합니다.
+- Hermes는 참조 어댑터입니다: 이어받기, 자세한 진행 스트리밍, 취소, Hermes 세션 파일에서 최종 답변 복구.
 
-새 백엔드는 같은 계약을 구현하고, voice/STT/TTS 동작은 어댑터 밖에 유지하는 것이 좋습니다.
+새 백엔드는 동일한 계약을 구현하고 음성/STT/TTS 동작은 어댑터 밖에 유지해야 합니다.
 
-## 예시 `.env`
+## `.env` 예시
 
 ```bash
 DISCORD_BOT_TOKEN="***"
@@ -95,15 +87,15 @@ AGENT_VERBOSE_PROGRESS="0"
 LATENCY_LOG_PATH="./.logs/latency.jsonl"
 ```
 
-## TTS 목소리 선택
+## TTS 음성 선택
 
-언어 프리셋과 목소리 선택은 분리되어 있습니다.
+언어 프리셋과 음성 선택은 별개입니다:
 
-- `vc language ko|en|auto`는 STT 언어, 진행 언어, 해당 언어의 기본 목소리를 함께 바꿉니다.
-- “남자 한국어 목소리로 바꿔”, “여자 한국어 목소리로 바꿔”, `change voice to Korean female`, `switch speaker to English` 같은 실시간 음성 명령은 말하는 사람/목소리 타입만 바꿉니다.
-- `!voice-test <text>`는 현재 선택된 백엔드와 목소리로 짧은 샘플을 재생합니다.
+- `vc language ko|en|auto`는 STT 언어, 진행 언어, 해당 언어의 기본 음성을 변경합니다.
+- “남자 한국어 목소리로 바꿔”, “여자 한국어 목소리로 바꿔”, `change voice to Korean female`, `switch speaker to English` 같은 라이브 음성 명령은 화자/음성 유형만 변경합니다.
+- `!voice-test <text>`는 현재 선택된 백엔드와 음성으로 빠른 샘플을 재생합니다.
 
-목소리 선택은 기본적으로 `config/tts-voices.json`에 저장됩니다. 경로는 `TTS_VOICE_CONFIG`로 바꿀 수 있습니다. 실행 중인 브릿지는 합성 직전에 목소리 선택을 다시 적용하므로, 음성 명령으로 바꾼 목소리는 전체 재시작 없이 바로 반영됩니다.
+음성 선택은 기본적으로 `config/tts-voices.json`에 저장됩니다. `TTS_VOICE_CONFIG`로 경로를 재정의하세요. 실행 중인 브리지는 합성 전에 음성 선택을 다시 읽고 적용하므로, 전체 재시작 없이도 음성 명령이 적용됩니다.
 
 기본 Edge 카탈로그:
 
@@ -115,7 +107,7 @@ LATENCY_LOG_PATH="./.logs/latency.jsonl"
 | `english_male` | `en-US-GuyNeural` | 영어 |
 | `english_female` | `en-US-AriaNeural` | 영어 |
 
-수동 영구 override 예시:
+수동 영구 재정의:
 
 ```bash
 TTS_BACKEND="edge"
@@ -124,29 +116,29 @@ TTS_VOICE="ko-KR-InJoonNeural"
 TTS_VOICE_CONFIG="config/tts-voices.json"
 ```
 
-OpenVoice, SpeechSwift, Supertonic을 쓸 때는 아래 백엔드별 reference/voice 설정을 유지하세요. 같은 voice catalog 파일에서 현재 voice type을 추적할 수 있습니다.
+OpenVoice, SpeechSwift 또는 Supertonic의 경우 아래 섹션의 백엔드별 음성/참조 설정을 유지하세요. 동일한 음성 카탈로그 파일은 여전히 활성 음성 유형을 추적할 수 있습니다.
 
-백엔드별 목소리 옵션:
+백엔드별 음성 옵션:
 
-| 백엔드 | 설정 | 목소리 선택지 |
+| 백엔드 | 설정 | 음성 선택지 |
 |---|---|---|
-| Edge | `TTS_VOICE_TYPE`, `TTS_VOICE` | 위 기본 타입, 또는 `edge-tts --list-voices`가 반환하는 모든 voice |
+| Edge | `TTS_VOICE_TYPE`, `TTS_VOICE` | 위 내장 유형 및 `edge-tts --list-voices`가 반환하는 모든 음성 |
 | Supertonic | `SUPERTONIC_VOICE`, `SUPERTONIC_LANGUAGE` | `M1`–`M5`, `F1`–`F5`; 언어 `ko`, `en`, `es`, `pt`, `fr` |
-| OpenVoice | `OPENVOICE_REF_AUDIO`, `OPENVOICE_STYLE`, `OPENVOICE_LANGUAGE` | 사용자가 제공한 허가된 reference WAV; style 기본값은 `default` |
-| SpeechSwift / CosyVoice | `SPEECHSWIFT_REF_AUDIO`, `SPEECHSWIFT_ENGINE`, `SPEECHSWIFT_SPEAKER`, `SPEECHSWIFT_MODEL_ID` | CosyVoice reference sample voice 또는 백엔드가 지원하는 speaker/model ID |
+| OpenVoice | `OPENVOICE_REF_AUDIO`, `OPENVOICE_STYLE`, `OPENVOICE_LANGUAGE` | 사용자가 제공한 허용된 참조 WAV; 스타일 기본값은 `default` |
+| SpeechSwift / CosyVoice | `SPEECHSWIFT_REF_AUDIO`, `SPEECHSWIFT_ENGINE`, `SPEECHSWIFT_SPEAKER`, `SPEECHSWIFT_MODEL_ID` | CosyVoice용 참조 샘플 음성 또는 백엔드가 지원하는 화자/모델 ID |
 
-## 발화 분리 설정
+## 발화 분할
 
-`UTTERANCE_IDLE_MS`는 음성 segment가 끝난 뒤 사용자의 말이 끝났다고 판단하고 STT를 시작하기 전까지 기다리는 시간입니다. 기본값은 `4500` ms입니다. 긴 지시 중 자연스러운 멈춤을 보존하기 위한 값입니다. 낮추면 짧은 명령 반응은 빨라지지만 긴 발화가 잘릴 수 있고, 높이면 생각하면서 말하는 긴 dictation에 더 안전합니다.
+`UTTERANCE_IDLE_MS`는 음성 구간 이후 사용자가 말을 끝냈다고 판단하고 STT를 시작하기 전까지 브리지가 기다리는 시간을 제어합니다. 기본값은 자연스러운 멈춤이 있는 긴 음성 지시를 보존하기 위해 `4500` ms입니다. 낮은 값은 짧은 명령에서 더 빠르게 느껴지지만 긴 받아쓰기를 나눌 수 있고, 높은 값은 생각하며 말할 때 더 안전합니다.
 
 ```bash
 UTTERANCE_IDLE_MS="4500"  # 균형 잡힌 기본값
-UTTERANCE_IDLE_MS="6000"  # 중간 멈춤이 있는 긴 발화에 더 안전
+UTTERANCE_IDLE_MS="6000"  # 멈춤이 있는 긴 받아쓰기에 더 안전
 ```
 
 ## MCP 서버
 
-VerbalCoding은 stdio MCP 서버를 포함합니다. Hermes Agent 또는 MCP client는 자유 형식 shell 명령 대신 도구로 브릿지를 제어할 수 있습니다.
+VerbalCoding은 stdio MCP 서버를 포함하므로 Hermes Agent 또는 모든 MCP 클라이언트가 skill이나 자유 형식 셸 명령에 의존하지 않고 도구를 통해 브리지를 제어할 수 있습니다.
 
 Hermes 설정 예시:
 
@@ -161,28 +153,28 @@ mcp_servers:
 
 노출되는 MCP 도구:
 
-| 도구 | 용도 |
+| 도구 | 목적 |
 |---|---|
-| `status` | 비밀값 없이 브릿지/설정 상태 보고 |
-| `doctor` | 비밀값을 숨긴 doctor 점검 실행 |
-| `set_auto_restart` | 커밋 시 음성 봇 자동 재시작 켜기/끄기 |
-| `set_language` | STT/진행/TTS 언어를 함께 변경 |
-| `start`, `stop`, `restart` | Discord 음성 브릿지 제어 |
+| `status` | 비밀 정보 없이 브리지/설정 상태 보고 |
+| `doctor` | 민감 정보가 제거된 doctor 점검 실행 |
+| `set_auto_restart` | 커밋 시점 음성 봇 자동 재시작 활성화/비활성화 |
+| `set_language` | STT/진행/TTS 언어를 함께 업데이트 |
+| `start`, `stop`, `restart` | Discord 음성 브리지 제어 |
 
-## 선택: OpenVoice TTS
+## 선택 사항: OpenVoice TTS
 
-Edge TTS가 기본값이자 fallback입니다. OpenVoice V2로 로컬 음성 복제를 시험하려면:
+Edge TTS는 기본값이자 폴백으로 유지됩니다. OpenVoice V2로 로컬 음성 복제를 시도하려면:
 
 ```bash
 ./scripts/setup_openvoice.sh
-# OpenVoice 문서에서 checkpoints_v2_0417.zip을 받아 vendor/OpenVoice/checkpoints_v2/ 아래에 풉니다.
+# OpenVoice 문서에서 checkpoints_v2_0417.zip을 다운로드하고 vendor/OpenVoice/checkpoints_v2/ 아래에 압축을 풉니다.
 mkdir -p voice-samples
-# 허가된 기준 샘플을 voice-samples/user-reference.wav에 넣거나,
-# Discord에서 !voice-clone capture로 샘플을 캡처합니다.
+# 허용된 참조 샘플을 voice-samples/user-reference.wav에 넣거나,
+# Discord에서 !voice-clone capture로 하나를 캡처합니다.
 python3 integrations/openvoice/synth.py --openvoice-dir vendor/OpenVoice --ref-audio voice-samples/user-reference.wav --text '안녕하세요. 버벌코딩 목소리 복제 테스트입니다.' --output /tmp/verbalcoding-openvoice-smoke.wav
 ```
 
-그 뒤 설정:
+그런 다음 다음을 설정하세요:
 
 ```bash
 TTS_BACKEND="openvoice"
@@ -190,16 +182,16 @@ OPENVOICE_REF_AUDIO="./voice-samples/user-reference.wav"
 OPENVOICE_PROGRESS="0"
 ```
 
-본인 소유이거나 사용 허가를 받은 목소리만 복제하세요. OpenVoice가 실패하거나 timeout되면 VerbalCoding은 Edge TTS로 fallback합니다.
+본인이 소유했거나 사용할 권한이 있는 음성만 복제하세요. OpenVoice가 실패하거나 시간이 초과되면 VerbalCoding은 Edge TTS로 폴백합니다.
 
-## 선택: Supertonic TTS
+## 선택 사항: Supertonic TTS
 
 ```bash
 ./scripts/setup_supertonic.sh
 supertonic tts '안녕하세요. 수퍼토닉 테스트입니다.' --lang ko --voice M1 --steps 2 --speed 1.0 -o /tmp/verbalcoding-supertonic.wav
 ```
 
-그 뒤 설정:
+그런 다음 다음을 설정하세요:
 
 ```bash
 TTS_BACKEND="supertonic"
@@ -211,11 +203,11 @@ SUPERTONIC_SPEED="1.0"
 SUPERTONIC_PROGRESS="0"
 ```
 
-Supertonic이 없거나 실패하거나 timeout되면 VerbalCoding은 Edge TTS로 fallback합니다.
+Supertonic이 없거나 실패하거나 시간이 초과되면 VerbalCoding은 Edge TTS로 폴백합니다.
 
-## 선택: SpeechSwift / CosyVoice TTS
+## 선택 사항: SpeechSwift / CosyVoice TTS
 
-Apple Silicon에서는 `speech-swift`가 MLX-native CosyVoice/Qwen3-TTS 기반 한국어 음성 복제용 로컬 백엔드로 동작할 수 있습니다.
+Apple Silicon에서 `speech-swift`는 MLX 네이티브 CosyVoice/Qwen3-TTS를 사용하는 한국어 음성 복제용 로컬 백엔드입니다.
 
 ```bash
 brew tap soniqo/speech https://github.com/soniqo/speech-swift
@@ -236,12 +228,12 @@ SPEECHSWIFT_SERVER_URL="http://127.0.0.1:18080"
 SPEECHSWIFT_PROGRESS="0"
 ```
 
-빠른 진행/짧은 backchannel prompt는 Edge를 유지하는 편이 안전합니다.
+빠른 진행/백채널 프롬프트에는 Edge를 유지하세요.
 
-## 운영 메모
+## 운영 참고 사항
 
-- 텍스트 명령을 쓰려면 Discord bot의 privileged Message Content intent가 켜져 있어야 합니다.
-- 봇에는 음성 채널 connect/speak 권한이 필요합니다.
-- Hermes Agent를 쓴다면 기본 프로필에서 Hermes를 정상 설정/인증하세요. 예: `hermes setup`, `hermes login` 등.
-- Claude Code, Codex, Gemini, OpenCode, OpenClaw를 쓰려면 해당 CLI를 별도로 설치하고 인증하세요.
-- CLI가 timeout 또는 signal 실패 중 diff/code를 출력하면 브릿지는 그 내용을 음성으로 읽지 않고 자세한 텍스트로만 보냅니다.
+- 봇은 텍스트 명령을 위해 Discord privileged Message Content intent가 활성화되어 있어야 합니다.
+- 봇은 음성 채널 connect/speak 권한이 필요합니다.
+- Hermes Agent의 경우 기본 프로필에서 Hermes를 일반적인 방식으로 설정/인증하세요(`hermes setup`, `hermes login` 등).
+- Claude Code, Codex, Gemini, OpenCode, OpenClaw의 경우 해당 CLI를 별도로 설치하고 인증하세요.
+- CLI가 시간 초과 또는 signal 실패 시 diff/code 출력을 내보내면, 브리지는 이를 소리 내어 읽지 않고 자세한 텍스트를 대신 보냅니다.

package/docs/i18n/CONFIGURATION.ru.md

@@ -0,0 +1,239 @@
+# Конфигурация VerbalCoding
+
+## Мастер настройки
+
+Настройка Discord-бота/приложения намеренно не объясняется здесь с нуля. Используйте эти исходные руководства для шагов на стороне Discord, затем вернитесь к настройке VerbalCoding:
+
+- Руководство Hermes Agent по сообщениям Discord: <https://hermes-agent.nousresearch.com/docs/user-guide/messaging/discord>
+- Официальный обзор ботов Discord: <https://docs.discord.com/developers/bots/overview>
+- Официальный quick start Discord: <https://docs.discord.com/developers/quick-start/getting-started>
+
+```bash
+./scripts/install.sh
+```
+
+Установщик спрашивает токен Discord, разрешённых пользователей, имена голосовых каналов для автоподключения, канал/тред расшифровок, бэкенд CLI-харнеса, язык голоса по умолчанию, настройки TTS и поведение wake-word. Он записывает `.env` с режимом `0600`; `.env` игнорируется git. Он также связывает короткую shell-команду `vc`.
+
+Если после ручной установки вам нужна только shell-команда:
+
+```bash
+npm link
+```
+
+## Поддерживаемые бэкенды агентов
+
+Задайте `AGENT_BACKEND` в `.env`.
+
+| Бэкенд | Команда по умолчанию | Примечания |
+|---|---|---|
+| `hermes` | `hermes chat -Q -q` | По умолчанию. Сохраняет поведение возобновления `.verbalcoding-session`. |
+| `claude-code` / `claude` | `claude -p` | Переопределяется через `CLAUDE_COMMAND` или `AGENT_COMMAND`. |
+| `codex` | `codex exec` | Переопределяется через `CODEX_COMMAND` или `AGENT_COMMAND`. |
+| `gemini` | `gemini -p` | Переопределяется через `GEMINI_COMMAND` или `AGENT_COMMAND`. |
+| `opencode` | `opencode run` | Переопределяется через `OPENCODE_COMMAND` или `AGENT_COMMAND`. |
+| `openclaw` | `openclaw run` | Переопределяется через `OPENCLAW_COMMAND` или `AGENT_COMMAND`. |
+| `custom` | требуется `AGENT_COMMAND` | Prompt добавляется как финальный аргумент argv. |
+
+Общие переопределения:
+
+```bash
+AGENT_BACKEND=custom
+AGENT_LABEL="My Harness"
+AGENT_COMMAND="my-harness run --non-interactive"
+AGENT_TASK_TIMEOUT_MS=0
+AGENT_CHAT_TIMEOUT_MS=45000
+AGENT_VERBOSE_PROGRESS=0
+UTTERANCE_IDLE_MS=4500
+LATENCY_LOG_PATH=./.logs/latency.jsonl
+```
+
+## Контракт адаптера агента
+
+Голосовой bridge взаимодействует с каждым бэкендом через единый контракт адаптера:
+
+- `run({ text }, signal, plan)` возвращает статус, текст финального ответа, метку бэкенда, прошедшее время и необязательные метаданные сессии.
+- `ask(text, signal, plan)` — совместимый короткий путь, который возвращает только текст финального ответа.
+- `capabilities` объявляет, поддерживает ли бэкенд возобновление сессии, потоковый прогресс и отмену.
+- Hermes — эталонный адаптер: возобновление, потоковый подробный прогресс, отмена и восстановление финального ответа из файлов сессий Hermes.
+
+Новые бэкенды должны реализовывать тот же контракт и держать поведение voice/STT/TTS вне адаптера.
+
+## Пример `.env`
+
+```bash
+DISCORD_BOT_TOKEN="***"
+DISCORD_ALLOWED_USERS="123456789012345678"
+AUTO_JOIN_VOICE_CHANNELS="일반,General,general"
+TRANSCRIPT_CHANNEL_ID="123456789012345678"
+
+AGENT_BACKEND="hermes"
+STT_ENGINE="whisper_cpp"
+WHISPER_CPP_BIN="whisper-cli"
+WHISPER_CPP_MODEL="./models/ggml-small-q5_1.bin"
+
+TTS_BACKEND="edge"
+TTS_VOICE_TYPE="korean_female"
+TTS_VOICE="ko-KR-SunHiNeural"
+TTS_RATE="+10%"
+TTS_MAX_CHARS="495"
+TTS_VOLUME="1.0"
+
+REQUIRE_WAKE_WORD="0"
+MIN_UTTERANCE_SECONDS="1.0"
+UTTERANCE_IDLE_MS="4500"
+HERMES_TASK_TIMEOUT_MS="0"
+HERMES_CHAT_TIMEOUT_MS="45000"
+AGENT_VERBOSE_PROGRESS="0"
+LATENCY_LOG_PATH="./.logs/latency.jsonl"
+```
+
+## Выбор голоса TTS
+
+Языковые пресеты и выбор голоса разделены:
+
+- `vc language ko|en|auto` меняет язык STT, язык прогресса и голос по умолчанию для этого языка.
+- Живые голосовые команды вроде “남자 한국어 목소리로 바꿔”, “여자 한국어 목소리로 바꿔”, `change voice to Korean female` и `switch speaker to English` меняют только диктора/тип голоса.
+- `!voice-test <text>` воспроизводит быстрый образец с текущим выбранным бэкендом и голосом.
+
+Выбор голоса по умолчанию хранится в `config/tts-voices.json`. Переопределите путь через `TTS_VOICE_CONFIG`. Работающий bridge перечитывает/применяет выбор голоса перед синтезом, поэтому голосовые команды вступают в силу без полного перезапуска.
+
+Стандартный каталог Edge:
+
+| `TTS_VOICE_TYPE` | `TTS_VOICE` | Язык |
+|---|---|---|
+| `korean_male` | `ko-KR-InJoonNeural` | Корейский |
+| `korean_female` | `ko-KR-SunHiNeural` | Корейский |
+| `korean_multilingual_male` | `ko-KR-HyunsuMultilingualNeural` | Корейский |
+| `english_male` | `en-US-GuyNeural` | Английский |
+| `english_female` | `en-US-AriaNeural` | Английский |
+
+Постоянное ручное переопределение:
+
+```bash
+TTS_BACKEND="edge"
+TTS_VOICE_TYPE="korean_male"
+TTS_VOICE="ko-KR-InJoonNeural"
+TTS_VOICE_CONFIG="config/tts-voices.json"
+```
+
+Для OpenVoice, SpeechSwift или Supertonic храните специфичные для бэкенда настройки голоса/референса в разделах ниже; тот же файл каталога голосов всё равно может отслеживать активный тип голоса.
+
+Голосовые параметры для конкретных бэкендов:
+
+| Бэкенд | Настройки | Варианты голосов |
+|---|---|---|
+| Edge | `TTS_VOICE_TYPE`, `TTS_VOICE` | Встроенные типы выше, плюс любой голос, возвращаемый `edge-tts --list-voices` |
+| Supertonic | `SUPERTONIC_VOICE`, `SUPERTONIC_LANGUAGE` | `M1`–`M5`, `F1`–`F5`; язык `ko`, `en`, `es`, `pt`, `fr` |
+| OpenVoice | `OPENVOICE_REF_AUDIO`, `OPENVOICE_STYLE`, `OPENVOICE_LANGUAGE` | Предоставленный пользователем разрешённый референсный WAV; стиль по умолчанию `default` |
+| SpeechSwift / CosyVoice | `SPEECHSWIFT_REF_AUDIO`, `SPEECHSWIFT_ENGINE`, `SPEECHSWIFT_SPEAKER`, `SPEECHSWIFT_MODEL_ID` | Голоса на базе референсных образцов для CosyVoice или поддерживаемые бэкендом ID диктора/модели |
+
+## Сегментация реплик
+
+`UTTERANCE_IDLE_MS` управляет тем, как долго bridge ждёт после речевого сегмента, прежде чем решить, что пользователь закончил, и запустить STT. Значение по умолчанию — `4500` мс, чтобы сохранять длинные произнесённые инструкции с естественными паузами. Более низкие значения ощущаются быстрее для коротких команд, но могут разделять длинную диктовку; более высокие безопаснее для вдумчивой речи.
+
+```bash
+UTTERANCE_IDLE_MS="4500"  # balanced default
+UTTERANCE_IDLE_MS="6000"  # safer for long dictation with pauses
+```
+
+## MCP-сервер
+
+VerbalCoding поставляется со stdio MCP-сервером, чтобы Hermes Agent или любой MCP-клиент мог управлять bridge через инструменты, а не полагаться на skills или свободные shell-команды.
+
+Пример конфигурации Hermes:
+
+```yaml
+mcp_servers:
+  verbalcoding:
+    command: "node"
+    args: ["/path/to/VerbalCoding/scripts/mcp-server.mjs"]
+    timeout: 120
+    connect_timeout: 30
+```
+
+Доступные MCP-инструменты:
+
+| Инструмент | Назначение |
+|---|---|
+| `status` | Сообщить статус bridge/конфигурации без секретов |
+| `doctor` | Запустить doctor-проверку с редактированием секретов |
+| `set_auto_restart` | Включить/выключить автоперезапуск голосового бота при коммите |
+| `set_language` | Обновить STT/прогресс/TTS язык вместе |
+| `start`, `stop`, `restart` | Управлять голосовым bridge Discord |
+
+## Необязательный TTS OpenVoice
+
+Edge TTS остаётся стандартным и резервным вариантом. Чтобы попробовать локальное клонирование голоса с OpenVoice V2:
+
+```bash
+./scripts/setup_openvoice.sh
+# Download checkpoints_v2_0417.zip from OpenVoice docs and extract under vendor/OpenVoice/checkpoints_v2/
+mkdir -p voice-samples
+# Put a permitted reference sample at voice-samples/user-reference.wav,
+# or capture one from Discord with !voice-clone capture.
+python3 integrations/openvoice/synth.py --openvoice-dir vendor/OpenVoice --ref-audio voice-samples/user-reference.wav --text '안녕하세요. 버벌코딩 목소리 복제 테스트입니다.' --output /tmp/verbalcoding-openvoice-smoke.wav
+```
+
+Затем задайте:
+
+```bash
+TTS_BACKEND="openvoice"
+OPENVOICE_REF_AUDIO="./voice-samples/user-reference.wav"
+OPENVOICE_PROGRESS="0"
+```
+
+Клонируйте только голоса, которыми вы владеете или на использование которых у вас есть разрешение. Если OpenVoice завершается ошибкой или по таймауту, VerbalCoding возвращается к Edge TTS.
+
+## Необязательный TTS Supertonic
+
+```bash
+./scripts/setup_supertonic.sh
+supertonic tts '안녕하세요. 수퍼토닉 테스트입니다.' --lang ko --voice M1 --steps 2 --speed 1.0 -o /tmp/verbalcoding-supertonic.wav
+```
+
+Затем задайте:
+
+```bash
+TTS_BACKEND="supertonic"
+SUPERTONIC_COMMAND="./.venv-supertonic/bin/supertonic"
+SUPERTONIC_VOICE="M1"
+SUPERTONIC_LANGUAGE="ko"
+SUPERTONIC_STEPS="2"
+SUPERTONIC_SPEED="1.0"
+SUPERTONIC_PROGRESS="0"
+```
+
+Если Supertonic отсутствует, завершается ошибкой или по таймауту, VerbalCoding возвращается к Edge TTS.
+
+## Необязательный TTS SpeechSwift / CosyVoice
+
+На Apple Silicon `speech-swift` — локальный бэкенд для корейского клонирования голоса с MLX-native CosyVoice/Qwen3-TTS.
+
+```bash
+brew tap soniqo/speech https://github.com/soniqo/speech-swift
+brew install speech
+```
+
+Рекомендуемое окружение:
+
+```bash
+TTS_BACKEND="speechswift"
+SPEECHSWIFT_MODE="server"
+SPEECHSWIFT_ENGINE="cosyvoice"
+SPEECHSWIFT_LANGUAGE="korean"
+SPEECHSWIFT_REF_AUDIO="./voice-samples/user-reference.wav"
+SPEECHSWIFT_SERVER_HOST="127.0.0.1"
+SPEECHSWIFT_SERVER_PORT="18080"
+SPEECHSWIFT_SERVER_URL="http://127.0.0.1:18080"
+SPEECHSWIFT_PROGRESS="0"
+```
+
+Оставьте Edge для быстрых подсказок прогресса/backchannel.
+
+## Эксплуатационные заметки
+
+- Боту нужен включённый привилегированный Discord intent Message Content для текстовых команд.
+- Боту нужны разрешения connect/speak в голосовом канале.
+- Для Hermes Agent настройте/аутентифицируйте Hermes обычным образом (`hermes setup`, `hermes login` и т. п.) в профиле по умолчанию.
+- Для Claude Code, Codex, Gemini, OpenCode, OpenClaw установите и аутентифицируйте эти CLI отдельно.
+- Если CLI выводит diff/code при таймауте или сбое сигнала, bridge не читает это вслух и вместо этого отправляет подробный текст.