verbalcoding 0.2.5 → 0.2.7

package/docs/i18n/FRESH_INSTALL.ru.md

@@ -0,0 +1,124 @@
+# Чистая установка
+
+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
+
+```bash
+npm install -g verbalcoding
+vc setup --yes
+```
+
+Or run the published package directly:
+
+```bash
+npx verbalcoding setup --yes
+```
+
+Contributor clone path:
+
+```bash
+git clone https://github.com/ca1773130n/VerbalCoding.git
+cd VerbalCoding
+./scripts/install.sh --yes
+```
+
+## 2. Bootstrap dependencies
+
+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`.
+
+Useful variants:
+
+```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
+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.
+
+## 3. Discord application setup
+
+Read the upstream bot guides first:
+
+- 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>
+
+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:
+
+```bash
+vc bot invite <discord-client-id>
+vc bot invite <discord-client-id> --guild <guild-id>
+```
+
+## 4. Verify
+
+```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.
+
+## 5. Run
+
+```bash
+vc start
+# or, from a GitHub clone:
+./run.sh
+```
+
+Expected log lines:
+
+```text
+Logged in as <bot-name>
+Listening in voice channel <server> / <channel>
+```
+
+In Discord:
+
+```text
+!ping
+!join
+!ask say hello briefly
+!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.
+
+## 6. Project-per-room setup
+
+For one permanent bot per project voice room, create one Discord application per project, then:
+
+```bash
+vc instance setup my-project
+vc bot invite <that-project-client-id>
+vc instance start my-project
+vc instance status my-project
+```
+
+## 7. Optional OpenVoice setup
+
+Keep `TTS_BACKEND=edge` for a fresh install. To enable OpenVoice later:
+
+```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
+```
+
+Then set `TTS_BACKEND=openvoice`, run `vc doctor`, and test `!voice-test <text>` in Discord.
+
+## 8. Maintainer smoke tests
+
+```bash
+./scripts/install.sh --yes --no-wizard
+npm pack --dry-run
+vc doctor || true
+./scripts/docker_ubuntu_smoke.sh
+```

package/docs/i18n/FRESH_INSTALL.zh.md

@@ -0,0 +1,124 @@
+# 全新安装
+
+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
+
+```bash
+npm install -g verbalcoding
+vc setup --yes
+```
+
+Or run the published package directly:
+
+```bash
+npx verbalcoding setup --yes
+```
+
+Contributor clone path:
+
+```bash
+git clone https://github.com/ca1773130n/VerbalCoding.git
+cd VerbalCoding
+./scripts/install.sh --yes
+```
+
+## 2. Bootstrap dependencies
+
+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`.
+
+Useful variants:
+
+```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
+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.
+
+## 3. Discord application setup
+
+Read the upstream bot guides first:
+
+- 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>
+
+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:
+
+```bash
+vc bot invite <discord-client-id>
+vc bot invite <discord-client-id> --guild <guild-id>
+```
+
+## 4. Verify
+
+```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.
+
+## 5. Run
+
+```bash
+vc start
+# or, from a GitHub clone:
+./run.sh
+```
+
+Expected log lines:
+
+```text
+Logged in as <bot-name>
+Listening in voice channel <server> / <channel>
+```
+
+In Discord:
+
+```text
+!ping
+!join
+!ask say hello briefly
+!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.
+
+## 6. Project-per-room setup
+
+For one permanent bot per project voice room, create one Discord application per project, then:
+
+```bash
+vc instance setup my-project
+vc bot invite <that-project-client-id>
+vc instance start my-project
+vc instance status my-project
+```
+
+## 7. Optional OpenVoice setup
+
+Keep `TTS_BACKEND=edge` for a fresh install. To enable OpenVoice later:
+
+```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
+```
+
+Then set `TTS_BACKEND=openvoice`, run `vc doctor`, and test `!voice-test <text>` in Discord.
+
+## 8. Maintainer smoke tests
+
+```bash
+./scripts/install.sh --yes --no-wizard
+npm pack --dry-run
+vc doctor || true
+./scripts/docker_ubuntu_smoke.sh
+```

package/docs/i18n/MULTI_INSTANCE.es.md

@@ -0,0 +1,121 @@
+# VerbalCoding Multiinstancia
+
+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.
+
+Use this when each project should permanently occupy its own Discord voice channel and write to its own transcript channel/thread.
+
+## 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.
+
+## File layout
+
+```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
+```
+
+Real `instances/*.env` files are ignored because they may contain Discord tokens.
+
+## Instance setup wizard
+
+```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.
+
+Generate invite URLs with:
+
+```bash
+vc bot invite <client-id>
+vc bot invite <client-id> --guild <guild-id>
+```
+
+## Hermes profile isolation
+
+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.
+
+`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}$`.
+
+## Minimal generated instance 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
+```
+
+`vc doctor` checks duplicate tokens, colliding runtime paths, missing profile directories, and `terminal.cwd` mismatches without printing secrets.
+
+## Commands
+
+```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
+```
+
+## Example: two permanent voice rooms
+
+1. Create two Discord applications/bots.
+2. Invite both with text and voice permissions. Use `vc bot invite <client-id>`.
+3. Run setup:
+
+```bash
+vc instance setup verbalcoding
+vc instance setup llm-wiki
+```
+
+4. Check and start:
+
+```bash
+vc doctor
+vc instance start verbalcoding
+vc instance start llm-wiki
+vc instance status
+```
+
+5. Verify logs:
+
+```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
+
+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"
+!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.fr.md

@@ -0,0 +1,121 @@
+# VerbalCoding Multi-instance
+
+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.
+
+Use this when each project should permanently occupy its own Discord voice channel and write to its own transcript channel/thread.
+
+## 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.
+
+## File layout
+
+```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
+```
+
+Real `instances/*.env` files are ignored because they may contain Discord tokens.
+
+## Instance setup wizard
+
+```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.
+
+Generate invite URLs with:
+
+```bash
+vc bot invite <client-id>
+vc bot invite <client-id> --guild <guild-id>
+```
+
+## Hermes profile isolation
+
+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.
+
+`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}$`.
+
+## Minimal generated instance 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
+```
+
+`vc doctor` checks duplicate tokens, colliding runtime paths, missing profile directories, and `terminal.cwd` mismatches without printing secrets.
+
+## Commands
+
+```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
+```
+
+## Example: two permanent voice rooms
+
+1. Create two Discord applications/bots.
+2. Invite both with text and voice permissions. Use `vc bot invite <client-id>`.
+3. Run setup:
+
+```bash
+vc instance setup verbalcoding
+vc instance setup llm-wiki
+```
+
+4. Check and start:
+
+```bash
+vc doctor
+vc instance start verbalcoding
+vc instance start llm-wiki
+vc instance status
+```
+
+5. Verify logs:
+
+```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
+
+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"
+!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.ja.md

@@ -0,0 +1,121 @@
+# 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.
+
+Use this when each project should permanently occupy its own Discord voice channel and write to its own transcript channel/thread.
+
+## 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.
+
+## File layout
+
+```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
+```
+
+Real `instances/*.env` files are ignored because they may contain Discord tokens.
+
+## Instance setup wizard
+
+```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.
+
+Generate invite URLs with:
+
+```bash
+vc bot invite <client-id>
+vc bot invite <client-id> --guild <guild-id>
+```
+
+## Hermes profile isolation
+
+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.
+
+`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}$`.
+
+## Minimal generated instance 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
+```
+
+`vc doctor` checks duplicate tokens, colliding runtime paths, missing profile directories, and `terminal.cwd` mismatches without printing secrets.
+
+## Commands
+
+```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
+```
+
+## Example: two permanent voice rooms
+
+1. Create two Discord applications/bots.
+2. Invite both with text and voice permissions. Use `vc bot invite <client-id>`.
+3. Run setup:
+
+```bash
+vc instance setup verbalcoding
+vc instance setup llm-wiki
+```
+
+4. Check and start:
+
+```bash
+vc doctor
+vc instance start verbalcoding
+vc instance start llm-wiki
+vc instance status
+```
+
+5. Verify logs:
+
+```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
+
+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"
+!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.