verbalcoding 0.2.6 → 0.2.8

package/docs/i18n/FRESH_INSTALL.ja.md

@@ -0,0 +1,207 @@
+# 新規インストール
+
+このガイドは、クリーンな公開インストール向けです。ローカル環境だけに依存する前提を避け、インストーラーで可能な限りブートストラップします。
+
+## 1. CLI をインストールする
+
+推奨 npm 手順:
+
+```bash
+npm install -g verbalcoding
+```
+
+または公開パッケージを直接実行します:
+
+```bash
+npx verbalcoding setup --yes
+```
+
+`npm install -g` を使った場合は、続けて次を実行します:
+
+```bash
+vc setup --yes
+```
+
+コントリビューター向けの GitHub クローン手順:
+
+```bash
+git clone https://github.com/ca1773130n/VerbalCoding.git
+cd VerbalCoding
+./scripts/install.sh --yes
+```
+
+## 2. 依存関係をブートストラップし、セットアップウィザードを実行する
+
+npm インストールでは、現在のディレクトリにリポジトリのチェックアウトがないため、`./scripts/install.sh` を直接実行しないでください。代わりにパッケージ済み CLI ラッパーを使います:
+
+```bash
+vc setup --yes
+```
+
+`vc setup` は、インストール済み npm パッケージ内の `scripts/install.sh` を実行します。`./scripts/install.sh --yes` は GitHub クローン内にいる場合だけ使ってください:
+
+```bash
+./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
+```
+
+OS が未対応の場合は、再実行する前に次を手動でインストールしてください:
+
+- Node.js 20+ と npm
+- ffmpeg
+- venv/pip 付き Python 3
+- whisper.cpp の `whisper-cli`
+- 認証済み CLI エージェントバックエンドを少なくとも 1 つ（デフォルトは Hermes Agent）
+
+## 3. Discord アプリケーションをセットアップする
+
+初めてボットを作る場合は、まず上流の Discord ボットセットアップガイドを読んでください:
+
+- 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>
+
+これらのページでは、Discord アプリケーションの作成、ボットユーザーの追加、特権インテントの有効化、サーバーへの招待方法を説明しています。VerbalCoding は同じ Discord ボット設定を使い、その上に音声受信、STT、CLI エージェント実行、TTS 再生を追加します。
+
+1. Discord Developer Portal で Discord アプリケーションとボットを作成します。
+2. Message Content 特権インテントを有効にします。
+3. ボットトークンをインストーラーのプロンプト、または `.env` の `DISCORD_BOT_TOKEN` にコピーします。
+4. 招待 URL を生成します:
+
+```bash
+vc bot invite <discord-client-id>
+# または 1 つのサーバーに固定します:
+vc bot invite <discord-client-id> --guild <guild-id>
+```
+
+この招待には、VerbalCoding が使うボットおよびスラッシュコマンドのスコープと、テキスト/音声権限が含まれます。
+
+## 4. 検証する
+
+```bash
+vc doctor
+```
+
+`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. 単一のデフォルトボットを実行する
+
+```bash
+vc start
+# または GitHub クローンから:
+./run.sh
+```
+
+起動に成功すると、ログには次のような行が含まれます:
+
+```text
+Logged in as <bot-name>
+Listening in voice channel <server> / <channel>
+```
+
+Discord 内:
+
+```text
+!ping
+!join
+!ask say hello briefly
+!verbose on
+```
+
+その後、設定済みの音声チャンネルで話してください。STT テキスト、詳細モードがオンの場合の進捗テキスト、最終テキスト回答が表示され、TTS 再生が聞こえるはずです。
+
+## 6. プロジェクトごとのルーム設定
+
+プロジェクト音声ルームごとに 1 つの永続ボットを使うには、プロジェクトごとに Discord アプリケーションを 1 つ作成してから、次を実行します:
+
+```bash
+vc instance setup my-project
+vc bot invite <that-project-client-id>
+vc instance start my-project
+vc instance status my-project
+```
+
+各インスタンスは、独自のトークン、音声チャンネル、文字起こし先、ログパス、Hermes セッションファイル、任意の Hermes プロファイルを含む、git で無視される `instances/<name>.env` を書き込みます。
+
+## 7. 任意の OpenVoice セットアップ
+
+OpenVoice の音声クローンは任意です。新規の公開インストールでは `TTS_BACKEND=edge` のままにしてください。後で OpenVoice を有効にするには:
+
+```bash
+./scripts/setup_openvoice.sh
+# 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
+```
+
+次に `TTS_BACKEND=openvoice` を設定し、`vc doctor` を実行して、Discord で `!voice-test <text>` をテストします。
+
+## 8. メンテナー向けクリーンクローンのスモークテスト
+
+ホストのみでの高速スモークテスト:
+
+```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.ko.md

@@ -1,28 +1,28 @@
-# VerbalCoding 새 설치 가이드
+# 새로 설치하기
 
-이 문서는 공개 npm 패키지 또는 깨끗한 GitHub 클론에서 처음 설치하는 흐름을 설명합니다. 로컬 전용 가정을 피하고, 설치 스크립트가 가능한 한 많은 준비 작업을 자동화하도록 구성돼 있습니다.
+이 가이드는 깨끗한 공개 설치를 위한 문서입니다. 로컬 환경에만 맞춘 가정을 피하고, 설치 프로그램으로 가능한 한 많은 부분을 부트스트랩합니다.
 
 ## 1. CLI 설치
 
-권장 npm 설치:
+권장 npm 경로:
 
 ```bash
 npm install -g verbalcoding
 ```
 
-전역 설치 없이 바로 실행하려면:
+또는 게시된 패키지를 바로 실행합니다:
 
 ```bash
 npx verbalcoding setup --yes
 ```
 
-전역 설치를 했다면 이어서:
+`npm install -g`를 사용했다면 다음을 계속 실행하세요:
 
 ```bash
 vc setup --yes
 ```
 
-기여자용 GitHub 클론 경로:
+기여자를 위한 GitHub 클론 경로:
 
 ```bash
 git clone https://github.com/ca1773130n/VerbalCoding.git
@@ -30,83 +30,89 @@ cd VerbalCoding
 ./scripts/install.sh --yes
 ```
 
-## 2. 의존성 부트스트랩과 설정 마법사
+## 2. 의존성 부트스트랩 및 설정 마법사 실행
 
-npm 명령은 클론 설치와 같은 부트스트래퍼를 실행합니다. 클론에서는 다음을 실행합니다.
+npm 설치에서는 현재 디렉터리에 저장소 체크아웃이 없으므로 `./scripts/install.sh`를 직접 실행하지 마세요. 대신 패키지된 CLI 래퍼를 사용하세요:
+
+```bash
+vc setup --yes
+```
+
+`vc setup`은 설치된 npm 패키지 안의 `scripts/install.sh`를 실행합니다. GitHub 클론 안에 있을 때만 `./scripts/install.sh --yes`를 사용하세요:
 
 ```bash
 ./scripts/install.sh --yes
 ```
 
-이 명령이 하는 일:
+수행되는 작업:
 
 - `node_modules/`가 없으면 npm 의존성을 설치합니다.
-- 클론 설치에서는 짧은 `vc` 셸 명령을 `npm link`로 연결합니다.
-- OS 패키지 매니저가 지원되면 `ffmpeg`, Node/npm, `whisper-cli`를 설치합니다.
-- 기본 모델 `models/ggml-small-q5_1.bin`을 다운로드합니다.
-- `edge-tts`가 PATH에 없으면 `.venv-tts`를 만들고 Edge TTS helper를 설치합니다.
-- 대화형 `.env` 설정 마법사를 실행합니다.
+- `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 | `apt-get`으로 Node/npm, ffmpeg, Python, build tools 설치; 필요 시 로컬 whisper.cpp 빌드 |
-| Fedora/RHEL | `dnf`로 Node/npm, ffmpeg, Python, build tools 설치; 필요 시 로컬 whisper.cpp 빌드 |
-| Arch | `pacman`으로 Node/npm, ffmpeg, Python, build tools 설치; 필요 시 로컬 whisper.cpp 빌드 |
+| 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 생성 생략
+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
 ```
 
-OS가 지원되지 않으면 아래를 직접 설치한 뒤 다시 실행하세요.
+OS가 지원되지 않으면 다시 실행하기 전에 다음을 수동으로 설치하세요:
 
 - Node.js 20+ 및 npm
 - ffmpeg
 - venv/pip가 포함된 Python 3
 - whisper.cpp `whisper-cli`
-- 인증된 CLI 에이전트 백엔드 하나 이상; 기본은 Hermes Agent
+- 인증된 CLI 에이전트 백엔드 하나 이상, 기본값은 Hermes Agent
 
 ## 3. Discord 애플리케이션 설정
 
-Discord 봇을 처음 만든다면 먼저 공식/상위 문서를 확인하세요.
+처음 봇을 만드는 경우 먼저 업스트림 Discord 봇 설정 가이드를 읽으세요:
 
 - 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>
 
-위 문서에는 Discord 애플리케이션 생성, bot user 추가, privileged intent 활성화, 서버 초대 방법이 설명되어 있습니다. VerbalCoding도 같은 Discord bot 설정을 사용하고, 그 위에 음성 수신, STT, CLI 에이전트 실행, TTS 재생을 얹습니다.
+이 페이지들은 Discord 애플리케이션 생성, 봇 사용자 추가, privileged intents 활성화, 서버 초대 방법을 보여줍니다. VerbalCoding은 동일한 Discord 봇 설정을 사용한 뒤 그 위에 음성 수신, STT, CLI 에이전트 실행, TTS 재생을 추가합니다.
 
-1. Discord Developer Portal에서 애플리케이션과 봇을 만듭니다.
-2. Message Content privileged intent를 켭니다.
-3. 봇 토큰을 설치 프롬프트 또는 `.env`의 `DISCORD_BOT_TOKEN`에 넣습니다.
-4. 초대 URL을 생성합니다.
+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>
 ```
 
-초대 URL에는 VerbalCoding이 쓰는 bot/application command scope와 텍스트/음성 권한이 포함됩니다.
+초대에는 VerbalCoding이 사용하는 텍스트/음성 권한과 bot 및 slash-command scope가 포함됩니다.
 
-## 4. 검증
+## 4. 확인
 
 ```bash
 vc doctor
 ```
 
-`vc doctor`는 토큰을 숨깁니다. 필요한 토큰, 명령, 모델이 있는지만 보여주고 비밀값은 출력하지 않습니다. 모든 `✗` 항목을 고친 뒤 다시 실행하세요.
+`vc doctor`는 민감 정보를 가립니다. 비밀 값을 출력하지 않고 누락된 토큰/명령/모델을 보고합니다. 수정 가능한 로컬 필수 구성요소(`ffmpeg`, `whisper-cli`, 기본 모델, Edge TTS 헬퍼)가 없으면 먼저 패키지된 부트스트랩을 자동으로 다시 실행합니다. 남은 `✗` 항목을 고친 뒤 다시 실행하세요.
 
-성공 예시는 다음과 같습니다.
+예상 성공 출력에는 다음이 포함됩니다:
 
 ```text
 ✓ Node.js
@@ -120,9 +126,9 @@ vc doctor
 Doctor passed. Run vc start to start VerbalCoding.
 ```
 
-설치기가 로컬 Edge TTS helper를 만들었다면 `.env`에는 `.venv-tts/bin/edge-tts`를 가리키는 `EDGE_TTS_COMMAND` 경로가 들어갑니다.
+설치 프로그램이 로컬 Edge TTS 헬퍼를 만들었다면 `.env`에는 `.venv-tts/bin/edge-tts`를 가리키는 `EDGE_TTS_COMMAND` 경로가 있어야 합니다.
 
-## 5. 기본 단일 봇 실행
+## 5. 단일 기본 봇 실행
 
 ```bash
 vc start
@@ -130,7 +136,7 @@ vc start
 ./run.sh
 ```
 
-성공한 시작 로그에는 다음 줄이 보입니다.
+성공적인 시작 로그에는 다음이 포함됩니다:
 
 ```text
 Logged in as <bot-name>
@@ -146,11 +152,11 @@ Discord에서:
 !verbose on
 ```
 
-그 다음 설정된 음성 채널에서 말해 보세요. STT 텍스트, verbose 모드의 진행 텍스트, 최종 텍스트 답변, TTS 재생을 확인할 수 있어야 합니다.
+그런 다음 설정된 음성 채널에서 말하세요. STT 텍스트, 자세한 모드가 켜졌을 때의 진행 텍스트, 최종 텍스트 답변을 볼 수 있고 TTS 재생도 들을 수 있어야 합니다.
 
-## 6. 프로젝트별 음성방 설정
+## 6. 프로젝트별 방 설정
 
-프로젝트 음성방마다 영구 봇 하나를 두려면 프로젝트마다 Discord 애플리케이션을 만든 뒤:
+프로젝트 음성 방마다 하나의 영구 봇을 두려면 프로젝트마다 Discord 애플리케이션을 하나씩 만들고 다음을 실행하세요:
 
 ```bash
 vc instance setup my-project
@@ -159,25 +165,25 @@ vc instance start my-project
 vc instance status my-project
 ```
 
-각 인스턴스는 무시되는 `instances/<name>.env`를 작성합니다. 이 파일에는 해당 봇의 토큰, 음성 채널, transcript 대상, 로그 경로, Hermes 세션 파일, 선택적 Hermes 프로필 정보가 들어갑니다.
+각 인스턴스는 자체 토큰, 음성 채널, 전사 대상, 로그 경로, Hermes 세션 파일, 선택적 Hermes 프로필을 가진 무시되는 `instances/<name>.env`를 작성합니다.
 
-## 7. 선택: OpenVoice 설정
+## 7. 선택 사항: OpenVoice 설정
 
-OpenVoice 음성 복제는 선택 기능입니다. 공개 설치 직후에는 `TTS_BACKEND=edge`를 유지하세요. 나중에 OpenVoice를 켜려면:
+OpenVoice 음성 복제는 선택 사항입니다. 깨끗한 공개 설치에서는 `TTS_BACKEND=edge`를 유지하세요. 나중에 OpenVoice를 활성화하려면:
 
 ```bash
 ./scripts/setup_openvoice.sh
-# OpenVoice V2 체크포인트를 vendor/OpenVoice/checkpoints_v2/ 아래에 넣습니다.
-# 허가된 로컬 샘플을 voice-samples/user-reference.wav에 두거나,
-# 봇 실행 후 “목소리 샘플 녹음 시작해”라고 말하고 10~30초 발화합니다.
+# 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
 ```
 
-그 뒤 `TTS_BACKEND=openvoice`로 설정하고 `vc doctor`, Discord의 `!voice-test <text>`로 테스트합니다.
+그런 다음 `TTS_BACKEND=openvoice`를 설정하고 `vc doctor`를 실행한 뒤 Discord에서 `!voice-test <text>`를 테스트하세요.
 
-## 8. 유지보수자용 클린 설치 스모크 테스트
+## 8. 유지관리자를 위한 깨끗한 클론 스모크 테스트
 
-빠른 호스트 스모크 테스트:
+빠른 호스트 전용 스모크 테스트:
 
 ```bash
 TMPDIR=$(mktemp -d)
@@ -190,12 +196,12 @@ chmod 600 .env
 vc doctor || true
 ```
 
-이 시점에서 예상되는 실패는 로컬 비밀값 누락 또는 인증되지 않은 에이전트 CLI입니다. 토큰 노출이나 설치 스크립트 누락이 나오면 안 됩니다.
+이 시점의 예상 실패는 로컬 비밀 정보 누락 또는 인증되지 않은 에이전트 CLI이며, 토큰 유출이나 설치 스크립트 누락이 아니어야 합니다.
 
-Docker 기반 Ubuntu 클린 설치 스모크 테스트:
+Docker 기반 Ubuntu 깨끗한 설치 스모크 테스트:
 
 ```bash
 ./scripts/docker_ubuntu_smoke.sh
 ```
 
-이 스크립트는 `ubuntu:24.04`에서 추적된 저장소 트리를 깨끗한 컨테이너로 복사하고, `./scripts/install.sh --yes --no-wizard`를 실행하고, 비밀값 없는 smoke `.env`를 만든 뒤 `vc`, Node 테스트, `vc doctor`를 확인합니다. Discord 음성 연결까지는 하지 않습니다. 실제 end-to-end 음성 테스트는 Ubuntu VM 또는 WSL2에서 별도로 진행하세요.
+이 스크립트는 `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

@@ -0,0 +1,207 @@
+# Чистая установка
+
+Это руководство предназначено для чистой публичной установки. Оно избегает локальных предположений и использует установщик, чтобы подготовить как можно больше компонентов.
+
+## 1. Установите CLI
+
+Рекомендуемый путь через npm:
+
+```bash
+npm install -g verbalcoding
+```
+
+Или запустите опубликованный пакет напрямую:
+
+```bash
+npx verbalcoding setup --yes
+```
+
+Если вы использовали `npm install -g`, продолжите так:
+
+```bash
+vc setup --yes
+```
+
+Путь через клон GitHub для контрибьюторов:
+
+```bash
+git clone https://github.com/ca1773130n/VerbalCoding.git
+cd VerbalCoding
+./scripts/install.sh --yes
+```
+
+## 2. Подготовьте зависимости и запустите мастер настройки
+
+При установке через npm не запускайте `./scripts/install.sh` напрямую: в текущем каталоге нет checkout репозитория. Вместо этого используйте упакованную CLI-обёртку:
+
+```bash
+vc setup --yes
+```
+
+`vc setup` запускает `scripts/install.sh`, включённый в установленный npm-пакет. Используйте `./scripts/install.sh --yes` только внутри GitHub-клона:
+
+```bash
+./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
+```
+
+Если ваша ОС не поддерживается, установите это вручную перед повторным запуском:
+
+- Node.js 20+ и npm
+- ffmpeg
+- Python 3 с venv/pip
+- `whisper-cli` из whisper.cpp
+- один аутентифицированный бэкенд CLI-агента, по умолчанию Hermes Agent
+
+## 3. Настройка приложения Discord
+
+Если это ваш первый бот, сначала прочитайте исходные руководства по настройке ботов Discord:
+
+- Руководство 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>
+
+Эти страницы показывают, как создать приложение 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>
+```
+
+Приглашение включает scopes бота и slash-команд, а также текстовые/голосовые разрешения, используемые VerbalCoding.
+
+## 4. Проверьте
+
+```bash
+vc doctor
+```
+
+`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. Запустите одного бота по умолчанию
+
+```bash
+vc start
+# or, from a GitHub clone:
+./run.sh
+```
+
+Логи успешного запуска включают:
+
+```text
+Logged in as <bot-name>
+Listening in voice channel <server> / <channel>
+```
+
+В Discord:
+
+```text
+!ping
+!join
+!ask say hello briefly
+!verbose on
+```
+
+Затем говорите в настроенном голосовом канале. Вы должны увидеть текст STT, текст прогресса при включённом подробном режиме, финальный текстовый ответ и услышать воспроизведение TTS.
+
+## 6. Настройка «проект на комнату»
+
+Для одного постоянного бота на голосовую комнату проекта создайте по одному приложению Discord на проект, затем:
+
+```bash
+vc instance setup my-project
+vc bot invite <that-project-client-id>
+vc instance start my-project
+vc instance status my-project
+```
+
+Каждый экземпляр записывает игнорируемый `instances/<name>.env` со своим токеном, голосовым каналом, целью расшифровок, путём лога, файлом сессии Hermes и необязательным профилем Hermes.
+
+## 7. Необязательная настройка OpenVoice
+
+Клонирование голоса 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.
+python3 integrations/openvoice/synth.py --openvoice-dir vendor/OpenVoice --ref-audio voice-samples/user-reference.wav --text '안녕하세요. 버벌코딩 목소리 복제 테스트입니다.' --output /tmp/verbalcoding-openvoice-smoke.wav
+```
+
+Затем установите `TTS_BACKEND=openvoice`, запустите `vc doctor` и протестируйте `!voice-test <text>` в Discord.
+
+## 8. Smoke-тест чистого клона для сопровождающих
+
+Быстрый 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 после этого, если нужен сквозной тест голосового канала.