verbalcoding 0.2.0

package/docs/USAGE.md

@@ -0,0 +1,108 @@
+# VerbalCoding Usage Guide
+
+This page holds the operational details that used to make the README too long.
+
+## CLI Commands
+
+```bash
+vc status                    # show STT language, progress language, and TTS voice
+vc language en               # English STT + English progress/TTS voice
+vc language ko               # Korean STT + Korean progress/TTS voice
+vc language auto             # Whisper auto-detect STT + English progress/TTS voice
+vc restart auto status       # show commit-time voice-bot auto-restart setting
+vc restart auto on           # enable commit-time voice-bot auto-restart
+vc restart auto off          # disable it; this is the default
+vc bot invite CLIENT_ID      # print a Discord invite URL with required permissions
+vc instance status           # list per-instance bridge configs and process status
+vc instance setup NAME       # write instances/NAME.env and create ~/.hermes/profiles/NAME
+vc instance start NAME       # start ./run.sh instances/NAME.env detached
+vc instance stop NAME        # stop a detached instance and remove its pid file
+vc doctor                    # run the redacted doctor check
+npm run mcp                  # run the stdio MCP server
+```
+
+Language changes update `.env`; restart the bridge with `./run.sh` or your process manager for them to take effect.
+
+## Run Modes
+
+Single-instance bridge:
+
+```bash
+./run.sh
+```
+
+Per-instance bridge using a local override env:
+
+```bash
+./run.sh instances/my-project.env
+# or
+VERBALCODING_INSTANCE_ENV=instances/my-project.env ./run.sh
+```
+
+The bot auto-joins the first configured channel name, defaulting to `일반,General,general`.
+
+## Discord Commands
+
+| Command | Purpose |
+|---|---|
+| `!ping` | Basic bot check |
+| `!join` / `!leave` | Join or leave voice |
+| `!say <text>` | Speak text directly through TTS |
+| `!voice-test <text>` | Test the active TTS backend |
+| `!voice-clone capture` | Save the next valid utterance as an OpenVoice reference sample |
+| `!voice-clone status` / `!voice-clone cancel` | Inspect or cancel capture |
+| `!ask <prompt>` | Send text through the same selected harness adapter as voice |
+| `!session status` | Show current project/default adapter session |
+| `!session new <name> <workdir> [context] --voice <voice-channel>` | Create a project-scoped Hermes session |
+| `!session attach-voice [sessionName] --voice <voice-channel>` | Bind text channel/thread to a voice channel |
+| `!session list` | List configured project sessions |
+| `!session reset` / `!reset-session` | Clear current project/default adapter session file |
+| `!verbose on/off` | Toggle detailed progress updates |
+| `!latency` / `!metrics` | Show recent latency summary |
+| `!sensitivity normal/conservative` | Switch barge-in sensitivity |
+
+Voice equivalents such as “외부 모드”, “보수 모드”, “실내”, “기본 감도”, and clear stop phrases like “잠깐”, “멈춰”, “그만” are handled by the bridge. You can also say “상세 진행 켜” / “상세 진행 꺼” to toggle verbose progress by voice.
+
+## Verbose Progress Mode
+
+Verbose progress is off by default unless `AGENT_VERBOSE_PROGRESS=1` is set. Enable it with `!verbose on` or a voice command like “상세 진행 켜”. It can emit short progress lines such as:
+
+```text
+🤖 Hermes Agent 호출 시작
+📖 파일 읽기 app-node/main.mjs
+🔎 웹 검색 실행
+⌨️ 터미널 명령 실행
+🤖 Hermes Agent 응답 수신
+```
+
+This mode asks the selected CLI harness to emit `VERBALCODING_PROGRESS: ...` lines and summarizes common tool markers from streaming stdout/stderr when available. Secret-looking fields are redacted and progress lines are removed from the final spoken answer.
+
+## Latency Metrics
+
+VerbalCoding writes per-turn latency records as JSONL. Default path:
+
+```text
+./.logs/latency.jsonl
+```
+
+Each record includes status, total time, voice capture time, utterance idle wait, STT time, agent time, TTS synthesis/playback time, chunk counts, transcript length, answer length, and audio levels where available.
+
+In Discord:
+
+```text
+!latency
+!metrics
+```
+
+The summary uses the latest 200 records: count, average, p95, max, and non-OK statuses.
+
+## Testing
+
+```bash
+node --check app-node/main.mjs
+npm test
+bash -n run.sh scripts/install.sh
+vc doctor
+```
+
+`vc doctor` intentionally redacts secrets and only reports whether required values are configured. It also checks `instances/*.env` for duplicate token fingerprints and colliding runtime paths.

package/docs/assets/figures/verbalcoding-flow.svg

@@ -0,0 +1,63 @@
+<svg width="1200" height="520" viewBox="0 0 1200 520" fill="none" xmlns="http://www.w3.org/2000/svg" role="img" aria-labelledby="title desc">
+  <title id="title">VerbalCoding voice-to-agent flow</title>
+  <desc id="desc">A stylized pipeline from Discord voice to speech recognition, CLI agent, text answer, and TTS playback.</desc>
+  <defs>
+    <linearGradient id="bg" x1="0" y1="0" x2="1200" y2="520" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#0F172A"/>
+      <stop offset="0.55" stop-color="#111827"/>
+      <stop offset="1" stop-color="#312E81"/>
+    </linearGradient>
+    <linearGradient id="card" x1="120" y1="84" x2="1080" y2="436" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#1E293B" stop-opacity="0.92"/>
+      <stop offset="1" stop-color="#020617" stop-opacity="0.86"/>
+    </linearGradient>
+    <filter id="shadow" x="-20%" y="-20%" width="140%" height="140%">
+      <feDropShadow dx="0" dy="18" stdDeviation="22" flood-color="#000" flood-opacity="0.35"/>
+    </filter>
+  </defs>
+  <rect width="1200" height="520" rx="34" fill="url(#bg)"/>
+  <circle cx="1030" cy="90" r="190" fill="#6366F1" opacity="0.16"/>
+  <circle cx="170" cy="430" r="210" fill="#06B6D4" opacity="0.13"/>
+  <rect x="70" y="54" width="1060" height="412" rx="32" fill="url(#card)" stroke="#334155" filter="url(#shadow)"/>
+  <text x="110" y="118" fill="#F8FAFC" font-family="Inter, ui-sans-serif, system-ui" font-size="42" font-weight="800">VerbalCoding</text>
+  <text x="110" y="154" fill="#94A3B8" font-family="Inter, ui-sans-serif, system-ui" font-size="20">Discord voice → local STT → CLI coding agent → spoken answer</text>
+
+  <g font-family="Inter, ui-sans-serif, system-ui" font-size="17" font-weight="700">
+    <rect x="110" y="220" width="150" height="92" rx="20" fill="#5865F2"/>
+    <text x="185" y="258" fill="white" text-anchor="middle">Discord</text>
+    <text x="185" y="284" fill="#E0E7FF" text-anchor="middle" font-size="14">voice channel</text>
+
+    <rect x="305" y="220" width="150" height="92" rx="20" fill="#0891B2"/>
+    <text x="380" y="258" fill="white" text-anchor="middle">whisper.cpp</text>
+    <text x="380" y="284" fill="#CFFAFE" text-anchor="middle" font-size="14">local STT</text>
+
+    <rect x="500" y="220" width="150" height="92" rx="20" fill="#7C3AED"/>
+    <text x="575" y="258" fill="white" text-anchor="middle">Adapter</text>
+    <text x="575" y="284" fill="#EDE9FE" text-anchor="middle" font-size="14">Hermes / Claude / Codex</text>
+
+    <rect x="695" y="220" width="150" height="92" rx="20" fill="#111827" stroke="#475569"/>
+    <text x="770" y="258" fill="white" text-anchor="middle">CLI Agent</text>
+    <text x="770" y="284" fill="#CBD5E1" text-anchor="middle" font-size="14">does the work</text>
+
+    <rect x="890" y="220" width="150" height="92" rx="20" fill="#0EA5E9"/>
+    <text x="965" y="258" fill="white" text-anchor="middle">TTS</text>
+    <text x="965" y="284" fill="#E0F2FE" text-anchor="middle" font-size="14">chunked playback</text>
+  </g>
+
+  <g stroke="#94A3B8" stroke-width="4" stroke-linecap="round">
+    <path d="M266 266H296"/>
+    <path d="M461 266H491"/>
+    <path d="M656 266H686"/>
+    <path d="M851 266H881"/>
+  </g>
+  <g fill="#94A3B8">
+    <path d="M296 266l-10-7v14l10-7z"/>
+    <path d="M491 266l-10-7v14l10-7z"/>
+    <path d="M686 266l-10-7v14l10-7z"/>
+    <path d="M881 266l-10-7v14l10-7z"/>
+  </g>
+
+  <rect x="150" y="360" width="900" height="54" rx="17" fill="#020617" stroke="#1F2937"/>
+  <text x="182" y="394" fill="#A7F3D0" font-family="SFMono-Regular, ui-monospace, monospace" font-size="18">$ vc language ko &amp;&amp; vc instance start my-project</text>
+  <text x="1045" y="394" fill="#64748B" text-anchor="end" font-family="Inter, ui-sans-serif, system-ui" font-size="15">hands-free coding loop</text>
+</svg>

package/docs/i18n/README.es.md

@@ -0,0 +1,121 @@
+# VerbalCoding
+
+<p align="center">
+  <strong>Habla con tus agentes de programación CLI por voz en Discord, como en una llamada.</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>
+
+## Why
+
+VerbalCoding convierte un canal de voz de Discord en una superficie manos libres para agentes de programación. Di una petición, deja que el agente CLI trabaje y escucha una respuesta concisa, con transcripciones, eventos de progreso y protecciones para no leer código o logs interminables.
+
+## Puntos clave
+
+| Qué ofrece | Por qué importa |
+|---|---|
+| Control por voz primero | Controla Hermes Agent, Claude Code, Codex, Gemini CLI, OpenCode, OpenClaw o cualquier CLI propia con la voz. |
+| Bucle de voz local-first | Voz de Discord → STT `whisper.cpp` → agente → reproducción TTS por fragmentos. |
+| Contexto compartido voz + texto | Los turnos de voz y `!ask` pueden reutilizar la misma sesión del agente compatible. |
+| Interrupciones y sensibilidad | Interrumpe la reproducción de forma natural y cambia entre sensibilidad normal o conservadora. |
+| Preajustes multilingües | `vc language ko/en/auto` cambia STT, idioma de progreso y voz TTS a la vez. |
+| Aislamiento por proyecto | Un bot, perfil Hermes, sesión, memoria y logs por sala/proyecto. |
+
+## Inicio rápido
+
+```bash
+git clone git@github.com:ca1773130n/VerbalCoding.git
+cd VerbalCoding
+./scripts/install.sh
+vc doctor
+./run.sh
+```
+
+## Cómo funciona
+
+```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"]
+```
+
+## Backends de agentes compatibles
+
+| 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 |
+
+## Aprende más
+
+| Guide | What you get |
+|---|---|
+| [Fresh Install](../FRESH_INSTALL.md) | Instalación desde cero, descarga del modelo y primera ejecución |
+| [Usage Guide](../USAGE.md) | Comandos CLI, comandos de Discord, progreso y métricas de latencia |
+| [Configuration](../CONFIGURATION.md) | .env, backends de agente, MCP, TTS y notas operativas |
+| [Multi-Instance](../MULTI_INSTANCE.md) | Una sala de voz persistente por proyecto |
+| [Release Notes](../RELEASE.md) | Capacidades actuales y checklist previo al lanzamiento |
+
+## Mapa rápido de comandos
+
+```bash
+vc status
+vc language ko|en|auto
+vc bot invite CLIENT_ID
+vc instance setup NAME
+vc instance start NAME
+vc doctor
+```
+
+## Requisitos
+
+| 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 |
+
+## Contribuir
+
+```bash
+node --check app-node/main.mjs
+npm test
+bash -n run.sh scripts/install.sh
+vc doctor
+```
+
+## Estado
+
+VerbalCoding is public-release oriented but still early. Demo video/GIF, broader Linux notes, and a formal license file are still TODOs.

package/docs/i18n/README.fr.md

@@ -0,0 +1,121 @@
+# VerbalCoding
+
+<p align="center">
+  <strong>Pilotez vos agents de code CLI à la voix dans Discord, comme au téléphone.</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>
+
+## Why
+
+VerbalCoding transforme un salon vocal Discord en interface mains libres pour agents de code. Dictez une demande, laissez le CLI travailler, puis écoutez une réponse concise — avec transcription texte, événements de progression et garde-fous pour éviter de lire de longs blocs de code ou logs.
+
+## Points forts
+
+| Fonction | Pourquoi c’est utile |
+|---|---|
+| Contrôle vocal d’abord | Pilotez Hermes Agent, Claude Code, Codex, Gemini CLI, OpenCode, OpenClaw ou un CLI personnalisé à la voix. |
+| Boucle vocale locale | Voix Discord → STT `whisper.cpp` → agent → lecture TTS par segments. |
+| Contexte partagé voix + texte | Les tours vocaux et `!ask` peuvent réutiliser la même session d’agent compatible. |
+| Interruption et sensibilité | Interrompez naturellement la lecture et basculez entre sensibilité normale ou conservatrice. |
+| Préréglages vocaux multilingues | `vc language ko/en/auto` change ensemble STT, langue de progression et voix TTS. |
+| Isolation par projet | Un bot, profil Hermes, session, mémoire et logs par salon/projet. |
+
+## Démarrage rapide
+
+```bash
+git clone git@github.com:ca1773130n/VerbalCoding.git
+cd VerbalCoding
+./scripts/install.sh
+vc doctor
+./run.sh
+```
+
+## Fonctionnement
+
+```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"]
+```
+
+## Backends d’agents pris en charge
+
+| 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 |
+
+## En savoir plus
+
+| Guide | What you get |
+|---|---|
+| [Fresh Install](../FRESH_INSTALL.md) | Installation propre, téléchargement du modèle, premier lancement |
+| [Usage Guide](../USAGE.md) | Commandes CLI, commandes Discord, progression, métriques de latence |
+| [Configuration](../CONFIGURATION.md) | .env, backends agent, MCP, TTS et notes d’exploitation |
+| [Multi-Instance](../MULTI_INSTANCE.md) | Un salon vocal Discord permanent par projet |
+| [Release Notes](../RELEASE.md) | Fonctionnalités actuelles et checklist pré-release |
+
+## Mini carte des commandes
+
+```bash
+vc status
+vc language ko|en|auto
+vc bot invite CLIENT_ID
+vc instance setup NAME
+vc instance start NAME
+vc doctor
+```
+
+## Prérequis
+
+| 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 |
+
+## Contribuer
+
+```bash
+node --check app-node/main.mjs
+npm test
+bash -n run.sh scripts/install.sh
+vc doctor
+```
+
+## Statut
+
+VerbalCoding is public-release oriented but still early. Demo video/GIF, broader Linux notes, and a formal license file are still TODOs.

package/docs/i18n/README.ja.md

@@ -0,0 +1,121 @@
+# VerbalCoding
+
+<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">
+</p>
+
+<p align="center">
+  <img src="../assets/figures/verbalcoding-flow.svg" alt="VerbalCoding voice-to-agent flow" width="860">
+</p>
+
+## Why
+
+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プロファイル、セッション、メモリ、ログを分離します。 |
+
+## クイックスタート
+
+```bash
+git clone git@github.com:ca1773130n/VerbalCoding.git
+cd VerbalCoding
+./scripts/install.sh
+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"]
+```
+
+## 対応エージェントバックエンド
+
+| 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 |
+
+## 詳しく見る
+
+| 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) | 現在の機能とリリース前チェックリスト |
+
+## 小さなコマンド表
+
+```bash
+vc status
+vc language ko|en|auto
+vc bot invite CLIENT_ID
+vc instance setup NAME
+vc instance start NAME
+vc doctor
+```
+
+## 要件
+
+| 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
+```
+
+## ステータス
+
+VerbalCoding is public-release oriented but still early. Demo video/GIF, broader Linux notes, and a formal license file are still TODOs.

package/docs/i18n/README.ko.md

@@ -0,0 +1,121 @@
+# VerbalCoding
+
+<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">
+</p>
+
+<p align="center">
+  <img src="../assets/figures/verbalcoding-flow.svg" alt="VerbalCoding voice-to-agent flow" width="860">
+</p>
+
+## Why
+
+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 프로필, 세션, 메모리, 로그를 둡니다. |
+
+## 빠른 시작
+
+```bash
+git clone git@github.com:ca1773130n/VerbalCoding.git
+cd VerbalCoding
+./scripts/install.sh
+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"]
+```
+
+## 지원 에이전트 백엔드
+
+| 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 |
+
+## 더 알아보기
+
+| 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) | 현재 기능과 릴리스 전 체크리스트 |
+
+## 작은 명령 지도
+
+```bash
+vc status
+vc language ko|en|auto
+vc bot invite CLIENT_ID
+vc instance setup NAME
+vc instance start NAME
+vc doctor
+```
+
+## 요구 사항
+
+| 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
+```
+
+## 상태
+
+VerbalCoding is public-release oriented but still early. Demo video/GIF, broader Linux notes, and a formal license file are still TODOs.