verbalcoding 0.2.7 → 0.2.8

package/docs/i18n/README.ja.md

@@ -1,27 +1,49 @@
 # VerbalCoding
 
-**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 の音声チャンネルを、コーディングエージェント向けのハンズフリー操作面に変えます。声で依頼し、CLI エージェントに作業させ、短い音声回答・文字起こし・進捗イベントを受け取れます。
-
-## Highlights
-
-| Feature | What it means |
+<p align="center">
+  <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> ·
+  <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">
+  <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 の音声からエージェントへのフロー" width="860">
+</p>
+
+## なぜ使うのか
+
+VerbalCoding は、Discord の音声チャンネルをコーディングエージェント向けのハンズフリー操作面に変えます。リクエストを話し、CLI エージェントに作業を任せ、簡潔な回答を音声で受け取れます。テキスト文字起こし、進捗イベント、ノイズの多いコード/ログ出力に対するガードレールも備えています。
+
+## ハイライト
+
+| 得られるもの | 何がうれしいか |
 |---|---|
-| 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. |
+| 音声ファーストのエージェント操作 | Hermes Agent、Claude Code、Codex、Gemini CLI、OpenCode、OpenClaw、または任意のカスタム CLI ハーネスに話しかけられます。 |
+| オンデバイスの音声ループ | Discord 音声キャプチャ → ローカル `whisper-cli` 文字起こし → エージェント → 分割 TTS 再生。 |
+| 音声 + テキストの共有コンテキスト | 音声ターンと `!ask` テキストコマンドで、対応する同じエージェントセッションを再利用できます。 |
+| 割り込み発話と感度モード | 再生を自然に中断し、通常環境と保守的/騒音環境向けのモードを切り替えられます。 |
+| 多言語音声プリセット | `vc language ko/en/auto` で STT、進捗言語、TTS 音声をまとめて切り替えます。 |
+| 複数ルームのプロジェクト分離 | プロジェクトルームごとに 1 つのボットを実行し、Hermes プロファイル、セッション、メモリ、ログを分離します。 |
 
-## Quick Start
+## クイックスタート
+
+npm を使う最短手順:
 
 ```bash
 npm install -g verbalcoding
@@ -30,7 +52,7 @@ vc doctor
 vc start
 ```
 
-Run without a permanent global install:
+永続的なグローバルインストールなしで直接実行する場合:
 
 ```bash
 npx verbalcoding setup --yes
@@ -38,7 +60,7 @@ vc doctor
 vc start
 ```
 
-Contributor clone path:
+コントリビューター向けの GitHub クローン手順:
 
 ```bash
 git clone https://github.com/ca1773130n/VerbalCoding.git
@@ -48,38 +70,80 @@ vc doctor
 ./run.sh
 ```
 
-`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.
+`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` を使います。
+
+クリーンインストールの手順が必要ですか？ [新規インストール](FRESH_INSTALL.ja.md) から始めてください。
+
+## 対応エージェントバックエンド
 
-## Guides
+| バックエンド | デフォルトコマンド | セッション対応 |
+|---|---:|---|
+| 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 | Link |
+## さらに詳しく
+
+| ガイド | 内容 |
 |---|---|
-| 新規インストール | [FRESH_INSTALL.ja.md](FRESH_INSTALL.ja.md) |
-| 使い方ガイド | [USAGE.ja.md](USAGE.ja.md) |
-| 設定 | [CONFIGURATION.ja.md](CONFIGURATION.ja.md) |
-| マルチインスタンス | [MULTI_INSTANCE.ja.md](MULTI_INSTANCE.ja.md) |
-| リリースノート | [RELEASE.ja.md](RELEASE.ja.md) |
+| [新規インストール](FRESH_INSTALL.ja.md) | クリーンなクローンセットアップ、モデルのダウンロード、初回実行 |
+| [使い方ガイド](USAGE.ja.md) | CLI コマンド、Discord コマンド、進捗モード、レイテンシ指標 |
+| [設定](CONFIGURATION.ja.md) | `.env`、エージェントバックエンド、MCP、TTS バックエンド、運用メモ |
+| [マルチインスタンス](MULTI_INSTANCE.ja.md) | プロジェクトごとに 1 つの永続 Discord 音声ルーム |
+| [リリースノート](RELEASE.ja.md) | 現在の機能とプレリリースチェックリスト |
 
-## Command map
+## 小さなコマンドマップ
 
 ```bash
-vc status
-vc language ko|en|auto
-vc bot invite CLIENT_ID
-vc instance setup NAME
-vc instance start NAME
-vc doctor
-vc start
+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 commands:
+Discord 内:
+
+| コマンド | 動作 |
+|---|---|
+| `!join` | 現在の音声チャンネルに参加します。 |
+| `!ask <prompt>` | 同じエージェントバックエンドにテキストを送信します。 |
+| `!verbose on\|off` | 短い進捗更新を表示/読み上げします。 |
+| `!latency` | 直近の音声/STT/エージェント/TTS レイテンシを要約します。 |
+| `!sensitivity normal` | 通常の屋内向け割り込み感度を使います。 |
+| `!sensitivity conservative` | 騒音/屋外向けのより厳しい感度を使います。 |
+| `!session new <name> <workdir> [context] --voice <voice-channel>` | プロジェクトセッションを音声ルームに紐付けます。 |
+
+## 要件
+
+| レイヤー | デフォルト |
+|---|---|
+| ランタイム | 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 ハーネスが少なくとも 1 つ。デフォルトは Hermes Agent |
+| 主な対象プラットフォーム | macOS / Apple Silicon で最も検証済み。Linux ブートストラップはベストエフォートで文書化されています |
+
+## コントリビュート
+
+変更を送る前に軽量チェックを実行してください:
 
-```text
-!join        !ask <prompt>       !verbose on/off
-!latency     !sensitivity normal !sensitivity conservative
-!session new <name> <workdir> [context] --voice <voice-channel>
+```bash
+node --check app-node/main.mjs
+npm test
+bash -n run.sh scripts/install.sh
+npm pack --dry-run
+vc doctor
 ```
 
-## Requirements
+## ステータス
 
-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.
+VerbalCoding は公開リリースを目指していますが、まだ初期段階です。デモ動画/GIF、より広範な Linux 検証、CI、より深いセキュリティレビューはまだ TODO です。

package/docs/i18n/README.ko.md

@@ -1,27 +1,48 @@
 # VerbalCoding
 
-**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 음성 채널을 코딩 에이전트용 핸즈프리 제어면으로 바꿉니다. 말로 요청하고, CLI 에이전트가 작업하게 두고, 간결한 음성 답변과 텍스트 기록을 함께 받습니다.
-
-## Highlights
-
-| Feature | What it means |
+<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="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">
+</p>
+
+<p align="center">
+  <img src="../assets/figures/verbalcoding-flow.svg" alt="VerbalCoding 음성-에이전트 흐름" width="860">
+</p>
+
+## 왜 필요한가
+
+VerbalCoding은 Discord 음성 채널을 코딩 에이전트를 위한 핸즈프리 제어면으로 바꿉니다. 요청을 말하고, CLI 에이전트가 작업하게 둔 뒤, 간결한 답변을 음성으로 들을 수 있습니다 — 텍스트 기록, 진행 이벤트, 시끄러운 코드/로그 출력에 대한 안전장치도 함께 제공합니다.
+
+## 주요 기능
+
+| 제공되는 것 | 좋은 이유 |
 |---|---|
-| 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. |
+| 음성 우선 에이전트 제어 | Hermes Agent, Claude Code, Codex, Gemini CLI, OpenCode, OpenClaw 또는 임의의 커스텀 CLI 하네스와 말로 대화합니다. |
+| 온디바이스 음성 루프 | Discord 음성 캡처 → 로컬 `whisper-cli` 전사 → 에이전트 → 분할 TTS 재생. |
+| 공유 음성 + 텍스트 컨텍스트 | 음성 턴과 `!ask` 텍스트 명령이 지원되는 동일 에이전트 세션을 재사용할 수 있습니다. |
+| 끼어들기 및 감도 모드 | 재생 중 자연스럽게 끼어들고 일반/보수적(시끄러운 환경) 모드를 전환합니다. |
+| 다국어 음성 프리셋 | `vc language ko/en/auto`로 STT, 진행 언어, TTS 음성을 함께 전환합니다. |
+| 여러 방의 프로젝트 격리 | 프로젝트 방마다 하나의 봇을 실행하고 Hermes 프로필, 세션, 메모리, 로그를 분리합니다. |
 
-## Quick Start
+## 빠른 시작
+
+npm으로 가장 빠르게 시작하는 방법:
 
 ```bash
 npm install -g verbalcoding
@@ -30,7 +51,7 @@ vc doctor
 vc start
 ```
 
-Run without a permanent global install:
+영구 전역 설치 없이 바로 실행하려면:
 
 ```bash
 npx verbalcoding setup --yes
@@ -38,7 +59,7 @@ vc doctor
 vc start
 ```
 
-Contributor clone path:
+기여자를 위한 GitHub 클론 경로:
 
 ```bash
 git clone https://github.com/ca1773130n/VerbalCoding.git
@@ -48,38 +69,80 @@ vc doctor
 ./run.sh
 ```
 
-`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.
+`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`을 사용하세요.
+
+깨끗한 설치 안내가 필요하다면 [Fresh Install](FRESH_INSTALL.ko.md)부터 시작하세요.
+
+## 지원되는 에이전트 백엔드
 
-## Guides
+| 백엔드 | 기본 명령 | 세션 지원 |
+|---|---:|---|
+| 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 | Link |
+## 더 알아보기
+
+| 가이드 | 제공 내용 |
 |---|---|
-| 새 설치 | [FRESH_INSTALL.ko.md](FRESH_INSTALL.ko.md) |
-| 사용 가이드 | [USAGE.ko.md](USAGE.ko.md) |
-| 설정 | [CONFIGURATION.ko.md](CONFIGURATION.ko.md) |
-| 멀티 인스턴스 | [MULTI_INSTANCE.ko.md](MULTI_INSTANCE.ko.md) |
-| 릴리스 노트 | [RELEASE.ko.md](RELEASE.ko.md) |
+| [Fresh Install](FRESH_INSTALL.ko.md) | 깨끗한 클론 설정, 모델 다운로드, 첫 실행 |
+| [Usage Guide](USAGE.ko.md) | CLI 명령, Discord 명령, 진행 모드, 지연 시간 지표 |
+| [Configuration](CONFIGURATION.ko.md) | `.env`, 에이전트 백엔드, MCP, TTS 백엔드, 운영 참고 사항 |
+| [Multi-Instance](MULTI_INSTANCE.ko.md) | 프로젝트마다 하나의 영구 Discord 음성 방 |
+| [Release Notes](RELEASE.ko.md) | 현재 기능과 사전 릴리스 체크리스트 |
 
-## Command map
+## 작은 명령 지도
 
 ```bash
-vc status
-vc language ko|en|auto
-vc bot invite CLIENT_ID
-vc instance setup NAME
-vc instance start NAME
-vc doctor
-vc start
+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 commands:
+Discord에서:
+
+| 명령 | 하는 일 |
+|---|---|
+| `!join` | 현재 음성 채널에 참가합니다. |
+| `!ask <prompt>` | 동일 에이전트 백엔드로 텍스트를 보냅니다. |
+| `!verbose on\|off` | 짧은 진행 업데이트를 표시/낭독합니다. |
+| `!latency` | 최근 음성/STT/에이전트/TTS 지연 시간을 요약합니다. |
+| `!sensitivity normal` | 일반 실내 끼어들기 감도를 사용합니다. |
+| `!sensitivity conservative` | 더 엄격한 시끄러운/실외 감도를 사용합니다. |
+| `!session new <name> <workdir> [context] --voice <voice-channel>` | 프로젝트 세션을 음성 방에 연결합니다. |
+
+## 요구 사항
+
+| 계층 | 기본값 |
+|---|---|
+| 런타임 | 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 부트스트랩은 최선 노력으로 문서화됨 |
+
+## 기여
+
+변경 사항을 보내기 전에 가벼운 점검을 실행하세요:
 
-```text
-!join        !ask <prompt>       !verbose on/off
-!latency     !sensitivity normal !sensitivity conservative
-!session new <name> <workdir> [context] --voice <voice-channel>
+```bash
+node --check app-node/main.mjs
+npm test
+bash -n run.sh scripts/install.sh
+npm pack --dry-run
+vc doctor
 ```
 
-## Requirements
+## 상태
 
-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.
+VerbalCoding은 공개 릴리스를 지향하지만 아직 초기 단계입니다. 데모 비디오/GIF, 더 넓은 Linux 검증, CI, 더 깊은 보안 검토는 아직 TODO입니다.

package/docs/i18n/README.ru.md

@@ -1,27 +1,49 @@
 # VerbalCoding
 
-**Управляйте 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 интерфейс для coding agents. Вы произносите задачу, CLI-агент работает, а вы получаете краткий голосовой ответ, текстовую расшифровку и события прогресса.
-
-## Highlights
-
-| Feature | What it means |
+<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">
+  <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 к агенту" width="860">
+</p>
+
+## Зачем
+
+VerbalCoding превращает голосовой канал Discord в панель управления кодинг-агентами без рук. Произнесите запрос, позвольте CLI-агенту выполнить работу и услышите краткий ответ — с текстовыми расшифровками, событиями прогресса и защитными ограничениями для шумного вывода кода/логов.
+
+## Главное
+
+| Что вы получаете | Почему это удобно |
 |---|---|
-| 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. |
+| Управление агентами голосом в первую очередь | Разговаривайте с Hermes Agent, Claude Code, Codex, Gemini CLI, OpenCode, OpenClaw или любым пользовательским CLI-харнесом. |
+| Речевой цикл на устройстве | Захват голоса Discord → локальная расшифровка `whisper-cli` → агент → фрагментированное воспроизведение TTS. |
+| Общий голосовой и текстовый контекст | Голосовые реплики и текстовые команды `!ask` могут повторно использовать одну и ту же поддерживаемую сессию агента. |
+| Перебивание и режимы чувствительности | Естественно прерывайте воспроизведение и переключайтесь между обычной и консервативной/шумной средой. |
+| Многоязычные голосовые пресеты | Переключайте STT, язык прогресса и голос TTS вместе через `vc language ko/en/auto`. |
+| Изоляция проектов по комнатам | Запускайте по одному боту на проектную комнату с отдельными профилями Hermes, сессиями, памятью и логами. |
 
-## Quick Start
+## Быстрый старт
+
+Самый быстрый путь через npm:
 
 ```bash
 npm install -g verbalcoding
@@ -30,7 +52,7 @@ vc doctor
 vc start
 ```
 
-Run without a permanent global install:
+Или запуск напрямую без постоянной глобальной установки:
 
 ```bash
 npx verbalcoding setup --yes
@@ -38,7 +60,7 @@ vc doctor
 vc start
 ```
 
-Contributor clone path:
+Путь через клон GitHub для контрибьюторов:
 
 ```bash
 git clone https://github.com/ca1773130n/VerbalCoding.git
@@ -48,38 +70,80 @@ vc doctor
 ./run.sh
 ```
 
-`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.
+`vc setup --yes` подготавливает локальные зависимости из установленного npm-пакета. `./scripts/install.sh --yes` делает то же самое только внутри GitHub-клона. Оба пути по возможности настраивают зависимости Node/npm, `ffmpeg`, `whisper-cli`, стандартную модель whisper.cpp, локальный помощник Edge TTS в `.venv-tts` и мастер настройки. Они поддерживают macOS/Homebrew и распространённые менеджеры пакетов Linux (`apt`, `dnf`, `pacman`); повторно запустите с `--no-wizard` для установки только зависимостей или с `--skip-system`, если хотите устанавливать пакеты ОС самостоятельно.
+
+Нужно пошаговое руководство по чистой установке? Начните с [Fresh Install](FRESH_INSTALL.ru.md).
+
+## Поддерживаемые бэкенды агентов
 
-## Guides
+| Бэкенд | Команда по умолчанию | Поддержка сессий |
+|---|---:|---|
+| 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 через настройки адаптера по умолчанию |
+| Пользовательский | `AGENT_COMMAND` | Подключите собственную неинтерактивную команду |
 
-| Guide | Link |
+## Узнать больше
+
+| Руководство | Что вы получите |
 |---|---|
-| Чистая установка | [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) |
+| [Чистая установка](FRESH_INSTALL.ru.md) | Настройка чистого клона, загрузка модели, первый запуск |
+| [Руководство по использованию](USAGE.ru.md) | CLI-команды, команды Discord, режим прогресса, метрики задержки |
+| [Конфигурация](CONFIGURATION.ru.md) | `.env`, бэкенды агентов, MCP, бэкенды TTS, эксплуатационные заметки |
+| [Многоэкземплярный режим](MULTI_INSTANCE.ru.md) | Одна постоянная голосовая комната Discord на проект |
+| [Заметки о релизе](RELEASE.ru.md) | Текущие возможности и чеклист перед релизом |
 
-## Command map
+## Краткая карта команд
 
 ```bash
-vc status
-vc language ko|en|auto
-vc bot invite CLIENT_ID
-vc instance setup NAME
-vc instance start NAME
-vc doctor
-vc start
+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
 ```
 
-Discord commands:
+В Discord:
+
+| Команда | Что делает |
+|---|---|
+| `!join` | Подключает бота к вашему текущему голосовому каналу. |
+| `!ask <prompt>` | Отправляет текст в тот же бэкенд агента. |
+| `!verbose on\|off` | Показывает/озвучивает короткие обновления прогресса. |
+| `!latency` | Сводка недавней задержки голоса/STT/агента/TTS. |
+| `!sensitivity normal` | Использует обычную чувствительность перебивания для помещений. |
+| `!sensitivity conservative` | Использует более строгую чувствительность для шумной/уличной среды. |
+| `!session new <name> <workdir> [context] --voice <voice-channel>` | Привязывает проектную сессию к голосовой комнате. |
+
+## Требования
+
+| Уровень | По умолчанию |
+|---|---|
+| Среда выполнения | Node.js 20+, npm; установочный скрипт может установить через Homebrew/apt/dnf/pacman |
+| Аудио | `ffmpeg`; установочный скрипт может установить его |
+| Распознавание речи | Локальный `whisper-cli` из whisper.cpp; установочный скрипт использует Homebrew на macOS или локальную резервную сборку Linux |
+| TTS | Edge TTS CLI; установочный скрипт создаёт `.venv-tts` при необходимости |
+| Discord | Токен бота, intent Message Content, голосовые разрешения |
+| Агент | Как минимум один аутентифицированный CLI-харнес, по умолчанию Hermes Agent |
+| Основная платформа | macOS / Apple Silicon протестированы лучше всего; bootstrap для Linux предоставляется по мере возможностей и документирован |
+
+## Участие в разработке
+
+Перед отправкой изменений выполните лёгкие проверки:
 
-```text
-!join        !ask <prompt>       !verbose on/off
-!latency     !sensitivity normal !sensitivity conservative
-!session new <name> <workdir> [context] --voice <voice-channel>
+```bash
+node --check app-node/main.mjs
+npm test
+bash -n run.sh scripts/install.sh
+npm pack --dry-run
+vc doctor
 ```
 
-## Requirements
+## Статус
 
-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.
+VerbalCoding ориентирован на публичный релиз, но всё ещё находится на ранней стадии. Демо-видео/GIF, более широкая проверка Linux, CI и более глубокий аудит безопасности пока остаются TODO.