verbalcoding 0.2.6 → 0.2.8

package/docs/i18n/MULTI_INSTANCE.ja.md

@@ -0,0 +1,179 @@
+# マルチインスタンス VerbalCoding
+
+VerbalCoding は、複数の独立した Discord 音声ブリッジプロセスを実行できます。各プロセスは既存の単一インスタンス Node ブリッジのままですが、異なる `instances/<name>.env` ファイルを読み込み、異なる Discord ボットトークンを使います。
+
+各プロジェクトが専用の Discord 音声チャンネルに常駐し、専用の文字起こしチャンネル/スレッドへ書き込む必要がある場合に使います。
+
+## 複数のボットトークンが必要な理由
+
+Discord 音声の常駐は、実質的に 1 つのギルドにつき 1 ボットアカウントあたり 1 つのアクティブな音声接続です。同じギルド内で 1 つのボットトークンが別の音声チャンネルに参加すると、以前のチャンネルに同時に常駐し続けることはできません。同時に使うプロジェクトルームには、プロジェクトごとに 1 つの Discord アプリケーション/ボットを作成してください。
+
+## ファイルレイアウト
+
+```text
+instances/
+  README.md
+  example.env
+  llm-wiki.env        # ローカルのみ、git で無視
+  verbalcoding.env    # ローカルのみ、git で無視
+.run/instances/
+  llm-wiki.pid        # 実行時のみ、git で無視
+```
+
+実際の `instances/*.env` ファイルは Discord トークンを含む可能性があるため無視されます。`instances/example.env` がコミット済みテンプレートです。
+
+## インスタンスセットアップウィザード
+
+通常利用では、ユーザーが env ファイルをコピーして手動編集すべきではありません。代わりにウィザードを実行してください:
+
+```bash
+vc instance setup llm-wiki
+# またはプロジェクトセットアップスクリプトから:
+./scripts/install.sh --instance llm-wiki
+```
+
+ウィザードは、ボットトークン、Discord Application/Client ID、音声チャンネル、文字起こし先、作業ディレクトリ、プロジェクトコンテキスト、分離されたランタイムパスを尋ねます。`instances/<name>.env` をモード `0600` で書き込み、上書き前に既存ファイルをバックアップし、次に使う start/status コマンドを表示します。
+
+セットアップ中に Discord Application/Client ID を入力すると、概要にそのボットの招待 URL も表示されます。同じ URL はいつでも次で生成できます:
+
+```bash
+vc bot invite <client-id>
+vc bot invite <client-id> --guild <guild-id>
+```
+
+同時に常駐する音声ルームごとに Discord Developer Portal のアプリケーション/ボットは依然として 1 つ必要ですが、OAuth URL や権限整数を手動で組み立てずに済みます。
+
+### Hermes プロファイル分離
+
+各インスタンスには `~/.hermes/profiles/<name>` に独自の Hermes ホームが与えられるため、メモリ、MEMORY.md、SOUL.md、学習済みスキルがプロジェクト間で漏れません。
+
+`vc instance setup <name>` は自動的に次を行います:
+
+- `hermes profile create <name> --clone-from default` を実行します（現在の `~/.hermes` から API キーとモデルを引き継ぎ、セッションとメモリは新規に開始します）。
+- 新しいプロファイルの `terminal.cwd` をインスタンスの作業ディレクトリに設定します。
+- ウィザードのプロジェクトコンテキスト回答から `<profile>/SOUL.md` を初期化します。
+- `instances/<name>.env` に `HERMES_HOME=...` を書き込みます。
+
+`vc instance start <name>` は自己修復します。env が指す Hermes プロファイルディレクトリが存在しない場合、起動前に再作成します。
+
+Hermes は名前をディレクトリおよび設定キーとして使うため、インスタンス名は `^[a-z0-9][a-z0-9_-]{0,63}$` に一致する必要があります。
+
+## 生成される最小インスタンス 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
+```
+
+各インスタンスには、ログ/デバッグ/セッションファイル用に一意の値を与えてください。`HERMES_HOME` と対応する `~/.hermes/profiles/<name>` ディレクトリは `vc instance setup` によって自動作成されます。`vc doctor` は、重複トークン、衝突するランタイムパス、存在しないプロファイルディレクトリ、プロファイルとインスタンス間の `terminal.cwd` 不一致を、秘密情報を出力せずに確認します。
+
+## コマンド
+
+```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
+```
+
+`start` は `./run.sh instances/<name>.env` をデタッチして実行し、`.run/instances/<name>.pid` を書き込みます。
+
+`stop` は `SIGTERM` を送り、最大 10 秒待ってから `SIGKILL` にフォールバックし、pid ファイルを削除します。
+
+## 例: 2 つの永続音声ルーム
+
+1. 2 つの Discord アプリケーション/ボットを作成します:
+   - VerbalCoding bot
+   - LLM-Wiki bot
+
+2. テキストおよび音声権限付きで両方をサーバーに招待します:
+   - チャンネルを見る
+   - メッセージを送信
+   - スレッドでメッセージを送信
+   - メッセージ履歴を読む
+   - アプリケーションコマンドを使う
+   - 接続
+   - 発話
+
+   各 Discord アプリケーション作成後に `vc bot invite <client-id>` を使うと、これらの権限を含む正確な招待 URL が出力されます。
+
+3. 各ローカルインスタンスでセットアップウィザードを実行します:
+
+```bash
+vc instance setup verbalcoding
+vc instance setup llm-wiki
+```
+
+ウィザードは、git で無視される `instances/verbalcoding.env` と `instances/llm-wiki.env` をモード `0600` で書き込みます。また、既存のインスタンス env を置き換える前にバックアップします。各実行では、デフォルト Hermes ホームから複製された `~/.hermes/profiles/<name>` も作成されるため、2 つのインスタンスは同じ認証/モデルで開始しながら、各プロジェクトの学習に伴って独立したメモリとスキルを蓄積します。
+
+4. 設定を確認します:
+
+```bash
+vc doctor
+```
+
+5. 両方を起動します:
+
+```bash
+vc instance start verbalcoding
+vc instance start llm-wiki
+vc instance status
+```
+
+6. ログを確認します:
+
+```bash
+tail -n 50 /tmp/verbalcoding-verbalcoding.log
+tail -n 50 /tmp/verbalcoding-llm-wiki.log
+```
+
+期待されるログ行:
+
+```text
+Listening in voice channel ... / VerbalCoding
+Listening in voice channel ... / LLM-Wiki
+```
+
+7. 両方を停止します:
+
+```bash
+vc instance stop verbalcoding
+vc instance stop llm-wiki
+```
+
+## 短期的な単一ボットでのテキスト/音声紐付け
+
+ボットトークンが 1 つしかない場合は、同時マルチチャンネル常駐ではなく、プロジェクトセッションの音声紐付けを使ってください。
+
+対象のテキストチャンネル/スレッドで次を実行します:
+
+```text
+!session attach-voice --voice "LLM-Wiki"
+```
+
+動作:
+
+- 選択した音声チャンネルを現在のテキストチャンネル/スレッドに紐付けます。
+- 現在のテキストチャンネルにプロジェクトセッションがない場合、アドホックな分離セッションを作成します。
+- 音声 STT/結果/進捗/最終回答テキストは、そのアクティブなプロジェクト文字起こし先へルーティングされます。
+
+既存の名前付きプロジェクトセッションを紐付けるには:
+
+```text
+!session voice llm-wiki --voice "LLM-Wiki"
+```
+
+これはルーティングには便利ですが、1 つのボットを同時に 2 つの音声チャンネルへ常駐させるものではありません。同時に永続常駐させるには、複数のボットトークン/プロセスを使ってください。

package/docs/i18n/MULTI_INSTANCE.ko.md

@@ -1,64 +1,64 @@
-# VerbalCoding 멀티 인스턴스
+# Multi-instance VerbalCoding
 
-VerbalCoding은 여러 개의 독립적인 Discord 음성 브릿지 프로세스를 실행할 수 있습니다. 각 프로세스는 같은 단일 인스턴스 Node 브릿지를 사용하지만, 서로 다른 `instances/<name>.env` 파일과 서로 다른 Discord bot token을 로드합니다.
+VerbalCoding은 여러 개의 독립적인 Discord 음성 브리지 프로세스를 실행할 수 있습니다. 각 프로세스는 여전히 기존 단일 인스턴스 Node 브리지이지만, 서로 다른 `instances/<name>.env` 파일을 로드하고 서로 다른 Discord 봇 토큰을 사용합니다.
 
-프로젝트마다 자기 Discord 음성 채널에 항상 붙어 있고, 자기 transcript 채널/스레드에 기록해야 할 때 사용하세요.
+각 프로젝트가 자체 Discord 음성 채널을 영구적으로 차지하고 자체 전사 채널/스레드에 기록해야 할 때 사용하세요.
 
-## 왜 여러 봇 토큰이 필요한가
+## 여러 봇 토큰이 필요한 이유
 
-Discord 음성 상주 방식은 사실상 길드마다 봇 계정 하나가 동시에 하나의 음성 연결만 유지하는 구조입니다. 같은 봇 토큰이 같은 길드의 다른 음성 채널에 들어가면 이전 채널에도 계속 남아 있을 수 없습니다. 동시에 여러 프로젝트 방을 유지하려면 프로젝트마다 Discord 애플리케이션/봇을 하나씩 만들어야 합니다.
+Discord 음성 상주는 사실상 길드당 봇 계정 하나에 활성 음성 연결 하나입니다. 같은 길드에서 하나의 봇 토큰이 다른 음성 채널에 참가하면 이전 채널에 영구 연결된 상태를 동시에 유지할 수 없습니다. 동시에 여러 프로젝트 방을 쓰려면 프로젝트마다 Discord 애플리케이션/봇을 하나씩 만드세요.
 
-## 파일 구조
+## 파일 배치
 
 ```text
 instances/
   README.md
   example.env
-  llm-wiki.env        # 로컬 전용, git에서 무시
-  verbalcoding.env    # 로컬 전용, git에서 무시
+  llm-wiki.env        # 로컬 전용, git에서 무시됨
+  verbalcoding.env    # 로컬 전용, git에서 무시됨
 .run/instances/
-  llm-wiki.pid        # 런타임 전용, git에서 무시
+  llm-wiki.pid        # 런타임 전용, git에서 무시됨
 ```
 
-실제 `instances/*.env` 파일에는 Discord 토큰이 들어갈 수 있으므로 git에서 무시됩니다. `instances/example.env`만 템플릿으로 커밋됩니다.
+실제 `instances/*.env` 파일은 Discord 토큰을 포함할 수 있으므로 무시됩니다. `instances/example.env`가 커밋된 템플릿입니다.
 
 ## 인스턴스 설정 마법사
 
-일반 사용자는 env 파일을 복사해서 직접 편집하지 않는 편이 좋습니다. 마법사를 실행하세요.
+일반 사용자는 env 파일을 복사해 수동으로 편집하지 않아도 됩니다. 대신 마법사를 실행하세요:
 
 ```bash
 vc instance setup llm-wiki
-# 또는 프로젝트 설정 스크립트에서:
+# 또는 프로젝트 설정 스크립트를 통해:
 ./scripts/install.sh --instance llm-wiki
 ```
 
-마법사는 봇 토큰, Discord Application/Client ID, 음성 채널, transcript 대상, 작업 디렉터리, 프로젝트 컨텍스트, 격리된 런타임 경로를 묻습니다. `instances/<name>.env`를 권한 `0600`으로 작성하고, 기존 파일이 있으면 덮어쓰기 전에 백업하며, 다음 start/status 명령을 출력합니다.
+마법사는 봇 토큰, Discord Application/Client ID, 음성 채널, 전사 대상, workdir, 프로젝트 컨텍스트, 격리된 런타임 경로를 묻습니다. mode `0600`으로 `instances/<name>.env`를 작성하고, 덮어쓰기 전에 기존 파일을 백업하며, 다음 start/status 명령을 출력합니다.
 
-설정 중 Discord Application/Client ID를 입력하면 요약에 해당 봇 초대 URL도 출력됩니다. 같은 URL은 언제든지 다시 만들 수 있습니다.
+설정 중 Discord Application/Client ID를 입력하면 요약에 해당 봇의 초대 URL도 출력됩니다. 같은 URL은 언제든 다음으로 생성할 수 있습니다:
 
 ```bash
 vc bot invite <client-id>
 vc bot invite <client-id> --guild <guild-id>
 ```
 
-Discord는 동시에 여러 음성방에 상주하려면 여전히 방마다 Developer Portal 애플리케이션/봇 하나가 필요합니다. 대신 VerbalCoding이 OAuth URL이나 permission integer를 직접 조립할 필요를 없애 줍니다.
+동시 음성 방마다 Developer Portal 애플리케이션/봇이 하나씩 필요한 점은 변하지 않지만, OAuth URL이나 권한 정수를 수동으로 만들 필요가 없습니다.
 
 ### Hermes 프로필 격리
 
-각 인스턴스는 `~/.hermes/profiles/<name>` 아래에 자기 Hermes home을 갖습니다. 이렇게 하면 memory, MEMORY.md, SOUL.md, 학습된 skills가 프로젝트 사이에 섞이지 않습니다.
+각 인스턴스는 `~/.hermes/profiles/<name>`에 자체 Hermes home을 갖습니다. 따라서 memory, MEMORY.md, SOUL.md, 학습된 skill이 프로젝트 간에 새지 않습니다.
 
-`vc instance setup <name>`은 자동으로 다음을 수행합니다.
+`vc instance setup <name>`은 자동으로 다음을 수행합니다:
 
-- `hermes profile create <name> --clone-from default` 실행: 현재 `~/.hermes`의 API key와 모델 설정은 가져오지만, 세션과 메모리는 새로 시작합니다.
-- 새 프로필의 `terminal.cwd`를 인스턴스 작업 디렉터리로 설정합니다.
-- 마법사에서 입력한 project context로 `<profile>/SOUL.md`를 초기화합니다.
-- `instances/<name>.env`에 `HERMES_HOME=...`을 씁니다.
+- `hermes profile create <name> --clone-from default` 실행(현재 `~/.hermes`의 API 키와 모델은 가져오며, 세션과 메모리는 새로 시작),
+- 새 프로필의 `terminal.cwd`를 인스턴스 workdir로 설정,
+- 마법사의 프로젝트 컨텍스트 답변으로 `<profile>/SOUL.md` 초기화,
+- `instances/<name>.env`에 `HERMES_HOME=...` 작성.
 
-`vc instance start <name>`은 self-heal을 수행합니다. env가 가리키는 Hermes profile directory가 사라졌다면 시작 전에 다시 만듭니다.
+`vc instance start <name>`은 자가 복구를 수행합니다. env가 더 이상 존재하지 않는 Hermes 프로필 디렉터리를 가리키면, 시작 명령은 실행 전에 해당 프로필을 다시 만듭니다.
 
-인스턴스 이름은 Hermes가 디렉터리와 config key로 쓰기 때문에 `^[a-z0-9][a-z0-9_-]{0,63}$` 형식이어야 합니다.
+Hermes가 이름을 디렉터리 및 설정 키로 사용하므로 인스턴스 이름은 `^[a-z0-9][a-z0-9_-]{0,63}$`와 일치해야 합니다.
 
-## 생성되는 최소 인스턴스 env 예시
+## 최소 생성 인스턴스 env
 
 ```env
 INSTANCE_NAME=my-project
@@ -76,7 +76,7 @@ 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` 불일치를 검사합니다.
+모든 인스턴스에 로그/디버그/세션 파일의 고유 값을 부여하세요. `HERMES_HOME`과 일치하는 `~/.hermes/profiles/<name>` 디렉터리는 `vc instance setup`이 자동으로 만듭니다. `vc doctor`는 비밀 정보를 출력하지 않고 중복 토큰, 충돌하는 런타임 경로, 누락된 프로필 디렉터리, 프로필과 인스턴스 사이의 `terminal.cwd` 불일치를 확인합니다.
 
 ## 명령
 
@@ -89,17 +89,17 @@ vc instance stop my-project
 vc instance restart my-project
 ```
 
-`start`는 `./run.sh instances/<name>.env`를 detached로 실행하고 `.run/instances/<name>.pid`를 씁니다.
+`start`는 `./run.sh instances/<name>.env`를 분리 실행하고 `.run/instances/<name>.pid`를 작성합니다.
 
-`stop`은 `SIGTERM`을 보내고 최대 10초 기다린 뒤, 필요하면 `SIGKILL`로 fallback하고 pid 파일을 제거합니다.
+`stop`은 `SIGTERM`을 보내고 최대 10초간 기다린 뒤, 필요하면 `SIGKILL`로 폴백하고 pid 파일을 제거합니다.
 
-## 예시: 영구 음성방 두 개
+## 예시: 두 개의 영구 음성 방
 
-1. Discord 애플리케이션/봇 두 개를 만듭니다.
+1. 두 개의 Discord 애플리케이션/봇을 만듭니다:
    - VerbalCoding bot
    - LLM-Wiki bot
 
-2. 둘 다 서버에 초대하고 텍스트/음성 권한을 줍니다.
+2. 텍스트 및 음성 권한으로 둘 다 서버에 초대합니다:
    - View Channel
    - Send Messages
    - Send Messages in Threads
@@ -108,24 +108,24 @@ vc instance restart my-project
    - Connect
    - Speak
 
-   각 Discord 애플리케이션을 만든 뒤 `vc bot invite <client-id>`를 실행하면 필요한 권한이 포함된 정확한 초대 URL을 출력합니다.
+   각 Discord 애플리케이션을 만든 뒤 `vc bot invite <client-id>`를 사용하면 해당 권한이 포함된 정확한 초대 URL을 출력할 수 있습니다.
 
-3. 각 로컬 인스턴스 설정 마법사를 실행합니다.
+3. 각 로컬 인스턴스에 대해 설정 마법사를 실행합니다:
 
 ```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를 쌓습니다.
+마법사는 mode `0600`으로 git에서 무시되는 `instances/verbalcoding.env` 및 `instances/llm-wiki.env` 파일을 작성합니다. 또한 기존 인스턴스 env를 교체하기 전에 백업합니다. 각 실행은 기본 Hermes home에서 복제한 `~/.hermes/profiles/<name>`도 생성하므로, 두 인스턴스는 같은 인증/모델로 시작하지만 각 프로젝트를 학습하면서 독립적인 메모리와 skill을 축적합니다.
 
-4. 설정을 확인합니다.
+4. 설정을 확인합니다:
 
 ```bash
 vc doctor
 ```
 
-5. 둘 다 시작합니다.
+5. 둘 다 시작합니다:
 
 ```bash
 vc instance start verbalcoding
@@ -133,32 +133,32 @@ vc instance start llm-wiki
 vc instance status
 ```
 
-6. 로그를 확인합니다.
+6. 로그를 확인합니다:
 
 ```bash
 tail -n 50 /tmp/verbalcoding-verbalcoding.log
 tail -n 50 /tmp/verbalcoding-llm-wiki.log
 ```
 
-예상 로그:
+예상 로그 줄:
 
 ```text
 Listening in voice channel ... / VerbalCoding
 Listening in voice channel ... / LLM-Wiki
 ```
 
-7. 둘 다 중지합니다.
+7. 둘 다 중지합니다:
 
 ```bash
 vc instance stop verbalcoding
 vc instance stop llm-wiki
 ```
 
-## 단기: 단일 봇 텍스트/음성 바인딩
+## 단기 단일 봇 텍스트/음성 바인딩
 
-봇 토큰이 하나뿐이라면 동시 다중 채널 상주 대신 project-session voice binding을 쓰세요.
+봇 토큰이 하나뿐이라면 동시 다중 채널 상주 대신 프로젝트 세션 음성 바인딩을 사용하세요.
 
-대상 텍스트 채널/스레드에서:
+대상 텍스트 채널/스레드에서 다음을 실행합니다:
 
 ```text
 !session attach-voice --voice "LLM-Wiki"
@@ -166,14 +166,14 @@ vc instance stop llm-wiki
 
 동작:
 
-- 선택된 음성 채널을 현재 텍스트 채널/스레드에 연결합니다.
-- 현재 텍스트 채널에 project session이 없으면 ad-hoc 격리 세션을 만듭니다.
-- 음성 STT/result/progress/final-answer 텍스트가 해당 project transcript 대상으로 라우팅됩니다.
+- 선택한 음성 채널을 현재 텍스트 채널/스레드에 바인딩합니다.
+- 현재 텍스트 채널에 프로젝트 세션이 없으면 임시 격리 세션을 만듭니다.
+- 음성 STT/결과/진행/최종 답변 텍스트가 해당 활성 프로젝트 전사 대상으로 라우팅됩니다.
 
-기존 named project session을 연결하려면:
+기존 이름 있는 프로젝트 세션을 연결하려면:
 
 ```text
 !session voice llm-wiki --voice "LLM-Wiki"
 ```
 
-이 방식은 라우팅에는 편하지만, 봇 하나를 동시에 두 음성 채널에 머물게 하지는 않습니다. 동시에 여러 프로젝트 방에 영구 상주하려면 여러 봇 토큰/프로세스를 사용하세요.
+이는 라우팅에는 편리하지만, 하나의 봇을 두 음성 채널에 동시에 머물게 하지는 않습니다. 동시 영구 상주에는 여러 봇 토큰/프로세스를 사용하세요.

package/docs/i18n/MULTI_INSTANCE.ru.md

@@ -0,0 +1,179 @@
+# Многоэкземплярный VerbalCoding
+
+VerbalCoding может запускать несколько независимых процессов голосового bridge Discord. Каждый процесс всё ещё является существующим одноэкземплярным Node bridge, но загружает другой файл `instances/<name>.env` и использует другой токен Discord-бота.
+
+Используйте это, когда каждый проект должен постоянно занимать собственный голосовой канал Discord и писать в собственный канал/тред расшифровок.
+
+## Почему требуется несколько токенов ботов
+
+Присутствие в голосе Discord фактически ограничено одним активным голосовым подключением на аккаунт бота в пределах guild. Если один токен бота подключается к другому голосовому каналу в той же guild, он не может одновременно оставаться постоянно подключённым к предыдущему каналу. Для одновременных проектных комнат создавайте по одному приложению/боту Discord на проект.
+
+## Структура файлов
+
+```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
+```
+
+Настоящие файлы `instances/*.env` игнорируются, потому что могут содержать токены Discord. `instances/example.env` — закоммиченный шаблон.
+
+## Мастер настройки экземпляра
+
+Пользователям не следует копировать и вручную редактировать env-файлы для обычного использования. Вместо этого запустите мастер:
+
+```bash
+vc instance setup llm-wiki
+# or through the project setup script:
+./scripts/install.sh --instance llm-wiki
+```
+
+Мастер запрашивает токен бота, Discord Application/Client ID, голосовой канал, цель расшифровок, workdir, контекст проекта и изолированные runtime-пути. Он записывает `instances/<name>.env` с режимом `0600`, создаёт резервную копию существующего файла перед перезаписью и печатает следующие команды start/status.
+
+Если во время настройки вы введёте Discord Application/Client ID, сводка также напечатает URL приглашения для этого бота. Тот же URL можно сгенерировать в любое время:
+
+```bash
+vc bot invite <client-id>
+vc bot invite <client-id> --guild <guild-id>
+```
+
+Discord всё равно требует одно приложение/бота Developer Portal на каждую одновременную голосовую комнату, но это избавляет от ручной сборки OAuth URL или целых чисел разрешений.
+
+### Изоляция профилей Hermes
+
+Каждый экземпляр получает собственный home Hermes в `~/.hermes/profiles/<name>`, чтобы память, MEMORY.md, SOUL.md и изученные skills не перетекали между проектами.
+
+`vc instance setup <name>` автоматически:
+
+- запускает `hermes profile create <name> --clone-from default` (переносит API-ключи и модель из текущего `~/.hermes`; сессии и память начинаются заново),
+- задаёт `terminal.cwd` нового профиля в workdir экземпляра,
+- заполняет `<profile>/SOUL.md` из ответа мастеру о контексте проекта,
+- записывает `HERMES_HOME=...` в `instances/<name>.env`.
+
+`vc instance start <name>` самовосстанавливается: если env указывает на директорию профиля Hermes, которой больше нет, команда start пересоздаёт её перед запуском.
+
+Имена экземпляров должны соответствовать `^[a-z0-9][a-z0-9_-]{0,63}$`, потому что Hermes использует имя как директорию и ключ конфигурации.
+
+## Минимальный сгенерированный 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
+```
+
+Дайте каждому экземпляру уникальные значения для файлов логов/debug/session. `HERMES_HOME` и соответствующая директория `~/.hermes/profiles/<name>` создаются автоматически командой `vc instance setup`. `vc doctor` проверяет повторяющиеся токены, конфликтующие runtime-пути, отсутствующие директории профилей и несоответствия `terminal.cwd` между профилем и экземпляром — всё это без печати секретов.
+
+## Команды
+
+```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
+```
+
+`start` запускает `./run.sh instances/<name>.env` в detached-режиме и записывает `.run/instances/<name>.pid`.
+
+`stop` отправляет `SIGTERM`, ждёт до 10 секунд, затем откатывается к `SIGKILL` и удаляет pid-файл.
+
+## Пример: две постоянные голосовые комнаты
+
+1. Создайте два приложения/бота Discord:
+   - бот VerbalCoding
+   - бот LLM-Wiki
+
+2. Пригласите обоих на сервер с текстовыми и голосовыми разрешениями:
+   - Просмотр канала
+   - Отправка сообщений
+   - Отправка сообщений в тредах
+   - Чтение истории сообщений
+   - Использование команд приложения
+   - Подключение
+   - Речь
+
+   Используйте `vc bot invite <client-id>` после создания каждого приложения Discord, чтобы напечатать точный URL приглашения с этими разрешениями.
+
+3. Запустите мастер настройки для каждого локального экземпляра:
+
+```bash
+vc instance setup verbalcoding
+vc instance setup llm-wiki
+```
+
+Мастер записывает игнорируемые файлы `instances/verbalcoding.env` и `instances/llm-wiki.env` с режимом `0600`; он также создаёт резервную копию существующего env экземпляра перед заменой. Каждый запуск также создаёт `~/.hermes/profiles/<name>`, клонированный из вашего стандартного Hermes home, поэтому два экземпляра стартуют с одинаковой аутентификацией/моделью, но накапливают независимую память и skills по мере изучения каждого проекта.
+
+4. Проверьте конфигурацию:
+
+```bash
+vc doctor
+```
+
+5. Запустите оба:
+
+```bash
+vc instance start verbalcoding
+vc instance start llm-wiki
+vc instance status
+```
+
+6. Проверьте логи:
+
+```bash
+tail -n 50 /tmp/verbalcoding-verbalcoding.log
+tail -n 50 /tmp/verbalcoding-llm-wiki.log
+```
+
+Ожидаемые строки логов:
+
+```text
+Listening in voice channel ... / VerbalCoding
+Listening in voice channel ... / LLM-Wiki
+```
+
+7. Остановите оба:
+
+```bash
+vc instance stop verbalcoding
+vc instance stop llm-wiki
+```
+
+## Краткосрочная привязка текста/голоса с одним ботом
+
+Если у вас есть только один токен бота, используйте привязку голоса проектной сессии вместо одновременного присутствия в нескольких каналах.
+
+Выполните это в целевом текстовом канале/треде:
+
+```text
+!session attach-voice --voice "LLM-Wiki"
+```
+
+Поведение:
+
+- Привязывает выбранный голосовой канал к текущему текстовому каналу/треду.
+- Если в текущем текстовом канале нет проектной сессии, создаёт ad-hoc изолированную сессию.
+- Текст voice STT/result/progress/final-answer направляется в активную цель расшифровок проекта.
+
+Чтобы привязать существующую именованную проектную сессию:
+
+```text
+!session voice llm-wiki --voice "LLM-Wiki"
+```
+
+Это удобно для маршрутизации, но не заставляет одного бота одновременно оставаться в двух голосовых каналах. Для одновременного постоянного присутствия используйте несколько токенов/процессов ботов.