verbalcoding 0.2.6 → 0.2.8

package/docs/i18n/MULTI_INSTANCE.zh.md

@@ -0,0 +1,179 @@
+# 多实例 VerbalCoding
+
+VerbalCoding 可以运行多个相互独立的 Discord 语音桥接进程。每个进程仍然是现有的单实例 Node 桥接，但会加载不同的 `instances/<name>.env` 文件，并使用不同的 Discord 机器人令牌。
+
+当每个项目都应长期占用自己的 Discord 语音频道，并写入自己的转写频道/thread 时，请使用此模式。
+
+## 为什么需要多个机器人令牌
+
+Discord 语音驻留实际上是每个机器人账号在每个 guild 中只能有一个活动语音连接。如果一个机器人令牌加入同一 guild 中的另一个语音频道，它就无法同时永久保持连接到先前的频道。若要同时使用多个项目房间，请为每个项目创建一个 Discord 应用/机器人。
+
+## 文件布局
+
+```text
+instances/
+  README.md
+  example.env
+  llm-wiki.env        # 仅本地，git 忽略
+  verbalcoding.env    # 仅本地，git 忽略
+.run/instances/
+  llm-wiki.pid        # 仅运行时，git 忽略
+```
+
+真实的 `instances/*.env` 文件会被忽略，因为它们可能包含 Discord 令牌。`instances/example.env` 是已提交的模板。
+
+## 实例设置向导
+
+正常使用时，用户不应复制并手动编辑 env 文件。请运行向导：
+
+```bash
+vc instance setup llm-wiki
+# 或通过项目设置脚本：
+./scripts/install.sh --instance llm-wiki
+```
+
+向导会提示输入机器人令牌、Discord Application/Client ID、语音频道、转写目标、workdir、项目上下文和隔离的运行时路径。它会以 `0600` 模式写入 `instances/<name>.env`，在覆盖现有文件前先备份，并打印下一步 start/status 命令。
+
+如果你在设置期间输入 Discord Application/Client ID，摘要也会打印该机器人的邀请 URL。你可以随时用以下命令生成同一 URL：
+
+```bash
+vc bot invite <client-id>
+vc bot invite <client-id> --guild <guild-id>
+```
+
+Discord 仍然要求每个同时存在的语音房间都有一个 Developer Portal 应用/机器人，但这可以避免手动构造 OAuth URL 或权限整数。
+
+### Hermes profile 隔离
+
+每个实例都会在 `~/.hermes/profiles/<name>` 获得自己的 Hermes home，因此 memory、MEMORY.md、SOUL.md 和已学习 skills 不会在项目之间泄漏。
+
+`vc instance setup <name>` 会自动：
+
+- 运行 `hermes profile create <name> --clone-from default`（从当前 `~/.hermes` 带入 API keys 和模型；会话与记忆从空白开始），
+- 将新 profile 的 `terminal.cwd` 设置为实例 workdir，
+- 使用向导中的项目上下文答案初始化 `<profile>/SOUL.md`，
+- 将 `HERMES_HOME=...` 写入 `instances/<name>.env`。
+
+`vc instance start <name>` 会自愈：如果 env 指向的 Hermes profile 目录不再存在，start 命令会在启动前重新创建它。
+
+实例名称必须匹配 `^[a-z0-9][a-z0-9_-]{0,63}$`，因为 Hermes 会将该名称用作目录和配置键。
+
+## 最小生成实例 env
+
+```env
+INSTANCE_NAME=my-project
+DISCORD_TOKEN=replac...oken
+DISCORD_CLIENT_ID=123456789012345678
+AUTO_JOIN_VOICE_CHANNELS=Project Room
+TRANSCRIPT_CHANNEL_ID=123456789012345678
+PROJECT_SESSIONS_FILE=config/project-sessions.my-project.json
+BRIDGE_LOG_PATH=/tmp/verbalcoding-my-project.log
+NODE_AUDIO_DEBUG_DIR=/tmp/verbalcoding-my-project-debug
+HERMES_SESSION_FILE=.agent-sessions/hermes/my-project.session
+HERMES_HOME=/home/you/.hermes/profiles/my-project
+AGENT_LABEL=VerbalCoding · My Project
+AGENT_CWD=/path/to/my-project
+AGENT_PROJECT_CONTEXT=Project session: My Project
+```
+
+请为每个实例提供唯一的日志/debug/会话文件值。`HERMES_HOME` 和匹配的 `~/.hermes/profiles/<name>` 目录会由 `vc instance setup` 自动创建。`vc doctor` 会检查重复令牌、冲突的运行时路径、缺失的 profile 目录，以及 profile 与实例之间的 `terminal.cwd` 不匹配——且不会打印密钥。
+
+## 命令
+
+```bash
+vc instance list
+vc instance status
+vc instance status my-project
+vc instance start my-project
+vc instance stop my-project
+vc instance restart my-project
+```
+
+`start` 会分离运行 `./run.sh instances/<name>.env`，并写入 `.run/instances/<name>.pid`。
+
+`stop` 会发送 `SIGTERM`，最多等待 10 秒，然后回退到 `SIGKILL` 并移除 pid 文件。
+
+## 示例：两个长期语音房间
+
+1. 创建两个 Discord 应用/机器人：
+   - VerbalCoding bot
+   - LLM-Wiki bot
+
+2. 使用文本和语音权限邀请两者加入服务器：
+   - View Channel
+   - Send Messages
+   - Send Messages in Threads
+   - Read Message History
+   - Use Application Commands
+   - Connect
+   - Speak
+
+   创建每个 Discord 应用后，使用 `vc bot invite <client-id>` 打印带这些权限的精确邀请 URL。
+
+3. 为每个本地实例运行设置向导：
+
+```bash
+vc instance setup verbalcoding
+vc instance setup llm-wiki
+```
+
+向导会以 `0600` 模式写入被忽略的 `instances/verbalcoding.env` 和 `instances/llm-wiki.env` 文件；它还会在替换前备份现有实例 env。每次运行还会从你的默认 Hermes home 克隆创建 `~/.hermes/profiles/<name>`，因此两个实例起始时具有相同 auth/model，但随着学习各自项目，会累积独立的记忆和 skills。
+
+4. 检查配置：
+
+```bash
+vc doctor
+```
+
+5. 启动两者：
+
+```bash
+vc instance start verbalcoding
+vc instance start llm-wiki
+vc instance status
+```
+
+6. 验证日志：
+
+```bash
+tail -n 50 /tmp/verbalcoding-verbalcoding.log
+tail -n 50 /tmp/verbalcoding-llm-wiki.log
+```
+
+预期日志行：
+
+```text
+Listening in voice channel ... / VerbalCoding
+Listening in voice channel ... / LLM-Wiki
+```
+
+7. 停止两者：
+
+```bash
+vc instance stop verbalcoding
+vc instance stop llm-wiki
+```
+
+## 短期单机器人文本/语音绑定
+
+如果你只有一个机器人令牌，请使用项目会话语音绑定，而不是同时驻留多个频道。
+
+在目标文本频道/thread 中运行：
+
+```text
+!session attach-voice --voice "LLM-Wiki"
+```
+
+行为：
+
+- 将所选语音频道绑定到当前文本频道/thread。
+- 如果当前文本频道没有项目会话，则创建一个临时隔离会话。
+- 语音 STT/结果/进度/最终答案文本会路由到该活动项目的转写目标。
+
+若要附加现有命名项目会话：
+
+```text
+!session voice llm-wiki --voice "LLM-Wiki"
+```
+
+这对路由很方便，但不会让一个机器人同时停留在两个语音频道中。若要同时长期驻留，请使用多个机器人令牌/进程。

package/docs/i18n/README.es.md

@@ -1,7 +1,7 @@
 # VerbalCoding
 
 <p align="center">
-  <strong>Habla con tus agentes de programación CLI por voz en Discord, como en una llamada.</strong>
+  <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">
@@ -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="Flujo de voz a agente de VerbalCoding" width="860">
 </p>
 
-## Why
+## Por qué
 
-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.
+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 clave
+## Puntos destacados
 
-| Qué ofrece | Por qué importa |
+| Qué obtienes | Por qué se siente bien |
 |---|---|
-| 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. |
+| 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:
+
+```bash
+npm install -g verbalcoding
+vc setup --yes
+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 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
 ```
 
-## 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"]
-```
+`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.
+
+¿Necesitas un recorrido de instalación limpia? Empieza con [Instalación limpia](FRESH_INSTALL.es.md).
 
 ## Backends de agentes compatibles
 
-| Backend | Default command | Session support |
+| Backend | Comando predeterminado | Soporte de sesión |
 |---|---:|---|
-| 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` | 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
 
-| Guide | What you get |
+| Guía | Qué obtienes |
 |---|---|
-| [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 |
+| [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 rápido de comandos
+## Mapa mínimo 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
+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
 
-| Layer | Default |
+| Capa | Predeterminado |
 |---|---|
-| 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 |
+| 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 |
 
 ## Contribuir
 
+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
 ```
 
 ## Estado
 
-VerbalCoding is public-release oriented but still early. Demo video/GIF, broader Linux notes, and a formal license file are still TODOs.
+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.

package/docs/i18n/README.fr.md

@@ -1,7 +1,7 @@
 # VerbalCoding
 
 <p align="center">
-  <strong>Pilotez vos agents de code CLI à la voix dans Discord, comme au téléphone.</strong>
+  <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">
@@ -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="Flux voix-vers-agent de VerbalCoding" width="860">
 </p>
 
-## Why
+## Pourquoi
 
-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.
+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
 
-| Fonction | Pourquoi c’est utile |
+| Ce que vous obtenez | Pourquoi c'est agréable |
 |---|---|
-| 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. |
+| 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 :
+
+```bash
+npm install -g verbalcoding
+vc setup --yes
+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 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
 ```
 
-## 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"]
-```
+`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.
 
-## Backends d’agents pris en charge
+Besoin d'une procédure d'installation propre ? Commencez par [Installation propre](FRESH_INSTALL.fr.md).
 
-| Backend | Default command | Session support |
+## Backends d'agents pris en charge
+
+| Backend | Commande par défaut | Prise en charge des sessions |
 |---|---:|---|
-| 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` | 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 | What you get |
+| Guide | Ce que vous obtenez |
 |---|---|
-| [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 |
+| [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
+## 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
+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
 ```
 
-## Prérequis
+Dans Discord :
 
-| Layer | Default |
+| Commande | Effet |
 |---|---|
-| 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 |
+| `!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 |
+|---|---|
+| 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 |
+
+## Contribution
 
-## Contribuer
+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
 ```
 
 ## Statut
 
-VerbalCoding is public-release oriented but still early. Demo video/GIF, broader Linux notes, and a formal license file are still TODOs.
+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.