verbalcoding 0.2.11 → 0.2.13

package/README.ko.md

@@ -0,0 +1,134 @@
+# VerbalCoding
+
+<p align="center"><strong>Discord 음성으로 CLI 코딩 에이전트와 통화하듯 작업하세요.</strong></p>
+
+<p align="center"><a href="./README.md">English</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="npm" src="https://img.shields.io/npm/v/verbalcoding?color=CB3837&logo=npm&logoColor=white">
+  <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%20SpeechSwift-0EA5E9">
+  <img alt="License" src="https://img.shields.io/github/license/ca1773130n/VerbalCoding">
+</p>
+
+<p align="center">
+  <img src="docs/assets/figures/verbalcoding-flow.svg" alt="VerbalCoding voice-to-agent flow" width="860">
+</p>
+
+## 존재 이유
+
+VerbalCoding은 Discord 음성 방을 코딩 에이전트용 핸즈프리 조종석으로 바꿉니다. 말로 요청하고, CLI 에이전트가 작업하게 두고, 간결한 음성 답변과 텍스트 기록을 받습니다. diff와 로그는 TTS로 길게 읽지 않도록 보호합니다.
+
+> **Hermes Agent를 이미 쓰고 있나요?** Hermes 자체도 `/voice join` / `/voice channel`로 Discord 음성 채널에 들어가 Whisper STT와 TTS 답변을 처리할 수 있습니다. 그 기본 루프만 필요하다면 VerbalCoding은 필수가 아닙니다. VerbalCoding은 그 위에 프로젝트/세션 라우팅, 음성+텍스트 공유 컨텍스트, 바지인 규칙, 진행 음성 안내, 언어 프리셋, 지연 시간 지표, Hermes 외 CLI 백엔드 전환을 얹는 워크플로 레이어입니다.
+
+## 무엇이 다른가
+
+| 기능 | 왜 중요한가 |
+|---|---|
+| 통화 같은 작업 흐름 | 한 Discord 음성 채널에서 말하고, 듣고, 끼어들고, 이어서 작업합니다. |
+| 안내형 사람용 설정 | `vc setup`이 prerequisites, Discord token/client ID, voice channel, transcript target, backend, TTS 설정을 한 흐름으로 묻습니다. |
+| 로컬 음성 루프 | Discord audio → local `whisper-cli` → selected CLI agent → TTS 답변. |
+| 에이전트 선택 | Hermes Agent, Claude Code, Codex, Gemini CLI, OpenCode, OpenClaw, Aider, Cursor CLI 또는 custom command를 지원합니다. `vc setup`이 설치된 것을 자동 감지해요. |
+| 음성으로 에이전트 라우팅 | `"코덱스한테 물어봐"`로 한 턴만 보내거나 `"aider로 전환"`으로 sticky 전환. `"기본으로 돌아가"`로 복귀. 없는 바이너리는 감지해서 기본 에이전트로 fallback할지 물어봐. |
+| Hermes 기본 음성 너머 | 같은 VC 음성 루프를 기반으로 프로젝트 방, `!ask` 공유 컨텍스트, 세밀한 끼어들기 처리, 진행/상태 음성 안내, 다중 에이전트 백엔드 제어를 더합니다. |
+| 운영 친화 기능 | doctor auto-fix, Docker UDP 안내, latency metrics, multi-instance rooms, redacted config checks가 포함됩니다. |
+
+## 빠른 시작
+
+```bash
+npm install -g verbalcoding@latest
+vc setup
+vc doctor
+vc start
+```
+
+`vc setup`이 일반 사용자 경로입니다. Discord Developer Portal을 열어 둔 상태에서 bot token, application/client ID, transcript target, voice channel names를 입력하세요.
+
+자동화에서는 프롬프트를 건너뛴 뒤 Discord 값을 나중에 넣을 수 있습니다.
+
+```bash
+vc setup --yes
+vc setup token <bot-token> --client-id <discord-client-id>
+vc setup channels "General,Team Voice"
+vc doctor
+```
+
+## Discord 설정 1분 요약
+
+1. Discord Developer Portal에서 application과 bot을 만듭니다.
+2. Message Content privileged intent를 켭니다.
+3. `vc setup`을 실행하고 bot token과 application/client ID를 붙여넣습니다.
+4. 자동 입장할 voice channel 이름을 정확히 입력합니다.
+5. 아래 명령으로 bot을 초대합니다.
+
+```bash
+vc bot invite <discord-client-id>
+vc bot invite <discord-client-id> --guild <guild-id>
+```
+
+## 작은 명령 지도
+
+```bash
+vc setup                                 # 안내형 설정: prerequisites, Discord, backend, voice
+vc setup --yes                           # 비대화형 bootstrap/starter config
+vc setup token                           # 나중에 Discord bot token과 client ID 회전/추가
+vc setup channels "General,Team Voice"   # auto-join voice channel names 업데이트
+vc bot invite CLIENT_ID                  # Discord bot invite URL 생성
+vc status                                # 현재 설정 표시
+vc language ko|en|auto                   # language preset 전환
+vc doctor                                # redacted health check와 auto-fix
+vc start                                 # 기본 bridge 시작
+vc instance setup NAME                   # 격리된 project voice bot 생성
+vc instance start NAME                   # 해당 bot을 background로 실행
+```
+
+## 더 보기
+
+| 가이드 | 내용 |
+|---|---|
+| [문서 허브](docs/i18n/README.ko.md) | 현지화된 가이드 색인. |
+| [Fresh Install](docs/i18n/FRESH_INSTALL.ko.md) | npm/global setup, Discord 설정, 첫 실행. |
+| [Usage](docs/i18n/USAGE.ko.md) | CLI 명령, Discord 명령, 실행 모드, latency. |
+| [하니스 사용법](docs/i18n/HARNESSES.ko.md) | Claude Code, Codex, Aider 등 백엔드별 설치·설정·음성 라우팅. |
+| [Hermes 기본 음성 vs VerbalCoding](docs/i18n/HERMES_VOICE.ko.md) | Hermes가 이미 지원하는 Discord 음성과 VerbalCoding의 차이. |
+| [Configuration](docs/i18n/CONFIGURATION.ko.md) | .env, agent backends, MCP, TTS, 운영. |
+| [Troubleshooting](docs/i18n/TROUBLESHOOTING.ko.md) | Docker UDP, token/channel 누락 점검. |
+| [Multi-Instance](docs/i18n/MULTI_INSTANCE.ko.md) | 프로젝트마다 하나의 고정 음성 방. |
+
+## 요구 사항
+
+| 계층 | 기본값 |
+|---|---|
+| Runtime | Node.js 20+와 npm. |
+| Audio | `ffmpeg`와 local `whisper-cli`. |
+| TTS | 기본 Edge TTS, 선택 OpenVoice, SpeechSwift/CosyVoice, Supertonic, OmniVoice, Qwen3 TTS CLI. |
+| Discord | Bot token, Message Content intent, voice permissions, 일치하는 channel names. |
+| Agent | 인증된 CLI harness 하나 이상, 기본은 Hermes Agent. |
+
+## Docker / 컨테이너 참고
+
+로그에 `Cannot perform IP discovery - socket closed`가 보이면 Discord voice UDP가 막힌 것입니다. Linux Docker Compose에서는 다음을 사용하세요:
+
+```yaml
+services:
+  verbalcoding:
+    network_mode: "host"
+```
+
+`network_mode: "host"`와 `ports:`를 함께 쓰지 마세요.
+
+## 기여
+
+```bash
+node --check app-node/main.mjs
+npm test
+bash -n run.sh scripts/install.sh scripts/bootstrap_prereqs.sh
+npm pack --dry-run
+vc doctor
+```
+
+## 상태
+
+VerbalCoding은 공개 릴리스를 지향하지만 아직 초기 단계입니다. 데모 영상/GIF, 더 넓은 Linux 검증, CI, 보안 리뷰는 TODO입니다.

package/README.md

@@ -1,148 +1,192 @@
 # VerbalCoding
 
 <p align="center">
-  <strong>Talk to your CLI coding agents through Discord voice — like a phone call for software work.</strong>
+  <strong>The voice layer for any coding agent — real barge-in, streaming latency, and the agents you already use.</strong>
 </p>
 
 <p align="center">
-  <a href="docs/i18n/README.ko.md">한국어</a> ·
-  <a href="docs/i18n/README.ja.md">日本語</a> ·
-  <a href="docs/i18n/README.zh.md">中文</a> ·
-  <a href="docs/i18n/README.es.md">Español</a> ·
-  <a href="docs/i18n/README.fr.md">Français</a> ·
-  <a href="docs/i18n/README.ru.md">Русский</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="npm" src="https://img.shields.io/npm/v/verbalcoding?color=CB3837&logo=npm&logoColor=white">
   <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">
-  <img alt="Agents" src="https://img.shields.io/badge/Agents-Hermes%20%7C%20Claude%20%7C%20Codex%20%7C%20Gemini%20%7C%20OpenCode-111827">
+  <img alt="TTS" src="https://img.shields.io/badge/TTS-Edge%20%7C%20OpenVoice%20%7C%20SpeechSwift-0EA5E9">
+  <img alt="License" src="https://img.shields.io/github/license/ca1773130n/VerbalCoding">
 </p>
 
 <p align="center">
   <img src="docs/assets/figures/verbalcoding-flow.svg" alt="VerbalCoding voice-to-agent flow" width="860">
 </p>
 
-## Why
+## Why it exists
 
-VerbalCoding turns a Discord voice channel into a hands-free control surface for coding agents. Speak a request, let your CLI agent work, and hear a concise answer back — with text transcripts, progress events, and guardrails for noisy code/log output.
+VerbalCoding turns a Discord voice channel into a hands-free cockpit for **any** CLI coding agent. Hermes ships its own `/voice join` for Hermes; VerbalCoding is a thin, agent-agnostic layer that puts the same loop on top of Hermes, Claude Code, Codex, Gemini, OpenCode, OpenClaw, Aider, Cursor CLI, or any non-interactive shell command — with the rough edges other voice frontends still have on their roadmap:
 
-## Highlights
+- **True audio barge-in** — interrupt the agent mid-sentence; Hermes' built-in voice pauses its listener during TTS.
+- **Streaming pipeline** — first sentence plays while the agent is still writing (Hermes lists this as a future Phase-4 item).
+- **Smart progress narration** — describes intent ("wiring the new login route"), not file lists.
+- **Voice plan mode** — say "plan it first", edit by voice ("skip step 3"), say "approve" to execute.
+- **Cross-agent routing by voice** — "ask Codex what it thinks" for a single turn, "switch to Aider" to make it sticky, "back to default" to restore. The plan can also emit a `which_agent` slot so the agent itself picks the next backend.
+- **Phone-down mode** — push notification with a voice summary when a long task completes and the room is empty.
 
-| What you get | Why it feels good |
+## What feels different
+
+| Capability | Why it matters |
 |---|---|
-| Voice-first agent control | Talk to Hermes Agent, Claude Code, Codex, Gemini CLI, OpenCode, OpenClaw, or any custom CLI harness. |
-| On-device speech loop | Discord voice capture → local `whisper-cli` transcription → 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 environments. |
-| Multilingual voice presets | Switch STT, progress language, and TTS voice together with `vc language ko/en/auto`. |
-| Multi-room project isolation | Run one bot per project room with isolated Hermes profiles, sessions, memory, and logs. |
+| Agent choice, first-class | Hermes Agent, Claude Code, Codex, Gemini CLI, OpenCode, OpenClaw, Aider, Cursor CLI, or any custom command. `vc setup` auto-detects what's installed. |
+| Cross-agent voice routing | Say "ask Codex …" (single turn), "switch to Aider" (sticky), or "back to default". Missing binaries are detected and the bridge offers to fall back to the default agent. Handoff prompts carry recent utterances + last plan decisions to the new agent. |
+| Real barge-in | VAD thresholds tuned for indoor and noisy rooms; cut in mid-utterance and resume the conversation. |
+| Streaming end-to-end | Sentence-by-sentence playback while the agent is still writing; first audio in well under a second on a warm cache. On by default — set `STREAMING_TTS=0` to fall back to whole-reply playback. |
+| Smart progress | Optional LLM summarizer collapses raw events into one human sentence; falls back to the existing regex labels when no key is set. |
+| Plan-mode by voice | Narrated, editable, voice-driven plans without touching the keyboard. |
+| Phone-down handoff | Long task + empty VC = push notification (`ntfy`/`pushover`) with a redacted one-line summary and tap-to-rejoin link. |
+| Local speech loop | Discord audio is transcribed by local `whisper-cli`; TTS via Edge, OpenVoice, SpeechSwift/CosyVoice, or Supertonic. |
+| Real operations support | Doctor auto-fixes, Docker UDP guidance, latency metrics, multi-instance project rooms, redacted config checks. |
+
+> **Already using Hermes Agent?** Hermes itself has a working Discord voice loop via `/voice join` / `/voice channel`. Use VerbalCoding when you want it agent-agnostic, want barge-in and streaming today, or want plan-mode, push handoff, and smart narration on top of the same loop. The two coexist — VerbalCoding can drive Hermes as its backend.
 
 ## Quick Start
 
-Fastest path with npm:
-
 ```bash
-npm install -g verbalcoding
-vc setup --yes
+npm install -g verbalcoding@latest
+vc setup       # detects installed agents and lets you pick
 vc doctor
 vc start
 ```
 
-Or run directly without a permanent global install:
+`vc setup` is the normal human path. Keep Discord Developer Portal open while it asks for your bot token, application/client ID, transcript target, and voice channel names.
+
+Automation can skip prompts, then fill Discord details later:
 
 ```bash
-npx verbalcoding setup --yes
+vc setup --yes
+vc setup token <bot-token> --client-id <discord-client-id>
+vc setup channels "General,Team Voice"
 vc doctor
-vc start
 ```
 
-GitHub clone path for contributors:
+Contributor clone path:
 
 ```bash
 git clone https://github.com/ca1773130n/VerbalCoding.git
 cd VerbalCoding
-./scripts/install.sh --yes
+./scripts/install.sh
 vc doctor
 ./run.sh
 ```
 
-`vc setup --yes` bootstraps local prerequisites from the npm package. `./scripts/install.sh --yes` does the same for GitHub clone installs. Both cover Node/npm dependencies, `ffmpeg`, `whisper-cli`, the default whisper.cpp model, a local `.venv-tts` Edge TTS helper, and setup wizard configuration where possible. They support macOS/Homebrew plus common Linux package managers (`apt`, `dnf`, `pacman`); rerun with `--no-wizard` for dependency-only setup or `--skip-system` if you want to install OS packages yourself.
+## Discord setup in one minute
 
-Need a clean install walkthrough? Start with [Fresh Install](docs/FRESH_INSTALL.md).
+1. Create a Discord application and bot in <https://discord.com/developers/applications>.
+2. Enable the Message Content privileged intent.
+3. Run `vc setup` and paste the bot token plus application/client ID when prompted.
+4. Enter exact voice channel names for auto-join.
+5. Invite the bot with:
 
-## Supported Agent Backends
-
-| 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 |
+```bash
+vc bot invite <discord-client-id>
+vc bot invite <discord-client-id> --guild <guild-id>
+```
 
-## Learn More
+Secrets are stored in ignored local env files with mode `0600` and are not printed back by `vc doctor`.
 
-| Guide | What you get |
-|---|---|
-| [Fresh Install](docs/FRESH_INSTALL.md) | Clean clone setup, model download, first run |
-| [Usage Guide](docs/USAGE.md) | CLI commands, Discord commands, progress mode, latency metrics |
-| [Configuration](docs/CONFIGURATION.md) | `.env`, agent backends, MCP, TTS backends, operational notes |
-| [Multi-Instance](docs/MULTI_INSTANCE.md) | One permanent Discord voice room per project |
-| [Release Notes](docs/RELEASE.md) | Current capabilities and pre-release checklist |
-
-## Tiny Command Map
+## Tiny command map
 
 ```bash
-vc status                 # current language, TTS, and bridge settings
-vc language ko|en|auto    # switch STT/progress/TTS language preset
-vc bot invite CLIENT_ID   # generate the Discord bot invite URL
-vc instance setup NAME    # create an isolated project voice bot
-vc instance start NAME    # run that bot in the background
-vc doctor                 # redacted health check
-vc start                  # start the default bridge
+vc setup                               # guided setup with agent auto-detection
+vc setup --yes                         # non-interactive bootstrap/starter config
+vc setup token                         # rotate or add Discord bot token/client ID later
+vc setup channels "General,Team Voice" # update auto-join voice channel names
+vc bot invite CLIENT_ID                # generate a Discord bot invite URL
+vc status                              # show active language, TTS, bridge settings, and resolved backend
+vc language ko|en|auto                 # switch STT/progress/TTS language preset
+vc doctor                              # redacted health check with auto-fix suggestions
+vc start                               # start the default bridge
+vc instance setup NAME                 # create an isolated project voice bot
+vc instance start NAME                 # run that bot in the background
 ```
 
 In Discord:
 
 | Command | What it does |
 |---|---|
-| `!join` | Join your current voice channel. |
-| `!ask <prompt>` | Send text to the same agent backend. |
-| `!verbose on\|off` | Show/speak short progress updates. |
-| `!latency` | Summarize recent voice/STT/agent/TTS latency. |
-| `!sensitivity normal` | Use normal indoor barge-in sensitivity. |
-| `!sensitivity conservative` | Use stricter noisy/outdoor sensitivity. |
+| `!join` / `!leave` | Join or leave your current voice channel. |
+| `!ask <prompt>` | Send text to the same selected agent backend. |
+| `!verbose on\|off` | Toggle short progress updates. |
+| `!latency` / `!metrics` | Summarize recent STT/agent/TTS latency. |
+| `!sensitivity normal\|conservative` | Tune barge-in for indoor or noisy environments. |
 | `!session new <name> <workdir> [context] --voice <voice-channel>` | Bind a project session to a voice room. |
 
+## Roadmap
+
+The differentiation push is tracked in [docs/ROADMAP.md](./docs/ROADMAP.md). Five phases land the claims above:
+
+| # | Phase | What it adds |
+|---|---|---|
+| 1 | Streaming pipeline | Sentence-by-sentence TTS while the agent is still writing. |
+| 2 | Agent-agnostic adapters | First-class Aider + Cursor CLI; `vc setup` auto-detects. |
+| 6 | Smart progress | LLM-summarized narration. Falls back to today's regex labels. |
+| 7 | Voice plan mode | Narrate plan, voice-edit, approve to execute. |
+| 10 | Push notification handoff | ntfy/Pushover when a long task ends and the room is empty. |
+
+## Learn more
+
+| Guide | What you get |
+|---|---|
+| [Docs hub](docs/README.md) | One page linking every guide and localized doc set. |
+| [Roadmap](docs/ROADMAP.md) | Differentiation plan and per-phase implementation plans. |
+| [Fresh Install](docs/FRESH_INSTALL.md) | npm/global setup, Discord app setup, token/channel commands, first run. |
+| [Usage Guide](docs/USAGE.md) | CLI commands, Discord commands, run modes, voice changes, latency metrics. |
+| [Hermes Built-in Voice vs VerbalCoding](docs/HERMES_VOICE.md) | What Hermes already supports and when VerbalCoding is worth adding. |
+| [Configuration](docs/CONFIGURATION.md) | `.env`, agent backends, MCP server, TTS backends, operational notes. |
+| [Troubleshooting](docs/TROUBLESHOOTING.md) | Docker host networking, UDP voice failures, missing token/channel diagnostics. |
+| [Multi-Instance](docs/MULTI_INSTANCE.md) | One permanent Discord voice room per project. |
+| [Release Notes](docs/RELEASE.md) | Current capabilities, checks, and public-release gaps. |
+
 ## Requirements
 
 | Layer | Default |
 |---|---|
-| Runtime | Node.js 20+, npm; install script can install via Homebrew/apt/dnf/pacman |
-| Audio | `ffmpeg`; install script can install it |
-| Speech recognition | Local `whisper-cli` from whisper.cpp; install script uses Homebrew on macOS or local Linux build fallback |
-| TTS | Edge TTS CLI; install script creates `.venv-tts` if needed |
-| Discord | Bot token, Message Content intent, voice permissions |
-| Agent | At least one authenticated CLI harness, Hermes Agent by default |
-| Platform focus | macOS / Apple Silicon most tested; Linux bootstrap is best-effort and documented |
+| Runtime | Node.js 20+ and npm; setup can install via Homebrew/apt/dnf/pacman where supported. |
+| Audio | `ffmpeg`; setup/doctor can install it on supported OSes. |
+| Speech recognition | Local `whisper-cli` from whisper.cpp plus `models/ggml-small-q5_1.bin`. |
+| TTS | Edge TTS by default; optional OpenVoice, SpeechSwift/CosyVoice, Supertonic, OmniVoice, and Qwen3 TTS CLI paths. |
+| Discord | Bot token, Message Content intent, voice permissions, matching auto-join channel names. |
+| Agent | At least one CLI harness installed; `vc setup` auto-detects Hermes, Claude Code, Codex, Gemini, OpenCode, OpenClaw, Aider, Cursor CLI. |
+| Platform focus | macOS / Apple Silicon most tested; Linux bootstrap is best-effort; Windows unsupported for now. |
+
+## Docker / container note
+
+Discord text login can work while voice join fails if outbound UDP is blocked. If logs show `Cannot perform IP discovery - socket closed`, use Linux host networking for the service that runs `vc start`:
+
+```yaml
+services:
+  verbalcoding:
+    network_mode: "host"
+```
+
+Do not combine `network_mode: "host"` with `ports:`. Docker Desktop for macOS/Windows behaves differently; if UDP still fails there, run VerbalCoding directly on the host or a Linux VM.
 
 ## Contributing
 
-Run the lightweight checks before sending changes:
+Run lightweight checks before sending changes:
 
 ```bash
 node --check app-node/main.mjs
 npm test
-bash -n run.sh scripts/install.sh
+bash -n run.sh scripts/install.sh scripts/bootstrap_prereqs.sh
 npm pack --dry-run
 vc doctor
 ```
 
 ## Status
 
-VerbalCoding is public-release oriented but still early. Demo video/GIF, broader Linux validation, CI, and deeper security review are still TODOs.
+Public-release oriented but still early. The roadmap above tracks live differentiation work. Demo video/GIF, broader Linux validation, CI, and deeper security review are still TODOs.

package/README.ru.md

@@ -0,0 +1,134 @@
+# 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></p>
+
+<p align="center">
+  <img alt="npm" src="https://img.shields.io/npm/v/verbalcoding?color=CB3837&logo=npm&logoColor=white">
+  <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%20SpeechSwift-0EA5E9">
+  <img alt="License" src="https://img.shields.io/github/license/ca1773130n/VerbalCoding">
+</p>
+
+<p align="center">
+  <img src="docs/assets/figures/verbalcoding-flow.svg" alt="VerbalCoding voice-to-agent flow" width="860">
+</p>
+
+## Зачем это нужно
+
+VerbalCoding превращает голосовую комнату Discord в hands-free кабину для coding agents. Вы произносите задачу, CLI-агент работает, а в ответ получаете короткую озвучку, текстовую расшифровку и события прогресса. Diffs и logs не зачитываются длинным TTS.
+
+> **Уже используете Hermes Agent?** В Hermes уже есть встроенная поддержка голосовых каналов Discord через `/voice join` / `/voice channel`: бот может зайти в текущий VC, распознать речь через Whisper и ответить TTS. Для этого базового цикла VerbalCoding не обязателен. VerbalCoding добавляет workflow-слой: маршрутизацию проектов/сессий, общий контекст голоса+текста, правила прерывания, голосовой прогресс, языковые пресеты, метрики задержки и переключение CLI-бэкендов помимо Hermes.
+
+## Что ощущается иначе
+
+| Возможность | Зачем это важно |
+|---|---|
+| Работа как звонок | Говорите, слушайте, перебивайте и продолжайте в одном голосовом канале Discord. |
+| Пошаговая настройка | `vc setup` проводит через prerequisites, Discord token/client ID, voice channel, transcript target, backend и TTS settings за один проход. |
+| Локальный голосовой цикл | Discord audio → local `whisper-cli` → selected CLI agent → TTS reply. |
+| Выбор агента | Hermes Agent, Claude Code, Codex, Gemini CLI, OpenCode, OpenClaw, Aider, Cursor CLI или custom command. `vc setup` автоматически находит установленные. |
+| Голосовая маршрутизация агента | `"ask Codex what it thinks"` — на один turn, `"switch to Aider"` — sticky, `"back to default"` — возврат. Отсутствующие бинарники определяются и мост предлагает fallback к агенту по умолчанию. |
+| Больше, чем встроенный голос Hermes | Сохраняет тот же VC-голосовой цикл и добавляет проектные комнаты, общий контекст `!ask`, тонкую обработку прерываний, голос прогресса/статуса и управление multi-agent бэкендами. |
+| Готовность к эксплуатации | doctor auto-fix, Docker UDP guide, latency metrics, multi-instance rooms и redacted config checks встроены. |
+
+## Быстрый старт
+
+```bash
+npm install -g verbalcoding@latest
+vc setup
+vc doctor
+vc start
+```
+
+`vc setup` — обычный путь для человека. Держите Discord Developer Portal открытым и введите bot token, application/client ID, transcript target и voice channel names.
+
+Для автоматизации можно пропустить prompts и добавить Discord-данные позже.
+
+```bash
+vc setup --yes
+vc setup token <bot-token> --client-id <discord-client-id>
+vc setup channels "General,Team Voice"
+vc doctor
+```
+
+## Discord за одну минуту
+
+1. Создайте application и bot в Discord Developer Portal.
+2. Включите Message Content privileged intent.
+3. Запустите `vc setup` и вставьте bot token и application/client ID.
+4. Введите точные имена voice channels для auto-join.
+5. Пригласите bot этими командами.
+
+```bash
+vc bot invite <discord-client-id>
+vc bot invite <discord-client-id> --guild <guild-id>
+```
+
+## Краткая карта команд
+
+```bash
+vc setup                                 # пошаговая настройка: prerequisites, Discord, backend, voice
+vc setup --yes                           # неинтерактивный bootstrap/starter config
+vc setup token                           # позже обновить или добавить Discord bot token/client ID
+vc setup channels "General,Team Voice"   # обновить auto-join voice channel names
+vc bot invite CLIENT_ID                  # сгенерировать Discord bot invite URL
+vc status                                # показать текущие настройки
+vc language ko|en|auto                   # переключить language preset
+vc doctor                                # redacted health check и auto-fixes
+vc start                                 # запустить bridge по умолчанию
+vc instance setup NAME                   # создать изолированный project voice bot
+vc instance start NAME                   # запустить этот bot в background
+```
+
+## Подробнее
+
+| Гайд | Что внутри |
+|---|---|
+| [Центр документации](docs/i18n/README.ru.md) | Индекс локализованных гайдов. |
+| [Fresh Install](docs/i18n/FRESH_INSTALL.ru.md) | npm/global setup, настройка Discord и первый запуск. |
+| [Usage](docs/i18n/USAGE.ru.md) | CLI-команды, Discord-команды, режимы запуска и latency. |
+| [Использование по harness](docs/i18n/HARNESSES.ru.md) | Установка, настройка и голосовая маршрутизация для Claude Code, Codex, Aider и других. |
+| [Встроенный голос Hermes vs VerbalCoding](docs/i18n/HERMES_VOICE.ru.md) | Что Hermes уже умеет в Discord voice и чем отличается VerbalCoding. |
+| [Configuration](docs/i18n/CONFIGURATION.ru.md) | .env, agent backends, MCP, TTS и эксплуатация. |
+| [Troubleshooting](docs/i18n/TROUBLESHOOTING.ru.md) | Docker UDP и проверки token/channel. |
+| [Multi-Instance](docs/i18n/MULTI_INSTANCE.ru.md) | Одна постоянная voice room на проект. |
+
+## Требования
+
+| Слой | По умолчанию |
+|---|---|
+| Runtime | Node.js 20+ и npm. |
+| Audio | `ffmpeg` и local `whisper-cli`. |
+| TTS | По умолчанию Edge TTS; опционально OpenVoice, SpeechSwift/CosyVoice, Supertonic. |
+| Discord | Bot token, Message Content intent, voice permissions и совпадающие channel names. |
+| Agent | Минимум один аутентифицированный CLI harness; по умолчанию Hermes Agent. |
+
+## Docker / контейнеры
+
+Если в logs видно `Cannot perform IP discovery - socket closed`, Discord voice UDP заблокирован. В Linux Docker Compose используйте:
+
+```yaml
+services:
+  verbalcoding:
+    network_mode: "host"
+```
+
+Не совмещайте `network_mode: "host"` с `ports:`.
+
+## Участие
+
+```bash
+node --check app-node/main.mjs
+npm test
+bash -n run.sh scripts/install.sh scripts/bootstrap_prereqs.sh
+npm pack --dry-run
+vc doctor
+```
+
+## Статус
+
+VerbalCoding ориентирован на публичный релиз, но проект ещё ранний. Demo video/GIF, более широкая Linux validation, CI и security review остаются TODO.