verbalcoding 0.2.7 → 0.2.8

package/docs/i18n/FRESH_INSTALL.zh.md

@@ -1,21 +1,28 @@
 # 全新安装
 
-This guide mirrors the English fresh-install flow for 中文. It is intended for a clean public install and avoids local-only assumptions.
+本指南用于干净的公开安装。它避免依赖本地专用假设，并使用安装器尽可能完成引导。
 
-## 1. Install the CLI
+## 1. 安装 CLI
+
+推荐的 npm 路径：
 
 ```bash
 npm install -g verbalcoding
-vc setup --yes
 ```
 
-Or run the published package directly:
+或者直接运行已发布的软件包：
 
 ```bash
 npx verbalcoding setup --yes
 ```
 
-Contributor clone path:
+如果你使用了 `npm install -g`，继续运行：
+
+```bash
+vc setup --yes
+```
+
+贡献者的 GitHub 克隆路径：
 
 ```bash
 git clone https://github.com/ca1773130n/VerbalCoding.git
@@ -23,62 +30,120 @@ cd VerbalCoding
 ./scripts/install.sh --yes
 ```
 
-## 2. Bootstrap dependencies
+## 2. 引导依赖并运行设置向导
 
-The setup flow installs npm dependencies when needed, links the short `vc` command for clone installs, installs `ffmpeg` / Node / `whisper-cli` where the OS package manager supports it, downloads `models/ggml-small-q5_1.bin`, creates `.venv-tts`, and writes `.env`.
+通过 npm 安装时，当前目录中没有仓库检出，因此不要直接运行 `./scripts/install.sh`。请改用打包好的 CLI 包装器：
 
-Useful variants:
+```bash
+vc setup --yes
+```
+
+`vc setup` 会运行已安装 npm 包内部的 `scripts/install.sh`。只有在 GitHub 克隆目录中时才使用 `./scripts/install.sh --yes`：
 
 ```bash
-vc setup --yes --no-wizard
-./scripts/install.sh --yes --no-wizard
-./scripts/install.sh --skip-system
-./scripts/install.sh --skip-model
-./scripts/install.sh --skip-edge-tts
+./scripts/install.sh --yes
+```
+
+它会执行以下操作：
+
+- 当缺少 `node_modules/` 时安装 npm 依赖，
+- 使用 `npm link` 安装简短的 `vc` shell 命令，
+- 在 OS 包管理器支持时安装 `ffmpeg`、Node/npm 和 `whisper-cli`，
+- 下载 `models/ggml-small-q5_1.bin`，
+- 当 `PATH` 上尚无 `edge-tts` 时创建 `.venv-tts` 并安装 `edge-tts`，
+- 运行交互式 `.env` 向导。
+
+支持的系统引导路径：
+
+| OS | 系统依赖路径 |
+|---|---|
+| macOS | Homebrew：按需执行 `brew install node ffmpeg whisper-cpp` |
+| Debian/Ubuntu | 使用 `apt-get` 安装 Node/npm、ffmpeg、Python、构建工具；本地 whisper.cpp 构建回退 |
+| Fedora/RHEL | 使用 `dnf` 安装 Node/npm、ffmpeg、Python、构建工具；本地 whisper.cpp 构建回退 |
+| Arch | 使用 `pacman` 安装 Node/npm、ffmpeg、Python、构建工具；本地 whisper.cpp 构建回退 |
+
+有用的安装器变体：
+
+```bash
+vc setup --yes --no-wizard                   # 仅从 npm 安装进行依赖/引导
+./scripts/install.sh --yes --no-wizard       # 仅从克隆仓库进行依赖/引导
+./scripts/install.sh --skip-system           # 不安装 OS 软件包
+./scripts/install.sh --skip-model            # 不下载默认 STT 模型
+./scripts/install.sh --skip-edge-tts         # 不创建 .venv-tts
 VERBALCODING_SKIP_CLI_LINK=1 ./scripts/install.sh --yes
 ```
 
-Supported bootstrap paths: macOS/Homebrew, Debian/Ubuntu `apt`, Fedora/RHEL `dnf`, and Arch `pacman`. If unsupported, manually install Node.js 20+, npm, ffmpeg, Python 3, `whisper-cli`, and an authenticated CLI agent backend.
+如果你的 OS 不受支持，请先手动安装以下内容，再重新运行：
+
+- Node.js 20+ 和 npm
+- ffmpeg
+- 带 venv/pip 的 Python 3
+- whisper.cpp `whisper-cli`
+- 一个已认证的 CLI 代理后端，默认是 Hermes Agent
 
-## 3. Discord application setup
+## 3. Discord 应用设置
 
-Read the upstream bot guides first:
+如果这是你的第一个机器人，请先阅读上游 Discord 机器人设置指南：
 
-- Hermes Agent Discord guide: <https://hermes-agent.nousresearch.com/docs/user-guide/messaging/discord>
-- Discord official bot overview: <https://docs.discord.com/developers/bots/overview>
-- Discord official getting started guide: <https://docs.discord.com/developers/quick-start/getting-started>
+- Hermes Agent Discord 消息指南：<https://hermes-agent.nousresearch.com/docs/user-guide/messaging/discord>
+- Discord 官方机器人概览：<https://docs.discord.com/developers/bots/overview>
+- Discord 官方入门指南：<https://docs.discord.com/developers/quick-start/getting-started>
 
-Create a Discord application and bot, enable the Message Content privileged intent, put the token in the installer or `.env` as `DISCORD_BOT_TOKEN`, then generate the invite URL:
+这些页面展示如何创建 Discord 应用、添加机器人用户、启用特权 intents，并邀请它加入服务器。VerbalCoding 使用同样的 Discord 机器人设置，然后在其上增加语音接收、STT、CLI 代理执行和 TTS 播放。
+
+1. 在 Discord Developer Portal 中创建 Discord 应用和机器人。
+2. 启用 Message Content 特权 intent。
+3. 将机器人令牌复制到安装器提示或 `.env` 中的 `DISCORD_BOT_TOKEN`。
+4. 生成邀请 URL：
 
 ```bash
 vc bot invite <discord-client-id>
+# 或将它固定到一个服务器：
 vc bot invite <discord-client-id> --guild <guild-id>
 ```
 
-## 4. Verify
+该邀请包含 VerbalCoding 使用的 bot 和 slash-command scopes，以及文本/语音权限。
+
+## 4. 验证
 
 ```bash
 vc doctor
 ```
 
-`vc doctor` redacts secrets and reports missing commands/models/tokens without printing sensitive values. Expected success includes Node.js, npm, ffmpeg, whisper-cli, the model, Discord bot token configured, edge-tts, and the selected agent CLI.
+`vc doctor` 会脱敏输出：它报告缺失的令牌/命令/模型，但不会打印密钥值。当可修复的本地前置依赖缺失（`ffmpeg`、`whisper-cli`、默认模型或 Edge TTS 辅助环境）时，它会先自动重新运行打包的引导程序。修复剩余的 `✗` 项，然后重新运行。
+
+预期成功输出包括：
+
+```text
+✓ Node.js
+✓ npm
+✓ ffmpeg
+✓ whisper-cli
+✓ whisper.cpp model
+✓ Discord bot token configured — [REDACTED]
+✓ edge-tts
+✓ hermes CLI
+Doctor passed. Run vc start to start VerbalCoding.
+```
+
+如果安装器创建了本地 Edge TTS 辅助环境，`.env` 应包含指向 `.venv-tts/bin/edge-tts` 的 `EDGE_TTS_COMMAND` 路径。
 
-## 5. Run
+## 5. 运行单个默认机器人
 
 ```bash
 vc start
-# or, from a GitHub clone:
+# 或者，从 GitHub 克隆仓库中：
 ./run.sh
 ```
 
-Expected log lines:
+成功启动日志包括：
 
 ```text
 Logged in as <bot-name>
 Listening in voice channel <server> / <channel>
 ```
 
-In Discord:
+在 Discord 中：
 
 ```text
 !ping
@@ -87,11 +152,11 @@ In Discord:
 !verbose on
 ```
 
-Then speak in the configured voice channel. You should see STT text, progress text when verbose mode is on, a final text answer, and hear TTS playback.
+然后在已配置的语音频道中说话。你应该会看到 STT 文本、详细模式开启时的进度文本、最终文本答案，并听到 TTS 播放。
 
-## 6. Project-per-room setup
+## 6. 每个项目一个房间的设置
 
-For one permanent bot per project voice room, create one Discord application per project, then:
+如果希望每个项目语音房间都有一个长期机器人，请为每个项目创建一个 Discord 应用，然后运行：
 
 ```bash
 vc instance setup my-project
@@ -100,25 +165,43 @@ vc instance start my-project
 vc instance status my-project
 ```
 
-## 7. Optional OpenVoice setup
+每个实例都会写入一个被忽略的 `instances/<name>.env`，其中包含自己的令牌、语音频道、转写目标、日志路径、Hermes 会话文件和可选 Hermes profile。
+
+## 7. 可选 OpenVoice 设置
 
-Keep `TTS_BACKEND=edge` for a fresh install. To enable OpenVoice later:
+OpenVoice 语音克隆是可选的。全新公开安装请保留 `TTS_BACKEND=edge`。之后若要启用 OpenVoice：
 
 ```bash
 ./scripts/setup_openvoice.sh
-# Download OpenVoice V2 checkpoints into vendor/OpenVoice/checkpoints_v2/
-# Add a permitted local sample at voice-samples/user-reference.wav,
-# or run the bot, say "목소리 샘플 녹음 시작해", then speak 10-30 seconds.
+# 将 OpenVoice V2 checkpoints 下载到 vendor/OpenVoice/checkpoints_v2/
+# 在 voice-samples/user-reference.wav 放入一个获准使用的本地样本，
+# 或运行机器人，说“목소리 샘플 녹음 시작해”，然后说话 10-30 秒。
 python3 integrations/openvoice/synth.py --openvoice-dir vendor/OpenVoice --ref-audio voice-samples/user-reference.wav --text '안녕하세요. 버벌코딩 목소리 복제 테스트입니다.' --output /tmp/verbalcoding-openvoice-smoke.wav
 ```
 
-Then set `TTS_BACKEND=openvoice`, run `vc doctor`, and test `!voice-test <text>` in Discord.
+然后设置 `TTS_BACKEND=openvoice`，运行 `vc doctor`，并在 Discord 中测试 `!voice-test <text>`。
+
+## 8. 维护者的干净克隆冒烟测试
 
-## 8. Maintainer smoke tests
+快速的仅主机冒烟测试：
 
 ```bash
+TMPDIR=$(mktemp -d)
+git clone https://github.com/ca1773130n/VerbalCoding.git "$TMPDIR/VerbalCoding"
+cd "$TMPDIR/VerbalCoding"
 ./scripts/install.sh --yes --no-wizard
 npm pack --dry-run
+cp .env.example .env
+chmod 600 .env
 vc doctor || true
+```
+
+此时预期失败应是缺少本地密钥或未认证的代理 CLI，而不是令牌泄漏或安装脚本缺失。
+
+基于 Docker 的 Ubuntu 干净安装冒烟测试：
+
+```bash
 ./scripts/docker_ubuntu_smoke.sh
 ```
+
+它会运行 `ubuntu:24.04`，将已跟踪的仓库树复制到干净容器中，执行 `./scripts/install.sh --yes --no-wizard`，写入无密钥的冒烟 `.env`，检查 `vc`，运行 Node 测试，并验证 `vc doctor`。它不会连接 Discord 语音；如果需要端到端语音频道测试，请在此之后使用真实 Ubuntu VM 或 WSL2。

package/docs/i18n/MULTI_INSTANCE.es.md

@@ -1,14 +1,14 @@
-# VerbalCoding Multiinstancia
+# VerbalCoding multiinstancia
 
-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 puede ejecutar múltiples procesos independientes de puente de voz de Discord. Cada proceso sigue siendo el puente Node de instancia única existente, pero carga un archivo `instances/<name>.env` diferente y usa un token de bot de Discord diferente.
 
-Use this when each project should permanently occupy its own Discord voice channel and write to its own transcript channel/thread.
+Usa esto cuando cada proyecto deba ocupar permanentemente su propio canal de voz de Discord y escribir en su propio canal/hilo de transcripción.
 
-## Why multiple bot tokens are required
+## Por qué se requieren varios tokens de bot
 
-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.
+La residencia de voz de Discord es efectivamente una conexión de voz activa por cuenta de bot y por guild. Si un token de bot se une a otro canal de voz en la misma guild, no puede permanecer también conectado de forma permanente al canal anterior. Para salas de proyecto simultáneas, crea una aplicación/bot de Discord por proyecto.
 
-## File layout
+## Diseño de archivos
 
 ```text
 instances/
@@ -20,31 +20,46 @@ instances/
   llm-wiki.pid        # runtime only, ignored by git
 ```
 
-Real `instances/*.env` files are ignored because they may contain Discord tokens.
+Los archivos reales `instances/*.env` se ignoran porque pueden contener tokens de Discord. `instances/example.env` es la plantilla versionada.
 
-## Instance setup wizard
+## Asistente de configuración de instancia
+
+Los usuarios no deberían copiar y editar manualmente archivos env para el uso normal. Ejecuta el asistente en su lugar:
 
 ```bash
 vc instance setup llm-wiki
+# o mediante el script de configuración del proyecto:
 ./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.
+El asistente solicita el token del bot, ID de aplicación/cliente de Discord, canal de voz, destino de transcripción, workdir, contexto del proyecto y rutas de ejecución aisladas. Escribe `instances/<name>.env` con modo `0600`, hace una copia de seguridad del archivo existente antes de sobrescribirlo e imprime los siguientes comandos de inicio/estado.
 
-Generate invite URLs with:
+Si introduces el ID de aplicación/cliente de Discord durante la configuración, el resumen también imprime la URL de invitación de ese bot. Puedes generar la misma URL en cualquier momento con:
 
 ```bash
 vc bot invite <client-id>
 vc bot invite <client-id> --guild <guild-id>
 ```
 
-## Hermes profile isolation
+Discord sigue requiriendo una aplicación/bot del Developer Portal por sala de voz simultánea, pero esto evita construir manualmente URLs OAuth o enteros de permisos.
+
+### Aislamiento de perfiles de Hermes
+
+Cada instancia obtiene su propio home de Hermes en `~/.hermes/profiles/<name>` para que memoria, MEMORY.md, SOUL.md y skills aprendidas no se filtren entre proyectos.
+
+`vc instance setup <name>` automáticamente:
 
-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.
+- ejecuta `hermes profile create <name> --clone-from default` (traslada claves API
+  y modelo desde tu `~/.hermes` actual; las sesiones y memoria empiezan limpias),
+- define el `terminal.cwd` del nuevo perfil al workdir de la instancia,
+- inicializa `<profile>/SOUL.md` desde la respuesta de contexto de proyecto del asistente,
+- escribe `HERMES_HOME=...` en `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>` se autorepara: si el env apunta a un directorio de perfil de Hermes que ya no existe, el comando de inicio lo recrea antes de lanzar.
 
-## Minimal generated instance env
+Los nombres de instancia deben coincidir con `^[a-z0-9][a-z0-9_-]{0,63}$` porque Hermes usa el nombre como directorio y clave de configuración.
+
+## Env mínimo generado para una instancia
 
 ```env
 INSTANCE_NAME=my-project
@@ -62,9 +77,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.
+Da a cada instancia valores únicos para archivos de registro/depuración/sesión. `HERMES_HOME` y el directorio correspondiente `~/.hermes/profiles/<name>` se crean automáticamente con `vc instance setup`. `vc doctor` comprueba tokens duplicados, rutas de ejecución en conflicto, directorios de perfil faltantes y discrepancias de `terminal.cwd` entre perfil e instancia, todo sin imprimir secretos.
 
-## Commands
+## Comandos
 
 ```bash
 vc instance list
@@ -75,47 +90,91 @@ vc instance stop my-project
 vc instance restart my-project
 ```
 
-## Example: two permanent voice rooms
+`start` ejecuta `./run.sh instances/<name>.env` desacoplado y escribe `.run/instances/<name>.pid`.
+
+`stop` envía `SIGTERM`, espera hasta 10 segundos, luego recurre a `SIGKILL` y elimina el archivo pid.
+
+## Ejemplo: dos salas de voz permanentes
 
-1. Create two Discord applications/bots.
-2. Invite both with text and voice permissions. Use `vc bot invite <client-id>`.
-3. Run setup:
+1. Crea dos aplicaciones/bots de Discord:
+   - Bot VerbalCoding
+   - Bot LLM-Wiki
+
+2. Invita ambos al servidor con permisos de texto y voz:
+   - Ver canal
+   - Enviar mensajes
+   - Enviar mensajes en hilos
+   - Leer historial de mensajes
+   - Usar comandos de aplicación
+   - Conectar
+   - Hablar
+
+   Usa `vc bot invite <client-id>` después de crear cada aplicación de Discord para imprimir la URL de invitación exacta con esos permisos.
+
+3. Ejecuta el asistente de configuración para cada instancia local:
 
 ```bash
 vc instance setup verbalcoding
 vc instance setup llm-wiki
 ```
 
-4. Check and start:
+El asistente escribe los archivos ignorados `instances/verbalcoding.env` e `instances/llm-wiki.env` con modo `0600`; también hace copia de seguridad de un env de instancia existente antes de reemplazarlo. Cada ejecución también crea `~/.hermes/profiles/<name>` clonado desde tu home de Hermes predeterminado, de modo que las dos instancias empiezan con la misma autenticación/modelo, pero acumulan memoria y skills independientes a medida que aprenden cada proyecto.
+
+4. Comprueba la configuración:
 
 ```bash
 vc doctor
+```
+
+5. Inicia ambos:
+
+```bash
 vc instance start verbalcoding
 vc instance start llm-wiki
 vc instance status
 ```
 
-5. Verify logs:
+6. Verifica los registros:
 
 ```bash
 tail -n 50 /tmp/verbalcoding-verbalcoding.log
 tail -n 50 /tmp/verbalcoding-llm-wiki.log
 ```
 
-Expected:
+Líneas de registro esperadas:
 
 ```text
 Listening in voice channel ... / VerbalCoding
 Listening in voice channel ... / LLM-Wiki
 ```
 
-## Short-term single-bot text/voice binding
+7. Detén ambos:
+
+```bash
+vc instance stop verbalcoding
+vc instance stop llm-wiki
+```
+
+## Vinculación de texto/voz de corto plazo con un solo bot
+
+Si solo tienes un token de bot, usa vinculación de voz de sesión de proyecto en lugar de residencia multicanal simultánea.
 
-If you only have one bot token, bind a project session to a voice channel instead of simultaneous residency:
+Ejecuta esto en el canal/hilo de texto objetivo:
 
 ```text
 !session attach-voice --voice "LLM-Wiki"
+```
+
+Comportamiento:
+
+- Vincula el canal de voz seleccionado al canal/hilo de texto actual.
+- Si el canal de texto actual no tiene sesión de proyecto, crea una sesión aislada ad hoc.
+- El texto de STT/resultado/progreso/respuesta final de voz se enruta al destino de transcripción de ese proyecto activo.
+
+Para adjuntar una sesión de proyecto nombrada existente:
+
+```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.
+Esto es conveniente para el enrutamiento, pero no hace que un bot permanezca en dos canales de voz al mismo tiempo. Usa varios tokens/procesos de bot para residencia permanente simultánea.

package/docs/i18n/MULTI_INSTANCE.fr.md

@@ -1,14 +1,14 @@
-# VerbalCoding Multi-instance
+# VerbalCoding multi-instance
 
-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 peut exécuter plusieurs processus indépendants de passerelle vocale Discord. Chaque processus reste la passerelle Node à instance unique existante, mais il charge un fichier `instances/<name>.env` différent et utilise un jeton de bot Discord différent.
 
-Use this when each project should permanently occupy its own Discord voice channel and write to its own transcript channel/thread.
+Utilisez ceci quand chaque projet doit occuper de façon permanente son propre salon vocal Discord et écrire dans son propre salon/fil de transcription.
 
-## Why multiple bot tokens are required
+## Pourquoi plusieurs jetons de bot sont nécessaires
 
-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.
+La résidence vocale Discord correspond en pratique à une connexion vocale active par compte bot et par guilde. Si un jeton de bot rejoint un autre salon vocal dans la même guilde, il ne peut pas aussi rester connecté en permanence au salon précédent. Pour des salons de projet simultanés, créez une application/un bot Discord par projet.
 
-## File layout
+## Organisation des fichiers
 
 ```text
 instances/
@@ -20,31 +20,46 @@ instances/
   llm-wiki.pid        # runtime only, ignored by git
 ```
 
-Real `instances/*.env` files are ignored because they may contain Discord tokens.
+Les vrais fichiers `instances/*.env` sont ignorés car ils peuvent contenir des jetons Discord. `instances/example.env` est le modèle commité.
 
-## Instance setup wizard
+## Assistant de configuration d'instance
+
+Les utilisateurs ne doivent pas copier et modifier manuellement les fichiers env pour un usage normal. Lancez plutôt l'assistant :
 
 ```bash
 vc instance setup llm-wiki
+# or through the project setup script:
 ./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.
+L'assistant demande le jeton du bot, l'ID Application/Client Discord, le salon vocal, la cible de transcription, le workdir, le contexte de projet et les chemins d'exécution isolés. Il écrit `instances/<name>.env` avec le mode `0600`, sauvegarde un fichier existant avant de l'écraser et imprime les prochaines commandes de démarrage/statut.
 
-Generate invite URLs with:
+Si vous saisissez l'ID Application/Client Discord pendant la configuration, le résumé imprime aussi l'URL d'invitation de ce bot. Vous pouvez générer la même URL à tout moment avec :
 
 ```bash
 vc bot invite <client-id>
 vc bot invite <client-id> --guild <guild-id>
 ```
 
-## Hermes profile isolation
+Discord exige toujours une application/un bot Developer Portal par salon vocal simultané, mais cela évite de construire manuellement des URL OAuth ou des entiers de permissions.
+
+### Isolation des profils Hermes
+
+Chaque instance reçoit son propre dossier Hermes à `~/.hermes/profiles/<name>` afin que la mémoire, MEMORY.md, SOUL.md et les skills appris ne fuient pas entre projets.
+
+`vc instance setup <name>` automatiquement :
 
-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.
+- exécute `hermes profile create <name> --clone-from default` (reprend les clés API
+  et le modèle de votre `~/.hermes` actuel ; les sessions et la mémoire repartent de zéro),
+- définit le `terminal.cwd` du nouveau profil sur le workdir de l'instance,
+- initialise `<profile>/SOUL.md` depuis la réponse de contexte de projet de l'assistant,
+- écrit `HERMES_HOME=...` dans `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>` s'auto-répare : si l'env pointe vers un répertoire de profil Hermes qui n'existe plus, la commande start le recrée avant le lancement.
 
-## Minimal generated instance env
+Les noms d'instance doivent correspondre à `^[a-z0-9][a-z0-9_-]{0,63}$`, car Hermes utilise le nom comme répertoire et clé de configuration.
+
+## Env minimal généré pour une instance
 
 ```env
 INSTANCE_NAME=my-project
@@ -62,9 +77,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.
+Donnez à chaque instance des valeurs uniques pour les fichiers de journal/debug/session. `HERMES_HOME` et le répertoire correspondant `~/.hermes/profiles/<name>` sont créés automatiquement par `vc instance setup`. `vc doctor` vérifie les jetons dupliqués, les chemins d'exécution en collision, les répertoires de profil manquants et les divergences de `terminal.cwd` entre profil et instance — le tout sans imprimer de secrets.
 
-## Commands
+## Commandes
 
 ```bash
 vc instance list
@@ -75,47 +90,91 @@ vc instance stop my-project
 vc instance restart my-project
 ```
 
-## Example: two permanent voice rooms
+`start` exécute `./run.sh instances/<name>.env` en mode détaché et écrit `.run/instances/<name>.pid`.
+
+`stop` envoie `SIGTERM`, attend jusqu'à 10 secondes, puis bascule vers `SIGKILL` et supprime le fichier pid.
+
+## Exemple : deux salons vocaux permanents
 
-1. Create two Discord applications/bots.
-2. Invite both with text and voice permissions. Use `vc bot invite <client-id>`.
-3. Run setup:
+1. Créez deux applications/bots Discord :
+   - bot VerbalCoding
+   - bot LLM-Wiki
+
+2. Invitez les deux sur le serveur avec permissions texte et voix :
+   - Voir le salon
+   - Envoyer des messages
+   - Envoyer des messages dans les fils
+   - Lire l'historique des messages
+   - Utiliser les commandes d'application
+   - Se connecter
+   - Parler
+
+   Utilisez `vc bot invite <client-id>` après avoir créé chaque application Discord pour imprimer l'URL d'invitation exacte avec ces permissions.
+
+3. Lancez l'assistant de configuration pour chaque instance locale :
 
 ```bash
 vc instance setup verbalcoding
 vc instance setup llm-wiki
 ```
 
-4. Check and start:
+L'assistant écrit les fichiers ignorés `instances/verbalcoding.env` et `instances/llm-wiki.env` avec le mode `0600` ; il sauvegarde aussi l'env d'une instance existante avant de le remplacer. Chaque exécution crée également `~/.hermes/profiles/<name>` cloné depuis votre dossier Hermes par défaut, afin que les deux instances démarrent avec la même auth/le même modèle mais accumulent mémoire et skills indépendants à mesure qu'elles apprennent chaque projet.
+
+4. Vérifiez la configuration :
 
 ```bash
 vc doctor
+```
+
+5. Démarrez les deux :
+
+```bash
 vc instance start verbalcoding
 vc instance start llm-wiki
 vc instance status
 ```
 
-5. Verify logs:
+6. Vérifiez les journaux :
 
 ```bash
 tail -n 50 /tmp/verbalcoding-verbalcoding.log
 tail -n 50 /tmp/verbalcoding-llm-wiki.log
 ```
 
-Expected:
+Lignes de journal attendues :
 
 ```text
 Listening in voice channel ... / VerbalCoding
 Listening in voice channel ... / LLM-Wiki
 ```
 
-## Short-term single-bot text/voice binding
+7. Arrêtez les deux :
+
+```bash
+vc instance stop verbalcoding
+vc instance stop llm-wiki
+```
+
+## Liaison texte/voix de courte durée avec un seul bot
+
+Si vous n'avez qu'un seul jeton de bot, utilisez plutôt la liaison vocale de session de projet au lieu d'une résidence multi-salons simultanée.
 
-If you only have one bot token, bind a project session to a voice channel instead of simultaneous residency:
+Exécutez ceci dans le salon/fil texte cible :
 
 ```text
 !session attach-voice --voice "LLM-Wiki"
+```
+
+Comportement :
+
+- Lie le salon vocal sélectionné au salon/fil texte actuel.
+- Si le salon texte actuel n'a pas de session de projet, crée une session isolée ad hoc.
+- Le texte STT/résultat/progression/réponse finale de la voix est routé vers cette cible de transcription de projet active.
+
+Pour attacher une session de projet nommée existante :
+
+```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.
+C'est pratique pour le routage, mais cela ne fait pas rester un même bot dans deux salons vocaux en même temps. Utilisez plusieurs jetons/processus de bots pour une résidence permanente simultanée.