verbalcoding 0.2.11 → 0.2.12

package/docs/i18n/README.es.md

@@ -1,149 +1,35 @@
-# VerbalCoding
+# Documentación de VerbalCoding
 
-<p align="center">
-  <strong>Habla con tus agentes de programación CLI por voz en Discord, como una llamada telefónica para trabajo de software.</strong>
-</p>
+<p align="center"><a href="../../README.md">English README</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">
-  <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>
+El README es la portada compacta; esta página es el índice de guías detalladas. Si configuras un bot de voz de Discord real por primera vez, empieza por Fresh Install.
 
-<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="Flujo de voz a agente de VerbalCoding" width="860">
-</p>
-
-## Por qué
-
-VerbalCoding convierte un canal de voz de Discord en una superficie de control manos libres para agentes de programación. Di una solicitud, deja que tu agente CLI trabaje y escucha una respuesta concisa de vuelta, con transcripciones de texto, eventos de progreso y protecciones para salidas ruidosas de código o registros.
-
-## Puntos destacados
-
-| Qué obtienes | Por qué se siente bien |
-|---|---|
-| Control de agentes con voz primero | Habla con Hermes Agent, Claude Code, Codex, Gemini CLI, OpenCode, OpenClaw o cualquier arnés CLI personalizado. |
-| Bucle de voz en el dispositivo | Captura de voz de Discord → transcripción local con `whisper-cli` → agente → reproducción TTS por fragmentos. |
-| Contexto compartido de voz y texto | Los turnos de voz y los comandos de texto `!ask` pueden reutilizar la misma sesión de agente compatible. |
-| Interrupción natural y modos de sensibilidad | Interrumpe la reproducción de forma natural y cambia entre entornos normales y conservadores/ruidosos. |
-| Preajustes de voz multilingües | Cambia STT, idioma de progreso y voz TTS juntos con `vc language ko/en/auto`. |
-| Aislamiento de proyectos por salas | Ejecuta un bot por sala de proyecto con perfiles, sesiones, memoria y registros de Hermes aislados. |
-
-## Inicio rápido
-
-Ruta más rápida con npm:
+## Ruta rápida
 
 ```bash
-npm install -g verbalcoding
-vc setup --yes
+npm install -g verbalcoding@latest
+vc setup
 vc doctor
 vc start
 ```
 
-O ejecútalo directamente sin una instalación global permanente:
-
-```bash
-npx verbalcoding setup --yes
-vc doctor
-vc start
-```
-
-Ruta de clonación de GitHub para colaboradores:
-
-```bash
-git clone https://github.com/ca1773130n/VerbalCoding.git
-cd VerbalCoding
-./scripts/install.sh --yes
-vc doctor
-./run.sh
-```
-
-`vc setup --yes` inicializa los prerrequisitos locales desde el paquete npm instalado. `./scripts/install.sh --yes` hace lo mismo solo dentro de un clon de GitHub. Ambos cubren, cuando es posible, dependencias de Node/npm, `ffmpeg`, `whisper-cli`, el modelo predeterminado de whisper.cpp, el asistente local de Edge TTS en `.venv-tts` y la configuración del asistente. Admiten macOS/Homebrew y administradores de paquetes comunes de Linux (`apt`, `dnf`, `pacman`); vuelve a ejecutar con `--no-wizard` para configurar solo dependencias o con `--skip-system` si quieres instalar los paquetes del sistema por tu cuenta.
+## Guías
 
-¿Necesitas un recorrido de instalación limpia? Empieza con [Instalación limpia](FRESH_INSTALL.es.md).
-
-## Backends de agentes compatibles
-
-| Backend | Comando predeterminado | Soporte de sesión |
-|---|---:|---|
-| Hermes Agent | `hermes chat -Q -q` | Reanudación, progreso detallado, cancelación, recuperación de respuesta final |
-| Claude Code | `claude -p` | Soporte de archivo de sesión CLI mediante los valores predeterminados del adaptador |
-| Codex CLI | `codex exec` | Soporte de archivo de sesión CLI mediante los valores predeterminados del adaptador |
-| Gemini CLI | `gemini -p` | Soporte de archivo de sesión CLI mediante los valores predeterminados del adaptador |
-| OpenCode | `opencode run` | Soporte de archivo de sesión CLI mediante los valores predeterminados del adaptador |
-| OpenClaw | `openclaw run` | Soporte de archivo de sesión CLI mediante los valores predeterminados del adaptador |
-| Personalizado | `AGENT_COMMAND` | Usa tu propio comando no interactivo |
-
-## Aprende más
-
-| Guía | Qué obtienes |
-|---|---|
-| [Instalación limpia](FRESH_INSTALL.es.md) | Configuración desde un clon limpio, descarga del modelo y primera ejecución |
-| [Guía de uso](USAGE.es.md) | Comandos CLI, comandos de Discord, modo de progreso y métricas de latencia |
-| [Configuración](CONFIGURATION.es.md) | `.env`, backends de agente, MCP, backends TTS y notas operativas |
-| [Multiinstancia](MULTI_INSTANCE.es.md) | Una sala de voz permanente de Discord por proyecto |
-| [Notas de versión](RELEASE.es.md) | Capacidades actuales y lista de verificación previa al lanzamiento |
-
-## Mapa mínimo de comandos
-
-```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
-```
-
-En Discord:
-
-| Comando | Qué hace |
-|---|---|
-| `!join` | Se une a tu canal de voz actual. |
-| `!ask <prompt>` | Envía texto al mismo backend de agente. |
-| `!verbose on\|off` | Muestra/dice actualizaciones cortas de progreso. |
-| `!latency` | Resume la latencia reciente de voz/STT/agente/TTS. |
-| `!sensitivity normal` | Usa sensibilidad normal de interrupción para interiores. |
-| `!sensitivity conservative` | Usa sensibilidad más estricta para entornos ruidosos/exteriores. |
-| `!session new <name> <workdir> [context] --voice <voice-channel>` | Vincula una sesión de proyecto a una sala de voz. |
-
-## Requisitos
-
-| Capa | Predeterminado |
+| Guías | Úsala cuando necesites |
 |---|---|
-| Runtime | Node.js 20+, npm; el script de instalación puede instalar vía Homebrew/apt/dnf/pacman |
-| Audio | `ffmpeg`; el script de instalación puede instalarlo |
-| Reconocimiento de voz | `whisper-cli` local de whisper.cpp; el script usa Homebrew en macOS o compilación local alternativa en Linux |
-| TTS | CLI de Edge TTS; el script de instalación crea `.venv-tts` si hace falta |
-| Discord | Token de bot, intent Message Content, permisos de voz |
-| Agente | Al menos un arnés CLI autenticado, Hermes Agent por defecto |
-| Enfoque de plataforma | macOS / Apple Silicon es lo más probado; el arranque de Linux es de mejor esfuerzo y está documentado |
+| [Fresh Install](FRESH_INSTALL.es.md) | npm/global install limpio, Discord app setup, primer bot invite y primera voice run. |
+| [Usage](USAGE.es.md) | Comandos CLI, comandos Discord, modos de ejecución, voice changes, progress y latency metrics. |
+| [Voz integrada de Hermes vs VerbalCoding](HERMES_VOICE.es.md) | Qué hace ya la voz de Discord integrada en Hermes y qué añade VerbalCoding. |
+| [Configuration](CONFIGURATION.es.md) | .env, agent backends, MCP server, TTS backends y ajustes operativos. |
+| [Troubleshooting](TROUBLESHOOTING.es.md) | Docker UDP, voice join failures, missing token/channel checks y doctor behavior. |
+| [Multi-Instance](MULTI_INSTANCE.es.md) | Un Discord voice bot fijo por sala de proyecto con Hermes profiles aislados. |
+| [Release Notes](RELEASE.es.md) | Capacidades actuales, verification checklist y TODO antes del public release. |
 
-## Contribuir
+## README localizado
 
-Ejecuta las comprobaciones ligeras antes de enviar cambios:
-
-```bash
-node --check app-node/main.mjs
-npm test
-bash -n run.sh scripts/install.sh
-npm pack --dry-run
-vc doctor
-```
+- [README.es.md](../../README.es.md)
+- [English README](../../README.md)
 
-## Estado
+## Nota para contribuidores
 
-VerbalCoding está orientado al lanzamiento público, pero aún es temprano. Video/GIF de demostración, validación más amplia en Linux, CI y una revisión de seguridad más profunda siguen pendientes.
+En documentación para usuarios, prioriza comandos `vc ...`. Reserva `./scripts/...` para flujos de contributor con source checkout.

package/docs/i18n/README.fr.md

@@ -1,149 +1,35 @@
-# VerbalCoding
+# Documentation VerbalCoding
 
-<p align="center">
-  <strong>Parlez à vos agents de codage CLI via la voix Discord — comme un appel téléphonique pour le travail logiciel.</strong>
-</p>
+<p align="center"><a href="../../README.md">English README</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">
-  <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>
+Le README est l’entrée compacte; cette page indexe les guides détaillés. Pour configurer un vrai bot vocal Discord pour la première fois, commencez par Fresh Install.
 
-<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="Flux voix-vers-agent de VerbalCoding" width="860">
-</p>
-
-## Pourquoi
-
-VerbalCoding transforme un salon vocal Discord en surface de contrôle mains libres pour agents de codage. Énoncez une demande, laissez votre agent CLI travailler, puis écoutez une réponse concise — avec transcriptions texte, événements de progression et garde-fous pour les sorties de code/journaux bruyantes.
-
-## Points forts
-
-| Ce que vous obtenez | Pourquoi c'est agréable |
-|---|---|
-| Contrôle d'agent pensé pour la voix | Parlez à Hermes Agent, Claude Code, Codex, Gemini CLI, OpenCode, OpenClaw ou à n'importe quel harnais CLI personnalisé. |
-| Boucle vocale sur l'appareil | Capture vocale Discord → transcription locale `whisper-cli` → agent → lecture TTS par morceaux. |
-| Contexte partagé voix + texte | Les tours vocaux et les commandes texte `!ask` peuvent réutiliser la même session d'agent prise en charge. |
-| Interruption et modes de sensibilité | Interrompez naturellement la lecture et basculez entre environnements normaux et conservateurs/bruyants. |
-| Préréglages vocaux multilingues | Changez ensemble la langue STT, la langue de progression et la voix TTS avec `vc language ko/en/auto`. |
-| Isolation multi-salons par projet | Lancez un bot par salon de projet avec profils Hermes, sessions, mémoire et journaux isolés. |
-
-## Démarrage rapide
-
-Chemin le plus rapide avec npm :
+## Chemin rapide
 
 ```bash
-npm install -g verbalcoding
-vc setup --yes
+npm install -g verbalcoding@latest
+vc setup
 vc doctor
 vc start
 ```
 
-Ou exécutez directement sans installation globale permanente :
-
-```bash
-npx verbalcoding setup --yes
-vc doctor
-vc start
-```
-
-Chemin de clonage GitHub pour les contributeurs :
-
-```bash
-git clone https://github.com/ca1773130n/VerbalCoding.git
-cd VerbalCoding
-./scripts/install.sh --yes
-vc doctor
-./run.sh
-```
-
-`vc setup --yes` amorce les prérequis locaux depuis le paquet npm installé. `./scripts/install.sh --yes` fait la même chose uniquement dans un clone GitHub. Les deux couvrent, quand c'est possible, les dépendances Node/npm, `ffmpeg`, `whisper-cli`, le modèle whisper.cpp par défaut, l'assistant Edge TTS local `.venv-tts` et la configuration par assistant. Ils prennent en charge macOS/Homebrew ainsi que les gestionnaires de paquets Linux courants (`apt`, `dnf`, `pacman`) ; relancez avec `--no-wizard` pour une configuration limitée aux dépendances ou `--skip-system` si vous voulez installer vous-même les paquets du système.
+## Guides
 
-Besoin d'une procédure d'installation propre ? Commencez par [Installation propre](FRESH_INSTALL.fr.md).
-
-## Backends d'agents pris en charge
-
-| Backend | Commande par défaut | Prise en charge des sessions |
-|---|---:|---|
-| Hermes Agent | `hermes chat -Q -q` | Reprise, progression détaillée, annulation, récupération de la réponse finale |
-| Claude Code | `claude -p` | Prise en charge du fichier de session CLI via les valeurs par défaut de l'adaptateur |
-| Codex CLI | `codex exec` | Prise en charge du fichier de session CLI via les valeurs par défaut de l'adaptateur |
-| Gemini CLI | `gemini -p` | Prise en charge du fichier de session CLI via les valeurs par défaut de l'adaptateur |
-| OpenCode | `opencode run` | Prise en charge du fichier de session CLI via les valeurs par défaut de l'adaptateur |
-| OpenClaw | `openclaw run` | Prise en charge du fichier de session CLI via les valeurs par défaut de l'adaptateur |
-| Personnalisé | `AGENT_COMMAND` | Apportez votre propre commande non interactive |
-
-## En savoir plus
-
-| Guide | Ce que vous obtenez |
-|---|---|
-| [Installation propre](FRESH_INSTALL.fr.md) | Configuration depuis un clone propre, téléchargement du modèle, premier lancement |
-| [Guide d'utilisation](USAGE.fr.md) | Commandes CLI, commandes Discord, mode progression, métriques de latence |
-| [Configuration](CONFIGURATION.fr.md) | `.env`, backends d'agents, MCP, backends TTS, notes d'exploitation |
-| [Multi-instance](MULTI_INSTANCE.fr.md) | Un salon vocal Discord permanent par projet |
-| [Notes de version](RELEASE.fr.md) | Capacités actuelles et checklist de pré-version |
-
-## Mini-carte des commandes
-
-```bash
-vc status                 # paramètres actuels de langue, TTS et passerelle
-vc language ko|en|auto    # changer le préréglage langue STT/progression/TTS
-vc bot invite CLIENT_ID   # générer l'URL d'invitation du bot Discord
-vc instance setup NAME    # créer un bot vocal de projet isolé
-vc instance start NAME    # exécuter ce bot en arrière-plan
-vc doctor                 # contrôle de santé expurgé
-vc start                  # démarrer la passerelle par défaut
-```
-
-Dans Discord :
-
-| Commande | Effet |
-|---|---|
-| `!join` | Rejoint votre salon vocal actuel. |
-| `!ask <prompt>` | Envoie du texte au même backend d'agent. |
-| `!verbose on\|off` | Affiche/énonce de courtes mises à jour de progression. |
-| `!latency` | Résume la latence récente voix/STT/agent/TTS. |
-| `!sensitivity normal` | Utilise la sensibilité d'interruption normale en intérieur. |
-| `!sensitivity conservative` | Utilise une sensibilité plus stricte pour les environnements bruyants/extérieurs. |
-| `!session new <name> <workdir> [context] --voice <voice-channel>` | Lie une session de projet à un salon vocal. |
-
-## Exigences
-
-| Couche | Valeur par défaut |
+| Guides | À utiliser pour |
 |---|---|
-| Runtime | Node.js 20+, npm ; le script d'installation peut l'installer via Homebrew/apt/dnf/pacman |
-| Audio | `ffmpeg` ; le script d'installation peut l'installer |
-| Reconnaissance vocale | `whisper-cli` local depuis whisper.cpp ; le script d'installation utilise Homebrew sur macOS ou un fallback de build Linux local |
-| TTS | CLI Edge TTS ; le script d'installation crée `.venv-tts` si nécessaire |
-| Discord | Jeton de bot, intent Message Content, permissions vocales |
-| Agent | Au moins un harnais CLI authentifié, Hermes Agent par défaut |
-| Plateforme privilégiée | macOS / Apple Silicon le plus testé ; l'amorçage Linux est documenté et fourni au mieux |
+| [Fresh Install](FRESH_INSTALL.fr.md) | npm/global install propre, Discord app setup, premier bot invite et première voice run. |
+| [Usage](USAGE.fr.md) | Commandes CLI, commandes Discord, modes d’exécution, voice changes, progress et latency metrics. |
+| [Voix intégrée Hermes vs VerbalCoding](HERMES_VOICE.fr.md) | Ce que fait déjà la voix Discord intégrée de Hermes et ce qu’ajoute VerbalCoding. |
+| [Configuration](CONFIGURATION.fr.md) | .env, agent backends, MCP server, TTS backends et réglages opérationnels. |
+| [Troubleshooting](TROUBLESHOOTING.fr.md) | Docker UDP, voice join failures, missing token/channel checks et doctor behavior. |
+| [Multi-Instance](MULTI_INSTANCE.fr.md) | Un Discord voice bot permanent par salon projet avec Hermes profiles isolés. |
+| [Release Notes](RELEASE.fr.md) | Capacités actuelles, verification checklist et TODO avant public release. |
 
-## Contribution
+## README localisé
 
-Exécutez les contrôles légers avant d'envoyer des changements :
-
-```bash
-node --check app-node/main.mjs
-npm test
-bash -n run.sh scripts/install.sh
-npm pack --dry-run
-vc doctor
-```
+- [README.fr.md](../../README.fr.md)
+- [English README](../../README.md)
 
-## Statut
+## Note contributeur
 
-VerbalCoding vise une publication publique mais reste jeune. Vidéo/GIF de démonstration, validation Linux plus large, CI et revue de sécurité plus approfondie restent à faire.
+Dans les docs utilisateur, privilégiez les commandes `vc ...`. Réservez `./scripts/...` aux flux contributor avec source checkout.

package/docs/i18n/README.ja.md

@@ -1,149 +1,35 @@
-# VerbalCoding
+# VerbalCoding ドキュメント
 
-<p align="center">
-  <strong>Discord 音声で CLI コーディングエージェントに話しかける — ソフトウェア作業のための電話のように。</strong>
-</p>
+<p align="center"><a href="../../README.md">English README</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">
-  <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>
+README は短い入口で、このページは詳細ガイドの索引です。初めて実際の Discord voice bot を設定する場合は Fresh Install から始めてください。
 
-<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 エージェントに作業を任せ、簡潔な回答を音声で受け取れます。テキスト文字起こし、進捗イベント、ノイズの多いコード/ログ出力に対するガードレールも備えています。
-
-## ハイライト
-
-| 得られるもの | 何がうれしいか |
-|---|---|
-| 音声ファーストのエージェント操作 | 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
+npm install -g verbalcoding@latest
+vc setup
 vc doctor
 vc start
 ```
 
-永続的なグローバルインストールなしで直接実行する場合:
-
-```bash
-npx verbalcoding setup --yes
-vc doctor
-vc start
-```
-
-コントリビューター向けの GitHub クローン手順:
-
-```bash
-git clone https://github.com/ca1773130n/VerbalCoding.git
-cd VerbalCoding
-./scripts/install.sh --yes
-vc doctor
-./run.sh
-```
-
-`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) から始めてください。
-
-## 対応エージェントバックエンド
-
-| バックエンド | デフォルトコマンド | セッション対応 |
-|---|---:|---|
-| 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` | 独自の非対話コマンドを持ち込めます |
-
-## さらに詳しく
-
-| ガイド | 内容 |
-|---|---|
-| [新規インストール](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                 # 現在の言語、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>` | プロジェクトセッションを音声ルームに紐付けます。 |
-
-## 要件
-
-| レイヤー | デフォルト |
+| ガイド | 必要になる場面 |
 |---|---|
-| ランタイム | 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 ブートストラップはベストエフォートで文書化されています |
+| [Fresh Install](FRESH_INSTALL.ja.md) | クリーンな npm/global install、Discord app setup、初回 bot invite、初回 voice run。 |
+| [Usage](USAGE.ja.md) | CLI コマンド、Discord コマンド、実行モード、voice changes、progress、latency metrics。 |
+| [Hermes 標準音声 vs VerbalCoding](HERMES_VOICE.ja.md) | Hermes の Discord 標準音声がすでにできることと、VerbalCoding が加えるもの。 |
+| [Configuration](CONFIGURATION.ja.md) | .env、agent backends、MCP server、TTS backends、運用設定。 |
+| [Troubleshooting](TROUBLESHOOTING.ja.md) | Docker UDP、voice join failures、missing token/channel checks、doctor behavior。 |
+| [Multi-Instance](MULTI_INSTANCE.ja.md) | 分離 Hermes profile でプロジェクト room ごとに固定 Discord voice bot を 1 つ。 |
+| [Release Notes](RELEASE.ja.md) | 現在の機能、verification checklist、public-release 前の TODO。 |
 
-## コントリビュート
+## ローカライズ README
 
-変更を送る前に軽量チェックを実行してください:
-
-```bash
-node --check app-node/main.mjs
-npm test
-bash -n run.sh scripts/install.sh
-npm pack --dry-run
-vc doctor
-```
+- [README.ja.md](../../README.ja.md)
+- [English README](../../README.md)
 
-## ステータス
+## コントリビューター向けメモ
 
-VerbalCoding は公開リリースを目指していますが、まだ初期段階です。デモ動画/GIF、より広範な Linux 検証、CI、より深いセキュリティレビューはまだ TODO です。
+ユーザー向けドキュメントでは `vc ...` コマンドを優先し、`./scripts/...` は source checkout の contributor flow に限定してください。