verbalcoding 0.2.6 → 0.2.7

package/docs/i18n/MULTI_INSTANCE.ko.md

@@ -1,64 +1,50 @@
 # VerbalCoding 멀티 인스턴스
 
-VerbalCoding은 여러 개의 독립적인 Discord 음성 브릿지 프로세스를 실행할 수 있습니다. 각 프로세스는 같은 단일 인스턴스 Node 브릿지를 사용하지만, 서로 다른 `instances/<name>.env` 파일과 서로 다른 Discord bot token을 로드합니다.
+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.
 
-프로젝트마다 자기 Discord 음성 채널에 항상 붙어 있고, 자기 transcript 채널/스레드에 기록해야 할 때 사용하세요.
+Use this when each project should permanently occupy its own Discord voice channel and write to its own transcript channel/thread.
 
-## 왜 여러 봇 토큰이 필요한가
+## Why multiple bot tokens are required
 
-Discord 음성 상주 방식은 사실상 길드마다 봇 계정 하나가 동시에 하나의 음성 연결만 유지하는 구조입니다. 같은 봇 토큰이 같은 길드의 다른 음성 채널에 들어가면 이전 채널에도 계속 남아 있을 수 없습니다. 동시에 여러 프로젝트 방을 유지하려면 프로젝트마다 Discord 애플리케이션/봇을 하나씩 만들어야 합니다.
+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.
 
-## 파일 구조
+## File layout
 
 ```text
 instances/
   README.md
   example.env
-  llm-wiki.env        # 로컬 전용, git에서 무시
-  verbalcoding.env    # 로컬 전용, git에서 무시
+  llm-wiki.env        # local only, ignored by git
+  verbalcoding.env    # local only, ignored by git
 .run/instances/
-  llm-wiki.pid        # 런타임 전용, git에서 무시
+  llm-wiki.pid        # runtime only, ignored by git
 ```
 
-실제 `instances/*.env` 파일에는 Discord 토큰이 들어갈 수 있으므로 git에서 무시됩니다. `instances/example.env`만 템플릿으로 커밋됩니다.
+Real `instances/*.env` files are ignored because they may contain Discord tokens.
 
-## 인스턴스 설정 마법사
-
-일반 사용자는 env 파일을 복사해서 직접 편집하지 않는 편이 좋습니다. 마법사를 실행하세요.
+## Instance setup wizard
 
 ```bash
 vc instance setup llm-wiki
-# 또는 프로젝트 설정 스크립트에서:
 ./scripts/install.sh --instance llm-wiki
 ```
 
-마법사는 봇 토큰, Discord Application/Client ID, 음성 채널, transcript 대상, 작업 디렉터리, 프로젝트 컨텍스트, 격리된 런타임 경로를 묻습니다. `instances/<name>.env`를 권한 `0600`으로 작성하고, 기존 파일이 있으면 덮어쓰기 전에 백업하며, 다음 start/status 명령을 출력합니다.
+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를 입력하면 요약에 해당 봇 초대 URL도 출력됩니다. 같은 URL은 언제든지 다시 만들 수 있습니다.
+Generate invite URLs with:
 
 ```bash
 vc bot invite <client-id>
 vc bot invite <client-id> --guild <guild-id>
 ```
 
-Discord는 동시에 여러 음성방에 상주하려면 여전히 방마다 Developer Portal 애플리케이션/봇 하나가 필요합니다. 대신 VerbalCoding이 OAuth URL이나 permission integer를 직접 조립할 필요를 없애 줍니다.
-
-### Hermes 프로필 격리
-
-각 인스턴스는 `~/.hermes/profiles/<name>` 아래에 자기 Hermes home을 갖습니다. 이렇게 하면 memory, MEMORY.md, SOUL.md, 학습된 skills가 프로젝트 사이에 섞이지 않습니다.
-
-`vc instance setup <name>`은 자동으로 다음을 수행합니다.
+## Hermes profile isolation
 
-- `hermes profile create <name> --clone-from default` 실행: 현재 `~/.hermes`의 API key와 모델 설정은 가져오지만, 세션과 메모리는 새로 시작합니다.
-- 새 프로필의 `terminal.cwd`를 인스턴스 작업 디렉터리로 설정합니다.
-- 마법사에서 입력한 project context로 `<profile>/SOUL.md`를 초기화합니다.
-- `instances/<name>.env`에 `HERMES_HOME=...`을 씁니다.
+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.
 
-`vc instance start <name>`은 self-heal을 수행합니다. env가 가리키는 Hermes profile directory가 사라졌다면 시작 전에 다시 만듭니다.
+`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}$`.
 
-인스턴스 이름은 Hermes가 디렉터리와 config key로 쓰기 때문에 `^[a-z0-9][a-z0-9_-]{0,63}$` 형식이어야 합니다.
-
-## 생성되는 최소 인스턴스 env 예시
+## Minimal generated instance env
 
 ```env
 INSTANCE_NAME=my-project
@@ -76,9 +62,9 @@ AGENT_CWD=/path/to/my-project
 AGENT_PROJECT_CONTEXT=Project session: My Project
 ```
 
-모든 인스턴스는 log/debug/session 파일 경로가 고유해야 합니다. `HERMES_HOME`과 대응하는 `~/.hermes/profiles/<name>` 디렉터리는 `vc instance setup`이 자동 생성합니다. `vc doctor`는 비밀값을 출력하지 않고 중복 토큰, 충돌하는 런타임 경로, 누락된 profile directory, profile과 instance의 `terminal.cwd` 불일치를 검사합니다.
+`vc doctor` checks duplicate tokens, colliding runtime paths, missing profile directories, and `terminal.cwd` mismatches without printing secrets.
 
-## 명령
+## Commands
 
 ```bash
 vc instance list
@@ -89,91 +75,47 @@ vc instance stop my-project
 vc instance restart my-project
 ```
 
-`start`는 `./run.sh instances/<name>.env`를 detached로 실행하고 `.run/instances/<name>.pid`를 씁니다.
-
-`stop`은 `SIGTERM`을 보내고 최대 10초 기다린 뒤, 필요하면 `SIGKILL`로 fallback하고 pid 파일을 제거합니다.
-
-## 예시: 영구 음성방 두 개
+## Example: two permanent voice rooms
 
-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. 각 로컬 인스턴스 설정 마법사를 실행합니다.
+1. Create two Discord applications/bots.
+2. Invite both with text and voice permissions. Use `vc bot invite <client-id>`.
+3. Run setup:
 
 ```bash
 vc instance setup verbalcoding
 vc instance setup llm-wiki
 ```
 
-마법사는 git에서 무시되는 `instances/verbalcoding.env`, `instances/llm-wiki.env`를 권한 `0600`으로 작성하고, 기존 env가 있으면 백업합니다. 각 실행은 기본 Hermes home에서 clone한 `~/.hermes/profiles/<name>`도 생성하므로 두 인스턴스는 같은 인증/모델 설정으로 시작하지만, 프로젝트를 학습하면서 서로 독립적인 memory와 skills를 쌓습니다.
-
-4. 설정을 확인합니다.
+4. Check and start:
 
 ```bash
 vc doctor
-```
-
-5. 둘 다 시작합니다.
-
-```bash
 vc instance start verbalcoding
 vc instance start llm-wiki
 vc instance status
 ```
 
-6. 로그를 확인합니다.
+5. Verify logs:
 
 ```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
 ```
 
-7. 둘 다 중지합니다.
-
-```bash
-vc instance stop verbalcoding
-vc instance stop llm-wiki
-```
-
-## 단기: 단일 봇 텍스트/음성 바인딩
-
-봇 토큰이 하나뿐이라면 동시 다중 채널 상주 대신 project-session voice binding을 쓰세요.
+## Short-term single-bot text/voice binding
 
-대상 텍스트 채널/스레드에서:
+If you only have one bot token, bind a project session to a voice channel instead of simultaneous residency:
 
 ```text
 !session attach-voice --voice "LLM-Wiki"
-```
-
-동작:
-
-- 선택된 음성 채널을 현재 텍스트 채널/스레드에 연결합니다.
-- 현재 텍스트 채널에 project session이 없으면 ad-hoc 격리 세션을 만듭니다.
-- 음성 STT/result/progress/final-answer 텍스트가 해당 project transcript 대상으로 라우팅됩니다.
-
-기존 named project session을 연결하려면:
-
-```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/MULTI_INSTANCE.ru.md

@@ -0,0 +1,121 @@
+# 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.
+
+Use this when each project should permanently occupy its own Discord voice channel and write to its own transcript channel/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.
+
+## File layout
+
+```text
+instances/
+  README.md
+  example.env
+  llm-wiki.env        # local only, ignored by git
+  verbalcoding.env    # local only, ignored by git
+.run/instances/
+  llm-wiki.pid        # runtime only, ignored by git
+```
+
+Real `instances/*.env` files are ignored because they may contain Discord tokens.
+
+## Instance setup wizard
+
+```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.
+
+Generate invite URLs with:
+
+```bash
+vc bot invite <client-id>
+vc bot invite <client-id> --guild <guild-id>
+```
+
+## Hermes profile isolation
+
+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.
+
+`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}$`.
+
+## Minimal generated instance 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
+```
+
+`vc doctor` checks duplicate tokens, colliding runtime paths, missing profile directories, and `terminal.cwd` mismatches without printing secrets.
+
+## Commands
+
+```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
+```
+
+## Example: two permanent voice rooms
+
+1. Create two Discord applications/bots.
+2. Invite both with text and voice permissions. Use `vc bot invite <client-id>`.
+3. Run setup:
+
+```bash
+vc instance setup verbalcoding
+vc instance setup llm-wiki
+```
+
+4. Check and start:
+
+```bash
+vc doctor
+vc instance start verbalcoding
+vc instance start llm-wiki
+vc instance status
+```
+
+5. Verify logs:
+
+```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
+
+If you only have one bot token, bind a project session to a voice channel instead of simultaneous residency:
+
+```text
+!session attach-voice --voice "LLM-Wiki"
+!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/MULTI_INSTANCE.zh.md

@@ -0,0 +1,121 @@
+# 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.
+
+Use this when each project should permanently occupy its own Discord voice channel and write to its own transcript channel/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.
+
+## File layout
+
+```text
+instances/
+  README.md
+  example.env
+  llm-wiki.env        # local only, ignored by git
+  verbalcoding.env    # local only, ignored by git
+.run/instances/
+  llm-wiki.pid        # runtime only, ignored by git
+```
+
+Real `instances/*.env` files are ignored because they may contain Discord tokens.
+
+## Instance setup wizard
+
+```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.
+
+Generate invite URLs with:
+
+```bash
+vc bot invite <client-id>
+vc bot invite <client-id> --guild <guild-id>
+```
+
+## Hermes profile isolation
+
+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.
+
+`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}$`.
+
+## Minimal generated instance 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
+```
+
+`vc doctor` checks duplicate tokens, colliding runtime paths, missing profile directories, and `terminal.cwd` mismatches without printing secrets.
+
+## Commands
+
+```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
+```
+
+## Example: two permanent voice rooms
+
+1. Create two Discord applications/bots.
+2. Invite both with text and voice permissions. Use `vc bot invite <client-id>`.
+3. Run setup:
+
+```bash
+vc instance setup verbalcoding
+vc instance setup llm-wiki
+```
+
+4. Check and start:
+
+```bash
+vc doctor
+vc instance start verbalcoding
+vc instance start llm-wiki
+vc instance status
+```
+
+5. Verify logs:
+
+```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
+
+If you only have one bot token, bind a project session to a voice channel instead of simultaneous residency:
+
+```text
+!session attach-voice --voice "LLM-Wiki"
+!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,91 +1,66 @@
 # VerbalCoding
 
-<p align="center">
-  <strong>Habla con tus agentes de programación CLI por voz en Discord, como en una llamada.</strong>
-</p>
-
-<p align="center">
-  <a href="../../README.md">English</a> ·
-  <a href="README.ko.md">한국어</a> ·
-  <a href="README.ja.md">日本語</a> ·
-  <a href="README.zh.md">中文</a> ·
-  <a href="README.es.md">Español</a> ·
-  <a href="README.fr.md">Français</a> ·
-  <a href="README.ru.md">Русский</a>
-</p>
-
-<p align="center">
-  <img alt="Node.js" src="https://img.shields.io/badge/Node.js-20%2B-339933?logo=node.js&logoColor=white">
-  <img alt="Discord" src="https://img.shields.io/badge/Discord-voice%20bridge-5865F2?logo=discord&logoColor=white">
-  <img alt="STT" src="https://img.shields.io/badge/STT-whisper.cpp-7C3AED">
-  <img alt="TTS" src="https://img.shields.io/badge/TTS-Edge%20%7C%20OpenVoice%20%7C%20Supertonic%20%7C%20SpeechSwift-0EA5E9">
-</p>
-
-<p align="center">
-  <img src="../assets/figures/verbalcoding-flow.svg" alt="VerbalCoding voice-to-agent flow" width="860">
-</p>
+**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 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. Dictas una solicitud, el agente CLI trabaja y recibes una respuesta breve por voz junto con transcripciones y eventos de progreso.
 
-## Puntos clave
+## Highlights
 
-| Qué ofrece | Por qué importa |
+| Feature | What it means |
 |---|---|
-| 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. |
+| 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. |
 
-## Inicio rápido
+## Quick Start
 
 ```bash
-git clone git@github.com:ca1773130n/VerbalCoding.git
-cd VerbalCoding
-./scripts/install.sh
+npm install -g verbalcoding
+vc setup --yes
 vc doctor
-./run.sh
+vc start
 ```
 
-## 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"]
+Run without a permanent global install:
+
+```bash
+npx verbalcoding setup --yes
+vc doctor
+vc start
 ```
 
-## Backends de agentes compatibles
+Contributor clone path:
+
+```bash
+git clone https://github.com/ca1773130n/VerbalCoding.git
+cd VerbalCoding
+./scripts/install.sh --yes
+vc doctor
+./run.sh
+```
 
-| Backend | Default command | Session support |
-|---|---:|---|
-| Hermes Agent | `hermes chat -Q -q` | Resume, verbose progress, cancellation, final-answer recovery |
-| Claude Code | `claude -p` | CLI session file support through adapter defaults |
-| Codex CLI | `codex exec` | CLI session file support through adapter defaults |
-| Gemini CLI | `gemini -p` | CLI session file support through adapter defaults |
-| OpenCode | `opencode run` | CLI session file support through adapter defaults |
-| OpenClaw | `openclaw run` | CLI session file support through adapter defaults |
-| Custom | `AGENT_COMMAND` | Bring your own non-interactive command |
+`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.
 
-## Aprende más
+## Guides
 
-| Guide | What you get |
+| Guide | Link |
 |---|---|
-| [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](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) |
 
-## Mapa rápido de comandos
+## Command map
 
 ```bash
 vc status
@@ -94,28 +69,17 @@ vc bot invite CLIENT_ID
 vc instance setup NAME
 vc instance start NAME
 vc doctor
+vc start
 ```
 
-## Requisitos
+Discord commands:
 
-| Layer | Default |
-|---|---|
-| Runtime | Node.js 20+, npm |
-| Audio | `ffmpeg` |
-| STT | `whisper.cpp` / `whisper-cli` |
-| Discord | Bot token, Message Content intent, voice permissions |
-| Agent | At least one authenticated CLI harness, Hermes Agent by default |
-| Platform focus | macOS / Apple Silicon currently gets the most testing |
-
-## Contribuir
-
-```bash
-node --check app-node/main.mjs
-npm test
-bash -n run.sh scripts/install.sh
-vc doctor
+```text
+!join        !ask <prompt>       !verbose on/off
+!latency     !sensitivity normal !sensitivity conservative
+!session new <name> <workdir> [context] --voice <voice-channel>
 ```
 
-## Estado
+## Requirements
 
-VerbalCoding is public-release oriented but still early. Demo video/GIF, broader Linux notes, and a formal license file are still TODOs.
+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.