verbalcoding 0.2.7 → 0.2.8

package/docs/i18n/FRESH_INSTALL.ko.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` 셸 명령을 설치합니다.
+- OS 패키지 관리자가 지원하는 경우 `ffmpeg`, Node/npm, `whisper-cli`를 설치합니다.
+- `models/ggml-small-q5_1.bin`을 다운로드합니다.
+- `edge-tts`가 `PATH`에 없으면 `.venv-tts`를 만들고 `edge-tts`를 설치합니다.
+- 대화형 `.env` 마법사를 실행합니다.
+
+지원되는 시스템 부트스트랩 경로:
+
+| OS | 시스템 의존성 경로 |
+|---|---|
+| macOS | 필요 시 Homebrew: `brew install node ffmpeg whisper-cpp` |
+| Debian/Ubuntu | Node/npm, ffmpeg, Python, 빌드 도구는 `apt-get`; 로컬 whisper.cpp 빌드 폴백 |
+| Fedora/RHEL | Node/npm, ffmpeg, Python, 빌드 도구는 `dnf`; 로컬 whisper.cpp 빌드 폴백 |
+| Arch | Node/npm, ffmpeg, Python, 빌드 도구는 `pacman`; 로컬 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 애플리케이션 생성, 봇 사용자 추가, privileged intents 활성화, 서버 초대 방법을 보여줍니다. VerbalCoding은 동일한 Discord 봇 설정을 사용한 뒤 그 위에 음성 수신, STT, CLI 에이전트 실행, TTS 재생을 추가합니다.
+
+1. Discord Developer Portal에서 Discord 애플리케이션과 봇을 만듭니다.
+2. Message Content privileged 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 scope가 포함됩니다.
+
+## 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
+각 인스턴스는 자체 토큰, 음성 채널, 전사 대상, 로그 경로, Hermes 세션 파일, 선택적 Hermes 프로필을 가진 무시되는 `instances/<name>.env`를 작성합니다.
+
+## 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/FRESH_INSTALL.ru.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,47 +30,105 @@ 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` напрямую: в текущем каталоге нет checkout репозитория. Вместо этого используйте упакованную CLI-обёртку:
 
-Useful variants:
+```bash
+vc setup --yes
+```
+
+`vc setup` запускает `scripts/install.sh`, включённый в установленный npm-пакет. Используйте `./scripts/install.sh --yes` только внутри GitHub-клона:
 
 ```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
+```
+
+Что это делает:
+
+- устанавливает npm-зависимости, если отсутствует `node_modules/`,
+- устанавливает короткую shell-команду `vc` через `npm link`,
+- устанавливает `ffmpeg`, Node/npm и `whisper-cli`, когда это поддерживается менеджером пакетов ОС,
+- загружает `models/ggml-small-q5_1.bin`,
+- создаёт `.venv-tts` и устанавливает `edge-tts`, если `edge-tts` ещё не находится в `PATH`,
+- запускает интерактивный мастер `.env`.
+
+Поддерживаемые пути системного bootstrap:
+
+| ОС | Путь системных зависимостей |
+|---|---|
+| 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                   # dependency/bootstrap only from npm install
+./scripts/install.sh --yes --no-wizard       # dependency/bootstrap only from a clone
+./scripts/install.sh --skip-system           # do not install OS packages
+./scripts/install.sh --skip-model            # do not download the default STT model
+./scripts/install.sh --skip-edge-tts         # do not create .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.
+Если ваша ОС не поддерживается, установите это вручную перед повторным запуском:
+
+- Node.js 20+ и npm
+- ffmpeg
+- Python 3 с venv/pip
+- `whisper-cli` из whisper.cpp
+- один аутентифицированный бэкенд 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 и бота в Discord Developer Portal.
+2. Включите привилегированный intent Message Content.
+3. Скопируйте токен бота в приглашение установщика или в `.env` как `DISCORD_BOT_TOKEN`.
+4. Сгенерируйте URL приглашения:
 
 ```bash
 vc bot invite <discord-client-id>
+# or pin it to one server:
 vc bot invite <discord-client-id> --guild <guild-id>
 ```
 
-## 4. Verify
+Приглашение включает scopes бота и slash-команд, а также текстовые/голосовые разрешения, используемые VerbalCoding.
+
+## 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), он сначала автоматически перезапускает упакованный bootstrap. Исправьте оставшиеся пункты `✗`, затем запустите снова.
+
+Ожидаемый успешный результат включает:
+
+```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` должен содержать путь `EDGE_TTS_COMMAND`, указывающий на `.venv-tts/bin/edge-tts`.
 
-## 5. Run
+## 5. Запустите одного бота по умолчанию
 
 ```bash
 vc start
@@ -71,14 +136,14 @@ vc start
 ./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,9 +165,11 @@ vc instance start my-project
 vc instance status my-project
 ```
 
-## 7. Optional OpenVoice setup
+Каждый экземпляр записывает игнорируемый `instances/<name>.env` со своим токеном, голосовым каналом, целью расшифровок, путём лога, файлом сессии Hermes и необязательным профилем Hermes.
+
+## 7. Необязательная настройка OpenVoice
 
-Keep `TTS_BACKEND=edge` for a fresh install. To enable OpenVoice later:
+Клонирование голоса OpenVoice необязательно. Для свежей публичной установки оставьте `TTS_BACKEND=edge`. Чтобы позже включить OpenVoice:
 
 ```bash
 ./scripts/setup_openvoice.sh
@@ -112,13 +179,29 @@ Keep `TTS_BACKEND=edge` for a fresh install. To enable OpenVoice later:
 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` и протестируйте `!voice-test <text>` в Discord.
+
+## 8. Smoke-тест чистого клона для сопровождающих
 
-## 8. Maintainer smoke tests
+Быстрый smoke-тест только на хосте:
 
 ```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 агента, а не утёкшие токены или отсутствующие установочные скрипты.
+
+Smoke-тест чистой установки Ubuntu на базе Docker:
+
+```bash
 ./scripts/docker_ubuntu_smoke.sh
 ```
+
+Он запускает `ubuntu:24.04`, копирует отслеживаемое дерево репозитория в чистый контейнер, выполняет `./scripts/install.sh --yes --no-wizard`, записывает несекретный smoke `.env`, проверяет `vc`, запускает Node-тесты и проверяет `vc doctor`. Он не подключается к голосу Discord; используйте настоящую Ubuntu VM или WSL2 после этого, если нужен сквозной тест голосового канала.