verbalcoding 0.2.6 → 0.2.8

package/docs/i18n/README.zh.md

@@ -1,11 +1,10 @@
 # VerbalCoding
 
 <p align="center">
-  <strong>通过 Discord 语音像打电话一样控制 CLI 编程 Agent。</strong>
+  <strong>通过 Discord 语音与 CLI 编码代理对话——就像给软件工作打一通电话。</strong>
 </p>
 
 <p align="center">
-  <a href="../../README.md">English</a> ·
   <a href="README.ko.md">한국어</a> ·
   <a href="README.ja.md">日本語</a> ·
   <a href="README.zh.md">中文</a> ·
@@ -19,103 +18,131 @@
   <img alt="Discord" src="https://img.shields.io/badge/Discord-voice%20bridge-5865F2?logo=discord&logoColor=white">
   <img alt="STT" src="https://img.shields.io/badge/STT-whisper.cpp-7C3AED">
   <img alt="TTS" src="https://img.shields.io/badge/TTS-Edge%20%7C%20OpenVoice%20%7C%20Supertonic%20%7C%20SpeechSwift-0EA5E9">
+  <img alt="Agents" src="https://img.shields.io/badge/Agents-Hermes%20%7C%20Claude%20%7C%20Codex%20%7C%20Gemini%20%7C%20OpenCode-111827">
 </p>
 
 <p align="center">
-  <img src="../assets/figures/verbalcoding-flow.svg" alt="VerbalCoding voice-to-agent flow" width="860">
+  <img src="../assets/figures/verbalcoding-flow.svg" alt="VerbalCoding 语音到代理流程" width="860">
 </p>
 
-## Why
+## 为什么需要它
 
-VerbalCoding 把 Discord 语音频道变成面向编程 Agent 的免手动控制台。你可以直接说出需求，让 CLI Agent 工作，再听到简洁的语音回答；同时保留文字记录、进度事件，并避免把大段代码或日志读出来。
+VerbalCoding 会把 Discord 语音频道变成编码代理的免手动控制面板。说出请求，让你的 CLI 代理执行工作，然后听到简洁的语音回复——同时保留文本转写、进度事件，以及针对嘈杂代码/日志输出的保护机制。
 
 ## 亮点
 
-| 能力 | 价值 |
+| 你能获得什么 | 为什么体验很好 |
 |---|---|
-| 语音优先的 Agent 控制 | 用语音控制 Hermes Agent、Claude Code、Codex、Gemini CLI、OpenCode、OpenClaw 或自定义 CLI。 |
-| 本地优先语音闭环 | Discord 语音捕获 → `whisper.cpp` STT → Agent → 分段 TTS 播放。 |
-| 语音 + 文本共享上下文 | 在支持的 Agent 中，语音轮次和 `!ask` 文本命令可复用同一会话。 |
-| 打断与灵敏度模式 | 可自然打断播放，并在普通/保守灵敏度之间切换。 |
-| 多语言语音预设 | 用 `vc language ko/en/auto` 同步切换 STT、进度语言和 TTS 声音。 |
-| 按项目隔离的多房间 | 每个项目房间使用独立 Bot、Hermes profile、会话、记忆和日志。 |
+| 语音优先的代理控制 | 可以与 Hermes Agent、Claude Code、Codex、Gemini CLI、OpenCode、OpenClaw 或任何自定义 CLI 驱动对话。 |
+| 本机语音闭环 | Discord 语音采集 → 本地 `whisper-cli` 转写 → 代理 → 分块 TTS 播放。 |
+| 共享语音 + 文本上下文 | 语音轮次和 `!ask` 文本命令可以复用同一个受支持的代理会话。 |
+| 插话和灵敏度模式 | 可以自然打断播放，并在普通环境与保守/嘈杂环境之间切换。 |
+| 多语言语音预设 | 使用 `vc language ko/en/auto` 同时切换 STT、进度语言和 TTS 声音。 |
+| 多房间项目隔离 | 每个项目房间运行一个机器人，并隔离 Hermes 配置、会话、记忆和日志。 |
 
 ## 快速开始
 
+使用 npm 的最快路径：
+
+```bash
+npm install -g verbalcoding
+vc setup --yes
+vc doctor
+vc start
+```
+
+或者无需永久全局安装，直接运行：
+
+```bash
+npx verbalcoding setup --yes
+vc doctor
+vc start
+```
+
+贡献者的 GitHub 克隆路径：
+
 ```bash
-git clone git@github.com:ca1773130n/VerbalCoding.git
+git clone https://github.com/ca1773130n/VerbalCoding.git
 cd VerbalCoding
-./scripts/install.sh
+./scripts/install.sh --yes
 vc doctor
 ./run.sh
 ```
 
-## 工作原理
-
-```mermaid
-flowchart LR
-  A[Discord voice] --> B["@discordjs/voice"]
-  B --> C[PCM cleanup + gates]
-  C --> D["whisper.cpp STT"]
-  D --> E["CLI agent adapter"]
-  E --> F["Concise answer"]
-  F --> G["Chunked TTS"]
-  G --> H["Discord playback"]
-```
+`vc setup --yes` 会通过 npm 包内置的安装器引导安装本地前置依赖。`./scripts/install.sh --yes` 只在 GitHub 克隆目录中执行同样的流程。两者都会在可行时处理 Node/npm 依赖、`ffmpeg`、`whisper-cli`、默认 whisper.cpp 模型、本地 `.venv-tts` Edge TTS 辅助环境以及设置向导配置。它们支持 macOS/Homebrew 以及常见 Linux 包管理器（`apt`、`dnf`、`pacman`）；如只想安装依赖而不运行向导，可用 `--no-wizard` 重新运行；如果想自行安装 OS 软件包，可用 `--skip-system`。
 
-## 支持的 Agent 后端
+需要干净安装演练？从[全新安装](FRESH_INSTALL.zh.md)开始。
 
-| Backend | Default command | Session support |
+## 支持的代理后端
+
+| 后端 | 默认命令 | 会话支持 |
 |---|---:|---|
-| Hermes Agent | `hermes chat -Q -q` | Resume, verbose progress, cancellation, final-answer recovery |
-| Claude Code | `claude -p` | CLI session file support through adapter defaults |
-| Codex CLI | `codex exec` | CLI session file support through adapter defaults |
-| Gemini CLI | `gemini -p` | CLI session file support through adapter defaults |
-| OpenCode | `opencode run` | CLI session file support through adapter defaults |
-| OpenClaw | `openclaw run` | CLI session file support through adapter defaults |
-| Custom | `AGENT_COMMAND` | Bring your own non-interactive command |
+| Hermes Agent | `hermes chat -Q -q` | 恢复、详细进度、取消、最终答案恢复 |
+| Claude Code | `claude -p` | 通过适配器默认值支持 CLI 会话文件 |
+| Codex CLI | `codex exec` | 通过适配器默认值支持 CLI 会话文件 |
+| Gemini CLI | `gemini -p` | 通过适配器默认值支持 CLI 会话文件 |
+| OpenCode | `opencode run` | 通过适配器默认值支持 CLI 会话文件 |
+| OpenClaw | `openclaw run` | 通过适配器默认值支持 CLI 会话文件 |
+| Custom | `AGENT_COMMAND` | 自带非交互式命令 |
 
 ## 了解更多
 
-| Guide | What you get |
+| 指南 | 你能获得什么 |
 |---|---|
-| [Fresh Install](../FRESH_INSTALL.md) | 干净克隆安装、模型下载、首次运行 |
-| [Usage Guide](../USAGE.md) | CLI 命令、Discord 命令、进度模式、延迟指标 |
-| [Configuration](../CONFIGURATION.md) | .env、Agent 后端、MCP、TTS 后端、运维说明 |
-| [Multi-Instance](../MULTI_INSTANCE.md) | 每个项目一个常驻 Discord 语音房间 |
-| [Release Notes](../RELEASE.md) | 当前能力与发布前检查清单 |
+| [全新安装](FRESH_INSTALL.zh.md) | 干净克隆设置、模型下载、首次运行 |
+| [使用指南](USAGE.zh.md) | CLI 命令、Discord 命令、进度模式、延迟指标 |
+| [配置](CONFIGURATION.zh.md) | `.env`、代理后端、MCP、TTS 后端、运维说明 |
+| [多实例](MULTI_INSTANCE.zh.md) | 每个项目一个长期 Discord 语音房间 |
+| [发行说明](RELEASE.zh.md) | 当前能力和预发布检查清单 |
 
-## 常用命令
+## 精简命令地图
 
 ```bash
-vc status
-vc language ko|en|auto
-vc bot invite CLIENT_ID
-vc instance setup NAME
-vc instance start NAME
-vc doctor
+vc status                 # 当前语言、TTS 和桥接设置
+vc language ko|en|auto    # 切换 STT/进度/TTS 语言预设
+vc bot invite CLIENT_ID   # 生成 Discord 机器人邀请 URL
+vc instance setup NAME    # 创建隔离的项目语音机器人
+vc instance start NAME    # 在后台运行该机器人
+vc doctor                 # 脱敏健康检查
+vc start                  # 启动默认桥接
 ```
 
+在 Discord 中：
+
+| 命令 | 作用 |
+|---|---|
+| `!join` | 加入你当前的语音频道。 |
+| `!ask <prompt>` | 将文本发送给同一个代理后端。 |
+| `!verbose on\|off` | 显示/朗读简短进度更新。 |
+| `!latency` | 汇总最近的语音/STT/代理/TTS 延迟。 |
+| `!sensitivity normal` | 使用普通室内插话灵敏度。 |
+| `!sensitivity conservative` | 使用更严格的嘈杂/户外灵敏度。 |
+| `!session new <name> <workdir> [context] --voice <voice-channel>` | 将项目会话绑定到语音房间。 |
+
 ## 要求
 
-| Layer | Default |
+| 层 | 默认值 |
 |---|---|
-| Runtime | Node.js 20+, npm |
-| Audio | `ffmpeg` |
-| STT | `whisper.cpp` / `whisper-cli` |
-| Discord | Bot token, Message Content intent, voice permissions |
-| Agent | At least one authenticated CLI harness, Hermes Agent by default |
-| Platform focus | macOS / Apple Silicon currently gets the most testing |
+| 运行时 | Node.js 20+、npm；安装脚本可通过 Homebrew/apt/dnf/pacman 安装 |
+| 音频 | `ffmpeg`；安装脚本可安装它 |
+| 语音识别 | 来自 whisper.cpp 的本地 `whisper-cli`；安装脚本在 macOS 使用 Homebrew，在 Linux 使用本地构建回退 |
+| TTS | Edge TTS CLI；安装脚本会在需要时创建 `.venv-tts` |
+| Discord | 机器人令牌、Message Content intent、语音权限 |
+| 代理 | 至少一个已认证的 CLI 驱动，默认是 Hermes Agent |
+| 平台重点 | macOS / Apple Silicon 测试最多；Linux 引导为尽力支持并已文档化 |
 
 ## 贡献
 
+提交更改前运行轻量检查：
+
 ```bash
 node --check app-node/main.mjs
 npm test
 bash -n run.sh scripts/install.sh
+npm pack --dry-run
 vc doctor
 ```
 
 ## 状态
 
-VerbalCoding is public-release oriented but still early. Demo video/GIF, broader Linux notes, and a formal license file are still TODOs.
+VerbalCoding 面向公开发布，但仍处于早期阶段。演示视频/GIF、更广泛的 Linux 验证、CI，以及更深入的安全审查仍在 TODO 中。

package/docs/i18n/RELEASE.es.md

@@ -0,0 +1,74 @@
+# Notas de versión de VerbalCoding
+
+## Candidato de lanzamiento actual
+
+VerbalCoding es un puente de voz de Discord para controlar por voz agentes de programación basados en CLI. Está orientado al lanzamiento público, con macOS / Apple Silicon como la ruta más probada y soporte de arranque de mejor esfuerzo en Linux para administradores de paquetes comunes.
+
+### Incluido
+
+- Recepción de voz de Discord mediante Node `@discordjs/voice`.
+- STT local en coreano mediante `whisper.cpp` + Metal.
+- Reproducción Edge TTS con voz coreana predeterminada.
+- Capa genérica de adaptador para arneses CLI:
+  - Hermes Agent
+  - Claude Code
+  - Codex CLI
+  - Gemini CLI
+  - OpenCode
+  - OpenClaw
+  - comando personalizado
+- Soporte de sesión compartida de voz/texto para el backend Hermes.
+- Fragmentación TTS de respuestas largas e interrupción receptiva.
+- Protecciones para diff/código/registros para que las salidas técnicas grandes no se lean en voz alta.
+- Modos de sensibilidad normal y conservador para uso en interiores frente a uso ruidoso/exterior.
+- Asistente de configuración, `.env.example`, comprobador de prerrequisitos `vc doctor` y arranque `./scripts/install.sh --yes` para paquetes del SO, dependencias npm, asistente de Edge TTS y el modelo predeterminado de whisper.cpp.
+- Ruta de instalación del paquete npm: `npm install -g verbalcoding`, `vc setup --yes` y `vc start`.
+- Modo opcional de progreso detallado para actualizaciones intermedias solo de texto durante trabajos largos del agente.
+- Métricas de latencia JSONL siempre activas más resumen `!latency` / `!metrics` para optimización del pipeline.
+- Espera de inactividad de emisión más paciente (`UTTERANCE_IDLE_MS=4500`) para que las instrucciones habladas largas con pausas naturales no se dividan en un prompt parcial más habla durante procesamiento ignorada.
+- Aislamiento de perfiles Hermes multiinstancia: `vc instance setup <name>` clona automáticamente un perfil Hermes a `~/.hermes/profiles/<name>` con el workdir de la instancia, inicializa SOUL.md y escribe `HERMES_HOME` en el env de la instancia para mantener separadas la memoria y las skills por proyecto; `vc instance start` autorepara un perfil faltante, y `vc doctor` comprueba la presencia del directorio de perfil y la consistencia de `terminal.cwd`.
+
+### Lista de verificación previa al lanzamiento
+
+Ejecuta desde la raíz del repositorio:
+
+```bash
+./scripts/install.sh --yes --no-wizard
+./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 ]  # 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
+```
+
+Prueba manual rápida:
+
+1. Inicia el puente con `vc start` o `./run.sh`.
+2. Verifica que el registro contenga `Logged in as <bot-name>`.
+3. Verifica que el registro contenga `Listening in voice channel ... / 일반` o el canal predeterminado configurado.
+4. En Discord, ejecuta `!ping`.
+5. En voz de Discord, di una solicitud corta en coreano.
+6. Verifica transcripción STT, respuesta del agente, reproducción TTS y comportamiento de interrupción.
+
+### Requisitos conocidos
+
+- macOS con Homebrew, o Linux con `apt`, `dnf` o `pacman` para arranque de mejor esfuerzo.
+- `ffmpeg`; el instalador intenta instalarlo.
+- `whisper-cli`; el instalador usa Homebrew en macOS o una compilación local alternativa de `vendor/whisper.cpp` en Linux.
+- Modelo predeterminado en `models/ggml-small-q5_1.bin`; el instalador lo descarga salvo que se use `--skip-model`.
+- CLI de Edge TTS en `PATH` o `.venv-tts/bin/edge-tts` local; el instalador crea el asistente local cuando hace falta.
+- Token de bot de Discord en `.env`, `instances/<name>.env`, `~/.zshrc` o env de runtime.
+- Arnés CLI seleccionado instalado y autenticado.
+
+### Aún no listo para lanzamiento público
+
+Antes del lanzamiento público, considera añadir:
+
+- CI de GitHub Actions.
+- Video / GIF de demostración.
+- Capturas de pantalla de configuración de bot de Discord.
+- Validación más amplia en distribuciones Linux reales más allá de comprobaciones a nivel de script.
+- Revisión de seguridad de todas las rutas de registro.

package/docs/i18n/RELEASE.fr.md

@@ -0,0 +1,74 @@
+# Notes de version de VerbalCoding
+
+## Candidat de version actuel
+
+VerbalCoding est une passerelle vocale Discord pour contrôler par la voix des agents de codage basés sur CLI. Il vise une publication publique, avec macOS / Apple Silicon comme chemin le plus testé et une prise en charge d'amorçage Linux au mieux pour les gestionnaires de paquets courants.
+
+### Inclus
+
+- Réception vocale Discord via Node `@discordjs/voice`.
+- STT coréen local via `whisper.cpp` + Metal.
+- Lecture Edge TTS avec voix coréenne par défaut.
+- Couche générique d'adaptateur de harnais CLI :
+  - Hermes Agent
+  - Claude Code
+  - Codex CLI
+  - Gemini CLI
+  - OpenCode
+  - OpenClaw
+  - commande personnalisée
+- Prise en charge de session voix/texte partagée pour le backend Hermes.
+- Découpage TTS des longues réponses et interruption réactive.
+- Garde-fous diff/code/journaux pour que les grandes sorties techniques ne soient pas lues à voix haute.
+- Modes de sensibilité normal et conservateur pour usage intérieur vs bruyant/extérieur.
+- Assistant de configuration, `.env.example`, vérificateur de prérequis `vc doctor` et amorçage `./scripts/install.sh --yes` pour les paquets OS, les dépendances npm, l'assistant Edge TTS et le modèle whisper.cpp par défaut.
+- Chemin d'installation par paquet npm : `npm install -g verbalcoding`, `vc setup --yes` et `vc start`.
+- Mode de progression détaillée facultatif pour les mises à jour textuelles d'étapes intermédiaires pendant les longs travaux d'agent.
+- Métriques de latence JSONL toujours actives plus résumé `!latency` / `!metrics` pour l'optimisation du pipeline.
+- Attente d'inactivité d'énonciation plus patiente (`UTTERANCE_IDLE_MS=4500`) afin que les longues instructions parlées avec pauses naturelles ne soient pas coupées en prompt partiel plus parole ignorée pendant le traitement.
+- Isolation multi-instance des profils Hermes : `vc instance setup <name>` clone automatiquement un profil Hermes vers `~/.hermes/profiles/<name>` avec le workdir de l'instance, initialise SOUL.md et écrit `HERMES_HOME` dans l'env de l'instance afin que la mémoire et les skills par projet restent séparés ; `vc instance start` répare automatiquement un profil manquant, et `vc doctor` vérifie la présence du répertoire de profil et la cohérence de `terminal.cwd`.
+
+### Checklist de pré-version
+
+Exécutez depuis la racine du dépôt :
+
+```bash
+./scripts/install.sh --yes --no-wizard
+./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 ]  # 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
+```
+
+Smoke test manuel :
+
+1. Démarrez la passerelle avec `vc start` ou `./run.sh`.
+2. Vérifiez que le journal contient `Logged in as <bot-name>`.
+3. Vérifiez que le journal contient `Listening in voice channel ... / 일반` ou le salon par défaut configuré.
+4. Dans Discord, exécutez `!ping`.
+5. Dans la voix Discord, dites une courte demande en coréen.
+6. Vérifiez la transcription STT, la réponse de l'agent, la lecture TTS et le comportement d'interruption.
+
+### Exigences connues
+
+- macOS avec Homebrew, ou Linux avec `apt`, `dnf` ou `pacman` pour l'amorçage au mieux.
+- `ffmpeg` ; l'installateur tente de l'installer.
+- `whisper-cli` ; l'installateur utilise Homebrew sur macOS ou un fallback de build local `vendor/whisper.cpp` sur Linux.
+- Modèle par défaut à `models/ggml-small-q5_1.bin` ; l'installateur le télécharge sauf si `--skip-model` est utilisé.
+- CLI Edge TTS dans `PATH` ou `.venv-tts/bin/edge-tts` local ; l'installateur crée l'assistant local si nécessaire.
+- Jeton de bot Discord dans `.env`, `instances/<name>.env`, `~/.zshrc` ou l'env d'exécution.
+- Harnais CLI sélectionné installé et authentifié.
+
+### Pas encore prêt pour la publication publique
+
+Avant la publication publique, envisagez d'ajouter :
+
+- CI GitHub Actions.
+- Vidéo / GIF de démonstration.
+- Captures d'écran de configuration du bot Discord.
+- Validation Linux plus large sur de vraies distributions au-delà des contrôles au niveau des scripts.
+- Revue de sécurité de tous les chemins de journalisation.

package/docs/i18n/RELEASE.ja.md

@@ -0,0 +1,74 @@
+# VerbalCoding リリースノート
+
+## 現在のリリース候補
+
+VerbalCoding は、CLI ベースのコーディングエージェントを音声で操作するための Discord 音声ブリッジです。公開リリースを意識しており、最も検証されている経路は macOS / Apple Silicon です。一般的なパッケージマネージャー向けに、Linux のベストエフォートなブートストラップもサポートしています。
+
+### 含まれるもの
+
+- 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 プロファイル分離: `vc instance setup <name>` は、インスタンス作業ディレクトリ付きで Hermes プロファイルを `~/.hermes/profiles/<name>` に自動複製し、SOUL.md を初期化し、インスタンス env に `HERMES_HOME` を書き込みます。これによりプロジェクトごとのメモリとスキルを分離できます。`vc instance start` は欠落したプロファイルを自己修復し、`vc doctor` はプロファイルディレクトリの存在と `terminal.cwd` の整合性を確認します。
+
+### プレリリースチェックリスト
+
+リポジトリルートから実行してください:
+
+```bash
+./scripts/install.sh --yes --no-wizard
+./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 ]  # 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
+```
+
+手動スモークテスト:
+
+1. `vc start` または `./run.sh` でブリッジを起動します。
+2. ログに `Logged in as <bot-name>` が含まれることを確認します。
+3. ログに `Listening in voice channel ... / 일반` または設定済みのデフォルトチャンネルが含まれることを確認します。
+4. Discord で `!ping` を実行します。
+5. Discord 音声で短い韓国語リクエストを話します。
+6. STT 文字起こし、エージェント応答、TTS 再生、割り込み発話の動作を確認します。
+
+### 既知の要件
+
+- ベストエフォートのブートストラップには、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 ハーネスがインストール済みで認証済みであること。
+
+### まだ公開リリース向けではないもの
+
+公開リリース前に、次の追加を検討してください:
+
+- GitHub Actions CI。
+- デモ動画 / GIF。
+- Discord ボットセットアップのスクリーンショット。
+- スクリプトレベルのチェックを超えた、実ディストリビューション上でのより広範な Linux 検証。
+- すべてのログパスのセキュリティレビュー。

package/docs/i18n/RELEASE.ko.md

@@ -2,42 +2,42 @@
 
 ## 현재 릴리스 후보
 
-VerbalCoding은 음성으로 CLI 기반 코딩 에이전트를 제어하기 위한 Discord 음성 브릿지입니다. 공개 릴리스를 지향하며, macOS / Apple Silicon 경로가 가장 많이 테스트되어 있고, 일반적인 Linux 패키지 매니저에 대해서는 best-effort 부트스트랩을 제공합니다.
+VerbalCoding은 CLI 기반 코딩 에이전트를 음성으로 제어하기 위한 Discord 음성 브리지입니다. 공개 릴리스를 지향하며, macOS / Apple Silicon 경로가 가장 많이 테스트되었고 일반적인 패키지 관리자에 대한 Linux 부트스트랩은 최선 노력으로 지원됩니다.
 
-### 포함된 기능
+### 포함됨
 
-- Node `@discordjs/voice` 기반 Discord 음성 수신.
-- `whisper.cpp` + Metal 기반 로컬 한국어 STT.
+- Node `@discordjs/voice`를 통한 Discord 음성 수신.
+- `whisper.cpp` + Metal을 통한 로컬 한국어 STT.
 - 한국어 기본 음성을 사용하는 Edge TTS 재생.
-- 범용 CLI 하네스 어댑터 레이어:
+- 범용 CLI 하네스 어댑터 계층:
   - Hermes Agent
   - Claude Code
   - Codex CLI
   - Gemini CLI
   - OpenCode
   - OpenClaw
-  - custom command
-- Hermes 백엔드의 음성/텍스트 공유 세션 지원.
-- 긴 답변 TTS chunking과 반응형 barge-in.
-- 큰 diff/code/log 출력이 음성으로 읽히지 않도록 하는 guardrail.
-- 실내와 noisy/outdoor 환경을 위한 normal/conservative 감도 모드.
-- 설정 마법사, `.env.example`, `vc doctor` prerequisite checker, OS 패키지/npm 의존성/Edge TTS helper/기본 whisper.cpp 모델을 준비하는 `./scripts/install.sh --yes` 부트스트랩.
-- 긴 에이전트 작업 중 텍스트 전용 중간 단계 업데이트를 위한 선택적 verbose progress mode.
-- 파이프라인 최적화를 위한 JSONL latency metrics와 `!latency` / `!metrics` 요약.
-- 더 여유 있는 utterance idle wait (`UTTERANCE_IDLE_MS=4500`)로 자연스러운 중간 멈춤이 있는 긴 지시가 앞부분 prompt와 무시되는 processing-time speech로 쪼개지지 않도록 개선.
-- 멀티 인스턴스 Hermes 프로필 격리: `vc instance setup <name>`이 자동으로 Hermes 프로필을 `~/.hermes/profiles/<name>`에 clone하고, instance workdir을 설정하고, SOUL.md를 초기화하고, instance env에 `HERMES_HOME`을 기록합니다. `vc instance start`는 누락된 profile을 self-heal하고, `vc doctor`는 profile-dir 존재와 `terminal.cwd` 일관성을 검사합니다.
-- npm 공개 패키지: `npm install -g verbalcoding`, `vc setup --yes`, `vc start` 경로 지원.
+  - 커스텀 명령
+- 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` 일관성을 확인합니다.
 
-### 릴리스 전 체크리스트
+### 사전 릴리스 체크리스트
 
-저장소 루트에서 실행:
+저장소 루트에서 실행하세요:
 
 ```bash
 ./scripts/install.sh --yes --no-wizard
-./scripts/docker_ubuntu_smoke.sh   # Docker 필요; ubuntu:24.04 clean install 검증
+./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 ]  # Python 테스트가 없으면 exit 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
@@ -46,27 +46,29 @@ git diff --check
 
 수동 스모크 테스트:
 
-1. `vc start` 또는 `./run.sh`로 브릿지를 시작합니다.
-2. 로그에 `Logged in as <bot-name>`이 있는지 확인합니다.
-3. 로그에 `Listening in voice channel ... / 일반` 또는 설정된 기본 채널이 있는지 확인합니다.
+1. `vc start` 또는 `./run.sh`로 브리지를 시작합니다.
+2. 로그에 `Logged in as <bot-name>`가 포함되는지 확인합니다.
+3. 로그에 `Listening in voice channel ... / 일반` 또는 설정된 기본 채널이 포함되는지 확인합니다.
 4. Discord에서 `!ping`을 실행합니다.
 5. Discord 음성에서 짧은 한국어 요청을 말합니다.
-6. STT transcript, agent response, TTS playback, barge-in 동작을 확인합니다.
+6. STT 전사, 에이전트 응답, TTS 재생, 끼어들기 동작을 확인합니다.
 
 ### 알려진 요구 사항
 
-- macOS + Homebrew 또는 Linux + `apt`, `dnf`, `pacman` best-effort bootstrap.
-- `ffmpeg`; 설치기가 설치를 시도합니다.
-- `whisper-cli`; macOS에서는 Homebrew를 사용하고, Linux에서는 로컬 `vendor/whisper.cpp` 빌드 fallback을 사용합니다.
-- 기본 모델 `models/ggml-small-q5_1.bin`; `--skip-model`을 쓰지 않으면 설치기가 다운로드합니다.
-- PATH의 Edge TTS CLI 또는 로컬 `.venv-tts/bin/edge-tts`; 필요하면 설치기가 로컬 helper를 만듭니다.
-- `.env`, `instances/<name>.env`, `~/.zshrc`, runtime env 중 하나에 Discord bot token.
-- 선택한 CLI 하네스가 설치되고 인증되어 있어야 합니다.
+- 최선 노력 부트스트랩을 위해 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 하네스가 설치 및 인증되어 있어야 합니다.
 
-### 아직 public release 전에 보강하면 좋은 것
+### 아직 공개 릴리스용은 아님
+
+공개 릴리스 전에 다음 추가를 고려하세요:
 
 - GitHub Actions CI.
-- Demo video / GIF.
-- Discord bot setup screenshots.
-- 스크립트 수준 검증을 넘어 실제 여러 Linux 배포판에서 더 넓은 검증.
-- 모든 logging path 보안 리뷰.
+- 데모 비디오 / GIF.
+- Discord 봇 설정 스크린샷.
+- 스크립트 수준 점검을 넘어 실제 배포판에서 더 넓은 Linux 검증.
+- 모든 로깅 경로의 보안 검토.

package/docs/i18n/RELEASE.ru.md

@@ -0,0 +1,74 @@
+# Заметки о релизе VerbalCoding
+
+## Текущий релиз-кандидат
+
+VerbalCoding — это голосовой bridge Discord для управления CLI-агентами кодинга голосом. Он ориентирован на публичный релиз; macOS / Apple Silicon — наиболее протестированный путь, а bootstrap-поддержка Linux для распространённых менеджеров пакетов предоставляется по мере возможностей.
+
+### Включено
+
+- Приём голоса 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`.
+
+### Чеклист перед релизом
+
+Запускайте из корня репозитория:
+
+```bash
+./scripts/install.sh --yes --no-wizard
+./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 ]  # 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
+```
+
+Ручной 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 и поведение перебивания.
+
+### Известные требования
+
+- 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-харнес установлен и аутентифицирован.
+
+### Пока не для публичного релиза
+
+Перед публичным релизом стоит добавить:
+
+- GitHub Actions CI.
+- Демо-видео / GIF.
+- Скриншоты настройки Discord-бота.
+- Более широкую проверку Linux на реальных дистрибутивах сверх проверок на уровне скриптов.
+- Аудит безопасности всех путей логирования.