verbalcoding 0.2.7 → 0.2.8

package/docs/i18n/RELEASE.ko.md

@@ -1,58 +1,74 @@
 # VerbalCoding 릴리스 노트
 
-## Current release candidate
+## 현재 릴리스 후보
 
-VerbalCoding is a Discord voice bridge for controlling CLI-based coding agents by voice. macOS / Apple Silicon is the most tested path; Linux bootstrap is best-effort for common package managers.
+VerbalCoding은 CLI 기반 코딩 에이전트를 음성으로 제어하기 위한 Discord 음성 브리지입니다. 공개 릴리스를 지향하며, macOS / Apple Silicon 경로가 가장 많이 테스트되었고 일반적인 패키지 관리자에 대한 Linux 부트스트랩은 최선 노력으로 지원됩니다.
 
-## Included
+### 포함됨
 
-- Discord voice receive via Node `@discordjs/voice`.
-- Local Korean STT via `whisper.cpp` + Metal.
-- Edge TTS playback with Korean default voice.
-- Generic CLI harness adapter layer: Hermes Agent, Claude Code, Codex CLI, Gemini CLI, OpenCode, OpenClaw, or custom command.
-- Shared voice/text session support for Hermes backend.
-- Long-answer TTS chunking and responsive barge-in.
-- Diff/code/log guardrails so large technical output is not read aloud.
-- Normal and conservative sensitivity modes.
-- Setup wizard, `.env.example`, `vc doctor`, `./scripts/install.sh --yes`, and npm install path.
-- `npm install -g verbalcoding`, `vc setup --yes`, and `vc start`.
-- Verbose progress mode, JSONL latency metrics, and `!latency` / `!metrics`.
-- `UTTERANCE_IDLE_MS=4500` for long spoken instructions with natural pauses.
-- Multi-instance Hermes profile isolation via `vc instance setup <name>` and `HERMES_HOME`.
+- Node `@discordjs/voice`를 통한 Discord 음성 수신.
+- `whisper.cpp` + Metal을 통한 로컬 한국어 STT.
+- 한국어 기본 음성을 사용하는 Edge TTS 재생.
+- 범용 CLI 하네스 어댑터 계층:
+  - Hermes Agent
+  - Claude Code
+  - Codex CLI
+  - Gemini CLI
+  - OpenCode
+  - OpenClaw
+  - 커스텀 명령
+- Hermes 백엔드의 공유 음성/텍스트 세션 지원.
+- 긴 답변 TTS 청킹 및 반응형 끼어들기.
+- 큰 기술 출력이 소리 내어 읽히지 않도록 하는 diff/code/log 안전장치.
+- 실내와 시끄러운/실외 사용을 위한 일반 및 보수적 감도 모드.
+- OS 패키지, npm 의존성, Edge TTS 헬퍼, 기본 whisper.cpp 모델을 위한 설정 마법사, `.env.example`, `vc doctor` 필수 조건 점검기, `./scripts/install.sh --yes` 부트스트랩.
+- npm 패키지 설치 경로: `npm install -g verbalcoding`, `vc setup --yes`, `vc start`.
+- 긴 에이전트 작업 중 텍스트 전용 중간 단계 업데이트를 위한 선택적 자세한 진행 모드.
+- 파이프라인 최적화를 위한 항상 켜진 JSONL 지연 시간 지표와 `!latency` / `!metrics` 요약.
+- 더 여유 있는 발화 유휴 대기(`UTTERANCE_IDLE_MS=4500`)로, 자연스러운 멈춤이 있는 긴 음성 지시가 부분 프롬프트와 무시되는 처리 중 발화로 나뉘지 않도록 함.
+- Multi-instance Hermes 프로필 격리: `vc instance setup <name>`은 인스턴스 workdir를 가진 Hermes 프로필을 `~/.hermes/profiles/<name>`에 자동 복제하고, SOUL.md를 초기화하며, 인스턴스 env에 `HERMES_HOME`을 작성하여 프로젝트별 메모리와 skill을 분리합니다. `vc instance start`는 누락된 프로필을 자가 복구하고, `vc doctor`는 프로필 디렉터리 존재와 `terminal.cwd` 일관성을 확인합니다.
 
-## Pre-release checklist
+### 사전 릴리스 체크리스트
+
+저장소 루트에서 실행하세요:
 
 ```bash
 ./scripts/install.sh --yes --no-wizard
-./scripts/docker_ubuntu_smoke.sh
+./scripts/docker_ubuntu_smoke.sh   # Docker 필요; ubuntu:24.04 깨끗한 설치 검증
 node --check app-node/main.mjs app-node/agent_adapters.mjs app-node/install_config.mjs scripts/install.mjs
 npm test
-PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 python3 -m pytest tests/ -q || [ $? -eq 5 ]
+PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 python3 -m pytest tests/ -q || [ $? -eq 5 ]  # Python 테스트가 없으면 OK
 bash -n run.sh scripts/install.sh scripts/bootstrap_prereqs.sh scripts/docker_ubuntu_smoke.sh
 npm pack --dry-run
 vc doctor
 git diff --check
 ```
 
-Manual smoke test:
+수동 스모크 테스트:
+
+1. `vc start` 또는 `./run.sh`로 브리지를 시작합니다.
+2. 로그에 `Logged in as <bot-name>`가 포함되는지 확인합니다.
+3. 로그에 `Listening in voice channel ... / 일반` 또는 설정된 기본 채널이 포함되는지 확인합니다.
+4. Discord에서 `!ping`을 실행합니다.
+5. Discord 음성에서 짧은 한국어 요청을 말합니다.
+6. STT 전사, 에이전트 응답, TTS 재생, 끼어들기 동작을 확인합니다.
 
-1. Start the bridge with `vc start` or `./run.sh`.
-2. Verify `Logged in as <bot-name>`.
-3. Verify `Listening in voice channel ...`.
-4. In Discord, run `!ping`.
-5. Say a short Korean request in voice.
-6. Verify STT transcript, agent response, TTS playback, and barge-in.
+### 알려진 요구 사항
 
-## Known requirements
+- 최선 노력 부트스트랩을 위해 Homebrew가 있는 macOS 또는 `apt`, `dnf`, `pacman`이 있는 Linux.
+- `ffmpeg`; 설치 프로그램이 설치를 시도합니다.
+- `whisper-cli`; 설치 프로그램은 macOS에서 Homebrew를 사용하거나 Linux에서 로컬 `vendor/whisper.cpp` 빌드 폴백을 사용합니다.
+- `models/ggml-small-q5_1.bin`의 기본 모델; `--skip-model`을 사용하지 않으면 설치 프로그램이 다운로드합니다.
+- `PATH`의 Edge TTS CLI 또는 로컬 `.venv-tts/bin/edge-tts`; 필요하면 설치 프로그램이 로컬 헬퍼를 만듭니다.
+- `.env`, `instances/<name>.env`, `~/.zshrc` 또는 런타임 env의 Discord 봇 토큰.
+- 선택한 CLI 하네스가 설치 및 인증되어 있어야 합니다.
 
-- macOS with Homebrew, or Linux with `apt`, `dnf`, or `pacman`.
-- `ffmpeg`.
-- `whisper-cli`.
-- `models/ggml-small-q5_1.bin`.
-- Edge TTS CLI or `.venv-tts/bin/edge-tts`.
-- Discord bot token in `.env`, `instances/<name>.env`, `~/.zshrc`, or runtime env.
-- Selected CLI harness installed and authenticated.
+### 아직 공개 릴리스용은 아님
 
-## Not for public release yet
+공개 릴리스 전에 다음 추가를 고려하세요:
 
-Consider adding GitHub Actions CI, demo video/GIF, Discord bot setup screenshots, broader real Linux validation, and security review of logging paths.
+- GitHub Actions CI.
+- 데모 비디오 / GIF.
+- Discord 봇 설정 스크린샷.
+- 스크립트 수준 점검을 넘어 실제 배포판에서 더 넓은 Linux 검증.
+- 모든 로깅 경로의 보안 검토.

package/docs/i18n/RELEASE.ru.md

@@ -1,58 +1,74 @@
-# VerbalCoding Заметки о релизе
+# Заметки о релизе VerbalCoding
 
-## Current release candidate
+## Текущий релиз-кандидат
 
-VerbalCoding is a Discord voice bridge for controlling CLI-based coding agents by voice. macOS / Apple Silicon is the most tested path; Linux bootstrap is best-effort for common package managers.
+VerbalCoding — это голосовой bridge Discord для управления CLI-агентами кодинга голосом. Он ориентирован на публичный релиз; macOS / Apple Silicon — наиболее протестированный путь, а bootstrap-поддержка Linux для распространённых менеджеров пакетов предоставляется по мере возможностей.
 
-## Included
+### Включено
 
-- Discord voice receive via Node `@discordjs/voice`.
-- Local Korean STT via `whisper.cpp` + Metal.
-- Edge TTS playback with Korean default voice.
-- Generic CLI harness adapter layer: Hermes Agent, Claude Code, Codex CLI, Gemini CLI, OpenCode, OpenClaw, or custom command.
-- Shared voice/text session support for Hermes backend.
-- Long-answer TTS chunking and responsive barge-in.
-- Diff/code/log guardrails so large technical output is not read aloud.
-- Normal and conservative sensitivity modes.
-- Setup wizard, `.env.example`, `vc doctor`, `./scripts/install.sh --yes`, and npm install path.
-- `npm install -g verbalcoding`, `vc setup --yes`, and `vc start`.
-- Verbose progress mode, JSONL latency metrics, and `!latency` / `!metrics`.
-- `UTTERANCE_IDLE_MS=4500` for long spoken instructions with natural pauses.
-- Multi-instance Hermes profile isolation via `vc instance setup <name>` and `HERMES_HOME`.
+- Приём голоса Discord через Node `@discordjs/voice`.
+- Локальный корейский STT через `whisper.cpp` + Metal.
+- Воспроизведение Edge TTS с корейским голосом по умолчанию.
+- Универсальный слой адаптеров CLI-харнесов:
+  - Hermes Agent
+  - Claude Code
+  - Codex CLI
+  - Gemini CLI
+  - OpenCode
+  - OpenClaw
+  - пользовательская команда
+- Поддержка общей голосовой/текстовой сессии для бэкенда Hermes.
+- Разбиение длинных TTS-ответов на фрагменты и отзывчивое перебивание.
+- Защитные ограничения для diff/code/log, чтобы большой технический вывод не читался вслух.
+- Обычный и консервативный режимы чувствительности для помещений по сравнению с шумным/уличным использованием.
+- Мастер настройки, `.env.example`, проверка prerequisites через `vc doctor` и bootstrap `./scripts/install.sh --yes` для пакетов ОС, npm-зависимостей, помощника Edge TTS и стандартной модели whisper.cpp.
+- Путь установки npm-пакета: `npm install -g verbalcoding`, `vc setup --yes` и `vc start`.
+- Необязательный режим подробного прогресса для текстовых обновлений промежуточных шагов во время долгой работы агента.
+- Постоянные JSONL-метрики задержки плюс сводка `!latency` / `!metrics` для оптимизации pipeline.
+- Более терпеливое ожидание бездействия реплики (`UTTERANCE_IDLE_MS=4500`), чтобы длинные голосовые инструкции с естественными паузами не разделялись на частичный prompt плюс игнорируемую речь во время обработки.
+- Изоляция профилей Hermes для нескольких экземпляров: `vc instance setup <name>` автоматически клонирует профиль Hermes в `~/.hermes/profiles/<name>` с workdir экземпляра, заполняет SOUL.md и записывает `HERMES_HOME` в env экземпляра, чтобы память и skills проектов оставались разделёнными; `vc instance start` самовосстанавливает отсутствующий профиль, а `vc doctor` проверяет наличие директории профиля и согласованность `terminal.cwd`.
 
-## Pre-release checklist
+### Чеклист перед релизом
+
+Запускайте из корня репозитория:
 
 ```bash
 ./scripts/install.sh --yes --no-wizard
-./scripts/docker_ubuntu_smoke.sh
+./scripts/docker_ubuntu_smoke.sh   # requires Docker; validates ubuntu:24.04 clean install
 node --check app-node/main.mjs app-node/agent_adapters.mjs app-node/install_config.mjs scripts/install.mjs
 npm test
-PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 python3 -m pytest tests/ -q || [ $? -eq 5 ]
+PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 python3 -m pytest tests/ -q || [ $? -eq 5 ]  # ok when no Python tests exist
 bash -n run.sh scripts/install.sh scripts/bootstrap_prereqs.sh scripts/docker_ubuntu_smoke.sh
 npm pack --dry-run
 vc doctor
 git diff --check
 ```
 
-Manual smoke test:
+Ручной smoke-тест:
+
+1. Запустите bridge через `vc start` или `./run.sh`.
+2. Проверьте, что лог содержит `Logged in as <bot-name>`.
+3. Проверьте, что лог содержит `Listening in voice channel ... / 일반` или настроенный канал по умолчанию.
+4. В Discord выполните `!ping`.
+5. В голосе Discord произнесите короткий корейский запрос.
+6. Проверьте STT-расшифровку, ответ агента, воспроизведение TTS и поведение перебивания.
 
-1. Start the bridge with `vc start` or `./run.sh`.
-2. Verify `Logged in as <bot-name>`.
-3. Verify `Listening in voice channel ...`.
-4. In Discord, run `!ping`.
-5. Say a short Korean request in voice.
-6. Verify STT transcript, agent response, TTS playback, and barge-in.
+### Известные требования
 
-## Known requirements
+- macOS с Homebrew или Linux с `apt`, `dnf` либо `pacman` для best-effort bootstrap.
+- `ffmpeg`; установщик пытается установить его.
+- `whisper-cli`; установщик использует Homebrew на macOS или резервную локальную сборку `vendor/whisper.cpp` на Linux.
+- Модель по умолчанию в `models/ggml-small-q5_1.bin`; установщик загружает её, если не используется `--skip-model`.
+- Edge TTS CLI в `PATH` или локальный `.venv-tts/bin/edge-tts`; установщик создаёт локальный помощник при необходимости.
+- Токен Discord-бота в `.env`, `instances/<name>.env`, `~/.zshrc` или runtime env.
+- Выбранный CLI-харнес установлен и аутентифицирован.
 
-- macOS with Homebrew, or Linux with `apt`, `dnf`, or `pacman`.
-- `ffmpeg`.
-- `whisper-cli`.
-- `models/ggml-small-q5_1.bin`.
-- Edge TTS CLI or `.venv-tts/bin/edge-tts`.
-- Discord bot token in `.env`, `instances/<name>.env`, `~/.zshrc`, or runtime env.
-- Selected CLI harness installed and authenticated.
+### Пока не для публичного релиза
 
-## Not for public release yet
+Перед публичным релизом стоит добавить:
 
-Consider adding GitHub Actions CI, demo video/GIF, Discord bot setup screenshots, broader real Linux validation, and security review of logging paths.
+- GitHub Actions CI.
+- Демо-видео / GIF.
+- Скриншоты настройки Discord-бота.
+- Более широкую проверку Linux на реальных дистрибутивах сверх проверок на уровне скриптов.
+- Аудит безопасности всех путей логирования.

package/docs/i18n/RELEASE.zh.md

@@ -1,58 +1,74 @@
-# VerbalCoding 发布说明
+# VerbalCoding 发行说明
 
-## Current release candidate
+## 当前候选版本
 
-VerbalCoding is a Discord voice bridge for controlling CLI-based coding agents by voice. macOS / Apple Silicon is the most tested path; Linux bootstrap is best-effort for common package managers.
+VerbalCoding 是一个 Discord 语音桥接，用于通过语音控制基于 CLI 的编码代理。它面向公开发布，macOS / Apple Silicon 是测试最多的路径，并为常见包管理器提供尽力支持的 Linux 引导。
 
-## Included
+### 已包含
 
-- Discord voice receive via Node `@discordjs/voice`.
-- Local Korean STT via `whisper.cpp` + Metal.
-- Edge TTS playback with Korean default voice.
-- Generic CLI harness adapter layer: Hermes Agent, Claude Code, Codex CLI, Gemini CLI, OpenCode, OpenClaw, or custom command.
-- Shared voice/text session support for Hermes backend.
-- Long-answer TTS chunking and responsive barge-in.
-- Diff/code/log guardrails so large technical output is not read aloud.
-- Normal and conservative sensitivity modes.
-- Setup wizard, `.env.example`, `vc doctor`, `./scripts/install.sh --yes`, and npm install path.
-- `npm install -g verbalcoding`, `vc setup --yes`, and `vc start`.
-- Verbose progress mode, JSONL latency metrics, and `!latency` / `!metrics`.
-- `UTTERANCE_IDLE_MS=4500` for long spoken instructions with natural pauses.
-- Multi-instance Hermes profile isolation via `vc instance setup <name>` and `HERMES_HOME`.
+- 通过 Node `@discordjs/voice` 接收 Discord 语音。
+- 通过 `whisper.cpp` + Metal 进行本地韩语 STT。
+- 使用韩语默认声音进行 Edge TTS 播放。
+- 通用 CLI 驱动适配器层：
+  - Hermes Agent
+  - Claude Code
+  - Codex CLI
+  - Gemini CLI
+  - OpenCode
+  - OpenClaw
+  - 自定义命令
+- Hermes 后端的共享语音/文本会话支持。
+- 长答案 TTS 分块和响应式插话。
+- Diff/code/log 保护机制，避免大段技术输出被朗读。
+- 面向室内与嘈杂/户外使用的普通和保守灵敏度模式。
+- 设置向导、`.env.example`、`vc doctor` 前置条件检查器，以及用于 OS 软件包、npm 依赖、Edge TTS 辅助环境和默认 whisper.cpp 模型的 `./scripts/install.sh --yes` 引导。
+- npm 包安装路径：`npm install -g verbalcoding`、`vc setup --yes` 和 `vc start`。
+- 可选详细进度模式，在长时间代理工作期间提供仅文本的中间步骤更新。
+- 常开 JSONL 延迟指标，以及用于流水线优化的 `!latency` / `!metrics` 摘要。
+- 更耐心的发言空闲等待（`UTTERANCE_IDLE_MS=4500`），使带自然停顿的长口述指令不会被拆成部分提示加被忽略的处理期间语音。
+- 多实例 Hermes profile 隔离：`vc instance setup <name>` 会自动将 Hermes profile 克隆到 `~/.hermes/profiles/<name>`，设置实例 workdir，初始化 SOUL.md，并将 `HERMES_HOME` 写入实例 env，使每项目记忆和 skills 保持分离；`vc instance start` 会自愈缺失 profile，`vc doctor` 会检查 profile 目录存在性和 `terminal.cwd` 一致性。
 
-## Pre-release checklist
+### 预发布检查清单
+
+从仓库根目录运行：
 
 ```bash
 ./scripts/install.sh --yes --no-wizard
-./scripts/docker_ubuntu_smoke.sh
+./scripts/docker_ubuntu_smoke.sh   # 需要 Docker；验证 ubuntu:24.04 干净安装
 node --check app-node/main.mjs app-node/agent_adapters.mjs app-node/install_config.mjs scripts/install.mjs
 npm test
-PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 python3 -m pytest tests/ -q || [ $? -eq 5 ]
+PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 python3 -m pytest tests/ -q || [ $? -eq 5 ]  # 没有 Python 测试时也可以
 bash -n run.sh scripts/install.sh scripts/bootstrap_prereqs.sh scripts/docker_ubuntu_smoke.sh
 npm pack --dry-run
 vc doctor
 git diff --check
 ```
 
-Manual smoke test:
+手动冒烟测试：
+
+1. 使用 `vc start` 或 `./run.sh` 启动桥接。
+2. 验证日志包含 `Logged in as <bot-name>`。
+3. 验证日志包含 `Listening in voice channel ... / 일반` 或已配置的默认频道。
+4. 在 Discord 中运行 `!ping`。
+5. 在 Discord 语音中说一个简短韩语请求。
+6. 验证 STT 转写、代理响应、TTS 播放和插话行为。
 
-1. Start the bridge with `vc start` or `./run.sh`.
-2. Verify `Logged in as <bot-name>`.
-3. Verify `Listening in voice channel ...`.
-4. In Discord, run `!ping`.
-5. Say a short Korean request in voice.
-6. Verify STT transcript, agent response, TTS playback, and barge-in.
+### 已知要求
 
-## Known requirements
+- macOS + Homebrew，或带 `apt`、`dnf`、`pacman` 的 Linux（用于尽力支持的引导）。
+- `ffmpeg`；安装器会尝试安装它。
+- `whisper-cli`；安装器在 macOS 使用 Homebrew，在 Linux 上回退到本地 `vendor/whisper.cpp` 构建。
+- 默认模型位于 `models/ggml-small-q5_1.bin`；除非使用 `--skip-model`，安装器会下载它。
+- `PATH` 上的 Edge TTS CLI，或本地 `.venv-tts/bin/edge-tts`；安装器会在需要时创建本地辅助环境。
+- `.env`、`instances/<name>.env`、`~/.zshrc` 或运行时 env 中的 Discord 机器人令牌。
+- 已安装并认证的所选 CLI 驱动。
 
-- macOS with Homebrew, or Linux with `apt`, `dnf`, or `pacman`.
-- `ffmpeg`.
-- `whisper-cli`.
-- `models/ggml-small-q5_1.bin`.
-- Edge TTS CLI or `.venv-tts/bin/edge-tts`.
-- Discord bot token in `.env`, `instances/<name>.env`, `~/.zshrc`, or runtime env.
-- Selected CLI harness installed and authenticated.
+### 尚不适合公开发布
 
-## Not for public release yet
+公开发布前，建议添加：
 
-Consider adding GitHub Actions CI, demo video/GIF, Discord bot setup screenshots, broader real Linux validation, and security review of logging paths.
+- GitHub Actions CI。
+- 演示视频 / GIF。
+- Discord 机器人设置截图。
+- 在脚本级检查之外，对真实发行版进行更广泛的 Linux 验证。
+- 对所有日志路径进行安全审查。

package/docs/i18n/USAGE.es.md

@@ -1,71 +1,78 @@
-# VerbalCoding Guía de uso
+# Guía de uso de VerbalCoding
 
-Operational details for Español users.
+Esta página contiene los detalles operativos que antes hacían que el README fuera demasiado largo.
 
-## CLI Commands
+## Comandos CLI
 
 ```bash
-vc status
-vc language en
-vc language ko
-vc language auto
-vc restart auto status
-vc restart auto on
-vc restart auto off
-vc bot invite CLIENT_ID
-vc instance status
-vc instance setup NAME
-vc instance start NAME
-vc instance stop NAME
-vc doctor
-npm run mcp
+vc status                    # show STT language, progress language, and TTS voice
+vc language en               # English STT + English progress/TTS voice
+vc language ko               # Korean STT + Korean progress/TTS voice
+vc language auto             # Whisper auto-detect STT + English progress/TTS voice
+vc restart auto status       # show commit-time voice-bot auto-restart setting
+vc restart auto on           # enable commit-time voice-bot auto-restart
+vc restart auto off          # disable it; this is the default
+vc bot invite CLIENT_ID      # print a Discord invite URL with required permissions
+vc instance status           # list per-instance bridge configs and process status
+vc instance setup NAME       # write instances/NAME.env and create ~/.hermes/profiles/NAME
+vc instance start NAME       # start ./run.sh instances/NAME.env detached
+vc instance stop NAME        # stop a detached instance and remove its pid file
+vc doctor                    # run the redacted doctor check
+npm run mcp                  # run the stdio MCP server
 ```
 
-Language commands update `.env`; restart with `vc start`, `./run.sh`, or your process manager.
+Los cambios de idioma actualizan `.env`; reinicia el puente con `./run.sh` o tu gestor de procesos para que surtan efecto.
+
+## Modos de ejecución
 
-## Run Modes
+Puente de instancia única:
 
 ```bash
-vc start
 ./run.sh
+```
+
+Puente por instancia usando un entorno local de sobrescritura:
+
+```bash
 ./run.sh instances/my-project.env
+# or
 VERBALCODING_INSTANCE_ENV=instances/my-project.env ./run.sh
 ```
 
-The bot auto-joins the first configured channel name, defaulting to `일반,General,general`.
+El bot se une automáticamente al primer nombre de canal configurado, con valor predeterminado `일반,General,general`.
 
-## Discord Commands
+## Comandos de Discord
 
-Before using commands, set up the Discord application/bot:
+Antes de cablear comandos, configura la aplicación/bot de Discord usando las guías originales:
 
-- Hermes Agent Discord guide: <https://hermes-agent.nousresearch.com/docs/user-guide/messaging/discord>
-- Discord official bot docs: <https://docs.discord.com/developers/bots/overview>
+- Guía de Discord de Hermes Agent: <https://hermes-agent.nousresearch.com/docs/user-guide/messaging/discord>
+- Documentación oficial de bots de Discord: <https://docs.discord.com/developers/bots/overview>
 
-Then run `vc bot invite CLIENT_ID` for the VerbalCoding permissions.
+Luego usa `vc bot invite CLIENT_ID` para generar la URL de invitación específica de VerbalCoding con permisos de texto y voz.
 
-| Command | Purpose |
+| Comando | Propósito |
 |---|---|
-| `!ping` | Basic bot check |
-| `!join` / `!leave` | Join or leave voice |
-| `!say <text>` | Speak text directly through TTS |
-| `!voice-test <text>` | Test the active TTS backend/voice |
-| `!voice-clone capture` | Save the next valid utterance as an OpenVoice reference sample |
-| `!voice-clone status` / `!voice-clone cancel` | Inspect or cancel capture |
-| `!ask <prompt>` | Send text through the same harness adapter as voice |
-| `!session status` | Show current project/default adapter session |
-| `!session new <name> <workdir> [context] --voice <voice-channel>` | Create a project-scoped Hermes session |
-| `!session attach-voice [sessionName] --voice <voice-channel>` | Bind a text channel/thread to a voice channel |
-| `!session list` | List configured project sessions |
-| `!session reset` / `!reset-session` | Clear the current session file |
-| `!verbose on/off` | Toggle detailed progress updates |
-| `!latency` / `!metrics` | Show recent latency summary |
-| `!sensitivity normal/conservative` | Switch barge-in sensitivity |
-
-Voice equivalents such as “외부 모드”, “보수 모드”, “실내”, “기본 감도”, “상세 진행 켜”, and clear stop phrases like “잠깐”, “멈춰”, “그만” are handled by the bridge.
-
-## Changing the Voice
-
-`vc language ko|en|auto` changes STT language, progress language, and the matching default TTS voice together. Live voice commands can change the speaker without restart:
+| `!ping` | Comprobación básica del bot |
+| `!join` / `!leave` | Unirse a voz o salir de voz |
+| `!say <text>` | Decir texto directamente mediante TTS |
+| `!voice-test <text>` | Probar el backend/voz TTS activo |
+| `!voice-clone capture` | Guardar la siguiente emisión válida como muestra de referencia para OpenVoice |
+| `!voice-clone status` / `!voice-clone cancel` | Inspeccionar o cancelar la captura |
+| `!ask <prompt>` | Enviar texto mediante el mismo adaptador de arnés seleccionado que la voz |
+| `!session status` | Mostrar la sesión actual de proyecto/adaptador predeterminado |
+| `!session new <name> <workdir> [context] --voice <voice-channel>` | Crear una sesión Hermes con alcance de proyecto |
+| `!session attach-voice [sessionName] --voice <voice-channel>` | Vincular canal/hilo de texto a un canal de voz |
+| `!session list` | Listar sesiones de proyecto configuradas |
+| `!session reset` / `!reset-session` | Borrar el archivo de sesión actual del proyecto/adaptador predeterminado |
+| `!verbose on/off` | Alternar actualizaciones de progreso detalladas |
+| `!latency` / `!metrics` | Mostrar resumen de latencia reciente |
+| `!sensitivity normal/conservative` | Cambiar sensibilidad de interrupción |
+
+Equivalentes de voz como “외부 모드”, “보수 모드”, “실내”, “기본 감도” y frases claras de parada como “잠깐”, “멈춰”, “그만” son gestionados por el puente. También puedes decir “상세 진행 켜” / “상세 진행 꺼” para alternar el progreso detallado por voz.
+
+## Cambiar la voz
+
+`vc language ko|en|auto` cambia juntos el idioma STT, el idioma de progreso y la voz TTS predeterminada correspondiente. Si solo quieres cambiar el hablante/voz mientras el puente está en ejecución, dilo en la voz de Discord:
 
 ```text
 남자 한국어 목소리로 바꿔
@@ -74,9 +81,11 @@ change voice to Korean female
 switch speaker to English
 ```
 
-Built-in Edge types:
+El puente en vivo reconoce esto como comandos de control por voz, actualiza `config/tts-voices.json`, actualiza el entorno TTS efectivo del proceso en ejecución y responde con una confirmación corta como “목소리를 Korean male로 바꿨어.” Usa `!voice-test <text>` justo después de cambiarla para escuchar el backend y la voz actuales.
+
+Tipos de voz Edge integrados:
 
-| Voice type | Edge voice |
+| Tipo de voz | Voz Edge |
 |---|---|
 | `korean_male` | `ko-KR-InJoonNeural` |
 | `korean_female` | `ko-KR-SunHiNeural` |
@@ -84,26 +93,32 @@ Built-in Edge types:
 | `english_male` | `en-US-GuyNeural` |
 | `english_female` | `en-US-AriaNeural` |
 
-Backend voice settings:
+Para configuración manual persistente, define `TTS_BACKEND=edge`, `TTS_VOICE_TYPE=<voice-type>` y opcionalmente `TTS_VOICE=<edge-voice>` en `.env`, o edita `config/tts-voices.json` para catálogos de voz personalizados.
 
-| Backend | Voice setting | Common choices |
+Controles de voz específicos de backend:
+
+| Backend | Ajuste de voz | Opciones comunes |
 |---|---|---|
-| Edge | `TTS_VOICE_TYPE`, `TTS_VOICE` | Built-in types or any Edge voice from `edge-tts --list-voices` |
-| Supertonic | `SUPERTONIC_VOICE` | `M1`–`M5`, `F1`–`F5`; `SUPERTONIC_LANGUAGE=ko|en|es|pt|fr` |
-| OpenVoice | `OPENVOICE_REF_AUDIO`, `OPENVOICE_STYLE` | A permitted reference WAV plus style such as `default` |
-| SpeechSwift / CosyVoice | `SPEECHSWIFT_REF_AUDIO`, `SPEECHSWIFT_ENGINE`, `SPEECHSWIFT_SPEAKER` | Reference WAV or backend speaker/model values |
+| Edge | `TTS_VOICE_TYPE`, `TTS_VOICE` | `korean_male`, `korean_female`, `korean_multilingual_male`, `english_male`, `english_female`; cualquier voz Edge de `edge-tts --list-voices` |
+| Supertonic | `SUPERTONIC_VOICE` | `M1`–`M5`, `F1`–`F5`; define `SUPERTONIC_LANGUAGE=ko|en|es|pt|fr` |
+| OpenVoice | `OPENVOICE_REF_AUDIO`, `OPENVOICE_STYLE` | una referencia WAV permitida más un estilo como `default` |
+| SpeechSwift / CosyVoice | `SPEECHSWIFT_REF_AUDIO`, `SPEECHSWIFT_ENGINE`, `SPEECHSWIFT_SPEAKER` | WAV de referencia para CosyVoice, o valores de hablante/modelo admitidos por el backend |
+
+Para Supertonic y backends locales de clonación, usa las variables de entorno del backend anteriores junto con `!voice-test <text>` para probar cambios. El cambio por comandos de voz actualmente asigna los tipos de voz integrados de estilo Edge; se pueden añadir catálogos de backend más completos en `config/tts-voices.json`.
 
-## Long Dictation and Pauses
+## Dictado largo y pausas
 
-The default `UTTERANCE_IDLE_MS=4500` waits long enough to keep natural pauses inside one spoken instruction. Lower it for faster short commands or raise it for long dictation:
+VerbalCoding espera una ventana de inactividad antes de enviar el habla a STT. El valor predeterminado `UTTERANCE_IDLE_MS=4500` es deliberadamente un poco paciente para que una pausa natural en una instrucción larga no divida la oración, inicie un turno de agente demasiado pronto y luego trate el resto como una interrupción durante el procesamiento.
+
+Si prefieres comandos cortos más rápidos, bájalo en `.env`; si el dictado largo en coreano aún se divide, súbelo:
 
 ```bash
 UTTERANCE_IDLE_MS="6000"
 ```
 
-## Verbose Progress Mode
+## Modo de progreso detallado
 
-Enable with `!verbose on`, `AGENT_VERBOSE_PROGRESS=1`, or “상세 진행 켜”. Progress lines look like:
+El progreso detallado está desactivado por defecto salvo que `AGENT_VERBOSE_PROGRESS=1` esté definido. Habilítalo con `!verbose on` o con un comando de voz como “상세 진행 켜”. Puede emitir líneas cortas de progreso como:
 
 ```text
 🤖 Hermes Agent 호출 시작
@@ -113,18 +128,28 @@ Enable with `!verbose on`, `AGENT_VERBOSE_PROGRESS=1`, or “상세 진행 켜
 🤖 Hermes Agent 응답 수신
 ```
 
-Secret-looking fields are redacted and progress lines are removed from final spoken answers.
+Este modo pide al arnés CLI seleccionado que emita líneas `VERBALCODING_PROGRESS: ...` y resume marcadores comunes de herramientas desde stdout/stderr en streaming cuando están disponibles. Los campos con aspecto de secreto se redactan y las líneas de progreso se eliminan de la respuesta final hablada.
+
+## Métricas de latencia
+
+VerbalCoding escribe registros de latencia por turno como JSONL. Ruta predeterminada:
+
+```text
+./.logs/latency.jsonl
+```
 
-## Latency Metrics
+Cada registro incluye estado, tiempo total, tiempo de captura de voz, espera de inactividad de emisión, tiempo STT, tiempo del agente, tiempo de síntesis/reproducción TTS, conteos de fragmentos, longitud de transcripción, longitud de respuesta y niveles de audio cuando están disponibles.
 
-Latency records are written to `./.logs/latency.jsonl`. In Discord, run:
+En Discord:
 
 ```text
 !latency
 !metrics
 ```
 
-## Testing
+El resumen usa los últimos 200 registros: conteo, promedio, p95, máximo y estados no OK.
+
+## Pruebas
 
 ```bash
 node --check app-node/main.mjs
@@ -132,3 +157,5 @@ npm test
 bash -n run.sh scripts/install.sh
 vc doctor
 ```
+
+`vc doctor` redacta secretos intencionadamente y solo informa si los valores requeridos están configurados. También comprueba `instances/*.env` en busca de huellas de token duplicadas y rutas de ejecución en conflicto.