verbalcoding 0.2.7 → 0.2.9

package/docs/i18n/MULTI_INSTANCE.zh.md

@@ -1,50 +1,64 @@
-# VerbalCoding 多实例
+# 多实例 VerbalCoding
 
-VerbalCoding can run multiple independent Discord voice bridge processes. Each process loads a different `instances/<name>.env` file and uses a different Discord bot token.
+VerbalCoding 可以运行多个相互独立的 Discord 语音桥接进程。每个进程仍然是现有的单实例 Node 桥接，但会加载不同的 `instances/<name>.env` 文件，并使用不同的 Discord 机器人令牌。
 
-Use this when each project should permanently occupy its own Discord voice channel and write to its own transcript channel/thread.
+当每个项目都应长期占用自己的 Discord 语音频道，并写入自己的转写频道/thread 时，请使用此模式。
 
-## Why multiple bot tokens are required
+## 为什么需要多个机器人令牌
 
-Discord voice residency is effectively one active voice connection per bot account per guild. For simultaneous project rooms, create one Discord application/bot per project.
+Discord 语音驻留实际上是每个机器人账号在每个 guild 中只能有一个活动语音连接。如果一个机器人令牌加入同一 guild 中的另一个语音频道，它就无法同时永久保持连接到先前的频道。若要同时使用多个项目房间，请为每个项目创建一个 Discord 应用/机器人。
 
-## File layout
+## 文件布局
 
 ```text
 instances/
   README.md
   example.env
-  llm-wiki.env        # local only, ignored by git
-  verbalcoding.env    # local only, ignored by git
+  llm-wiki.env        # 仅本地，git 忽略
+  verbalcoding.env    # 仅本地，git 忽略
 .run/instances/
-  llm-wiki.pid        # runtime only, ignored by git
+  llm-wiki.pid        # 仅运行时，git 忽略
 ```
 
-Real `instances/*.env` files are ignored because they may contain Discord tokens.
+真实的 `instances/*.env` 文件会被忽略，因为它们可能包含 Discord 令牌。`instances/example.env` 是已提交的模板。
 
-## Instance setup wizard
+## 实例设置向导
+
+正常使用时，用户不应复制并手动编辑 env 文件。请运行向导：
 
 ```bash
 vc instance setup llm-wiki
+# 或通过项目设置脚本：
 ./scripts/install.sh --instance llm-wiki
 ```
 
-The wizard asks for bot token, Discord Application/Client ID, voice channel, transcript target, workdir, project context, and isolated runtime paths. It writes `instances/<name>.env` with mode `0600` and backs up an existing file.
+向导会提示输入机器人令牌、Discord Application/Client ID、语音频道、转写目标、workdir、项目上下文和隔离的运行时路径。它会以 `0600` 模式写入 `instances/<name>.env`，在覆盖现有文件前先备份，并打印下一步 start/status 命令。
 
-Generate invite URLs with:
+如果你在设置期间输入 Discord Application/Client ID，摘要也会打印该机器人的邀请 URL。你可以随时用以下命令生成同一 URL：
 
 ```bash
 vc bot invite <client-id>
 vc bot invite <client-id> --guild <guild-id>
 ```
 
-## Hermes profile isolation
+Discord 仍然要求每个同时存在的语音房间都有一个 Developer Portal 应用/机器人，但这可以避免手动构造 OAuth URL 或权限整数。
+
+### Hermes profile 隔离
+
+每个实例都会在 `~/.hermes/profiles/<name>` 获得自己的 Hermes home，因此 memory、MEMORY.md、SOUL.md 和已学习 skills 不会在项目之间泄漏。
+
+`vc instance setup <name>` 会自动：
 
-Each instance gets its own Hermes home at `~/.hermes/profiles/<name>` so memory, `MEMORY.md`, `SOUL.md`, and learned skills do not leak across projects.
+- 运行 `hermes profile create <name> --clone-from default`（从当前 `~/.hermes` 带入 API keys 和模型；会话与记忆从空白开始），
+- 将新 profile 的 `terminal.cwd` 设置为实例 workdir，
+- 使用向导中的项目上下文答案初始化 `<profile>/SOUL.md`，
+- 将 `HERMES_HOME=...` 写入 `instances/<name>.env`。
 
-`vc instance setup <name>` creates or reuses the profile, sets `terminal.cwd`, seeds `SOUL.md`, and writes `HERMES_HOME` into the instance env. Instance names must match `^[a-z0-9][a-z0-9_-]{0,63}$`.
+`vc instance start <name>` 会自愈：如果 env 指向的 Hermes profile 目录不再存在，start 命令会在启动前重新创建它。
 
-## Minimal generated instance env
+实例名称必须匹配 `^[a-z0-9][a-z0-9_-]{0,63}$`，因为 Hermes 会将该名称用作目录和配置键。
+
+## 最小生成实例 env
 
 ```env
 INSTANCE_NAME=my-project
@@ -62,9 +76,9 @@ AGENT_CWD=/path/to/my-project
 AGENT_PROJECT_CONTEXT=Project session: My Project
 ```
 
-`vc doctor` checks duplicate tokens, colliding runtime paths, missing profile directories, and `terminal.cwd` mismatches without printing secrets.
+请为每个实例提供唯一的日志/debug/会话文件值。`HERMES_HOME` 和匹配的 `~/.hermes/profiles/<name>` 目录会由 `vc instance setup` 自动创建。`vc doctor` 会检查重复令牌、冲突的运行时路径、缺失的 profile 目录，以及 profile 与实例之间的 `terminal.cwd` 不匹配——且不会打印密钥。
 
-## Commands
+## 命令
 
 ```bash
 vc instance list
@@ -75,47 +89,91 @@ vc instance stop my-project
 vc instance restart my-project
 ```
 
-## Example: two permanent voice rooms
+`start` 会分离运行 `./run.sh instances/<name>.env`，并写入 `.run/instances/<name>.pid`。
+
+`stop` 会发送 `SIGTERM`，最多等待 10 秒，然后回退到 `SIGKILL` 并移除 pid 文件。
+
+## 示例：两个长期语音房间
 
-1. Create two Discord applications/bots.
-2. Invite both with text and voice permissions. Use `vc bot invite <client-id>`.
-3. Run setup:
+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
 ```
 
-4. Check and start:
+向导会以 `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
 ```
 
-5. Verify logs:
+6. 验证日志：
 
 ```bash
 tail -n 50 /tmp/verbalcoding-verbalcoding.log
 tail -n 50 /tmp/verbalcoding-llm-wiki.log
 ```
 
-Expected:
+预期日志行：
 
 ```text
 Listening in voice channel ... / VerbalCoding
 Listening in voice channel ... / LLM-Wiki
 ```
 
-## Short-term single-bot text/voice binding
+7. 停止两者：
+
+```bash
+vc instance stop verbalcoding
+vc instance stop llm-wiki
+```
+
+## 短期单机器人文本/语音绑定
+
+如果你只有一个机器人令牌，请使用项目会话语音绑定，而不是同时驻留多个频道。
 
-If you only have one bot token, bind a project session to a voice channel instead of simultaneous residency:
+在目标文本频道/thread 中运行：
 
 ```text
 !session attach-voice --voice "LLM-Wiki"
+```
+
+行为：
+
+- 将所选语音频道绑定到当前文本频道/thread。
+- 如果当前文本频道没有项目会话，则创建一个临时隔离会话。
+- 语音 STT/结果/进度/最终答案文本会路由到该活动项目的转写目标。
+
+若要附加现有命名项目会话：
+
+```text
 !session voice llm-wiki --voice "LLM-Wiki"
 ```
 
-This routes text/STT/result/progress/final answer messages correctly, but it does not make one bot stay in two voice channels at the same time.
+这对路由很方便，但不会让一个机器人同时停留在两个语音频道中。若要同时长期驻留，请使用多个机器人令牌/进程。

package/docs/i18n/README.es.md

@@ -1,27 +1,49 @@
 # VerbalCoding
 
-**Habla con tus agentes de programación CLI por voz en Discord, como una llamada.**
-
-[English](../../README.md) · [한국어](README.ko.md) · [日本語](README.ja.md) · [中文](README.zh.md) · [Español](README.es.md) · [Français](README.fr.md) · [Русский](README.ru.md)
-
-![VerbalCoding voice-to-agent flow](../assets/figures/verbalcoding-flow.svg)
-
-## Why
-
-VerbalCoding convierte un canal de voz de Discord en una superficie de control manos libres para agentes de programación. Dictas una solicitud, el agente CLI trabaja y recibes una respuesta breve por voz junto con transcripciones y eventos de progreso.
-
-## Highlights
-
-| Feature | What it means |
+<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</a> ·
+  <a href="README.ko.md">한국어</a> ·
+  <a href="README.ja.md">日本語</a> ·
+  <a href="README.zh.md">中文</a> ·
+  <a href="README.es.md">Español</a> ·
+  <a href="README.fr.md">Français</a> ·
+  <a href="README.ru.md">Русский</a>
+</p>
+
+<p align="center">
+  <img alt="Node.js" src="https://img.shields.io/badge/Node.js-20%2B-339933?logo=node.js&logoColor=white">
+  <img alt="Discord" src="https://img.shields.io/badge/Discord-voice%20bridge-5865F2?logo=discord&logoColor=white">
+  <img alt="STT" src="https://img.shields.io/badge/STT-whisper.cpp-7C3AED">
+  <img alt="TTS" src="https://img.shields.io/badge/TTS-Edge%20%7C%20OpenVoice%20%7C%20Supertonic%20%7C%20SpeechSwift-0EA5E9">
+  <img alt="Agents" src="https://img.shields.io/badge/Agents-Hermes%20%7C%20Claude%20%7C%20Codex%20%7C%20Gemini%20%7C%20OpenCode-111827">
+</p>
+
+<p align="center">
+  <img src="../assets/figures/verbalcoding-flow.svg" alt="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 |
 |---|---|
-| Voice-first agent control | Hermes Agent, Claude Code, Codex, Gemini CLI, OpenCode, OpenClaw, or a custom CLI harness. |
-| Local-first speech loop | Discord voice capture → `whisper.cpp` STT → agent → chunked TTS playback. |
-| Shared voice + text context | Voice turns and `!ask` text commands can reuse the same supported agent session. |
-| Barge-in and sensitivity modes | Interrupt playback naturally and switch between normal and conservative/noisy modes. |
-| Multilingual voice presets | `vc language ko/en/auto` changes STT, progress language, and TTS voice together. |
-| Multi-room project isolation | Run one bot per project room with isolated Hermes profiles, sessions, memory, and logs. |
+| 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. |
 
-## Quick Start
+## Inicio rápido
+
+Ruta más rápida con npm:
 
 ```bash
 npm install -g verbalcoding
@@ -30,7 +52,7 @@ vc doctor
 vc start
 ```
 
-Run without a permanent global install:
+O ejecútalo directamente sin una instalación global permanente:
 
 ```bash
 npx verbalcoding setup --yes
@@ -38,7 +60,7 @@ vc doctor
 vc start
 ```
 
-Contributor clone path:
+Ruta de clonación de GitHub para colaboradores:
 
 ```bash
 git clone https://github.com/ca1773130n/VerbalCoding.git
@@ -48,38 +70,80 @@ vc doctor
 ./run.sh
 ```
 
-`vc setup --yes` and `./scripts/install.sh --yes` bootstrap npm dependencies, `ffmpeg`, `whisper-cli`, the default whisper.cpp model, a local Edge TTS helper, and the short `vc` command where possible.
+`vc setup --yes` 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
 
-## Guides
+| 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 |
 
-| Guide | Link |
+## Aprende más
+
+| Guía | Qué obtienes |
 |---|---|
-| Instalación limpia | [FRESH_INSTALL.es.md](FRESH_INSTALL.es.md) |
-| Guía de uso | [USAGE.es.md](USAGE.es.md) |
-| Configuración | [CONFIGURATION.es.md](CONFIGURATION.es.md) |
-| Multiinstancia | [MULTI_INSTANCE.es.md](MULTI_INSTANCE.es.md) |
-| Notas de versión | [RELEASE.es.md](RELEASE.es.md) |
+| [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 |
 
-## Command map
+## 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 start
+vc status                 # current language, TTS, and bridge settings
+vc language ko|en|auto    # switch STT/progress/TTS language preset
+vc bot invite CLIENT_ID   # generate the Discord bot invite URL
+vc instance setup NAME    # create an isolated project voice bot
+vc instance start NAME    # run that bot in the background
+vc doctor                 # redacted health check
+vc start                  # start the default bridge
 ```
 
-Discord commands:
+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 |
+|---|---|
+| 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:
 
-```text
-!join        !ask <prompt>       !verbose on/off
-!latency     !sensitivity normal !sensitivity conservative
-!session new <name> <workdir> [context] --voice <voice-channel>
+```bash
+node --check app-node/main.mjs
+npm test
+bash -n run.sh scripts/install.sh
+npm pack --dry-run
+vc doctor
 ```
 
-## Requirements
+## Estado
 
-Node.js 20+, npm, `ffmpeg`, `whisper.cpp` / `whisper-cli`, Edge TTS CLI, a Discord bot token with Message Content intent and voice permissions, and at least one authenticated CLI agent backend.
+VerbalCoding 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,27 +1,49 @@
 # VerbalCoding
 
-**Parlez à vos agents de code en CLI via la voix Discord, comme lors d’un appel.**
-
-[English](../../README.md) · [한국어](README.ko.md) · [日本語](README.ja.md) · [中文](README.zh.md) · [Español](README.es.md) · [Français](README.fr.md) · [Русский](README.ru.md)
-
-![VerbalCoding voice-to-agent flow](../assets/figures/verbalcoding-flow.svg)
-
-## Why
-
-VerbalCoding transforme un salon vocal Discord en interface mains libres pour agents de programmation. Vous dictez une demande, l’agent CLI travaille, puis vous recevez une réponse vocale concise avec transcription texte et événements de progression.
-
-## Highlights
-
-| Feature | What it means |
+<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</a> ·
+  <a href="README.ko.md">한국어</a> ·
+  <a href="README.ja.md">日本語</a> ·
+  <a href="README.zh.md">中文</a> ·
+  <a href="README.es.md">Español</a> ·
+  <a href="README.fr.md">Français</a> ·
+  <a href="README.ru.md">Русский</a>
+</p>
+
+<p align="center">
+  <img alt="Node.js" src="https://img.shields.io/badge/Node.js-20%2B-339933?logo=node.js&logoColor=white">
+  <img alt="Discord" src="https://img.shields.io/badge/Discord-voice%20bridge-5865F2?logo=discord&logoColor=white">
+  <img alt="STT" src="https://img.shields.io/badge/STT-whisper.cpp-7C3AED">
+  <img alt="TTS" src="https://img.shields.io/badge/TTS-Edge%20%7C%20OpenVoice%20%7C%20Supertonic%20%7C%20SpeechSwift-0EA5E9">
+  <img alt="Agents" src="https://img.shields.io/badge/Agents-Hermes%20%7C%20Claude%20%7C%20Codex%20%7C%20Gemini%20%7C%20OpenCode-111827">
+</p>
+
+<p align="center">
+  <img src="../assets/figures/verbalcoding-flow.svg" alt="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 |
 |---|---|
-| Voice-first agent control | Hermes Agent, Claude Code, Codex, Gemini CLI, OpenCode, OpenClaw, or a custom CLI harness. |
-| Local-first speech loop | Discord voice capture → `whisper.cpp` STT → agent → chunked TTS playback. |
-| Shared voice + text context | Voice turns and `!ask` text commands can reuse the same supported agent session. |
-| Barge-in and sensitivity modes | Interrupt playback naturally and switch between normal and conservative/noisy modes. |
-| Multilingual voice presets | `vc language ko/en/auto` changes STT, progress language, and TTS voice together. |
-| Multi-room project isolation | Run one bot per project room with isolated Hermes profiles, sessions, memory, and logs. |
+| 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. |
 
-## Quick Start
+## Démarrage rapide
+
+Chemin le plus rapide avec npm :
 
 ```bash
 npm install -g verbalcoding
@@ -30,7 +52,7 @@ vc doctor
 vc start
 ```
 
-Run without a permanent global install:
+Ou exécutez directement sans installation globale permanente :
 
 ```bash
 npx verbalcoding setup --yes
@@ -38,7 +60,7 @@ vc doctor
 vc start
 ```
 
-Contributor clone path:
+Chemin de clonage GitHub pour les contributeurs :
 
 ```bash
 git clone https://github.com/ca1773130n/VerbalCoding.git
@@ -48,38 +70,80 @@ vc doctor
 ./run.sh
 ```
 
-`vc setup --yes` and `./scripts/install.sh --yes` bootstrap npm dependencies, `ffmpeg`, `whisper-cli`, the default whisper.cpp model, a local Edge TTS helper, and the short `vc` command where possible.
+`vc setup --yes` 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.
+
+Besoin d'une procédure d'installation propre ? Commencez par [Installation propre](FRESH_INSTALL.fr.md).
+
+## Backends d'agents pris en charge
 
-## Guides
+| 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 |
 
-| Guide | Link |
+## En savoir plus
+
+| Guide | Ce que vous obtenez |
 |---|---|
-| Installation propre | [FRESH_INSTALL.fr.md](FRESH_INSTALL.fr.md) |
-| Guide d’utilisation | [USAGE.fr.md](USAGE.fr.md) |
-| Configuration | [CONFIGURATION.fr.md](CONFIGURATION.fr.md) |
-| Multi-instance | [MULTI_INSTANCE.fr.md](MULTI_INSTANCE.fr.md) |
-| Notes de version | [RELEASE.fr.md](RELEASE.fr.md) |
+| [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 |
 
-## Command map
+## 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 start
+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
 ```
 
-Discord commands:
+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 |
+|---|---|
+| 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
+
+Exécutez les contrôles légers avant d'envoyer des changements :
 
-```text
-!join        !ask <prompt>       !verbose on/off
-!latency     !sensitivity normal !sensitivity conservative
-!session new <name> <workdir> [context] --voice <voice-channel>
+```bash
+node --check app-node/main.mjs
+npm test
+bash -n run.sh scripts/install.sh
+npm pack --dry-run
+vc doctor
 ```
 
-## Requirements
+## Statut
 
-Node.js 20+, npm, `ffmpeg`, `whisper.cpp` / `whisper-cli`, Edge TTS CLI, a Discord bot token with Message Content intent and voice permissions, and at least one authenticated CLI agent backend.
+VerbalCoding 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.