verbalcoding 0.2.7 → 0.2.9

package/docs/i18n/MULTI_INSTANCE.ja.md

@@ -1,50 +1,64 @@
-# VerbalCoding マルチインスタンス
+# マルチインスタンス 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.
+VerbalCoding は、複数の独立した Discord 音声ブリッジプロセスを実行できます。各プロセスは既存の単一インスタンス Node ブリッジのままですが、異なる `instances/<name>.env` ファイルを読み込み、異なる Discord ボットトークンを使います。
 
-Use this when each project should permanently occupy its own Discord voice channel and write to its own transcript channel/thread.
+各プロジェクトが専用の Discord 音声チャンネルに常駐し、専用の文字起こしチャンネル/スレッドへ書き込む必要がある場合に使います。
 
-## 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.
+Discord 音声の常駐は、実質的に 1 つのギルドにつき 1 ボットアカウントあたり 1 つのアクティブな音声接続です。同じギルド内で 1 つのボットトークンが別の音声チャンネルに参加すると、以前のチャンネルに同時に常駐し続けることはできません。同時に使うプロジェクトルームには、プロジェクトごとに 1 つの Discord アプリケーション/ボットを作成してください。
 
-## File layout
+## ファイルレイアウト
 
 ```text
 instances/
   README.md
   example.env
-  llm-wiki.env        # local only, ignored by git
-  verbalcoding.env    # local only, ignored by git
+  llm-wiki.env        # ローカルのみ、git で無視
+  verbalcoding.env    # ローカルのみ、git で無視
 .run/instances/
-  llm-wiki.pid        # runtime only, ignored by git
+  llm-wiki.pid        # 実行時のみ、git で無視
 ```
 
-Real `instances/*.env` files are ignored because they may contain Discord tokens.
+実際の `instances/*.env` ファイルは Discord トークンを含む可能性があるため無視されます。`instances/example.env` がコミット済みテンプレートです。
 
-## Instance setup wizard
+## インスタンスセットアップウィザード
+
+通常利用では、ユーザーが env ファイルをコピーして手動編集すべきではありません。代わりにウィザードを実行してください:
 
 ```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.
+ウィザードは、ボットトークン、Discord Application/Client ID、音声チャンネル、文字起こし先、作業ディレクトリ、プロジェクトコンテキスト、分離されたランタイムパスを尋ねます。`instances/<name>.env` をモード `0600` で書き込み、上書き前に既存ファイルをバックアップし、次に使う start/status コマンドを表示します。
 
-Generate invite URLs with:
+セットアップ中に Discord Application/Client ID を入力すると、概要にそのボットの招待 URL も表示されます。同じ URL はいつでも次で生成できます:
 
 ```bash
 vc bot invite <client-id>
 vc bot invite <client-id> --guild <guild-id>
 ```
 
-## Hermes profile isolation
+同時に常駐する音声ルームごとに Discord Developer Portal のアプリケーション/ボットは依然として 1 つ必要ですが、OAuth URL や権限整数を手動で組み立てずに済みます。
+
+### Hermes プロファイル分離
+
+各インスタンスには `~/.hermes/profiles/<name>` に独自の Hermes ホームが与えられるため、メモリ、MEMORY.md、SOUL.md、学習済みスキルがプロジェクト間で漏れません。
+
+`vc instance setup <name>` は自動的に次を行います:
 
-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.
+- `hermes profile create <name> --clone-from default` を実行します（現在の `~/.hermes` から API キーとモデルを引き継ぎ、セッションとメモリは新規に開始します）。
+- 新しいプロファイルの `terminal.cwd` をインスタンスの作業ディレクトリに設定します。
+- ウィザードのプロジェクトコンテキスト回答から `<profile>/SOUL.md` を初期化します。
+- `instances/<name>.env` に `HERMES_HOME=...` を書き込みます。
 
-`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}$`.
+`vc instance start <name>` は自己修復します。env が指す Hermes プロファイルディレクトリが存在しない場合、起動前に再作成します。
 
-## Minimal generated instance env
+Hermes は名前をディレクトリおよび設定キーとして使うため、インスタンス名は `^[a-z0-9][a-z0-9_-]{0,63}$` に一致する必要があります。
+
+## 生成される最小インスタンス env
 
 ```env
 INSTANCE_NAME=my-project
@@ -62,9 +76,9 @@ 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.
+各インスタンスには、ログ/デバッグ/セッションファイル用に一意の値を与えてください。`HERMES_HOME` と対応する `~/.hermes/profiles/<name>` ディレクトリは `vc instance setup` によって自動作成されます。`vc doctor` は、重複トークン、衝突するランタイムパス、存在しないプロファイルディレクトリ、プロファイルとインスタンス間の `terminal.cwd` 不一致を、秘密情報を出力せずに確認します。
 
-## Commands
+## コマンド
 
 ```bash
 vc instance list
@@ -75,47 +89,91 @@ vc instance stop my-project
 vc instance restart my-project
 ```
 
-## Example: two permanent voice rooms
+`start` は `./run.sh instances/<name>.env` をデタッチして実行し、`.run/instances/<name>.pid` を書き込みます。
+
+`stop` は `SIGTERM` を送り、最大 10 秒待ってから `SIGKILL` にフォールバックし、pid ファイルを削除します。
+
+## 例: 2 つの永続音声ルーム
 
-1. Create two Discord applications/bots.
-2. Invite both with text and voice permissions. Use `vc bot invite <client-id>`.
-3. Run setup:
+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
 ```
 
-4. Check and start:
+ウィザードは、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
 ```
 
-5. Verify logs:
+6. ログを確認します:
 
 ```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
+7. 両方を停止します:
+
+```bash
+vc instance stop verbalcoding
+vc instance stop llm-wiki
+```
+
+## 短期的な単一ボットでのテキスト/音声紐付け
+
+ボットトークンが 1 つしかない場合は、同時マルチチャンネル常駐ではなく、プロジェクトセッションの音声紐付けを使ってください。
 
-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"
+```
+
+動作:
+
+- 選択した音声チャンネルを現在のテキストチャンネル/スレッドに紐付けます。
+- 現在のテキストチャンネルにプロジェクトセッションがない場合、アドホックな分離セッションを作成します。
+- 音声 STT/結果/進捗/最終回答テキストは、そのアクティブなプロジェクト文字起こし先へルーティングされます。
+
+既存の名前付きプロジェクトセッションを紐付けるには:
+
+```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.
+これはルーティングには便利ですが、1 つのボットを同時に 2 つの音声チャンネルへ常駐させるものではありません。同時に永続常駐させるには、複数のボットトークン/プロセスを使ってください。

package/docs/i18n/MULTI_INSTANCE.ko.md

@@ -1,50 +1,64 @@
-# VerbalCoding 멀티 인스턴스
+# Multi-instance 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.
+VerbalCoding은 여러 개의 독립적인 Discord 음성 브리지 프로세스를 실행할 수 있습니다. 각 프로세스는 여전히 기존 단일 인스턴스 Node 브리지이지만, 서로 다른 `instances/<name>.env` 파일을 로드하고 서로 다른 Discord 봇 토큰을 사용합니다.
 
-Use this when each project should permanently occupy its own Discord voice channel and write to its own transcript channel/thread.
+각 프로젝트가 자체 Discord 음성 채널을 영구적으로 차지하고 자체 전사 채널/스레드에 기록해야 할 때 사용하세요.
 
-## 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.
+Discord 음성 상주는 사실상 길드당 봇 계정 하나에 활성 음성 연결 하나입니다. 같은 길드에서 하나의 봇 토큰이 다른 음성 채널에 참가하면 이전 채널에 영구 연결된 상태를 동시에 유지할 수 없습니다. 동시에 여러 프로젝트 방을 쓰려면 프로젝트마다 Discord 애플리케이션/봇을 하나씩 만드세요.
 
-## File layout
+## 파일 배치
 
 ```text
 instances/
   README.md
   example.env
-  llm-wiki.env        # local only, ignored by git
-  verbalcoding.env    # local only, ignored by git
+  llm-wiki.env        # 로컬 전용, git에서 무시됨
+  verbalcoding.env    # 로컬 전용, git에서 무시됨
 .run/instances/
-  llm-wiki.pid        # runtime only, ignored by git
+  llm-wiki.pid        # 런타임 전용, git에서 무시됨
 ```
 
-Real `instances/*.env` files are ignored because they may contain Discord tokens.
+실제 `instances/*.env` 파일은 Discord 토큰을 포함할 수 있으므로 무시됩니다. `instances/example.env`가 커밋된 템플릿입니다.
 
-## Instance setup wizard
+## 인스턴스 설정 마법사
+
+일반 사용자는 env 파일을 복사해 수동으로 편집하지 않아도 됩니다. 대신 마법사를 실행하세요:
 
 ```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.
+마법사는 봇 토큰, Discord Application/Client ID, 음성 채널, 전사 대상, workdir, 프로젝트 컨텍스트, 격리된 런타임 경로를 묻습니다. mode `0600`으로 `instances/<name>.env`를 작성하고, 덮어쓰기 전에 기존 파일을 백업하며, 다음 start/status 명령을 출력합니다.
 
-Generate invite URLs with:
+설정 중 Discord Application/Client ID를 입력하면 요약에 해당 봇의 초대 URL도 출력됩니다. 같은 URL은 언제든 다음으로 생성할 수 있습니다:
 
 ```bash
 vc bot invite <client-id>
 vc bot invite <client-id> --guild <guild-id>
 ```
 
-## Hermes profile isolation
+동시 음성 방마다 Developer Portal 애플리케이션/봇이 하나씩 필요한 점은 변하지 않지만, OAuth URL이나 권한 정수를 수동으로 만들 필요가 없습니다.
+
+### Hermes 프로필 격리
+
+각 인스턴스는 `~/.hermes/profiles/<name>`에 자체 Hermes home을 갖습니다. 따라서 memory, MEMORY.md, SOUL.md, 학습된 skill이 프로젝트 간에 새지 않습니다.
+
+`vc instance setup <name>`은 자동으로 다음을 수행합니다:
 
-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.
+- `hermes profile create <name> --clone-from default` 실행(현재 `~/.hermes`의 API 키와 모델은 가져오며, 세션과 메모리는 새로 시작),
+- 새 프로필의 `terminal.cwd`를 인스턴스 workdir로 설정,
+- 마법사의 프로젝트 컨텍스트 답변으로 `<profile>/SOUL.md` 초기화,
+- `instances/<name>.env`에 `HERMES_HOME=...` 작성.
 
-`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}$`.
+`vc instance start <name>`은 자가 복구를 수행합니다. env가 더 이상 존재하지 않는 Hermes 프로필 디렉터리를 가리키면, 시작 명령은 실행 전에 해당 프로필을 다시 만듭니다.
 
-## Minimal generated instance env
+Hermes가 이름을 디렉터리 및 설정 키로 사용하므로 인스턴스 이름은 `^[a-z0-9][a-z0-9_-]{0,63}$`와 일치해야 합니다.
+
+## 최소 생성 인스턴스 env
 
 ```env
 INSTANCE_NAME=my-project
@@ -62,9 +76,9 @@ 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.
+모든 인스턴스에 로그/디버그/세션 파일의 고유 값을 부여하세요. `HERMES_HOME`과 일치하는 `~/.hermes/profiles/<name>` 디렉터리는 `vc instance setup`이 자동으로 만듭니다. `vc doctor`는 비밀 정보를 출력하지 않고 중복 토큰, 충돌하는 런타임 경로, 누락된 프로필 디렉터리, 프로필과 인스턴스 사이의 `terminal.cwd` 불일치를 확인합니다.
 
-## Commands
+## 명령
 
 ```bash
 vc instance list
@@ -75,47 +89,91 @@ vc instance stop my-project
 vc instance restart my-project
 ```
 
-## Example: two permanent voice rooms
+`start`는 `./run.sh instances/<name>.env`를 분리 실행하고 `.run/instances/<name>.pid`를 작성합니다.
+
+`stop`은 `SIGTERM`을 보내고 최대 10초간 기다린 뒤, 필요하면 `SIGKILL`로 폴백하고 pid 파일을 제거합니다.
+
+## 예시: 두 개의 영구 음성 방
 
-1. Create two Discord applications/bots.
-2. Invite both with text and voice permissions. Use `vc bot invite <client-id>`.
-3. Run setup:
+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. 각 로컬 인스턴스에 대해 설정 마법사를 실행합니다:
 
 ```bash
 vc instance setup verbalcoding
 vc instance setup llm-wiki
 ```
 
-4. Check and start:
+마법사는 mode `0600`으로 git에서 무시되는 `instances/verbalcoding.env` 및 `instances/llm-wiki.env` 파일을 작성합니다. 또한 기존 인스턴스 env를 교체하기 전에 백업합니다. 각 실행은 기본 Hermes home에서 복제한 `~/.hermes/profiles/<name>`도 생성하므로, 두 인스턴스는 같은 인증/모델로 시작하지만 각 프로젝트를 학습하면서 독립적인 메모리와 skill을 축적합니다.
+
+4. 설정을 확인합니다:
 
 ```bash
 vc doctor
+```
+
+5. 둘 다 시작합니다:
+
+```bash
 vc instance start verbalcoding
 vc instance start llm-wiki
 vc instance status
 ```
 
-5. Verify logs:
+6. 로그를 확인합니다:
 
 ```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
+7. 둘 다 중지합니다:
+
+```bash
+vc instance stop verbalcoding
+vc instance stop llm-wiki
+```
+
+## 단기 단일 봇 텍스트/음성 바인딩
+
+봇 토큰이 하나뿐이라면 동시 다중 채널 상주 대신 프로젝트 세션 음성 바인딩을 사용하세요.
 
-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"
+```
+
+동작:
+
+- 선택한 음성 채널을 현재 텍스트 채널/스레드에 바인딩합니다.
+- 현재 텍스트 채널에 프로젝트 세션이 없으면 임시 격리 세션을 만듭니다.
+- 음성 STT/결과/진행/최종 답변 텍스트가 해당 활성 프로젝트 전사 대상으로 라우팅됩니다.
+
+기존 이름 있는 프로젝트 세션을 연결하려면:
+
+```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

@@ -1,14 +1,14 @@
-# VerbalCoding Мульти-инстансы
+# Многоэкземплярный 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.
+VerbalCoding может запускать несколько независимых процессов голосового bridge Discord. Каждый процесс всё ещё является существующим одноэкземплярным Node bridge, но загружает другой файл `instances/<name>.env` и использует другой токен Discord-бота.
 
-Use this when each project should permanently occupy its own Discord voice channel and write to its own transcript channel/thread.
+Используйте это, когда каждый проект должен постоянно занимать собственный голосовой канал Discord и писать в собственный канал/тред расшифровок.
 
-## 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.
+Присутствие в голосе Discord фактически ограничено одним активным голосовым подключением на аккаунт бота в пределах guild. Если один токен бота подключается к другому голосовому каналу в той же guild, он не может одновременно оставаться постоянно подключённым к предыдущему каналу. Для одновременных проектных комнат создавайте по одному приложению/боту Discord на проект.
 
-## File layout
+## Структура файлов
 
 ```text
 instances/
@@ -20,31 +20,45 @@ instances/
   llm-wiki.pid        # runtime only, ignored by git
 ```
 
-Real `instances/*.env` files are ignored because they may contain Discord tokens.
+Настоящие файлы `instances/*.env` игнорируются, потому что могут содержать токены Discord. `instances/example.env` — закоммиченный шаблон.
 
-## Instance setup wizard
+## Мастер настройки экземпляра
+
+Пользователям не следует копировать и вручную редактировать env-файлы для обычного использования. Вместо этого запустите мастер:
 
 ```bash
 vc instance setup llm-wiki
+# or through the project setup script:
 ./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.
+Мастер запрашивает токен бота, Discord Application/Client ID, голосовой канал, цель расшифровок, workdir, контекст проекта и изолированные runtime-пути. Он записывает `instances/<name>.env` с режимом `0600`, создаёт резервную копию существующего файла перед перезаписью и печатает следующие команды start/status.
 
-Generate invite URLs with:
+Если во время настройки вы введёте Discord Application/Client ID, сводка также напечатает URL приглашения для этого бота. Тот же URL можно сгенерировать в любое время:
 
 ```bash
 vc bot invite <client-id>
 vc bot invite <client-id> --guild <guild-id>
 ```
 
-## Hermes profile isolation
+Discord всё равно требует одно приложение/бота Developer Portal на каждую одновременную голосовую комнату, но это избавляет от ручной сборки OAuth URL или целых чисел разрешений.
+
+### Изоляция профилей Hermes
+
+Каждый экземпляр получает собственный home Hermes в `~/.hermes/profiles/<name>`, чтобы память, MEMORY.md, SOUL.md и изученные skills не перетекали между проектами.
+
+`vc instance setup <name>` автоматически:
 
-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.
+- запускает `hermes profile create <name> --clone-from default` (переносит API-ключи и модель из текущего `~/.hermes`; сессии и память начинаются заново),
+- задаёт `terminal.cwd` нового профиля в workdir экземпляра,
+- заполняет `<profile>/SOUL.md` из ответа мастеру о контексте проекта,
+- записывает `HERMES_HOME=...` в `instances/<name>.env`.
 
-`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}$`.
+`vc instance start <name>` самовосстанавливается: если env указывает на директорию профиля Hermes, которой больше нет, команда start пересоздаёт её перед запуском.
 
-## Minimal generated instance env
+Имена экземпляров должны соответствовать `^[a-z0-9][a-z0-9_-]{0,63}$`, потому что Hermes использует имя как директорию и ключ конфигурации.
+
+## Минимальный сгенерированный env экземпляра
 
 ```env
 INSTANCE_NAME=my-project
@@ -62,9 +76,9 @@ 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.
+Дайте каждому экземпляру уникальные значения для файлов логов/debug/session. `HERMES_HOME` и соответствующая директория `~/.hermes/profiles/<name>` создаются автоматически командой `vc instance setup`. `vc doctor` проверяет повторяющиеся токены, конфликтующие runtime-пути, отсутствующие директории профилей и несоответствия `terminal.cwd` между профилем и экземпляром — всё это без печати секретов.
 
-## Commands
+## Команды
 
 ```bash
 vc instance list
@@ -75,47 +89,91 @@ vc instance stop my-project
 vc instance restart my-project
 ```
 
-## Example: two permanent voice rooms
+`start` запускает `./run.sh instances/<name>.env` в detached-режиме и записывает `.run/instances/<name>.pid`.
+
+`stop` отправляет `SIGTERM`, ждёт до 10 секунд, затем откатывается к `SIGKILL` и удаляет pid-файл.
+
+## Пример: две постоянные голосовые комнаты
 
-1. Create two Discord applications/bots.
-2. Invite both with text and voice permissions. Use `vc bot invite <client-id>`.
-3. Run setup:
+1. Создайте два приложения/бота Discord:
+   - бот VerbalCoding
+   - бот LLM-Wiki
+
+2. Пригласите обоих на сервер с текстовыми и голосовыми разрешениями:
+   - Просмотр канала
+   - Отправка сообщений
+   - Отправка сообщений в тредах
+   - Чтение истории сообщений
+   - Использование команд приложения
+   - Подключение
+   - Речь
+
+   Используйте `vc bot invite <client-id>` после создания каждого приложения Discord, чтобы напечатать точный URL приглашения с этими разрешениями.
+
+3. Запустите мастер настройки для каждого локального экземпляра:
 
 ```bash
 vc instance setup verbalcoding
 vc instance setup llm-wiki
 ```
 
-4. Check and start:
+Мастер записывает игнорируемые файлы `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
 ```
 
-5. Verify logs:
+6. Проверьте логи:
 
 ```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
+7. Остановите оба:
+
+```bash
+vc instance stop verbalcoding
+vc instance stop llm-wiki
+```
+
+## Краткосрочная привязка текста/голоса с одним ботом
+
+Если у вас есть только один токен бота, используйте привязку голоса проектной сессии вместо одновременного присутствия в нескольких каналах.
 
-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"
+```
+
+Поведение:
+
+- Привязывает выбранный голосовой канал к текущему текстовому каналу/треду.
+- Если в текущем текстовом канале нет проектной сессии, создаёт ad-hoc изолированную сессию.
+- Текст voice STT/result/progress/final-answer направляется в активную цель расшифровок проекта.
+
+Чтобы привязать существующую именованную проектную сессию:
+
+```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.
+Это удобно для маршрутизации, но не заставляет одного бота одновременно оставаться в двух голосовых каналах. Для одновременного постоянного присутствия используйте несколько токенов/процессов ботов.