verbalcoding 0.2.6 → 0.2.8

package/docs/i18n/CONFIGURATION.zh.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>
+- Discord 官方快速开始：<https://docs.discord.com/developers/quick-start/getting-started>
+
+```bash
+./scripts/install.sh
+```
+
+安装器会询问 Discord 令牌、允许的用户、自动加入的语音频道名称、转写频道/thread、CLI 驱动后端、默认语音语言、TTS 设置和唤醒词行为。它会以 `0600` 模式写入 `.env`；`.env` 会被 git 忽略。它还会链接简短的 shell 命令 `vc`。
+
+如果你在手动安装后只需要 shell 命令：
+
+```bash
+npm link
+```
+
+## 支持的代理后端
+
+在 `.env` 中设置 `AGENT_BACKEND`。
+
+| 后端 | 默认命令 | 说明 |
+|---|---|---|
+| `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 参数追加。 |
+
+通用覆盖：
+
+```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
+```
+
+## 代理适配器契约
+
+语音桥接通过一个适配器契约与每个后端通信：
+
+- `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"
+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` 覆盖路径。运行中的桥接会在合成前重新读取/应用声音选择，因此语音命令无需完整重启即可生效。
+
+默认 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` 控制桥接在语音片段后等待多久，才判定用户说完并启动 STT。默认值是 `4500` ms，用于保留带自然停顿的较长口述指令。较低值让短命令感觉更快，但可能拆分长听写；较高值更适合需要思考停顿的语音。
+
+```bash
+UTTERANCE_IDLE_MS="4500"  # 平衡默认值
+UTTERANCE_IDLE_MS="6000"  # 对带停顿的长听写更安全
+```
+
+## MCP 服务器
+
+VerbalCoding 附带一个 stdio MCP 服务器，因此 Hermes Agent 或任何 MCP 客户端都可以通过工具控制桥接，而不必依赖 skills 或自由形式 shell 命令。
+
+Hermes 配置示例：
+
+```yaml
+mcp_servers:
+  verbalcoding:
+    command: "node"
+    args: ["/path/to/VerbalCoding/scripts/mcp-server.mjs"]
+    timeout: 120
+    connect_timeout: 30
+```
+
+暴露的 MCP 工具：
+
+| 工具 | 用途 |
+|---|---|
+| `status` | 在不暴露密钥的情况下报告桥接/配置状态 |
+| `doctor` | 运行脱敏 doctor 检查 |
+| `set_auto_restart` | 启用/禁用提交时语音机器人自动重启 |
+| `set_language` | 同时更新 STT/进度/TTS 语言 |
+| `start`, `stop`, `restart` | 控制 Discord 语音桥接 |
+
+## 可选 OpenVoice TTS
+
+Edge TTS 仍是默认值和回退。若要尝试使用 OpenVoice V2 进行本地语音克隆：
+
+```bash
+./scripts/setup_openvoice.sh
+# 从 OpenVoice 文档下载 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"
+```
+
+只克隆你拥有或获准使用的声音。如果 OpenVoice 失败或超时，VerbalCoding 会回退到 Edge 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"
+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
+```
+
+推荐 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 用于快速进度/回声提示。
+
+## 运维说明
+
+- 机器人需要启用 Discord 特权 Message Content intent 才能使用文本命令。
+- 机器人需要语音频道连接/发言权限。
+- 对于 Hermes Agent，请在默认 profile 上正常配置/认证 Hermes（`hermes setup`、`hermes login` 等）。
+- 对于 Claude Code、Codex、Gemini、OpenCode、OpenClaw，请分别安装并认证这些 CLI。
+- 如果某个 CLI 在超时或信号失败时输出 diff/code，桥接会避免朗读它，而改为发送详细文本。

package/docs/i18n/FRESH_INSTALL.es.md

@@ -0,0 +1,207 @@
+# Instalación limpia
+
+Esta guía es para una instalación pública limpia. Evita suposiciones locales y usa el instalador para inicializar todo lo posible.
+
+## 1. Instala la CLI
+
+Ruta recomendada con npm:
+
+```bash
+npm install -g verbalcoding
+```
+
+O ejecuta directamente el paquete publicado:
+
+```bash
+npx verbalcoding setup --yes
+```
+
+Si usaste `npm install -g`, continúa con:
+
+```bash
+vc setup --yes
+```
+
+Ruta de clonación de GitHub para colaboradores:
+
+```bash
+git clone https://github.com/ca1773130n/VerbalCoding.git
+cd VerbalCoding
+./scripts/install.sh --yes
+```
+
+## 2. Inicializa dependencias y ejecuta el asistente de configuración
+
+En una instalación npm, no ejecutes `./scripts/install.sh` directamente; no hay un checkout del repositorio en tu directorio actual. Usa en su lugar el wrapper CLI empaquetado:
+
+```bash
+vc setup --yes
+```
+
+`vc setup` ejecuta el `scripts/install.sh` incluido dentro del paquete npm instalado. Usa `./scripts/install.sh --yes` solo cuando estés dentro de un clon de GitHub:
+
+```bash
+./scripts/install.sh --yes
+```
+
+Qué hace esto:
+
+- instala las dependencias npm cuando falta `node_modules/`,
+- instala el comando corto de shell `vc` con `npm link`,
+- instala `ffmpeg`, Node/npm y `whisper-cli` cuando el administrador de paquetes del SO lo admite,
+- descarga `models/ggml-small-q5_1.bin`,
+- crea `.venv-tts` e instala `edge-tts` cuando `edge-tts` no está ya en `PATH`,
+- ejecuta el asistente interactivo de `.env`.
+
+Rutas de arranque del sistema compatibles:
+
+| SO | Ruta de dependencias del sistema |
+|---|---|
+| macOS | Homebrew: `brew install node ffmpeg whisper-cpp` según sea necesario |
+| Debian/Ubuntu | `apt-get` para Node/npm, ffmpeg, Python y herramientas de compilación; compilación local alternativa de whisper.cpp |
+| Fedora/RHEL | `dnf` para Node/npm, ffmpeg, Python y herramientas de compilación; compilación local alternativa de whisper.cpp |
+| Arch | `pacman` para Node/npm, ffmpeg, Python y herramientas de compilación; compilación local alternativa de whisper.cpp |
+
+Variantes útiles del instalador:
+
+```bash
+vc setup --yes --no-wizard                   # dependency/bootstrap only from npm install
+./scripts/install.sh --yes --no-wizard       # dependency/bootstrap only from a clone
+./scripts/install.sh --skip-system           # do not install OS packages
+./scripts/install.sh --skip-model            # do not download the default STT model
+./scripts/install.sh --skip-edge-tts         # do not create .venv-tts
+VERBALCODING_SKIP_CLI_LINK=1 ./scripts/install.sh --yes
+```
+
+Si tu SO no es compatible, instala esto manualmente antes de volver a ejecutar:
+
+- Node.js 20+ y npm
+- ffmpeg
+- Python 3 con venv/pip
+- `whisper-cli` de whisper.cpp
+- un backend de agente CLI autenticado, Hermes Agent por defecto
+
+## 3. Configuración de la aplicación de Discord
+
+Lee primero las guías originales de configuración de bots de Discord si este es tu primer bot:
+
+- Guía de mensajería Discord de Hermes Agent: <https://hermes-agent.nousresearch.com/docs/user-guide/messaging/discord>
+- Resumen oficial de bots de Discord: <https://docs.discord.com/developers/bots/overview>
+- Guía oficial de primeros pasos de Discord: <https://docs.discord.com/developers/quick-start/getting-started>
+
+Esas páginas muestran cómo crear una aplicación de Discord, añadir un usuario bot, habilitar intents privilegiados e invitarlo a un servidor. VerbalCoding usa la misma configuración de bot de Discord y luego añade recepción de voz, STT, ejecución de agentes CLI y reproducción TTS encima.
+
+1. Crea una aplicación y un bot de Discord en el Discord Developer Portal.
+2. Habilita el intent privilegiado Message Content.
+3. Copia el token del bot en el prompt del instalador o en `.env` como `DISCORD_BOT_TOKEN`.
+4. Genera una URL de invitación:
+
+```bash
+vc bot invite <discord-client-id>
+# or pin it to one server:
+vc bot invite <discord-client-id> --guild <guild-id>
+```
+
+La invitación incluye los scopes de bot y comandos slash, además de los permisos de texto/voz usados por VerbalCoding.
+
+## 4. Verifica
+
+```bash
+vc doctor
+```
+
+`vc doctor` está redactado: informa tokens/comandos/modelos faltantes sin imprimir valores secretos. Cuando falten prerrequisitos locales reparables (`ffmpeg`, `whisper-cli`, el modelo predeterminado o el asistente Edge TTS), primero vuelve a ejecutar automáticamente el bootstrap empaquetado. Corrige cualquier elemento `✗` restante y vuelve a ejecutarlo.
+
+El éxito esperado incluye:
+
+```text
+✓ Node.js
+✓ npm
+✓ ffmpeg
+✓ whisper-cli
+✓ whisper.cpp model
+✓ Discord bot token configured — [REDACTED]
+✓ edge-tts
+✓ hermes CLI
+Doctor passed. Run vc start to start VerbalCoding.
+```
+
+Si el instalador creó un asistente local de Edge TTS, `.env` debería contener una ruta `EDGE_TTS_COMMAND` que apunte a `.venv-tts/bin/edge-tts`.
+
+## 5. Ejecuta el bot predeterminado único
+
+```bash
+vc start
+# or, from a GitHub clone:
+./run.sh
+```
+
+Los registros de inicio correcto incluyen:
+
+```text
+Logged in as <bot-name>
+Listening in voice channel <server> / <channel>
+```
+
+En Discord:
+
+```text
+!ping
+!join
+!ask say hello briefly
+!verbose on
+```
+
+Luego habla en el canal de voz configurado. Deberías ver texto STT, texto de progreso cuando el modo detallado está activado, una respuesta final de texto y escuchar la reproducción TTS.
+
+## 6. Configuración de un proyecto por sala
+
+Para un bot permanente por sala de voz de proyecto, crea una aplicación de Discord por proyecto y luego:
+
+```bash
+vc instance setup my-project
+vc bot invite <that-project-client-id>
+vc instance start my-project
+vc instance status my-project
+```
+
+Cada instancia escribe un `instances/<name>.env` ignorado con su propio token, canal de voz, destino de transcripción, ruta de registro, archivo de sesión de Hermes y perfil de Hermes opcional.
+
+## 7. Configuración opcional de OpenVoice
+
+La clonación de voz de OpenVoice es opcional. Mantén `TTS_BACKEND=edge` para una instalación pública nueva. Para habilitar OpenVoice más adelante:
+
+```bash
+./scripts/setup_openvoice.sh
+# Download OpenVoice V2 checkpoints into vendor/OpenVoice/checkpoints_v2/
+# Add a permitted local sample at voice-samples/user-reference.wav,
+# or run the bot, say "목소리 샘플 녹음 시작해", then speak 10-30 seconds.
+python3 integrations/openvoice/synth.py --openvoice-dir vendor/OpenVoice --ref-audio voice-samples/user-reference.wav --text '안녕하세요. 버벌코딩 목소리 복제 테스트입니다.' --output /tmp/verbalcoding-openvoice-smoke.wav
+```
+
+Luego define `TTS_BACKEND=openvoice`, ejecuta `vc doctor` y prueba `!voice-test <text>` en Discord.
+
+## 8. Prueba rápida de clon limpio para mantenedores
+
+Prueba rápida solo en el host:
+
+```bash
+TMPDIR=$(mktemp -d)
+git clone https://github.com/ca1773130n/VerbalCoding.git "$TMPDIR/VerbalCoding"
+cd "$TMPDIR/VerbalCoding"
+./scripts/install.sh --yes --no-wizard
+npm pack --dry-run
+cp .env.example .env
+chmod 600 .env
+vc doctor || true
+```
+
+El fallo esperado en este punto es la ausencia de secretos locales o una CLI de agente no autenticada, no tokens filtrados ni scripts de instalación faltantes.
+
+Prueba rápida de instalación limpia en Ubuntu basada en Docker:
+
+```bash
+./scripts/docker_ubuntu_smoke.sh
+```
+
+Esto ejecuta `ubuntu:24.04`, copia el árbol del repositorio rastreado a un contenedor limpio, ejecuta `./scripts/install.sh --yes --no-wizard`, escribe un `.env` de prueba sin secretos, comprueba `vc`, ejecuta pruebas de Node y verifica `vc doctor`. No se conecta a voz de Discord; usa una VM real de Ubuntu o WSL2 después de esto si necesitas una prueba de extremo a extremo con canal de voz.

package/docs/i18n/FRESH_INSTALL.fr.md

@@ -0,0 +1,207 @@
+# Installation propre
+
+Ce guide couvre une installation publique propre. Il évite les hypothèses propres à une machine locale et utilise l'installateur pour amorcer autant d'éléments que possible.
+
+## 1. Installer la CLI
+
+Chemin npm recommandé :
+
+```bash
+npm install -g verbalcoding
+```
+
+Ou exécutez directement le paquet publié :
+
+```bash
+npx verbalcoding setup --yes
+```
+
+Si vous avez utilisé `npm install -g`, continuez avec :
+
+```bash
+vc setup --yes
+```
+
+Chemin de clonage GitHub pour les contributeurs :
+
+```bash
+git clone https://github.com/ca1773130n/VerbalCoding.git
+cd VerbalCoding
+./scripts/install.sh --yes
+```
+
+## 2. Amorcer les dépendances et lancer l'assistant de configuration
+
+Pour une installation npm, n'exécutez pas `./scripts/install.sh` directement : il n'y a pas de checkout du dépôt dans votre répertoire courant. Utilisez plutôt l'enveloppe CLI empaquetée :
+
+```bash
+vc setup --yes
+```
+
+`vc setup` exécute le `scripts/install.sh` inclus dans le paquet npm installé. N'utilisez `./scripts/install.sh --yes` que lorsque vous êtes dans un clone GitHub :
+
+```bash
+./scripts/install.sh --yes
+```
+
+Ce que cela fait :
+
+- installe les dépendances npm quand `node_modules/` est absent,
+- installe la commande shell courte `vc` avec `npm link`,
+- installe `ffmpeg`, Node/npm et `whisper-cli` quand le gestionnaire de paquets de l'OS le permet,
+- télécharge `models/ggml-small-q5_1.bin`,
+- crée `.venv-tts` et installe `edge-tts` quand `edge-tts` n'est pas déjà dans `PATH`,
+- lance l'assistant interactif `.env`.
+
+Chemins d'amorçage système pris en charge :
+
+| OS | Chemin pour les dépendances système |
+|---|---|
+| macOS | Homebrew : `brew install node ffmpeg whisper-cpp` selon les besoins |
+| Debian/Ubuntu | `apt-get` pour Node/npm, ffmpeg, Python, outils de build ; fallback de build whisper.cpp local |
+| Fedora/RHEL | `dnf` pour Node/npm, ffmpeg, Python, outils de build ; fallback de build whisper.cpp local |
+| Arch | `pacman` pour Node/npm, ffmpeg, Python, outils de build ; fallback de build whisper.cpp local |
+
+Variantes utiles de l'installateur :
+
+```bash
+vc setup --yes --no-wizard                   # dépendances/amorcage seulement depuis l'installation npm
+./scripts/install.sh --yes --no-wizard       # dépendances/amorcage seulement depuis un clone
+./scripts/install.sh --skip-system           # ne pas installer de paquets OS
+./scripts/install.sh --skip-model            # ne pas télécharger le modèle STT par défaut
+./scripts/install.sh --skip-edge-tts         # ne pas créer .venv-tts
+VERBALCODING_SKIP_CLI_LINK=1 ./scripts/install.sh --yes
+```
+
+Si votre OS n'est pas pris en charge, installez manuellement ces éléments avant de relancer :
+
+- Node.js 20+ et npm
+- ffmpeg
+- Python 3 avec venv/pip
+- `whisper-cli` de whisper.cpp
+- un backend d'agent CLI authentifié, Hermes Agent par défaut
+
+## 3. Configuration de l'application Discord
+
+Lisez d'abord les guides amont de configuration d'un bot Discord si c'est votre premier bot :
+
+- 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>
+- Guide officiel de démarrage Discord : <https://docs.discord.com/developers/quick-start/getting-started>
+
+Ces pages montrent comment créer une application Discord, ajouter un utilisateur bot, activer les intents privilégiés et l'inviter sur un serveur. VerbalCoding utilise la même configuration de bot Discord, puis ajoute par-dessus la réception vocale, le STT, l'exécution d'agent CLI et la lecture TTS.
+
+1. Créez une application Discord et un bot dans le portail développeur Discord.
+2. Activez l'intent privilégié Message Content.
+3. Copiez le jeton du bot dans l'invite de l'installateur ou dans `.env` en tant que `DISCORD_BOT_TOKEN`.
+4. Générez une URL d'invitation :
+
+```bash
+vc bot invite <discord-client-id>
+# or pin it to one server:
+vc bot invite <discord-client-id> --guild <guild-id>
+```
+
+L'invitation inclut les scopes bot et commandes slash ainsi que les permissions texte/voix utilisées par VerbalCoding.
+
+## 4. Vérifier
+
+```bash
+vc doctor
+```
+
+`vc doctor` est expurgé : il signale les jetons/commandes/modèles manquants sans imprimer de valeurs secrètes. Quand des prérequis locaux réparables manquent (`ffmpeg`, `whisper-cli`, le modèle par défaut ou l'assistant Edge TTS), il relance d'abord automatiquement le bootstrap empaqueté. Corrigez les éléments `✗` restants, puis relancez-le.
+
+Un succès attendu ressemble à :
+
+```text
+✓ Node.js
+✓ npm
+✓ ffmpeg
+✓ whisper-cli
+✓ whisper.cpp model
+✓ Discord bot token configured — [REDACTED]
+✓ edge-tts
+✓ hermes CLI
+Doctor passed. Run vc start to start VerbalCoding.
+```
+
+Si l'installateur a créé un assistant Edge TTS local, `.env` doit contenir un chemin `EDGE_TTS_COMMAND` pointant vers `.venv-tts/bin/edge-tts`.
+
+## 5. Lancer le bot par défaut unique
+
+```bash
+vc start
+# or, from a GitHub clone:
+./run.sh
+```
+
+Les journaux d'un démarrage réussi incluent :
+
+```text
+Logged in as <bot-name>
+Listening in voice channel <server> / <channel>
+```
+
+Dans Discord :
+
+```text
+!ping
+!join
+!ask say hello briefly
+!verbose on
+```
+
+Parlez ensuite dans le salon vocal configuré. Vous devriez voir le texte STT, le texte de progression quand le mode détaillé est activé, une réponse texte finale et entendre la lecture TTS.
+
+## 6. Configuration un projet par salon
+
+Pour un bot permanent par salon vocal de projet, créez une application Discord par projet, puis :
+
+```bash
+vc instance setup my-project
+vc bot invite <that-project-client-id>
+vc instance start my-project
+vc instance status my-project
+```
+
+Chaque instance écrit un fichier ignoré `instances/<name>.env` avec son propre jeton, salon vocal, cible de transcription, chemin de journal, fichier de session Hermes et profil Hermes facultatif.
+
+## 7. Configuration OpenVoice facultative
+
+Le clonage vocal OpenVoice est facultatif. Gardez `TTS_BACKEND=edge` pour une nouvelle installation publique. Pour activer OpenVoice plus tard :
+
+```bash
+./scripts/setup_openvoice.sh
+# Download OpenVoice V2 checkpoints into vendor/OpenVoice/checkpoints_v2/
+# Add a permitted local sample at voice-samples/user-reference.wav,
+# or run the bot, say "목소리 샘플 녹음 시작해", then speak 10-30 seconds.
+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 `TTS_BACKEND=openvoice`, exécutez `vc doctor` et testez `!voice-test <text>` dans Discord.
+
+## 8. Smoke test de clone propre pour les mainteneurs
+
+Smoke test rapide sur l'hôte uniquement :
+
+```bash
+TMPDIR=$(mktemp -d)
+git clone https://github.com/ca1773130n/VerbalCoding.git "$TMPDIR/VerbalCoding"
+cd "$TMPDIR/VerbalCoding"
+./scripts/install.sh --yes --no-wizard
+npm pack --dry-run
+cp .env.example .env
+chmod 600 .env
+vc doctor || true
+```
+
+L'échec attendu à ce stade est l'absence de secrets locaux ou d'authentification de la CLI d'agent, et non une fuite de jetons ou des scripts d'installation manquants.
+
+Smoke test d'installation propre Ubuntu basé sur Docker :
+
+```bash
+./scripts/docker_ubuntu_smoke.sh
+```
+
+Cela lance `ubuntu:24.04`, copie l'arborescence suivie du dépôt dans un conteneur propre, exécute `./scripts/install.sh --yes --no-wizard`, écrit un `.env` de smoke test sans secret, vérifie `vc`, lance les tests Node et vérifie `vc doctor`. Il ne se connecte pas à la voix Discord ; utilisez une vraie VM Ubuntu ou WSL2 après cela si vous avez besoin d'un test de bout en bout dans un salon vocal.