verbalcoding 0.2.7 → 0.2.9

package/docs/i18n/CONFIGURATION.fr.md

@@ -1,36 +1,40 @@
-# VerbalCoding Configuration
+# Configuration de VerbalCoding
 
-## Setup Wizard
+## Assistant de configuration
 
-Use upstream Discord-side guides first, then return to VerbalCoding:
+La configuration du bot/de l'application Discord n'est volontairement pas réexpliquée depuis zéro ici. Utilisez ces guides amont pour les étapes côté Discord, puis revenez à la configuration de VerbalCoding :
 
-- Hermes Agent Discord messaging guide: <https://hermes-agent.nousresearch.com/docs/user-guide/messaging/discord>
-- Discord official bot overview: <https://docs.discord.com/developers/bots/overview>
-- Discord official quick start: <https://docs.discord.com/developers/quick-start/getting-started>
+- Guide de messagerie Discord de Hermes Agent : <https://hermes-agent.nousresearch.com/docs/user-guide/messaging/discord>
+- Vue d'ensemble officielle des bots Discord : <https://docs.discord.com/developers/bots/overview>
+- Démarrage rapide officiel Discord : <https://docs.discord.com/developers/quick-start/getting-started>
 
 ```bash
-vc setup --yes
-# or from a clone
 ./scripts/install.sh
 ```
 
-The installer asks for the Discord token, allowed users, auto-join voice channel names, transcript channel/thread, CLI harness backend, default voice language, TTS settings, and wake-word behavior. It writes `.env` with mode `0600`.
+L'installateur demande le jeton Discord, les utilisateurs autorisés, les noms de salons vocaux à rejoindre automatiquement, le salon/fil de transcription, le backend de harnais CLI, la langue vocale par défaut, les paramètres TTS et le comportement du mot de réveil. Il écrit `.env` avec le mode `0600` ; `.env` est ignoré par git. Il lie aussi la commande shell courte `vc`.
 
-## Supported Agent Backends
+Si vous avez seulement besoin de la commande shell après une installation manuelle :
 
-Set `AGENT_BACKEND` in `.env`.
+```bash
+npm link
+```
+
+## Backends d'agents pris en charge
 
-| Backend | Default command | Notes |
+Définissez `AGENT_BACKEND` dans `.env`.
+
+| Backend | Commande par défaut | Notes |
 |---|---|---|
-| `hermes` | `hermes chat -Q -q` | Default; supports resume and verbose progress |
-| `claude-code` / `claude` | `claude -p` | Override with `CLAUDE_COMMAND` or `AGENT_COMMAND` |
-| `codex` | `codex exec` | Override with `CODEX_COMMAND` or `AGENT_COMMAND` |
-| `gemini` | `gemini -p` | Override with `GEMINI_COMMAND` or `AGENT_COMMAND` |
-| `opencode` | `opencode run` | Override with `OPENCODE_COMMAND` or `AGENT_COMMAND` |
-| `openclaw` | `openclaw run` | Override with `OPENCLAW_COMMAND` or `AGENT_COMMAND` |
-| `custom` | `AGENT_COMMAND` required | Prompt is appended as final argv |
+| `hermes` | `hermes chat -Q -q` | Par défaut. Préserve le comportement de reprise `.verbalcoding-session`. |
+| `claude-code` / `claude` | `claude -p` | Remplacer avec `CLAUDE_COMMAND` ou `AGENT_COMMAND`. |
+| `codex` | `codex exec` | Remplacer avec `CODEX_COMMAND` ou `AGENT_COMMAND`. |
+| `gemini` | `gemini -p` | Remplacer avec `GEMINI_COMMAND` ou `AGENT_COMMAND`. |
+| `opencode` | `opencode run` | Remplacer avec `OPENCODE_COMMAND` ou `AGENT_COMMAND`. |
+| `openclaw` | `openclaw run` | Remplacer avec `OPENCLAW_COMMAND` ou `AGENT_COMMAND`. |
+| `custom` | `AGENT_COMMAND` requis | Le prompt est ajouté comme dernier argument argv. |
 
-Generic overrides:
+Remplacements génériques :
 
 ```bash
 AGENT_BACKEND=custom
@@ -43,23 +47,37 @@ UTTERANCE_IDLE_MS=4500
 LATENCY_LOG_PATH=./.logs/latency.jsonl
 ```
 
-## Example `.env`
+## Contrat des adaptateurs d'agent
+
+La passerelle vocale parle à chaque backend via un seul contrat d'adaptateur :
+
+- `run({ text }, signal, plan)` renvoie le statut, le texte de réponse finale, le libellé du backend, le temps écoulé et des métadonnées de session facultatives.
+- `ask(text, signal, plan)` est le raccourci de compatibilité qui renvoie seulement le texte de réponse finale.
+- `capabilities` déclare si le backend prend en charge la reprise de session, la progression en streaming et l'annulation.
+- Hermes est l'adaptateur de référence : reprise, streaming de progression détaillée, annulation et récupération de la réponse finale depuis les fichiers de session Hermes.
+
+Les nouveaux backends doivent implémenter le même contrat et garder le comportement voix/STT/TTS hors de l'adaptateur.
+
+## Exemple `.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"
@@ -69,39 +87,60 @@ AGENT_VERBOSE_PROGRESS="0"
 LATENCY_LOG_PATH="./.logs/latency.jsonl"
 ```
 
-## TTS Voice Selection
+## Sélection de la voix TTS
+
+Les préréglages de langue et la sélection de voix sont séparés :
 
-`vc language ko|en|auto` changes STT language, progress language, and default TTS voice. Live commands such as “남자 한국어 목소리로 바꿔”, “여자 한국어 목소리로 바꿔”, `change voice to Korean female`, and `switch speaker to English` change only the speaker/voice type.
+- `vc language ko|en|auto` change la langue STT, la langue de progression et la voix par défaut pour cette langue.
+- Les commandes vocales en direct comme “남자 한국어 목소리로 바꿔”, “여자 한국어 목소리로 바꿔”, `change voice to Korean female` et `switch speaker to English` ne changent que le locuteur/type de voix.
+- `!voice-test <text>` joue un court échantillon avec le backend et la voix actuellement sélectionnés.
 
-Default Edge catalog:
+La sélection de voix est stockée par défaut dans `config/tts-voices.json`. Remplacez le chemin avec `TTS_VOICE_CONFIG`. La passerelle en cours d'exécution relit/applique la sélection de voix avant la synthèse, donc les commandes vocales prennent effet sans redémarrage complet.
 
-| `TTS_VOICE_TYPE` | `TTS_VOICE` | Language |
+Catalogue Edge par défaut :
+
+| `TTS_VOICE_TYPE` | `TTS_VOICE` | Langue |
 |---|---|---|
-| `korean_male` | `ko-KR-InJoonNeural` | Korean |
-| `korean_female` | `ko-KR-SunHiNeural` | Korean |
-| `korean_multilingual_male` | `ko-KR-HyunsuMultilingualNeural` | Korean |
-| `english_male` | `en-US-GuyNeural` | English |
-| `english_female` | `en-US-AriaNeural` | English |
+| `korean_male` | `ko-KR-InJoonNeural` | Coréen |
+| `korean_female` | `ko-KR-SunHiNeural` | Coréen |
+| `korean_multilingual_male` | `ko-KR-HyunsuMultilingualNeural` | Coréen |
+| `english_male` | `en-US-GuyNeural` | Anglais |
+| `english_female` | `en-US-AriaNeural` | Anglais |
+
+Remplacement manuel persistant :
+
+```bash
+TTS_BACKEND="edge"
+TTS_VOICE_TYPE="korean_male"
+TTS_VOICE="ko-KR-InJoonNeural"
+TTS_VOICE_CONFIG="config/tts-voices.json"
+```
 
-Backend-specific voice options:
+Pour OpenVoice, SpeechSwift ou Supertonic, conservez les paramètres de voix/référence propres au backend dans les sections ci-dessous ; le même fichier de catalogue de voix peut tout de même suivre le type de voix actif.
 
-| Backend | Settings | Voice choices |
+Options vocales propres au backend :
+
+| Backend | Paramètres | Choix de voix |
 |---|---|---|
-| Edge | `TTS_VOICE_TYPE`, `TTS_VOICE` | Built-in types plus any `edge-tts --list-voices` voice |
-| Supertonic | `SUPERTONIC_VOICE`, `SUPERTONIC_LANGUAGE` | `M1`–`M5`, `F1`–`F5`; `ko`, `en`, `es`, `pt`, `fr` |
-| OpenVoice | `OPENVOICE_REF_AUDIO`, `OPENVOICE_STYLE`, `OPENVOICE_LANGUAGE` | User-provided permitted reference WAV |
-| SpeechSwift / CosyVoice | `SPEECHSWIFT_REF_AUDIO`, `SPEECHSWIFT_ENGINE`, `SPEECHSWIFT_SPEAKER`, `SPEECHSWIFT_MODEL_ID` | Reference-sample voice or backend speaker/model ID |
+| Edge | `TTS_VOICE_TYPE`, `TTS_VOICE` | Types intégrés ci-dessus, plus toute voix renvoyée par `edge-tts --list-voices` |
+| Supertonic | `SUPERTONIC_VOICE`, `SUPERTONIC_LANGUAGE` | `M1`–`M5`, `F1`–`F5` ; langue `ko`, `en`, `es`, `pt`, `fr` |
+| OpenVoice | `OPENVOICE_REF_AUDIO`, `OPENVOICE_STYLE`, `OPENVOICE_LANGUAGE` | WAV de référence autorisé fourni par l'utilisateur ; style par défaut `default` |
+| SpeechSwift / CosyVoice | `SPEECHSWIFT_REF_AUDIO`, `SPEECHSWIFT_ENGINE`, `SPEECHSWIFT_SPEAKER`, `SPEECHSWIFT_MODEL_ID` | Voix par échantillon de référence pour CosyVoice, ou IDs locuteur/modèle pris en charge par le backend |
 
-## Utterance Segmentation
+## Segmentation des énonciations
 
-`UTTERANCE_IDLE_MS` controls how long the bridge waits after speech before starting STT. Default is `4500` ms.
+`UTTERANCE_IDLE_MS` contrôle combien de temps la passerelle attend après un segment de parole avant de décider que l'utilisateur a terminé et de démarrer le STT. La valeur par défaut est `4500` ms afin de préserver les longues instructions parlées avec pauses naturelles. Les valeurs plus basses semblent plus rapides pour les commandes courtes mais peuvent couper une longue dictée ; les valeurs plus hautes sont plus sûres pour une parole réfléchie.
 
 ```bash
-UTTERANCE_IDLE_MS="4500"
-UTTERANCE_IDLE_MS="6000"
+UTTERANCE_IDLE_MS="4500"  # balanced default
+UTTERANCE_IDLE_MS="6000"  # safer for long dictation with pauses
 ```
 
-## MCP Server
+## Serveur MCP
+
+VerbalCoding fournit un serveur MCP stdio afin que Hermes Agent ou tout client MCP puisse contrôler la passerelle via des outils au lieu de s'appuyer sur des skills ou des commandes shell libres.
+
+Exemple de configuration Hermes :
 
 ```yaml
 mcp_servers:
@@ -112,39 +151,89 @@ mcp_servers:
     connect_timeout: 30
 ```
 
-Tools: `status`, `doctor`, `set_auto_restart`, `set_language`, `start`, `stop`, and `restart`.
+Outils MCP exposés :
+
+| Outil | Objectif |
+|---|---|
+| `status` | Signaler l'état passerelle/config sans secrets |
+| `doctor` | Exécuter le contrôle doctor expurgé |
+| `set_auto_restart` | Activer/désactiver le redémarrage automatique du bot vocal au moment des commits |
+| `set_language` | Mettre à jour ensemble les langues STT/progression/TTS |
+| `start`, `stop`, `restart` | Contrôler la passerelle vocale Discord |
 
-## Optional OpenVoice TTS
+## TTS OpenVoice facultatif
+
+Edge TTS reste la valeur par défaut et le fallback. Pour essayer le clonage vocal local avec 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
 ```
 
+Définissez ensuite :
+
 ```bash
 TTS_BACKEND="openvoice"
 OPENVOICE_REF_AUDIO="./voice-samples/user-reference.wav"
 OPENVOICE_PROGRESS="0"
 ```
 
-Only clone voices you own or have permission to use. OpenVoice falls back to Edge on failure.
+Clonez uniquement des voix que vous possédez ou que vous avez l'autorisation d'utiliser. Si OpenVoice échoue ou expire, VerbalCoding revient à Edge TTS.
 
-## Optional Supertonic TTS
+## TTS Supertonic facultatif
 
 ```bash
 ./scripts/setup_supertonic.sh
 supertonic tts '안녕하세요. 수퍼토닉 테스트입니다.' --lang ko --voice M1 --steps 2 --speed 1.0 -o /tmp/verbalcoding-supertonic.wav
 ```
 
-## Optional SpeechSwift / CosyVoice TTS
+Définissez ensuite :
+
+```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"
+```
+
+Si Supertonic est absent, échoue ou expire, VerbalCoding revient à Edge TTS.
+
+## TTS SpeechSwift / CosyVoice facultatif
+
+Sur Apple Silicon, `speech-swift` est un backend local de clonage vocal coréen avec CosyVoice/Qwen3-TTS natif MLX.
 
 ```bash
 brew tap soniqo/speech https://github.com/soniqo/speech-swift
 brew install speech
 ```
 
-Recommended env includes `TTS_BACKEND="speechswift"`, `SPEECHSWIFT_MODE="server"`, `SPEECHSWIFT_ENGINE="cosyvoice"`, `SPEECHSWIFT_REF_AUDIO`, and `SPEECHSWIFT_SERVER_URL`. Keep Edge for quick progress prompts.
+Env recommandé :
+
+```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"
+```
+
+Gardez Edge pour les prompts rapides de progression/backchannel.
 
-## Operational Notes
+## Notes d'exploitation
 
-Enable Discord Message Content intent, grant voice connect/speak permissions, authenticate the selected CLI harness separately, and avoid reading diffs/log dumps aloud.
+- Le bot a besoin de l'intent privilégié Discord Message Content activé pour les commandes texte.
+- Le bot a besoin des permissions de connexion/parole dans le salon vocal.
+- Pour Hermes Agent, configurez/authentifiez Hermes normalement (`hermes setup`, `hermes login`, etc.) sur votre profil par défaut.
+- Pour Claude Code, Codex, Gemini, OpenCode, OpenClaw, installez et authentifiez ces CLI séparément.
+- Si une CLI émet une sortie diff/code lors d'un timeout ou d'un échec de signal, la passerelle évite de la lire à voix haute et envoie plutôt le texte détaillé.

package/docs/i18n/CONFIGURATION.ja.md

@@ -1,36 +1,40 @@
 # VerbalCoding 設定
 
-## Setup Wizard
+## セットアップウィザード
 
-Use upstream Discord-side guides first, then return to VerbalCoding:
+Discord ボット/アプリケーションのセットアップ手順は、ここでは最初から説明し直しません。Discord 側の手順には次の上流ガイドを使い、その後 VerbalCoding のセットアップに戻ってください:
 
-- Hermes Agent Discord messaging guide: <https://hermes-agent.nousresearch.com/docs/user-guide/messaging/discord>
-- Discord official bot overview: <https://docs.discord.com/developers/bots/overview>
-- Discord official quick start: <https://docs.discord.com/developers/quick-start/getting-started>
+- 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>
 
 ```bash
-vc setup --yes
-# or from a clone
 ./scripts/install.sh
 ```
 
-The installer asks for the Discord token, allowed users, auto-join voice channel names, transcript channel/thread, CLI harness backend, default voice language, TTS settings, and wake-word behavior. It writes `.env` with mode `0600`.
+インストーラーは、Discord トークン、許可ユーザー、自動参加する音声チャンネル名、文字起こし先チャンネル/スレッド、CLI ハーネスバックエンド、デフォルト音声言語、TTS 設定、ウェイクワード動作を尋ねます。モード `0600` で `.env` を書き込みます。`.env` は git で無視されます。また、短いシェルコマンド `vc` もリンクします。
 
-## Supported Agent Backends
+手動インストール後にシェルコマンドだけが必要な場合:
 
-Set `AGENT_BACKEND` in `.env`.
+```bash
+npm link
+```
+
+## 対応エージェントバックエンド
 
-| Backend | Default command | Notes |
+`.env` で `AGENT_BACKEND` を設定します。
+
+| バックエンド | デフォルトコマンド | メモ |
 |---|---|---|
-| `hermes` | `hermes chat -Q -q` | Default; supports resume and verbose progress |
-| `claude-code` / `claude` | `claude -p` | Override with `CLAUDE_COMMAND` or `AGENT_COMMAND` |
-| `codex` | `codex exec` | Override with `CODEX_COMMAND` or `AGENT_COMMAND` |
-| `gemini` | `gemini -p` | Override with `GEMINI_COMMAND` or `AGENT_COMMAND` |
-| `opencode` | `opencode run` | Override with `OPENCODE_COMMAND` or `AGENT_COMMAND` |
-| `openclaw` | `openclaw run` | Override with `OPENCLAW_COMMAND` or `AGENT_COMMAND` |
-| `custom` | `AGENT_COMMAND` required | Prompt is appended as final 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 引数として追加されます。 |
 
-Generic overrides:
+汎用の上書き設定:
 
 ```bash
 AGENT_BACKEND=custom
@@ -43,23 +47,37 @@ UTTERANCE_IDLE_MS=4500
 LATENCY_LOG_PATH=./.logs/latency.jsonl
 ```
 
-## Example `.env`
+## エージェントアダプター契約
+
+音声ブリッジは、すべてのバックエンドと 1 つのアダプター契約を通じてやり取りします:
+
+- `run({ text }, signal, plan)` はステータス、最終回答テキスト、バックエンドラベル、経過時間、任意のセッションメタデータを返します。
+- `ask(text, signal, plan)` は互換性用のショートカットで、最終回答テキストだけを返します。
+- `capabilities` は、バックエンドがセッション再開、ストリーミング進捗、キャンセルをサポートするかを宣言します。
+- Hermes は参照アダプターです。再開、詳細進捗ストリーミング、キャンセル、Hermes セッションファイルからの最終回答復元に対応します。
+
+新しいバックエンドは同じ契約を実装し、音声/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"
@@ -69,39 +87,60 @@ AGENT_VERBOSE_PROGRESS="0"
 LATENCY_LOG_PATH="./.logs/latency.jsonl"
 ```
 
-## TTS Voice Selection
+## TTS 音声選択
+
+言語プリセットと音声選択は別のものです:
 
-`vc language ko|en|auto` changes STT language, progress language, and default TTS voice. Live commands such as “남자 한국어 목소리로 바꿔”, “여자 한국어 목소리로 바꿔”, `change voice to Korean female`, and `switch speaker to English` change only the speaker/voice type.
+- `vc language ko|en|auto` は STT 言語、進捗言語、その言語のデフォルト音声を変更します。
+- 「남자 한국어 목소리로 바꿔」「여자 한국어 목소리로 바꿔」、`change voice to Korean female`、`switch speaker to English` などのライブ音声コマンドは、話者/音声タイプだけを変更します。
+- `!voice-test <text>` は、現在選択されているバックエンドと音声で短いサンプルを再生します。
 
-Default Edge catalog:
+音声選択はデフォルトで `config/tts-voices.json` に保存されます。パスは `TTS_VOICE_CONFIG` で上書きできます。実行中のブリッジは合成前に音声選択を再読み込み/適用するため、音声コマンドは完全な再起動なしで反映されます。
 
-| `TTS_VOICE_TYPE` | `TTS_VOICE` | Language |
+デフォルト Edge カタログ:
+
+| `TTS_VOICE_TYPE` | `TTS_VOICE` | 言語 |
 |---|---|---|
-| `korean_male` | `ko-KR-InJoonNeural` | Korean |
-| `korean_female` | `ko-KR-SunHiNeural` | Korean |
-| `korean_multilingual_male` | `ko-KR-HyunsuMultilingualNeural` | Korean |
-| `english_male` | `en-US-GuyNeural` | English |
-| `english_female` | `en-US-AriaNeural` | English |
+| `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"
+```
 
-Backend-specific voice options:
+OpenVoice、SpeechSwift、Supertonic では、下のセクションにあるバックエンド固有の音声/参照設定を維持してください。同じ音声カタログファイルで有効な音声タイプを追跡することは可能です。
 
-| Backend | Settings | Voice choices |
+バックエンド固有の音声オプション:
+
+| バックエンド | 設定 | 音声の選択肢 |
 |---|---|---|
-| Edge | `TTS_VOICE_TYPE`, `TTS_VOICE` | Built-in types plus any `edge-tts --list-voices` voice |
-| Supertonic | `SUPERTONIC_VOICE`, `SUPERTONIC_LANGUAGE` | `M1`–`M5`, `F1`–`F5`; `ko`, `en`, `es`, `pt`, `fr` |
-| OpenVoice | `OPENVOICE_REF_AUDIO`, `OPENVOICE_STYLE`, `OPENVOICE_LANGUAGE` | User-provided permitted reference WAV |
-| SpeechSwift / CosyVoice | `SPEECHSWIFT_REF_AUDIO`, `SPEECHSWIFT_ENGINE`, `SPEECHSWIFT_SPEAKER`, `SPEECHSWIFT_MODEL_ID` | Reference-sample voice or backend speaker/model ID |
+| 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 Segmentation
+## 発話の分割
 
-`UTTERANCE_IDLE_MS` controls how long the bridge waits after speech before starting STT. Default is `4500` ms.
+`UTTERANCE_IDLE_MS` は、音声セグメント後に、ブリッジがユーザーの発話完了を判断して STT を開始するまで待つ時間を制御します。デフォルトは `4500` ms で、自然な間を含む長めの音声指示を保つためです。値を小さくすると短いコマンドでは速く感じますが、長いディクテーションを分割することがあります。大きい値は、考えながら話す場合により安全です。
 
 ```bash
-UTTERANCE_IDLE_MS="4500"
-UTTERANCE_IDLE_MS="6000"
+UTTERANCE_IDLE_MS="4500"  # バランスのよいデフォルト
+UTTERANCE_IDLE_MS="6000"  # ポーズを含む長いディクテーションでより安全
 ```
 
-## MCP Server
+## MCP サーバー
+
+VerbalCoding には stdio MCP サーバーが付属しており、Hermes Agent または任意の MCP クライアントは、スキルや自由形式のシェルコマンドに頼らず、ツール経由でブリッジを制御できます。
+
+Hermes 設定例:
 
 ```yaml
 mcp_servers:
@@ -112,39 +151,89 @@ mcp_servers:
     connect_timeout: 30
 ```
 
-Tools: `status`, `doctor`, `set_auto_restart`, `set_language`, `start`, `stop`, and `restart`.
+公開される MCP ツール:
+
+| ツール | 目的 |
+|---|---|
+| `status` | 秘密情報を出さずにブリッジ/設定状態を報告 |
+| `doctor` | 秘密情報を伏せた doctor チェックを実行 |
+| `set_auto_restart` | コミット時の音声ボット自動再起動を有効/無効化 |
+| `set_language` | STT/進捗/TTS 言語をまとめて更新 |
+| `start`, `stop`, `restart` | Discord 音声ブリッジを制御 |
 
-## Optional OpenVoice TTS
+## 任意の OpenVoice TTS
+
+Edge TTS がデフォルトかつフォールバックです。OpenVoice V2 によるローカル音声クローンを試すには:
 
 ```bash
 ./scripts/setup_openvoice.sh
+# OpenVoice docs から checkpoints_v2_0417.zip をダウンロードし、vendor/OpenVoice/checkpoints_v2/ の下に展開します
+mkdir -p voice-samples
+# 許可済み参照サンプルを 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"
 OPENVOICE_REF_AUDIO="./voice-samples/user-reference.wav"
 OPENVOICE_PROGRESS="0"
 ```
 
-Only clone voices you own or have permission to use. OpenVoice falls back to Edge on failure.
+自分が所有している、または使用許可を得ている音声だけをクローンしてください。OpenVoice が失敗またはタイムアウトした場合、VerbalCoding は Edge TTS にフォールバックします。
 
-## Optional 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
 ```
 
-## Optional SpeechSwift / CosyVoice TTS
+次を設定します:
+
+```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 にフォールバックします。
+
+## 任意の SpeechSwift / CosyVoice TTS
+
+Apple Silicon では、`speech-swift` は MLX ネイティブの CosyVoice/Qwen3-TTS を使った韓国語音声クローン用ローカルバックエンドです。
 
 ```bash
 brew tap soniqo/speech https://github.com/soniqo/speech-swift
 brew install speech
 ```
 
-Recommended env includes `TTS_BACKEND="speechswift"`, `SPEECHSWIFT_MODE="server"`, `SPEECHSWIFT_ENGINE="cosyvoice"`, `SPEECHSWIFT_REF_AUDIO`, and `SPEECHSWIFT_SERVER_URL`. Keep Edge for quick progress prompts.
+推奨 env:
+
+```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 を維持してください。
 
-## Operational Notes
+## 運用メモ
 
-Enable Discord Message Content intent, grant voice connect/speak permissions, authenticate the selected CLI harness separately, and avoid reading diffs/log dumps aloud.
+- テキストコマンドには、Discord の特権 Message Content intent をボットで有効にする必要があります。
+- ボットには音声チャンネルへの接続/発話権限が必要です。
+- Hermes Agent では、デフォルトプロファイルで通常どおり Hermes を設定/認証してください（`hermes setup`、`hermes login` など）。
+- Claude Code、Codex、Gemini、OpenCode、OpenClaw では、それぞれの CLI を別途インストールして認証してください。
+- CLI がタイムアウトやシグナル失敗時に diff/code 出力を出した場合、ブリッジはそれを読み上げず、詳細テキストとして送信します。