verbalcoding 0.2.11 → 0.2.12

package/docs/i18n/README.ko.md

@@ -1,148 +1,35 @@
-# VerbalCoding
+# VerbalCoding 문서
 
-<p align="center">
-  <strong>Discord 음성으로 CLI 코딩 에이전트와 대화하세요 — 소프트웨어 작업을 위한 전화 통화처럼.</strong>
-</p>
+<p align="center"><a href="../../README.md">English README</a> · <a href="../../README.ko.md">한국어</a> · <a href="../../README.ja.md">日本語</a> · <a href="../../README.zh.md">中文</a> · <a href="../../README.es.md">Español</a> · <a href="../../README.fr.md">Français</a> · <a href="../../README.ru.md">Русский</a></p>
 
-<p align="center">
-  <a href="../../README.md">English</a> ·
-  <a href="README.ja.md">日本語</a> ·
-  <a href="README.zh.md">中文</a> ·
-  <a href="README.es.md">Español</a> ·
-  <a href="README.fr.md">Français</a> ·
-  <a href="README.ru.md">Русский</a>
-</p>
+README는 간결한 첫 화면이고, 이 페이지는 상세 가이드 색인입니다. 실제 Discord 음성 bot을 처음 설정한다면 Fresh Install부터 시작하세요.
 
-<p align="center">
-  <img alt="Node.js" src="https://img.shields.io/badge/Node.js-20%2B-339933?logo=node.js&logoColor=white">
-  <img alt="Discord" src="https://img.shields.io/badge/Discord-voice%20bridge-5865F2?logo=discord&logoColor=white">
-  <img alt="STT" src="https://img.shields.io/badge/STT-whisper.cpp-7C3AED">
-  <img alt="TTS" src="https://img.shields.io/badge/TTS-Edge%20%7C%20OpenVoice%20%7C%20Supertonic%20%7C%20SpeechSwift-0EA5E9">
-  <img alt="Agents" src="https://img.shields.io/badge/Agents-Hermes%20%7C%20Claude%20%7C%20Codex%20%7C%20Gemini%20%7C%20OpenCode-111827">
-</p>
-
-<p align="center">
-  <img src="../assets/figures/verbalcoding-flow.svg" alt="VerbalCoding 음성-에이전트 흐름" width="860">
-</p>
-
-## 왜 필요한가
-
-VerbalCoding은 Discord 음성 채널을 코딩 에이전트를 위한 핸즈프리 제어면으로 바꿉니다. 요청을 말하고, CLI 에이전트가 작업하게 둔 뒤, 간결한 답변을 음성으로 들을 수 있습니다 — 텍스트 기록, 진행 이벤트, 시끄러운 코드/로그 출력에 대한 안전장치도 함께 제공합니다.
-
-## 주요 기능
-
-| 제공되는 것 | 좋은 이유 |
-|---|---|
-| 음성 우선 에이전트 제어 | Hermes Agent, Claude Code, Codex, Gemini CLI, OpenCode, OpenClaw 또는 임의의 커스텀 CLI 하네스와 말로 대화합니다. |
-| 온디바이스 음성 루프 | Discord 음성 캡처 → 로컬 `whisper-cli` 전사 → 에이전트 → 분할 TTS 재생. |
-| 공유 음성 + 텍스트 컨텍스트 | 음성 턴과 `!ask` 텍스트 명령이 지원되는 동일 에이전트 세션을 재사용할 수 있습니다. |
-| 끼어들기 및 감도 모드 | 재생 중 자연스럽게 끼어들고 일반/보수적(시끄러운 환경) 모드를 전환합니다. |
-| 다국어 음성 프리셋 | `vc language ko/en/auto`로 STT, 진행 언어, TTS 음성을 함께 전환합니다. |
-| 여러 방의 프로젝트 격리 | 프로젝트 방마다 하나의 봇을 실행하고 Hermes 프로필, 세션, 메모리, 로그를 분리합니다. |
-
-## 빠른 시작
-
-npm으로 가장 빠르게 시작하는 방법:
+## 빠른 경로
 
 ```bash
-npm install -g verbalcoding
-vc setup --yes
+npm install -g verbalcoding@latest
+vc setup
 vc doctor
 vc start
 ```
 
-영구 전역 설치 없이 바로 실행하려면:
-
-```bash
-npx verbalcoding setup --yes
-vc doctor
-vc start
-```
-
-기여자를 위한 GitHub 클론 경로:
-
-```bash
-git clone https://github.com/ca1773130n/VerbalCoding.git
-cd VerbalCoding
-./scripts/install.sh --yes
-vc doctor
-./run.sh
-```
-
-`vc setup --yes`는 npm 패키지 안에 포함된 설치 스크립트로 로컬 필수 구성요소를 부트스트랩합니다. `./scripts/install.sh --yes`는 GitHub 클론 안에서 같은 작업을 수행합니다. 둘 다 가능한 경우 Node/npm 의존성, `ffmpeg`, `whisper-cli`, 기본 whisper.cpp 모델, 로컬 `.venv-tts` Edge TTS 헬퍼, 설정 마법사를 처리합니다. macOS/Homebrew와 일반적인 Linux 패키지 관리자(`apt`, `dnf`, `pacman`)를 지원합니다. 의존성만 설정하려면 `--no-wizard`로 다시 실행하고, OS 패키지를 직접 설치하려면 `--skip-system`을 사용하세요.
+## 가이드
 
-깨끗한 설치 안내가 필요하다면 [Fresh Install](FRESH_INSTALL.ko.md)부터 시작하세요.
-
-## 지원되는 에이전트 백엔드
-
-| 백엔드 | 기본 명령 | 세션 지원 |
-|---|---:|---|
-| Hermes Agent | `hermes chat -Q -q` | 이어받기, 자세한 진행, 취소, 최종 답변 복구 |
-| Claude Code | `claude -p` | 어댑터 기본값을 통한 CLI 세션 파일 지원 |
-| Codex CLI | `codex exec` | 어댑터 기본값을 통한 CLI 세션 파일 지원 |
-| Gemini CLI | `gemini -p` | 어댑터 기본값을 통한 CLI 세션 파일 지원 |
-| OpenCode | `opencode run` | 어댑터 기본값을 통한 CLI 세션 파일 지원 |
-| OpenClaw | `openclaw run` | 어댑터 기본값을 통한 CLI 세션 파일 지원 |
-| Custom | `AGENT_COMMAND` | 직접 만든 비대화형 명령 사용 |
-
-## 더 알아보기
-
-| 가이드 | 제공 내용 |
-|---|---|
-| [Fresh Install](FRESH_INSTALL.ko.md) | 깨끗한 클론 설정, 모델 다운로드, 첫 실행 |
-| [Usage Guide](USAGE.ko.md) | CLI 명령, Discord 명령, 진행 모드, 지연 시간 지표 |
-| [Configuration](CONFIGURATION.ko.md) | `.env`, 에이전트 백엔드, MCP, TTS 백엔드, 운영 참고 사항 |
-| [Multi-Instance](MULTI_INSTANCE.ko.md) | 프로젝트마다 하나의 영구 Discord 음성 방 |
-| [Release Notes](RELEASE.ko.md) | 현재 기능과 사전 릴리스 체크리스트 |
-
-## 작은 명령 지도
-
-```bash
-vc status                 # 현재 언어, TTS, 브리지 설정
-vc language ko|en|auto    # STT/진행/TTS 언어 프리셋 전환
-vc bot invite CLIENT_ID   # Discord 봇 초대 URL 생성
-vc instance setup NAME    # 격리된 프로젝트 음성 봇 생성
-vc instance start NAME    # 해당 봇을 백그라운드에서 실행
-vc doctor                 # 민감 정보가 제거된 상태 점검
-vc start                  # 기본 브리지 시작
-```
-
-Discord에서:
-
-| 명령 | 하는 일 |
-|---|---|
-| `!join` | 현재 음성 채널에 참가합니다. |
-| `!ask <prompt>` | 동일 에이전트 백엔드로 텍스트를 보냅니다. |
-| `!verbose on\|off` | 짧은 진행 업데이트를 표시/낭독합니다. |
-| `!latency` | 최근 음성/STT/에이전트/TTS 지연 시간을 요약합니다. |
-| `!sensitivity normal` | 일반 실내 끼어들기 감도를 사용합니다. |
-| `!sensitivity conservative` | 더 엄격한 시끄러운/실외 감도를 사용합니다. |
-| `!session new <name> <workdir> [context] --voice <voice-channel>` | 프로젝트 세션을 음성 방에 연결합니다. |
-
-## 요구 사항
-
-| 계층 | 기본값 |
+| 가이드 | 필요할 때 |
 |---|---|
-| 런타임 | Node.js 20+, npm; 설치 스크립트가 Homebrew/apt/dnf/pacman으로 설치 가능 |
-| 오디오 | `ffmpeg`; 설치 스크립트가 설치 가능 |
-| 음성 인식 | whisper.cpp의 로컬 `whisper-cli`; 설치 스크립트는 macOS에서 Homebrew를 사용하거나 Linux에서 로컬 빌드 폴백 사용 |
-| TTS | Edge TTS CLI; 필요한 경우 설치 스크립트가 `.venv-tts` 생성 |
-| Discord | 봇 토큰, Message Content intent, 음성 권한 |
-| 에이전트 | 인증된 CLI 하네스 하나 이상, 기본값은 Hermes Agent |
-| 중점 플랫폼 | macOS / Apple Silicon에서 가장 많이 테스트됨; Linux 부트스트랩은 최선 노력으로 문서화됨 |
+| [Fresh Install](FRESH_INSTALL.ko.md) | 깨끗한 npm/global install, Discord app setup, 첫 bot invite, 첫 voice run. |
+| [Usage](USAGE.ko.md) | CLI 명령, Discord 명령, 실행 모드, voice changes, progress, latency metrics. |
+| [Hermes 기본 음성 vs VerbalCoding](HERMES_VOICE.ko.md) | Hermes 기본 Discord 음성이 이미 하는 일과 VerbalCoding이 더하는 것. |
+| [Configuration](CONFIGURATION.ko.md) | .env, agent backends, MCP server, TTS backends, 운영 설정. |
+| [Troubleshooting](TROUBLESHOOTING.ko.md) | Docker UDP, voice join failures, missing token/channel checks, doctor behavior. |
+| [Multi-Instance](MULTI_INSTANCE.ko.md) | 격리된 Hermes profile로 프로젝트 방마다 고정 Discord voice bot 하나. |
+| [Release Notes](RELEASE.ko.md) | 현재 기능, verification checklist, public-release 전 TODO. |
 
-## 기여
+## 현지화된 README
 
-변경 사항을 보내기 전에 가벼운 점검을 실행하세요:
-
-```bash
-node --check app-node/main.mjs
-npm test
-bash -n run.sh scripts/install.sh
-npm pack --dry-run
-vc doctor
-```
+- [README.ko.md](../../README.ko.md)
+- [English README](../../README.md)
 
-## 상태
+## 기여자 참고
 
-VerbalCoding은 공개 릴리스를 지향하지만 아직 초기 단계입니다. 데모 비디오/GIF, 더 넓은 Linux 검증, CI, 더 깊은 보안 검토는 아직 TODO입니다.
+사용자 문서에서는 `vc ...` 명령을 우선 사용하고, `./scripts/...` 명령은 source checkout 기여자 흐름에만 사용하세요.

package/docs/i18n/README.ru.md

@@ -1,149 +1,35 @@
-# VerbalCoding
+# Документация VerbalCoding
 
-<p align="center">
-  <strong>Разговаривайте с CLI-агентами для кодинга через голос Discord — как по телефону для разработки ПО.</strong>
-</p>
+<p align="center"><a href="../../README.md">English README</a> · <a href="../../README.ko.md">한국어</a> · <a href="../../README.ja.md">日本語</a> · <a href="../../README.zh.md">中文</a> · <a href="../../README.es.md">Español</a> · <a href="../../README.fr.md">Français</a> · <a href="../../README.ru.md">Русский</a></p>
 
-<p align="center">
-  <a href="../../README.md">English</a> ·
-  <a href="README.ko.md">한국어</a> ·
-  <a href="README.ja.md">日本語</a> ·
-  <a href="README.zh.md">中文</a> ·
-  <a href="README.es.md">Español</a> ·
-  <a href="README.fr.md">Français</a> ·
-  <a href="README.ru.md">Русский</a>
-</p>
+README — краткая витрина; эта страница — индекс подробных гайдов. Если вы впервые настраиваете реальный Discord voice bot, начните с Fresh Install.
 
-<p align="center">
-  <img alt="Node.js" src="https://img.shields.io/badge/Node.js-20%2B-339933?logo=node.js&logoColor=white">
-  <img alt="Discord" src="https://img.shields.io/badge/Discord-voice%20bridge-5865F2?logo=discord&logoColor=white">
-  <img alt="STT" src="https://img.shields.io/badge/STT-whisper.cpp-7C3AED">
-  <img alt="TTS" src="https://img.shields.io/badge/TTS-Edge%20%7C%20OpenVoice%20%7C%20Supertonic%20%7C%20SpeechSwift-0EA5E9">
-  <img alt="Agents" src="https://img.shields.io/badge/Agents-Hermes%20%7C%20Claude%20%7C%20Codex%20%7C%20Gemini%20%7C%20OpenCode-111827">
-</p>
-
-<p align="center">
-  <img src="../assets/figures/verbalcoding-flow.svg" alt="Голосовой поток VerbalCoding к агенту" width="860">
-</p>
-
-## Зачем
-
-VerbalCoding превращает голосовой канал Discord в панель управления кодинг-агентами без рук. Произнесите запрос, позвольте CLI-агенту выполнить работу и услышите краткий ответ — с текстовыми расшифровками, событиями прогресса и защитными ограничениями для шумного вывода кода/логов.
-
-## Главное
-
-| Что вы получаете | Почему это удобно |
-|---|---|
-| Управление агентами голосом в первую очередь | Разговаривайте с Hermes Agent, Claude Code, Codex, Gemini CLI, OpenCode, OpenClaw или любым пользовательским CLI-харнесом. |
-| Речевой цикл на устройстве | Захват голоса Discord → локальная расшифровка `whisper-cli` → агент → фрагментированное воспроизведение TTS. |
-| Общий голосовой и текстовый контекст | Голосовые реплики и текстовые команды `!ask` могут повторно использовать одну и ту же поддерживаемую сессию агента. |
-| Перебивание и режимы чувствительности | Естественно прерывайте воспроизведение и переключайтесь между обычной и консервативной/шумной средой. |
-| Многоязычные голосовые пресеты | Переключайте STT, язык прогресса и голос TTS вместе через `vc language ko/en/auto`. |
-| Изоляция проектов по комнатам | Запускайте по одному боту на проектную комнату с отдельными профилями Hermes, сессиями, памятью и логами. |
-
-## Быстрый старт
-
-Самый быстрый путь через npm:
+## Быстрый путь
 
 ```bash
-npm install -g verbalcoding
-vc setup --yes
+npm install -g verbalcoding@latest
+vc setup
 vc doctor
 vc start
 ```
 
-Или запуск напрямую без постоянной глобальной установки:
-
-```bash
-npx verbalcoding setup --yes
-vc doctor
-vc start
-```
-
-Путь через клон GitHub для контрибьюторов:
-
-```bash
-git clone https://github.com/ca1773130n/VerbalCoding.git
-cd VerbalCoding
-./scripts/install.sh --yes
-vc doctor
-./run.sh
-```
-
-`vc setup --yes` подготавливает локальные зависимости из установленного npm-пакета. `./scripts/install.sh --yes` делает то же самое только внутри GitHub-клона. Оба пути по возможности настраивают зависимости Node/npm, `ffmpeg`, `whisper-cli`, стандартную модель whisper.cpp, локальный помощник Edge TTS в `.venv-tts` и мастер настройки. Они поддерживают macOS/Homebrew и распространённые менеджеры пакетов Linux (`apt`, `dnf`, `pacman`); повторно запустите с `--no-wizard` для установки только зависимостей или с `--skip-system`, если хотите устанавливать пакеты ОС самостоятельно.
+## Гайды
 
-Нужно пошаговое руководство по чистой установке? Начните с [Fresh Install](FRESH_INSTALL.ru.md).
-
-## Поддерживаемые бэкенды агентов
-
-| Бэкенд | Команда по умолчанию | Поддержка сессий |
-|---|---:|---|
-| Hermes Agent | `hermes chat -Q -q` | Возобновление, подробный прогресс, отмена, восстановление финального ответа |
-| Claude Code | `claude -p` | Поддержка файла сессии CLI через настройки адаптера по умолчанию |
-| Codex CLI | `codex exec` | Поддержка файла сессии CLI через настройки адаптера по умолчанию |
-| Gemini CLI | `gemini -p` | Поддержка файла сессии CLI через настройки адаптера по умолчанию |
-| OpenCode | `opencode run` | Поддержка файла сессии CLI через настройки адаптера по умолчанию |
-| OpenClaw | `openclaw run` | Поддержка файла сессии CLI через настройки адаптера по умолчанию |
-| Пользовательский | `AGENT_COMMAND` | Подключите собственную неинтерактивную команду |
-
-## Узнать больше
-
-| Руководство | Что вы получите |
-|---|---|
-| [Чистая установка](FRESH_INSTALL.ru.md) | Настройка чистого клона, загрузка модели, первый запуск |
-| [Руководство по использованию](USAGE.ru.md) | CLI-команды, команды Discord, режим прогресса, метрики задержки |
-| [Конфигурация](CONFIGURATION.ru.md) | `.env`, бэкенды агентов, MCP, бэкенды TTS, эксплуатационные заметки |
-| [Многоэкземплярный режим](MULTI_INSTANCE.ru.md) | Одна постоянная голосовая комната Discord на проект |
-| [Заметки о релизе](RELEASE.ru.md) | Текущие возможности и чеклист перед релизом |
-
-## Краткая карта команд
-
-```bash
-vc status                 # current language, TTS, and bridge settings
-vc language ko|en|auto    # switch STT/progress/TTS language preset
-vc bot invite CLIENT_ID   # generate the Discord bot invite URL
-vc instance setup NAME    # create an isolated project voice bot
-vc instance start NAME    # run that bot in the background
-vc doctor                 # redacted health check
-vc start                  # start the default bridge
-```
-
-В Discord:
-
-| Команда | Что делает |
-|---|---|
-| `!join` | Подключает бота к вашему текущему голосовому каналу. |
-| `!ask <prompt>` | Отправляет текст в тот же бэкенд агента. |
-| `!verbose on\|off` | Показывает/озвучивает короткие обновления прогресса. |
-| `!latency` | Сводка недавней задержки голоса/STT/агента/TTS. |
-| `!sensitivity normal` | Использует обычную чувствительность перебивания для помещений. |
-| `!sensitivity conservative` | Использует более строгую чувствительность для шумной/уличной среды. |
-| `!session new <name> <workdir> [context] --voice <voice-channel>` | Привязывает проектную сессию к голосовой комнате. |
-
-## Требования
-
-| Уровень | По умолчанию |
+| Гайды | Когда использовать |
 |---|---|
-| Среда выполнения | Node.js 20+, npm; установочный скрипт может установить через Homebrew/apt/dnf/pacman |
-| Аудио | `ffmpeg`; установочный скрипт может установить его |
-| Распознавание речи | Локальный `whisper-cli` из whisper.cpp; установочный скрипт использует Homebrew на macOS или локальную резервную сборку Linux |
-| TTS | Edge TTS CLI; установочный скрипт создаёт `.venv-tts` при необходимости |
-| Discord | Токен бота, intent Message Content, голосовые разрешения |
-| Агент | Как минимум один аутентифицированный CLI-харнес, по умолчанию Hermes Agent |
-| Основная платформа | macOS / Apple Silicon протестированы лучше всего; bootstrap для Linux предоставляется по мере возможностей и документирован |
+| [Fresh Install](FRESH_INSTALL.ru.md) | чистый npm/global install, Discord app setup, первый bot invite и первый voice run. |
+| [Usage](USAGE.ru.md) | CLI-команды, Discord-команды, режимы запуска, voice changes, progress и latency metrics. |
+| [Встроенный голос Hermes vs VerbalCoding](HERMES_VOICE.ru.md) | Что уже умеет встроенный Discord voice в Hermes и что добавляет VerbalCoding. |
+| [Configuration](CONFIGURATION.ru.md) | .env, agent backends, MCP server, TTS backends и эксплуатационные настройки. |
+| [Troubleshooting](TROUBLESHOOTING.ru.md) | Docker UDP, voice join failures, missing token/channel checks и doctor behavior. |
+| [Multi-Instance](MULTI_INSTANCE.ru.md) | один постоянный Discord voice bot на проектную room с изолированными Hermes profiles. |
+| [Release Notes](RELEASE.ru.md) | текущие возможности, verification checklist и TODO перед public release. |
 
-## Участие в разработке
+## Локализованный README
 
-Перед отправкой изменений выполните лёгкие проверки:
-
-```bash
-node --check app-node/main.mjs
-npm test
-bash -n run.sh scripts/install.sh
-npm pack --dry-run
-vc doctor
-```
+- [README.ru.md](../../README.ru.md)
+- [English README](../../README.md)
 
-## Статус
+## Заметка для contributors
 
-VerbalCoding ориентирован на публичный релиз, но всё ещё находится на ранней стадии. Демо-видео/GIF, более широкая проверка Linux, CI и более глубокий аудит безопасности пока остаются TODO.
+В пользовательских docs предпочитайте команды `vc ...`. Команды `./scripts/...` оставляйте для contributor flow из source checkout.

package/docs/i18n/README.zh.md

@@ -1,148 +1,35 @@
-# VerbalCoding
+# VerbalCoding 文档
 
-<p align="center">
-  <strong>通过 Discord 语音与 CLI 编码代理对话——就像给软件工作打一通电话。</strong>
-</p>
+<p align="center"><a href="../../README.md">English README</a> · <a href="../../README.ko.md">한국어</a> · <a href="../../README.ja.md">日本語</a> · <a href="../../README.zh.md">中文</a> · <a href="../../README.es.md">Español</a> · <a href="../../README.fr.md">Français</a> · <a href="../../README.ru.md">Русский</a></p>
 
-<p align="center">
-  <a href="README.ko.md">한국어</a> ·
-  <a href="README.ja.md">日本語</a> ·
-  <a href="README.zh.md">中文</a> ·
-  <a href="README.es.md">Español</a> ·
-  <a href="README.fr.md">Français</a> ·
-  <a href="README.ru.md">Русский</a>
-</p>
+README 是精简入口；本页是详细指南索引。第一次设置真实 Discord 语音 bot 时，请从 Fresh Install 开始。
 
-<p align="center">
-  <img alt="Node.js" src="https://img.shields.io/badge/Node.js-20%2B-339933?logo=node.js&logoColor=white">
-  <img alt="Discord" src="https://img.shields.io/badge/Discord-voice%20bridge-5865F2?logo=discord&logoColor=white">
-  <img alt="STT" src="https://img.shields.io/badge/STT-whisper.cpp-7C3AED">
-  <img alt="TTS" src="https://img.shields.io/badge/TTS-Edge%20%7C%20OpenVoice%20%7C%20Supertonic%20%7C%20SpeechSwift-0EA5E9">
-  <img alt="Agents" src="https://img.shields.io/badge/Agents-Hermes%20%7C%20Claude%20%7C%20Codex%20%7C%20Gemini%20%7C%20OpenCode-111827">
-</p>
-
-<p align="center">
-  <img src="../assets/figures/verbalcoding-flow.svg" alt="VerbalCoding 语音到代理流程" width="860">
-</p>
-
-## 为什么需要它
-
-VerbalCoding 会把 Discord 语音频道变成编码代理的免手动控制面板。说出请求，让你的 CLI 代理执行工作，然后听到简洁的语音回复——同时保留文本转写、进度事件，以及针对嘈杂代码/日志输出的保护机制。
-
-## 亮点
-
-| 你能获得什么 | 为什么体验很好 |
-|---|---|
-| 语音优先的代理控制 | 可以与 Hermes Agent、Claude Code、Codex、Gemini CLI、OpenCode、OpenClaw 或任何自定义 CLI 驱动对话。 |
-| 本机语音闭环 | Discord 语音采集 → 本地 `whisper-cli` 转写 → 代理 → 分块 TTS 播放。 |
-| 共享语音 + 文本上下文 | 语音轮次和 `!ask` 文本命令可以复用同一个受支持的代理会话。 |
-| 插话和灵敏度模式 | 可以自然打断播放，并在普通环境与保守/嘈杂环境之间切换。 |
-| 多语言语音预设 | 使用 `vc language ko/en/auto` 同时切换 STT、进度语言和 TTS 声音。 |
-| 多房间项目隔离 | 每个项目房间运行一个机器人，并隔离 Hermes 配置、会话、记忆和日志。 |
-
-## 快速开始
-
-使用 npm 的最快路径：
+## 最快路径
 
 ```bash
-npm install -g verbalcoding
-vc setup --yes
+npm install -g verbalcoding@latest
+vc setup
 vc doctor
 vc start
 ```
 
-或者无需永久全局安装，直接运行：
-
-```bash
-npx verbalcoding setup --yes
-vc doctor
-vc start
-```
-
-贡献者的 GitHub 克隆路径：
-
-```bash
-git clone https://github.com/ca1773130n/VerbalCoding.git
-cd VerbalCoding
-./scripts/install.sh --yes
-vc doctor
-./run.sh
-```
-
-`vc setup --yes` 会通过 npm 包内置的安装器引导安装本地前置依赖。`./scripts/install.sh --yes` 只在 GitHub 克隆目录中执行同样的流程。两者都会在可行时处理 Node/npm 依赖、`ffmpeg`、`whisper-cli`、默认 whisper.cpp 模型、本地 `.venv-tts` Edge TTS 辅助环境以及设置向导配置。它们支持 macOS/Homebrew 以及常见 Linux 包管理器（`apt`、`dnf`、`pacman`）；如只想安装依赖而不运行向导，可用 `--no-wizard` 重新运行；如果想自行安装 OS 软件包，可用 `--skip-system`。
+## 指南
 
-需要干净安装演练？从[全新安装](FRESH_INSTALL.zh.md)开始。
-
-## 支持的代理后端
-
-| 后端 | 默认命令 | 会话支持 |
-|---|---:|---|
-| Hermes Agent | `hermes chat -Q -q` | 恢复、详细进度、取消、最终答案恢复 |
-| Claude Code | `claude -p` | 通过适配器默认值支持 CLI 会话文件 |
-| Codex CLI | `codex exec` | 通过适配器默认值支持 CLI 会话文件 |
-| Gemini CLI | `gemini -p` | 通过适配器默认值支持 CLI 会话文件 |
-| OpenCode | `opencode run` | 通过适配器默认值支持 CLI 会话文件 |
-| OpenClaw | `openclaw run` | 通过适配器默认值支持 CLI 会话文件 |
-| Custom | `AGENT_COMMAND` | 自带非交互式命令 |
-
-## 了解更多
-
-| 指南 | 你能获得什么 |
-|---|---|
-| [全新安装](FRESH_INSTALL.zh.md) | 干净克隆设置、模型下载、首次运行 |
-| [使用指南](USAGE.zh.md) | CLI 命令、Discord 命令、进度模式、延迟指标 |
-| [配置](CONFIGURATION.zh.md) | `.env`、代理后端、MCP、TTS 后端、运维说明 |
-| [多实例](MULTI_INSTANCE.zh.md) | 每个项目一个长期 Discord 语音房间 |
-| [发行说明](RELEASE.zh.md) | 当前能力和预发布检查清单 |
-
-## 精简命令地图
-
-```bash
-vc status                 # 当前语言、TTS 和桥接设置
-vc language ko|en|auto    # 切换 STT/进度/TTS 语言预设
-vc bot invite CLIENT_ID   # 生成 Discord 机器人邀请 URL
-vc instance setup NAME    # 创建隔离的项目语音机器人
-vc instance start NAME    # 在后台运行该机器人
-vc doctor                 # 脱敏健康检查
-vc start                  # 启动默认桥接
-```
-
-在 Discord 中：
-
-| 命令 | 作用 |
-|---|---|
-| `!join` | 加入你当前的语音频道。 |
-| `!ask <prompt>` | 将文本发送给同一个代理后端。 |
-| `!verbose on\|off` | 显示/朗读简短进度更新。 |
-| `!latency` | 汇总最近的语音/STT/代理/TTS 延迟。 |
-| `!sensitivity normal` | 使用普通室内插话灵敏度。 |
-| `!sensitivity conservative` | 使用更严格的嘈杂/户外灵敏度。 |
-| `!session new <name> <workdir> [context] --voice <voice-channel>` | 将项目会话绑定到语音房间。 |
-
-## 要求
-
-| 层 | 默认值 |
+| 指南 | 适用场景 |
 |---|---|
-| 运行时 | Node.js 20+、npm；安装脚本可通过 Homebrew/apt/dnf/pacman 安装 |
-| 音频 | `ffmpeg`；安装脚本可安装它 |
-| 语音识别 | 来自 whisper.cpp 的本地 `whisper-cli`；安装脚本在 macOS 使用 Homebrew，在 Linux 使用本地构建回退 |
-| TTS | Edge TTS CLI；安装脚本会在需要时创建 `.venv-tts` |
-| Discord | 机器人令牌、Message Content intent、语音权限 |
-| 代理 | 至少一个已认证的 CLI 驱动，默认是 Hermes Agent |
-| 平台重点 | macOS / Apple Silicon 测试最多；Linux 引导为尽力支持并已文档化 |
+| [Fresh Install](FRESH_INSTALL.zh.md) | 干净的 npm/global install、Discord app setup、首次 bot invite、首次 voice run。 |
+| [Usage](USAGE.zh.md) | CLI 命令、Discord 命令、运行模式、voice changes、progress、latency metrics。 |
+| [Hermes 内置语音 vs VerbalCoding](HERMES_VOICE.zh.md) | Hermes 内置 Discord 语音已经支持什么，以及 VerbalCoding 增加什么。 |
+| [Configuration](CONFIGURATION.zh.md) | .env、agent backends、MCP server、TTS backends、运维设置。 |
+| [Troubleshooting](TROUBLESHOOTING.zh.md) | Docker UDP、voice join failures、missing token/channel checks、doctor behavior。 |
+| [Multi-Instance](MULTI_INSTANCE.zh.md) | 使用隔离 Hermes profile，让每个项目房间拥有一个固定 Discord voice bot。 |
+| [Release Notes](RELEASE.zh.md) | 当前功能、verification checklist、public-release 前 TODO。 |
 
-## 贡献
+## 本地化 README
 
-提交更改前运行轻量检查：
-
-```bash
-node --check app-node/main.mjs
-npm test
-bash -n run.sh scripts/install.sh
-npm pack --dry-run
-vc doctor
-```
+- [README.zh.md](../../README.zh.md)
+- [English README](../../README.md)
 
-## 状态
+## 贡献者说明
 
-VerbalCoding 面向公开发布，但仍处于早期阶段。演示视频/GIF、更广泛的 Linux 验证、CI，以及更深入的安全审查仍在 TODO 中。
+面向用户的文档优先使用 `vc ...` 命令；`./scripts/...` 仅用于 source checkout 的贡献者流程。

package/docs/i18n/RELEASE.es.md

@@ -1,5 +1,30 @@
 # Notas de versión de VerbalCoding
 
+<!-- readme-glow-up:intro -->
+<p align="center">
+  <a href="../../README.es.md">README</a> ·
+  <a href="README.es.md">Centro de documentación</a> ·
+  <a href="FRESH_INSTALL.es.md">Fresh Install</a> ·
+  <a href="USAGE.es.md">Usage</a> ·
+  <a href="CONFIGURATION.es.md">Configuration</a> ·
+  <a href="TROUBLESHOOTING.es.md">Troubleshooting</a> ·
+  <a href="MULTI_INSTANCE.es.md">Multi-Instance</a>
+</p>
+
+> Ruta rápida: `npm install -g verbalcoding@latest → vc setup → vc doctor → vc start`
+<!-- /readme-glow-up:intro -->
+
+## Flujo setup actualizado
+
+```bash
+npm install -g verbalcoding@latest
+vc setup
+vc doctor
+vc start
+```
+
+No edites `.env` manualmente: usa `vc setup token` para guardar `DISCORD_BOT_TOKEN`/`DISCORD_CLIENT_ID` y `vc setup channels` para guardar `AUTO_JOIN_VOICE_CHANNELS`. Si Docker muestra `Cannot perform IP discovery - socket closed`, usa `network_mode: "host"` en Linux Compose y elimina `ports:`.
+
 ## Candidato de lanzamiento actual
 
 VerbalCoding es un puente de voz de Discord para controlar por voz agentes de programación basados en CLI. Está orientado al lanzamiento público, con macOS / Apple Silicon como la ruta más probada y soporte de arranque de mejor esfuerzo en Linux para administradores de paquetes comunes.
@@ -22,7 +47,7 @@ VerbalCoding es un puente de voz de Discord para controlar por voz agentes de pr
 - Protecciones para diff/código/registros para que las salidas técnicas grandes no se lean en voz alta.
 - Modos de sensibilidad normal y conservador para uso en interiores frente a uso ruidoso/exterior.
 - Asistente de configuración, `.env.example`, comprobador de prerrequisitos `vc doctor` y arranque `./scripts/install.sh --yes` para paquetes del SO, dependencias npm, asistente de Edge TTS y el modelo predeterminado de whisper.cpp.
-- Ruta de instalación del paquete npm: `npm install -g verbalcoding`, `vc setup --yes` y `vc start`.
+- Ruta de instalación del paquete npm: `npm install -g verbalcoding`, `vc setup` guiado y `vc start`.
 - Modo opcional de progreso detallado para actualizaciones intermedias solo de texto durante trabajos largos del agente.
 - Métricas de latencia JSONL siempre activas más resumen `!latency` / `!metrics` para optimización del pipeline.
 - Espera de inactividad de emisión más paciente (`UTTERANCE_IDLE_MS=4500`) para que las instrucciones habladas largas con pausas naturales no se dividan en un prompt parcial más habla durante procesamiento ignorada.

package/docs/i18n/RELEASE.fr.md

@@ -1,5 +1,30 @@
 # Notes de version de VerbalCoding
 
+<!-- readme-glow-up:intro -->
+<p align="center">
+  <a href="../../README.fr.md">README</a> ·
+  <a href="README.fr.md">Centre de documentation</a> ·
+  <a href="FRESH_INSTALL.fr.md">Fresh Install</a> ·
+  <a href="USAGE.fr.md">Usage</a> ·
+  <a href="CONFIGURATION.fr.md">Configuration</a> ·
+  <a href="TROUBLESHOOTING.fr.md">Troubleshooting</a> ·
+  <a href="MULTI_INSTANCE.fr.md">Multi-Instance</a>
+</p>
+
+> Chemin rapide: `npm install -g verbalcoding@latest → vc setup → vc doctor → vc start`
+<!-- /readme-glow-up:intro -->
+
+## Flux setup actuel
+
+```bash
+npm install -g verbalcoding@latest
+vc setup
+vc doctor
+vc start
+```
+
+Ne modifiez pas `.env` à la main : utilisez `vc setup token` pour enregistrer `DISCORD_BOT_TOKEN`/`DISCORD_CLIENT_ID`, et `vc setup channels` pour `AUTO_JOIN_VOICE_CHANNELS`. Si Docker affiche `Cannot perform IP discovery - socket closed`, utilisez `network_mode: "host"` avec Compose sous Linux et supprimez `ports:`.
+
 ## Candidat de version actuel
 
 VerbalCoding est une passerelle vocale Discord pour contrôler par la voix des agents de codage basés sur CLI. Il vise une publication publique, avec macOS / Apple Silicon comme chemin le plus testé et une prise en charge d'amorçage Linux au mieux pour les gestionnaires de paquets courants.
@@ -22,7 +47,7 @@ VerbalCoding est une passerelle vocale Discord pour contrôler par la voix des a
 - Garde-fous diff/code/journaux pour que les grandes sorties techniques ne soient pas lues à voix haute.
 - Modes de sensibilité normal et conservateur pour usage intérieur vs bruyant/extérieur.
 - Assistant de configuration, `.env.example`, vérificateur de prérequis `vc doctor` et amorçage `./scripts/install.sh --yes` pour les paquets OS, les dépendances npm, l'assistant Edge TTS et le modèle whisper.cpp par défaut.
-- Chemin d'installation par paquet npm : `npm install -g verbalcoding`, `vc setup --yes` et `vc start`.
+- Chemin d'installation par paquet npm : `npm install -g verbalcoding`, `vc setup` guidé et `vc start`.
 - Mode de progression détaillée facultatif pour les mises à jour textuelles d'étapes intermédiaires pendant les longs travaux d'agent.
 - Métriques de latence JSONL toujours actives plus résumé `!latency` / `!metrics` pour l'optimisation du pipeline.
 - Attente d'inactivité d'énonciation plus patiente (`UTTERANCE_IDLE_MS=4500`) afin que les longues instructions parlées avec pauses naturelles ne soient pas coupées en prompt partiel plus parole ignorée pendant le traitement.

package/docs/i18n/RELEASE.ja.md

@@ -1,5 +1,30 @@
 # VerbalCoding リリースノート
 
+<!-- readme-glow-up:intro -->
+<p align="center">
+  <a href="../../README.ja.md">README</a> ·
+  <a href="README.ja.md">ドキュメントハブ</a> ·
+  <a href="FRESH_INSTALL.ja.md">Fresh Install</a> ·
+  <a href="USAGE.ja.md">Usage</a> ·
+  <a href="CONFIGURATION.ja.md">Configuration</a> ·
+  <a href="TROUBLESHOOTING.ja.md">Troubleshooting</a> ·
+  <a href="MULTI_INSTANCE.ja.md">Multi-Instance</a>
+</p>
+
+> 最短経路: `npm install -g verbalcoding@latest → vc setup → vc doctor → vc start`
+<!-- /readme-glow-up:intro -->
+
+## 最新の setup フロー
+
+```bash
+npm install -g verbalcoding@latest
+vc setup
+vc doctor
+vc start
+```
+
+手動で `.env` を編集せず、`vc setup token` で `DISCORD_BOT_TOKEN`/`DISCORD_CLIENT_ID`、`vc setup channels` で `AUTO_JOIN_VOICE_CHANNELS` を保存してください。Docker で `Cannot perform IP discovery - socket closed` が出る場合、Linux Compose サービスに `network_mode: "host"` を使い、`ports:` を削除します。
+
 ## 現在のリリース候補
 
 VerbalCoding は、CLI ベースのコーディングエージェントを音声で操作するための Discord 音声ブリッジです。公開リリースを意識しており、最も検証されている経路は macOS / Apple Silicon です。一般的なパッケージマネージャー向けに、Linux のベストエフォートなブートストラップもサポートしています。
@@ -22,7 +47,7 @@ VerbalCoding は、CLI ベースのコーディングエージェントを音声
 - 大きな技術出力を読み上げないための diff/code/log ガードレール。
 - 屋内利用と騒音/屋外利用向けの通常および保守的な感度モード。
 - セットアップウィザード、`.env.example`、`vc doctor` 前提条件チェッカー、OS パッケージ、npm 依存関係、Edge TTS ヘルパー、デフォルト whisper.cpp モデルをブートストラップする `./scripts/install.sh --yes`。
-- npm パッケージのインストール手順: `npm install -g verbalcoding`、`vc setup --yes`、`vc start`。
+- npm パッケージのインストール手順: `npm install -g verbalcoding`、guided `vc setup`、`vc start`。
 - 長いエージェント作業中に、テキストのみの中間ステップ更新を出す任意の詳細進捗モード。
 - パイプライン最適化のための常時オン JSONL レイテンシ指標と、`!latency` / `!metrics` 要約。
 - より余裕のある発話アイドル待ち（`UTTERANCE_IDLE_MS=4500`）。自然な間を含む長い音声指示が、部分プロンプトと無視される処理中発話に分割されないようにします。