verbalcoding 0.2.7 → 0.2.9

package/docs/i18n/CONFIGURATION.zh.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 令牌、允许的用户、自动加入的语音频道名称、转写频道/thread、CLI 驱动后端、默认语音语言、TTS 设置和唤醒词行为。它会以 `0600` 模式写入 `.env`；`.env` 会被 git 忽略。它还会链接简短的 shell 命令 `vc`。
 
-## Supported Agent Backends
+如果你在手动安装后只需要 shell 命令：
 
-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`
+## 代理适配器契约
+
+语音桥接通过一个适配器契约与每个后端通信：
+
+- `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 客户端都可以通过工具控制桥接，而不必依赖 skills 或自由形式 shell 命令。
+
+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 文档下载 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，请在默认 profile 上正常配置/认证 Hermes（`hermes setup`、`hermes login` 等）。
+- 对于 Claude Code、Codex、Gemini、OpenCode、OpenClaw，请分别安装并认证这些 CLI。
+- 如果某个 CLI 在超时或信号失败时输出 diff/code，桥接会避免朗读它，而改为发送详细文本。

package/docs/i18n/FRESH_INSTALL.es.md

@@ -1,21 +1,28 @@
 # Instalación limpia
 
-This guide mirrors the English fresh-install flow for Español. It is intended for a clean public install and avoids local-only assumptions.
+Esta guía es para una instalación pública limpia. Evita suposiciones locales y usa el instalador para inicializar todo lo posible.
 
-## 1. Install the CLI
+## 1. Instala la CLI
+
+Ruta recomendada con npm:
 
 ```bash
 npm install -g verbalcoding
-vc setup --yes
 ```
 
-Or run the published package directly:
+O ejecuta directamente el paquete publicado:
 
 ```bash
 npx verbalcoding setup --yes
 ```
 
-Contributor clone path:
+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
@@ -23,47 +30,105 @@ cd VerbalCoding
 ./scripts/install.sh --yes
 ```
 
-## 2. Bootstrap dependencies
+## 2. Inicializa dependencias y ejecuta el asistente de configuración
 
-The setup flow installs npm dependencies when needed, links the short `vc` command for clone installs, installs `ffmpeg` / Node / `whisper-cli` where the OS package manager supports it, downloads `models/ggml-small-q5_1.bin`, creates `.venv-tts`, and writes `.env`.
+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:
 
-Useful variants:
+```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
-vc setup --yes --no-wizard
-./scripts/install.sh --yes --no-wizard
-./scripts/install.sh --skip-system
-./scripts/install.sh --skip-model
-./scripts/install.sh --skip-edge-tts
+./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
 ```
 
-Supported bootstrap paths: macOS/Homebrew, Debian/Ubuntu `apt`, Fedora/RHEL `dnf`, and Arch `pacman`. If unsupported, manually install Node.js 20+, npm, ffmpeg, Python 3, `whisper-cli`, and an authenticated CLI agent backend.
+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. Discord application setup
+## 3. Configuración de la aplicación de Discord
 
-Read the upstream bot guides first:
+Lee primero las guías originales de configuración de bots de Discord si este es tu primer bot:
 
-- Hermes Agent Discord guide: <https://hermes-agent.nousresearch.com/docs/user-guide/messaging/discord>
-- Discord official bot overview: <https://docs.discord.com/developers/bots/overview>
-- Discord official getting started guide: <https://docs.discord.com/developers/quick-start/getting-started>
+- 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>
 
-Create a Discord application and bot, enable the Message Content privileged intent, put the token in the installer or `.env` as `DISCORD_BOT_TOKEN`, then generate the invite URL:
+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>
 ```
 
-## 4. Verify
+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` redacts secrets and reports missing commands/models/tokens without printing sensitive values. Expected success includes Node.js, npm, ffmpeg, whisper-cli, the model, Discord bot token configured, edge-tts, and the selected agent CLI.
+`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. Run
+## 5. Ejecuta el bot predeterminado único
 
 ```bash
 vc start
@@ -71,14 +136,14 @@ vc start
 ./run.sh
 ```
 
-Expected log lines:
+Los registros de inicio correcto incluyen:
 
 ```text
 Logged in as <bot-name>
 Listening in voice channel <server> / <channel>
 ```
 
-In Discord:
+En Discord:
 
 ```text
 !ping
@@ -87,11 +152,11 @@ In Discord:
 !verbose on
 ```
 
-Then speak in the configured voice channel. You should see STT text, progress text when verbose mode is on, a final text answer, and hear TTS playback.
+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. Project-per-room setup
+## 6. Configuración de un proyecto por sala
 
-For one permanent bot per project voice room, create one Discord application per project, then:
+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
@@ -100,9 +165,11 @@ vc instance start my-project
 vc instance status my-project
 ```
 
-## 7. Optional OpenVoice setup
+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
 
-Keep `TTS_BACKEND=edge` for a fresh install. To enable OpenVoice later:
+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
@@ -112,13 +179,29 @@ Keep `TTS_BACKEND=edge` for a fresh install. To enable OpenVoice later:
 python3 integrations/openvoice/synth.py --openvoice-dir vendor/OpenVoice --ref-audio voice-samples/user-reference.wav --text '안녕하세요. 버벌코딩 목소리 복제 테스트입니다.' --output /tmp/verbalcoding-openvoice-smoke.wav
 ```
 
-Then set `TTS_BACKEND=openvoice`, run `vc doctor`, and test `!voice-test <text>` in Discord.
+Luego define `TTS_BACKEND=openvoice`, ejecuta `vc doctor` y prueba `!voice-test <text>` en Discord.
+
+## 8. Prueba rápida de clon limpio para mantenedores
 
-## 8. Maintainer smoke tests
+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.