verbalcoding 0.2.6 → 0.2.7

package/docs/i18n/README.ru.md

@@ -1,91 +1,66 @@
 # VerbalCoding
 
-<p align="center">
-  <strong>Общайтесь с CLI-агентами для программирования голосом в Discord — почти как по телефону.</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> ·
-  <a href="README.es.md">Español</a> ·
-  <a href="README.fr.md">Français</a> ·
-  <a href="README.ru.md">Русский</a>
-</p>
-
-<p align="center">
-  <img alt="Node.js" src="https://img.shields.io/badge/Node.js-20%2B-339933?logo=node.js&logoColor=white">
-  <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">
-</p>
-
-<p align="center">
-  <img src="../assets/figures/verbalcoding-flow.svg" alt="VerbalCoding voice-to-agent flow" width="860">
-</p>
+**Управляйте CLI-агентами для кода голосом в Discord — почти как по телефону.**
+
+[English](../../README.md) · [한국어](README.ko.md) · [日本語](README.ja.md) · [中文](README.zh.md) · [Español](README.es.md) · [Français](README.fr.md) · [Русский](README.ru.md)
+
+![VerbalCoding voice-to-agent flow](../assets/figures/verbalcoding-flow.svg)
 
 ## Why
 
-VerbalCoding превращает голосовой канал Discord в hands-free панель управления агентами для разработки. Скажите задачу, дайте CLI-агенту выполнить работу и получите краткий голосовой ответ — с текстовыми транскриптами, событиями прогресса и защитой от зачитывания длинного кода или логов.
+VerbalCoding превращает голосовой канал Discord в hands-free интерфейс для coding agents. Вы произносите задачу, CLI-агент работает, а вы получаете краткий голосовой ответ, текстовую расшифровку и события прогресса.
 
-## Возможности
+## Highlights
 
-| Что есть | Почему это удобно |
+| Feature | What it means |
 |---|---|
-| Голосовое управление прежде всего | Управляйте Hermes Agent, Claude Code, Codex, Gemini CLI, OpenCode, OpenClaw или своим CLI голосом. |
-| Локальный voice loop | Голос Discord → STT `whisper.cpp` → агент → фрагментированное TTS-воспроизведение. |
-| Общий контекст голоса и текста | Голосовые реплики и `!ask` могут использовать одну и ту же поддерживаемую сессию агента. |
-| Barge-in и режимы чувствительности | Естественно перебивайте воспроизведение и переключайте normal/conservative режимы. |
-| Многоязычные voice presets | `vc language ko/en/auto` одновременно меняет STT, язык прогресса и TTS-голос. |
-| Изоляция комнат по проектам | Отдельный bot, Hermes profile, сессия, память и логи для каждого проекта. |
+| Voice-first agent control | Hermes Agent, Claude Code, Codex, Gemini CLI, OpenCode, OpenClaw, or a custom CLI harness. |
+| Local-first speech loop | Discord voice capture → `whisper.cpp` STT → agent → chunked TTS playback. |
+| Shared voice + text context | Voice turns and `!ask` text commands can reuse the same supported agent session. |
+| Barge-in and sensitivity modes | Interrupt playback naturally and switch between normal and conservative/noisy modes. |
+| Multilingual voice presets | `vc language ko/en/auto` changes STT, progress language, and TTS voice together. |
+| Multi-room project isolation | Run one bot per project room with isolated Hermes profiles, sessions, memory, and logs. |
 
-## Быстрый старт
+## Quick Start
 
 ```bash
-git clone git@github.com:ca1773130n/VerbalCoding.git
-cd VerbalCoding
-./scripts/install.sh
+npm install -g verbalcoding
+vc setup --yes
 vc doctor
-./run.sh
+vc start
 ```
 
-## Как это работает
-
-```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"]
+Run without a permanent global install:
+
+```bash
+npx verbalcoding setup --yes
+vc doctor
+vc start
 ```
 
-## Поддерживаемые agent-бэкенды
+Contributor clone path:
+
+```bash
+git clone https://github.com/ca1773130n/VerbalCoding.git
+cd VerbalCoding
+./scripts/install.sh --yes
+vc doctor
+./run.sh
+```
 
-| 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 |
+`vc setup --yes` and `./scripts/install.sh --yes` bootstrap npm dependencies, `ffmpeg`, `whisper-cli`, the default whisper.cpp model, a local Edge TTS helper, and the short `vc` command where possible.
 
-## Подробнее
+## Guides
 
-| Guide | What you get |
+| Guide | Link |
 |---|---|
-| [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) | Текущие возможности и pre-release checklist |
+| Чистая установка | [FRESH_INSTALL.ru.md](FRESH_INSTALL.ru.md) |
+| Руководство по использованию | [USAGE.ru.md](USAGE.ru.md) |
+| Конфигурация | [CONFIGURATION.ru.md](CONFIGURATION.ru.md) |
+| Мульти-инстансы | [MULTI_INSTANCE.ru.md](MULTI_INSTANCE.ru.md) |
+| Заметки о релизе | [RELEASE.ru.md](RELEASE.ru.md) |
 
-## Карта команд
+## Command map
 
 ```bash
 vc status
@@ -94,28 +69,17 @@ vc bot invite CLIENT_ID
 vc instance setup NAME
 vc instance start NAME
 vc doctor
+vc start
 ```
 
-## Требования
+Discord commands:
 
-| 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 |
-
-## Участие
-
-```bash
-node --check app-node/main.mjs
-npm test
-bash -n run.sh scripts/install.sh
-vc doctor
+```text
+!join        !ask <prompt>       !verbose on/off
+!latency     !sensitivity normal !sensitivity conservative
+!session new <name> <workdir> [context] --voice <voice-channel>
 ```
 
-## Статус
+## Requirements
 
-VerbalCoding is public-release oriented but still early. Demo video/GIF, broader Linux notes, and a formal license file are still TODOs.
+Node.js 20+, npm, `ffmpeg`, `whisper.cpp` / `whisper-cli`, Edge TTS CLI, a Discord bot token with Message Content intent and voice permissions, and at least one authenticated CLI agent backend.

package/docs/i18n/README.zh.md

@@ -1,91 +1,66 @@
 # VerbalCoding
 
-<p align="center">
-  <strong>通过 Discord 语音像打电话一样控制 CLI 编程 Agent。</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> ·
-  <a href="README.es.md">Español</a> ·
-  <a href="README.fr.md">Français</a> ·
-  <a href="README.ru.md">Русский</a>
-</p>
-
-<p align="center">
-  <img alt="Node.js" src="https://img.shields.io/badge/Node.js-20%2B-339933?logo=node.js&logoColor=white">
-  <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">
-</p>
-
-<p align="center">
-  <img src="../assets/figures/verbalcoding-flow.svg" alt="VerbalCoding voice-to-agent flow" width="860">
-</p>
+**通过 Discord 语音像打电话一样控制 CLI 编程代理。**
+
+[English](../../README.md) · [한국어](README.ko.md) · [日本語](README.ja.md) · [中文](README.zh.md) · [Español](README.es.md) · [Français](README.fr.md) · [Русский](README.ru.md)
+
+![VerbalCoding voice-to-agent flow](../assets/figures/verbalcoding-flow.svg)
 
 ## Why
 
-VerbalCoding 把 Discord 语音频道变成面向编程 Agent 的免手动控制台。你可以直接说出需求，让 CLI Agent 工作，再听到简洁的语音回答；同时保留文字记录、进度事件，并避免把大段代码或日志读出来。
+VerbalCoding 把 Discord 语音频道变成编程代理的免手控制界面。说出需求，让 CLI 代理工作，然后收到简洁的语音回复、文本转录和进度事件。
 
-## 亮点
+## Highlights
 
-| 能力 | 价值 |
+| Feature | What it means |
 |---|---|
-| 语音优先的 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、会话、记忆和日志。 |
+| Voice-first agent control | Hermes Agent, Claude Code, Codex, Gemini CLI, OpenCode, OpenClaw, or a custom CLI harness. |
+| Local-first speech loop | Discord voice capture → `whisper.cpp` STT → agent → chunked TTS playback. |
+| Shared voice + text context | Voice turns and `!ask` text commands can reuse the same supported agent session. |
+| Barge-in and sensitivity modes | Interrupt playback naturally and switch between normal and conservative/noisy modes. |
+| Multilingual voice presets | `vc language ko/en/auto` changes STT, progress language, and TTS voice together. |
+| Multi-room project isolation | Run one bot per project room with isolated Hermes profiles, sessions, memory, and logs. |
 
-## 快速开始
+## Quick Start
 
 ```bash
-git clone git@github.com:ca1773130n/VerbalCoding.git
-cd VerbalCoding
-./scripts/install.sh
+npm install -g verbalcoding
+vc setup --yes
 vc doctor
-./run.sh
+vc start
 ```
 
-## 工作原理
-
-```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"]
+Run without a permanent global install:
+
+```bash
+npx verbalcoding setup --yes
+vc doctor
+vc start
 ```
 
-## 支持的 Agent 后端
+Contributor clone path:
+
+```bash
+git clone https://github.com/ca1773130n/VerbalCoding.git
+cd VerbalCoding
+./scripts/install.sh --yes
+vc doctor
+./run.sh
+```
 
-| 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 |
+`vc setup --yes` and `./scripts/install.sh --yes` bootstrap npm dependencies, `ffmpeg`, `whisper-cli`, the default whisper.cpp model, a local Edge TTS helper, and the short `vc` command where possible.
 
-## 了解更多
+## Guides
 
-| Guide | What you get |
+| Guide | Link |
 |---|---|
-| [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](FRESH_INSTALL.zh.md) |
+| 使用指南 | [USAGE.zh.md](USAGE.zh.md) |
+| 配置 | [CONFIGURATION.zh.md](CONFIGURATION.zh.md) |
+| 多实例 | [MULTI_INSTANCE.zh.md](MULTI_INSTANCE.zh.md) |
+| 发布说明 | [RELEASE.zh.md](RELEASE.zh.md) |
 
-## 常用命令
+## Command map
 
 ```bash
 vc status
@@ -94,28 +69,17 @@ vc bot invite CLIENT_ID
 vc instance setup NAME
 vc instance start NAME
 vc doctor
+vc start
 ```
 
-## 要求
+Discord commands:
 
-| 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 |
-
-## 贡献
-
-```bash
-node --check app-node/main.mjs
-npm test
-bash -n run.sh scripts/install.sh
-vc doctor
+```text
+!join        !ask <prompt>       !verbose on/off
+!latency     !sensitivity normal !sensitivity conservative
+!session new <name> <workdir> [context] --voice <voice-channel>
 ```
 
-## 状态
+## Requirements
 
-VerbalCoding is public-release oriented but still early. Demo video/GIF, broader Linux notes, and a formal license file are still TODOs.
+Node.js 20+, npm, `ffmpeg`, `whisper.cpp` / `whisper-cli`, Edge TTS CLI, a Discord bot token with Message Content intent and voice permissions, and at least one authenticated CLI agent backend.

package/docs/i18n/RELEASE.es.md

@@ -0,0 +1,58 @@
+# VerbalCoding Notas de versión
+
+## 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.
+
+## 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`.
+
+## Pre-release checklist
+
+```bash
+./scripts/install.sh --yes --no-wizard
+./scripts/docker_ubuntu_smoke.sh
+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 ]
+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. 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 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.

package/docs/i18n/RELEASE.fr.md

@@ -0,0 +1,58 @@
+# VerbalCoding Notes de version
+
+## 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.
+
+## 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`.
+
+## Pre-release checklist
+
+```bash
+./scripts/install.sh --yes --no-wizard
+./scripts/docker_ubuntu_smoke.sh
+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 ]
+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. 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 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.

package/docs/i18n/RELEASE.ja.md

@@ -0,0 +1,58 @@
+# 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.
+
+## 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`.
+
+## Pre-release checklist
+
+```bash
+./scripts/install.sh --yes --no-wizard
+./scripts/docker_ubuntu_smoke.sh
+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 ]
+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. 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 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.

package/docs/i18n/RELEASE.ko.md

@@ -1,72 +1,58 @@
 # VerbalCoding 릴리스 노트
 
-## 현재 릴리스 후보
+## Current release candidate
 
-VerbalCoding은 음성으로 CLI 기반 코딩 에이전트를 제어하기 위한 Discord 음성 브릿지입니다. 공개 릴리스를 지향하며, macOS / Apple Silicon 경로가 가장 많이 테스트되어 있고, 일반적인 Linux 패키지 매니저에 대해서는 best-effort 부트스트랩을 제공합니다.
+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.
 
-### 포함된 기능
+## Included
 
-- Node `@discordjs/voice` 기반 Discord 음성 수신.
-- `whisper.cpp` + Metal 기반 로컬 한국어 STT.
-- 한국어 기본 음성을 사용하는 Edge TTS 재생.
-- 범용 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` 경로 지원.
+- 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`.
 
-### 릴리스 전 체크리스트
-
-저장소 루트에서 실행:
+## Pre-release checklist
 
 ```bash
 ./scripts/install.sh --yes --no-wizard
-./scripts/docker_ubuntu_smoke.sh   # Docker 필요; ubuntu:24.04 clean install 검증
+./scripts/docker_ubuntu_smoke.sh
 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 ]
 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 transcript, agent response, TTS playback, barge-in 동작을 확인합니다.
+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`; 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 하네스가 설치되고 인증되어 있어야 합니다.
+- 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.
 
-### 아직 public release 전에 보강하면 좋은 것
+## Not for public release yet
 
-- GitHub Actions CI.
-- Demo video / GIF.
-- Discord bot setup screenshots.
-- 스크립트 수준 검증을 넘어 실제 여러 Linux 배포판에서 더 넓은 검증.
-- 모든 logging path 보안 리뷰.
+Consider adding GitHub Actions CI, demo video/GIF, Discord bot setup screenshots, broader real Linux validation, and security review of logging paths.