verbalcoding 0.2.6 → 0.2.8

package/docs/i18n/README.ja.md

@@ -1,7 +1,7 @@
 # VerbalCoding
 
 <p align="center">
-  <strong>Discord音声でCLIコーディングエージェントと通話するように作業できます。</strong>
+  <strong>Discord 音声で CLI コーディングエージェントに話しかける — ソフトウェア作業のための電話のように。</strong>
 </p>
 
 <p align="center">
@@ -19,103 +19,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の音声チャンネルを、コーディングエージェントのハンズフリー操作面に変えます。声で依頼し、CLIエージェントに作業させ、要点だけを音声で受け取れます。テキスト記録、進捗イベント、コードやログを読み上げすぎないガードも備えています。
+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プロファイル、セッション、メモリ、ログを分離します。 |
+| 音声ファーストのエージェント操作 | Hermes Agent、Claude Code、Codex、Gemini CLI、OpenCode、OpenClaw、または任意のカスタム CLI ハーネスに話しかけられます。 |
+| オンデバイスの音声ループ | Discord 音声キャプチャ → ローカル `whisper-cli` 文字起こし → エージェント → 分割 TTS 再生。 |
+| 音声 + テキストの共有コンテキスト | 音声ターンと `!ask` テキストコマンドで、対応する同じエージェントセッションを再利用できます。 |
+| 割り込み発話と感度モード | 再生を自然に中断し、通常環境と保守的/騒音環境向けのモードを切り替えられます。 |
+| 多言語音声プリセット | `vc language ko/en/auto` で STT、進捗言語、TTS 音声をまとめて切り替えます。 |
+| 複数ルームのプロジェクト分離 | プロジェクトルームごとに 1 つのボットを実行し、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` を使います。
+
+クリーンインストールの手順が必要ですか？ [新規インストール](FRESH_INSTALL.ja.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、エージェントバックエンド、MCP、TTSバックエンド、運用メモ |
-| [Multi-Instance](../MULTI_INSTANCE.md) | プロジェクトごとに常駐Discord音声ルームを用意 |
-| [Release Notes](../RELEASE.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) | 現在の機能とプレリリースチェックリスト |
 
-## 小さなコマンド表
+## 小さなコマンドマップ
 
 ```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 ハーネスが少なくとも 1 つ。デフォルトは 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/README.ko.md

@@ -1,12 +1,11 @@
 # VerbalCoding
 
 <p align="center">
-  <strong>Discord 음성으로 CLI 코딩 에이전트와 통화하듯 작업하세요.</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> ·
   <a href="README.es.md">Español</a> ·
@@ -23,27 +22,27 @@
 </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>
 
 ## 왜 필요한가
 
-VerbalCoding은 Discord 음성 채널을 코딩 에이전트용 핸즈프리 조작면으로 바꿉니다. 말로 요청하고, CLI 에이전트가 작업하게 두고, 핵심 답변을 음성으로 다시 들을 수 있습니다. 텍스트 기록, 진행 이벤트, 코드/로그 낭독 방지 장치도 함께 제공합니다.
+VerbalCoding은 Discord 음성 채널을 코딩 에이전트를 위한 핸즈프리 제어면으로 바꿉니다. 요청을 말하고, CLI 에이전트가 작업하게 둔 뒤, 간결한 답변을 음성으로 들을 수 있습니다 — 텍스트 기록, 진행 이벤트, 시끄러운 코드/로그 출력에 대한 안전장치도 함께 제공합니다.
 
-## 핵심 기능
+## 주요 기능
 
-| 제공 기능 | 좋은 이유 |
+| 제공되는 것 | 좋은 이유 |
 |---|---|
-| 음성 우선 에이전트 제어 | Hermes Agent, Claude Code, Codex, Gemini CLI, OpenCode, OpenClaw 또는 커스텀 CLI를 말로 제어합니다. |
-| 로컬 우선 음성 루프 | Discord 음성 캡처 → `whisper.cpp` STT → 에이전트 → 분할 TTS 재생. |
-| 음성 + 텍스트 컨텍스트 공유 | 지원되는 에이전트에서는 음성 턴과 `!ask` 텍스트 명령이 같은 세션을 재사용합니다. |
-| 끼어들기와 감도 모드 | 재생 중 자연스럽게 끼어들고, 일반/보수 감도 모드를 전환합니다. |
-| 다국어 음성 프리셋 | `vc language ko/en/auto`로 STT, 진행 언어, TTS 음성을 함께 바꿉니다. |
-| 프로젝트별 멀티룸 격리 | 프로젝트 방마다 별도 봇과 Hermes 프로필, 세션, 메모리, 로그를 둡니다. |
+| 음성 우선 에이전트 제어 | Hermes Agent, Claude Code, Codex, Gemini CLI, OpenCode, OpenClaw 또는 임의의 커스텀 CLI 하네스와 말로 대화합니다. |
+| 온디바이스 음성 루프 | Discord 음성 캡처 → 로컬 `whisper-cli` 전사 → 에이전트 → 분할 TTS 재생. |
+| 공유 음성 + 텍스트 컨텍스트 | 음성 턴과 `!ask` 텍스트 명령이 지원되는 동일 에이전트 세션을 재사용할 수 있습니다. |
+| 끼어들기 및 감도 모드 | 재생 중 자연스럽게 끼어들고 일반/보수적(시끄러운 환경) 모드를 전환합니다. |
+| 다국어 음성 프리셋 | `vc language ko/en/auto`로 STT, 진행 언어, TTS 음성을 함께 전환합니다. |
+| 여러 방의 프로젝트 격리 | 프로젝트 방마다 하나의 봇을 실행하고 Hermes 프로필, 세션, 메모리, 로그를 분리합니다. |
 
 ## 빠른 시작
 
-가장 쉬운 npm 설치:
+npm으로 가장 빠르게 시작하는 방법:
 
 ```bash
 npm install -g verbalcoding
@@ -52,7 +51,7 @@ vc doctor
 vc start
 ```
 
-전역 설치 없이 바로 실행:
+영구 전역 설치 없이 바로 실행하려면:
 
 ```bash
 npx verbalcoding setup --yes
@@ -60,7 +59,7 @@ vc doctor
 vc start
 ```
 
-기여자용 GitHub 클론:
+기여자를 위한 GitHub 클론 경로:
 
 ```bash
 git clone https://github.com/ca1773130n/VerbalCoding.git
@@ -70,79 +69,71 @@ vc doctor
 ./run.sh
 ```
 
-`vc setup --yes`와 `./scripts/install.sh --yes`는 가능한 경우 Node/npm 의존성, `ffmpeg`, `whisper-cli`, 기본 whisper.cpp 모델, 로컬 `.venv-tts` Edge TTS helper를 준비합니다. macOS/Homebrew와 일반적인 Linux 패키지 매니저(`apt`, `dnf`, `pacman`)를 지원합니다.
+`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)부터 시작하세요.
 
-```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"]
-```
-
-## 지원 에이전트 백엔드
+## 지원되는 에이전트 백엔드
 
 | 백엔드 | 기본 명령 | 세션 지원 |
 |---|---:|---|
-| Hermes Agent | `hermes chat -Q -q` | resume, 자세한 진행, cancellation, 최종 답변 복구 |
+| 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` | 비대화형 명령을 직접 연결 |
+| Custom | `AGENT_COMMAND` | 직접 만든 비대화형 명령 사용 |
 
 ## 더 알아보기
 
-| 문서 | 내용 |
+| 가이드 | 제공 내용 |
 |---|---|
-| [새 설치](FRESH_INSTALL.ko.md) | npm 설치, 클린 클론, 모델 다운로드, 첫 실행 |
-| [사용 가이드](USAGE.ko.md) | CLI 명령, Discord 명령, 진행 모드, 지연 시간 지표 |
-| [설정](CONFIGURATION.ko.md) | `.env`, 에이전트 백엔드, MCP, TTS 백엔드, 운영 메모 |
-| [멀티 인스턴스](MULTI_INSTANCE.ko.md) | 프로젝트마다 영구 Discord 음성방 하나씩 운영 |
-| [릴리스 노트](RELEASE.ko.md) | 현재 기능과 릴리스 전 체크리스트 |
-| [English docs](../../README.md) | 영어 canonical README와 문서 |
+| [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) | 현재 기능과 사전 릴리스 체크리스트 |
 
 ## 작은 명령 지도
 
 ```bash
-vc status                 # 현재 언어, TTS, 브릿지 설정 보기
+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                  # 기본 브릿지 시작
+vc instance start NAME    # 해당 봇을 백그라운드에서 실행
+vc doctor                 # 민감 정보가 제거된 상태 점검
+vc start                  # 기본 브리지 시작
 ```
 
 Discord에서:
 
-```text
-!join        !ask <prompt>       !verbose on/off
-!latency     !sensitivity normal !sensitivity conservative
-!session new <name> <workdir> [context] --voice <voice-channel>
-```
+| 명령 | 하는 일 |
+|---|---|
+| `!join` | 현재 음성 채널에 참가합니다. |
+| `!ask <prompt>` | 동일 에이전트 백엔드로 텍스트를 보냅니다. |
+| `!verbose on\|off` | 짧은 진행 업데이트를 표시/낭독합니다. |
+| `!latency` | 최근 음성/STT/에이전트/TTS 지연 시간을 요약합니다. |
+| `!sensitivity normal` | 일반 실내 끼어들기 감도를 사용합니다. |
+| `!sensitivity conservative` | 더 엄격한 시끄러운/실외 감도를 사용합니다. |
+| `!session new <name> <workdir> [context] --voice <voice-channel>` | 프로젝트 세션을 음성 방에 연결합니다. |
 
 ## 요구 사항
 
 | 계층 | 기본값 |
 |---|---|
-| Runtime | Node.js 20+, npm; 설치 스크립트가 Homebrew/apt/dnf/pacman으로 설치 시도 |
-| Audio | `ffmpeg`; 설치 스크립트가 설치 시도 |
-| STT | `whisper.cpp` / `whisper-cli`; macOS는 Homebrew, Linux는 로컬 빌드 fallback |
-| TTS | Edge TTS CLI; 필요하면 `.venv-tts` 생성 |
-| Discord | Bot token, Message Content intent, voice permissions |
-| Agent | 인증된 CLI 하네스 하나 이상; 기본은 Hermes Agent |
-| Platform focus | macOS / Apple Silicon을 가장 많이 테스트; Linux bootstrap은 best-effort |
+| 런타임 | 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
@@ -154,4 +145,4 @@ vc doctor
 
 ## 상태
 
-VerbalCoding은 공개 릴리스를 지향하지만 아직 초기 단계입니다. 데모 영상/GIF, 더 넓은 Linux 검증, CI와 보안 리뷰를 계속 보강하면 좋습니다.
+VerbalCoding은 공개 릴리스를 지향하지만 아직 초기 단계입니다. 데모 비디오/GIF, 더 넓은 Linux 검증, CI, 더 깊은 보안 검토는 아직 TODO입니다.

package/docs/i18n/README.ru.md

@@ -1,7 +1,7 @@
 # VerbalCoding
 
 <p align="center">
-  <strong>Общайтесь с CLI-агентами для программирования голосом в Discord — почти как по телефону.</strong>
+  <strong>Разговаривайте с CLI-агентами для кодинга через голос Discord — как по телефону для разработки ПО.</strong>
 </p>
 
 <p align="center">
@@ -19,103 +19,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 в hands-free панель управления агентами для разработки. Скажите задачу, дайте CLI-агенту выполнить работу и получите краткий голосовой ответ — с текстовыми транскриптами, событиями прогресса и защитой от зачитывания длинного кода или логов.
+VerbalCoding превращает голосовой канал Discord в панель управления кодинг-агентами без рук. Произнесите запрос, позвольте CLI-агенту выполнить работу и услышите краткий ответ — с текстовыми расшифровками, событиями прогресса и защитными ограничениями для шумного вывода кода/логов.
 
-## Возможности
+## Главное
 
-| Что есть | Почему это удобно |
+| Что вы получаете | Почему это удобно |
 |---|---|
-| Голосовое управление прежде всего | Управляйте 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, сессия, память и логи для каждого проекта. |
+| Управление агентами голосом в первую очередь | Разговаривайте с Hermes Agent, Claude Code, Codex, Gemini CLI, OpenCode, OpenClaw или любым пользовательским CLI-харнесом. |
+| Речевой цикл на устройстве | Захват голоса Discord → локальная расшифровка `whisper-cli` → агент → фрагментированное воспроизведение TTS. |
+| Общий голосовой и текстовый контекст | Голосовые реплики и текстовые команды `!ask` могут повторно использовать одну и ту же поддерживаемую сессию агента. |
+| Перебивание и режимы чувствительности | Естественно прерывайте воспроизведение и переключайтесь между обычной и консервативной/шумной средой. |
+| Многоязычные голосовые пресеты | Переключайте STT, язык прогресса и голос TTS вместе через `vc language ko/en/auto`. |
+| Изоляция проектов по комнатам | Запускайте по одному боту на проектную комнату с отдельными профилями 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, локальный помощник Edge TTS в `.venv-tts` и мастер настройки. Они поддерживают macOS/Homebrew и распространённые менеджеры пакетов Linux (`apt`, `dnf`, `pacman`); повторно запустите с `--no-wizard` для установки только зависимостей или с `--skip-system`, если хотите устанавливать пакеты ОС самостоятельно.
 
-## Поддерживаемые agent-бэкенды
+Нужно пошаговое руководство по чистой установке? Начните с [Fresh Install](FRESH_INSTALL.ru.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 через настройки адаптера по умолчанию |
+| Пользовательский | `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) | Текущие возможности и pre-release checklist |
+| [Чистая установка](FRESH_INSTALL.ru.md) | Настройка чистого клона, загрузка модели, первый запуск |
+| [Руководство по использованию](USAGE.ru.md) | CLI-команды, команды Discord, режим прогресса, метрики задержки |
+| [Конфигурация](CONFIGURATION.ru.md) | `.env`, бэкенды агентов, MCP, бэкенды TTS, эксплуатационные заметки |
+| [Многоэкземплярный режим](MULTI_INSTANCE.ru.md) | Одна постоянная голосовая комната Discord на проект |
+| [Заметки о релизе](RELEASE.ru.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                 # 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:
+
+| Команда | Что делает |
+|---|---|
+| `!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-cli` из whisper.cpp; установочный скрипт использует Homebrew на macOS или локальную резервную сборку Linux |
+| TTS | Edge TTS CLI; установочный скрипт создаёт `.venv-tts` при необходимости |
+| Discord | Токен бота, intent Message Content, голосовые разрешения |
+| Агент | Как минимум один аутентифицированный CLI-харнес, по умолчанию Hermes Agent |
+| Основная платформа | macOS / Apple Silicon протестированы лучше всего; bootstrap для 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.