verbalcoding 0.2.0

package/docs/CONFIGURATION.md

@@ -0,0 +1,183 @@
+# VerbalCoding Configuration
+
+## Setup Wizard
+
+```bash
+./scripts/install.sh
+```
+
+The installer asks for Discord token, allowed users, auto-join voice channel names, transcript channel/thread, CLI harness backend, default voice language, TTS settings, and wake-word behavior. It writes `.env` with mode `0600`; `.env` is ignored by git. It also links the short shell command `vc`.
+
+If you only need the shell command after manual install:
+
+```bash
+npm link
+```
+
+## Supported Agent Backends
+
+Set `AGENT_BACKEND` in `.env`.
+
+| Backend | Default command | Notes |
+|---|---|---|
+| `hermes` | `hermes chat -Q -q` | Default. Preserves `.verbalcoding-session` resume behavior. |
+| `claude-code` / `claude` | `claude -p` | Override with `CLAUDE_COMMAND` or `AGENT_COMMAND`. |
+| `codex` | `codex exec` | Override with `CODEX_COMMAND` or `AGENT_COMMAND`. |
+| `gemini` | `gemini -p` | Override with `GEMINI_COMMAND` or `AGENT_COMMAND`. |
+| `opencode` | `opencode run` | Override with `OPENCODE_COMMAND` or `AGENT_COMMAND`. |
+| `openclaw` | `openclaw run` | Override with `OPENCLAW_COMMAND` or `AGENT_COMMAND`. |
+| `custom` | required `AGENT_COMMAND` | Prompt is appended as the final argv argument. |
+
+Generic overrides:
+
+```bash
+AGENT_BACKEND=custom
+AGENT_LABEL="My Harness"
+AGENT_COMMAND="my-harness run --non-interactive"
+AGENT_TASK_TIMEOUT_MS=0
+AGENT_CHAT_TIMEOUT_MS=45000
+AGENT_VERBOSE_PROGRESS=0
+UTTERANCE_IDLE_MS=2000
+LATENCY_LOG_PATH=./.logs/latency.jsonl
+```
+
+## Agent Adapter Contract
+
+The voice bridge talks to every backend through one adapter contract:
+
+- `run({ text }, signal, plan)` returns status, final answer text, backend label, elapsed time, and optional session metadata.
+- `ask(text, signal, plan)` is the compatibility shortcut that returns only final answer text.
+- `capabilities` declares whether the backend supports session resume, streaming progress, and cancellation.
+- Hermes is the reference adapter: resume, verbose progress streaming, cancellation, and final-answer recovery from Hermes session files.
+
+New backends should implement the same contract and keep voice/STT/TTS behavior outside the adapter.
+
+## Example `.env`
+
+```bash
+DISCORD_BOT_TOKEN="***"
+DISCORD_ALLOWED_USERS="123456789012345678"
+AUTO_JOIN_VOICE_CHANNELS="일반,General,general"
+TRANSCRIPT_CHANNEL_ID="123456789012345678"
+
+AGENT_BACKEND="hermes"
+STT_ENGINE="whisper_cpp"
+WHISPER_CPP_BIN="whisper-cli"
+WHISPER_CPP_MODEL="./models/ggml-small-q5_1.bin"
+
+TTS_BACKEND="edge"
+TTS_VOICE="ko-KR-SunHiNeural"
+TTS_RATE="+10%"
+TTS_MAX_CHARS="495"
+TTS_VOLUME="1.0"
+
+REQUIRE_WAKE_WORD="0"
+MIN_UTTERANCE_SECONDS="1.0"
+UTTERANCE_IDLE_MS="2000"
+HERMES_TASK_TIMEOUT_MS="0"
+HERMES_CHAT_TIMEOUT_MS="45000"
+AGENT_VERBOSE_PROGRESS="0"
+LATENCY_LOG_PATH="./.logs/latency.jsonl"
+```
+
+## MCP Server
+
+VerbalCoding ships a stdio MCP server so Hermes Agent or any MCP client can control the bridge through tools instead of relying on skills or free-form shell commands.
+
+Hermes config example:
+
+```yaml
+mcp_servers:
+  verbalcoding:
+    command: "node"
+    args: ["/path/to/VerbalCoding/scripts/mcp-server.mjs"]
+    timeout: 120
+    connect_timeout: 30
+```
+
+Exposed MCP tools:
+
+| Tool | Purpose |
+|---|---|
+| `status` | Report bridge/config status without secrets |
+| `doctor` | Run the redacted doctor check |
+| `set_auto_restart` | Enable/disable commit-time voice-bot auto-restart |
+| `set_language` | Update STT/progress/TTS language together |
+| `start`, `stop`, `restart` | Control the Discord voice bridge |
+
+## Optional OpenVoice TTS
+
+Edge TTS remains the default and fallback. To try local voice cloning with OpenVoice V2:
+
+```bash
+./scripts/setup_openvoice.sh
+# Download checkpoints_v2_0417.zip from OpenVoice docs and extract under vendor/OpenVoice/checkpoints_v2/
+mkdir -p voice-samples
+# Put a permitted reference sample at voice-samples/user-reference.wav,
+# or capture one from Discord with !voice-clone capture.
+python3 scripts/openvoice_smoke.py
+```
+
+Then set:
+
+```bash
+TTS_BACKEND="openvoice"
+OPENVOICE_REF_AUDIO="./voice-samples/user-reference.wav"
+OPENVOICE_PROGRESS="0"
+```
+
+Only clone voices you own or have permission to use. If OpenVoice fails or times out, VerbalCoding falls back to Edge TTS.
+
+## Optional Supertonic TTS
+
+```bash
+./scripts/setup_supertonic.sh
+supertonic tts '안녕하세요. 수퍼토닉 테스트입니다.' --lang ko --voice M1 --steps 2 --speed 1.0 -o /tmp/verbalcoding-supertonic.wav
+```
+
+Then set:
+
+```bash
+TTS_BACKEND="supertonic"
+SUPERTONIC_COMMAND="./.venv-supertonic/bin/supertonic"
+SUPERTONIC_VOICE="M1"
+SUPERTONIC_LANGUAGE="ko"
+SUPERTONIC_STEPS="2"
+SUPERTONIC_SPEED="1.0"
+SUPERTONIC_PROGRESS="0"
+```
+
+If Supertonic is missing, fails, or times out, VerbalCoding falls back to Edge TTS.
+
+## Optional SpeechSwift / CosyVoice TTS
+
+On Apple Silicon, `speech-swift` is a local backend for Korean voice cloning with MLX-native CosyVoice/Qwen3-TTS.
+
+```bash
+brew tap soniqo/speech https://github.com/soniqo/speech-swift
+brew install speech
+```
+
+Recommended env:
+
+```bash
+TTS_BACKEND="speechswift"
+SPEECHSWIFT_MODE="server"
+SPEECHSWIFT_ENGINE="cosyvoice"
+SPEECHSWIFT_LANGUAGE="korean"
+SPEECHSWIFT_REF_AUDIO="./voice-samples/user-reference.wav"
+SPEECHSWIFT_SERVER_HOST="127.0.0.1"
+SPEECHSWIFT_SERVER_PORT="18080"
+SPEECHSWIFT_SERVER_URL="http://127.0.0.1:18080"
+SPEECHSWIFT_PROGRESS="0"
+```
+
+Keep Edge for quick progress/backchannel prompts.
+
+## Operational Notes
+
+- Bot needs Discord privileged Message Content intent enabled for text commands.
+- Bot needs voice channel connect/speak permissions.
+- For Hermes Agent, configure/authenticate Hermes normally (`hermes setup`, `hermes login`, etc.) on your default profile.
+- For Claude Code, Codex, Gemini, OpenCode, OpenClaw, install and authenticate those CLIs separately.
+- If a CLI emits diff/code output on timeout or signal failure, the bridge avoids reading it aloud and sends detailed text instead.

package/docs/FRESH_INSTALL.md

@@ -0,0 +1,193 @@
+# Fresh install
+
+This guide is for a clean public install. It avoids local-only assumptions and uses the installer to bootstrap as much as possible.
+
+## 1. Install the CLI
+
+Recommended npm path:
+
+```bash
+npm install -g verbalcoding
+```
+
+Or run the published package directly:
+
+```bash
+npx verbalcoding setup --yes
+```
+
+If you used `npm install -g`, continue with:
+
+```bash
+vc setup --yes
+```
+
+Contributor GitHub clone path:
+
+```bash
+git clone https://github.com/ca1773130n/VerbalCoding.git
+cd VerbalCoding
+./scripts/install.sh --yes
+```
+
+## 2. Bootstrap dependencies and run the setup wizard
+
+The npm commands above run the same bootstrapper as the clone install. For a clone, run:
+
+```bash
+./scripts/install.sh --yes
+```
+
+What this does:
+
+- installs npm dependencies when `node_modules/` is missing,
+- installs the short `vc` shell command with `npm link`,
+- installs `ffmpeg`, Node/npm, and `whisper-cli` when supported by the OS package manager,
+- downloads `models/ggml-small-q5_1.bin`,
+- creates `.venv-tts` and installs `edge-tts` when `edge-tts` is not already on `PATH`,
+- runs the interactive `.env` wizard.
+
+Supported system bootstrap paths:
+
+| OS | System dependency path |
+|---|---|
+| macOS | Homebrew: `brew install node ffmpeg whisper-cpp` as needed |
+| Debian/Ubuntu | `apt-get` for Node/npm, ffmpeg, Python, build tools; local whisper.cpp build fallback |
+| Fedora/RHEL | `dnf` for Node/npm, ffmpeg, Python, build tools; local whisper.cpp build fallback |
+| Arch | `pacman` for Node/npm, ffmpeg, Python, build tools; local whisper.cpp build fallback |
+
+Useful installer variants:
+
+```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
+```
+
+If your OS is unsupported, install these manually before rerunning:
+
+- Node.js 20+ and npm
+- ffmpeg
+- Python 3 with venv/pip
+- whisper.cpp `whisper-cli`
+- one authenticated CLI agent backend, Hermes Agent by default
+
+## 3. Discord application setup
+
+1. Create a Discord application and bot in the Discord Developer Portal.
+2. Enable the Message Content privileged intent.
+3. Copy the bot token into the installer prompt or `.env` as `DISCORD_BOT_TOKEN`.
+4. Generate an invite URL:
+
+```bash
+vc bot invite <discord-client-id>
+# or pin it to one server:
+vc bot invite <discord-client-id> --guild <guild-id>
+```
+
+The invite includes bot and slash-command scopes plus text/voice permissions used by VerbalCoding.
+
+## 4. Verify
+
+```bash
+vc doctor
+```
+
+`vc doctor` is redacted: it reports missing tokens/commands/models without printing secret values. Fix every `✗` item, then rerun it.
+
+Expected success includes:
+
+```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.
+```
+
+If the installer created a local Edge TTS helper, `.env` should contain an `EDGE_TTS_COMMAND` path pointing at `.venv-tts/bin/edge-tts`.
+
+## 5. Run the single default bot
+
+```bash
+vc start
+# or, from a GitHub clone:
+./run.sh
+```
+
+Successful startup logs include:
+
+```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
+```
+
+Each instance writes an ignored `instances/<name>.env` with its own token, voice channel, transcript target, log path, Hermes session file, and optional Hermes profile.
+
+## 7. Optional OpenVoice setup
+
+OpenVoice voice cloning is optional. Keep `TTS_BACKEND=edge` for a fresh public 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 scripts/openvoice_smoke.py
+```
+
+Then set `TTS_BACKEND=openvoice`, run `vc doctor`, and test `!voice-test <text>` in Discord.
+
+## 8. Clean clone smoke test for maintainers
+
+Fast host-only smoke test:
+
+```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
+```
+
+The expected failure at this point is missing local secrets or unauthenticated agent CLI, not leaked tokens or missing install scripts.
+
+Docker-based Ubuntu clean install smoke test:
+
+```bash
+./scripts/docker_ubuntu_smoke.sh
+```
+
+This runs `ubuntu:24.04`, copies the tracked repository tree into a clean container, runs `./scripts/install.sh --yes --no-wizard`, writes a non-secret smoke `.env`, checks `vc`, runs Node tests, and verifies `vc doctor`. It does not connect to Discord voice; use a real Ubuntu VM or WSL2 after this if you need an end-to-end voice-channel test.

package/docs/MULTI_INSTANCE.md

@@ -0,0 +1,183 @@
+# Multi-instance VerbalCoding
+
+VerbalCoding can run multiple independent Discord voice bridge processes. Each process is still the existing single-instance Node bridge, but it 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. If one bot token joins another voice channel in the same guild, it cannot also remain permanently connected to the previous channel. 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. `instances/example.env` is the committed template.
+
+## Instance setup wizard
+
+Users should not copy and manually edit env files for normal use. Run the wizard instead:
+
+```bash
+vc instance setup llm-wiki
+# or through the project setup script:
+./scripts/install.sh --instance llm-wiki
+```
+
+The wizard prompts for the 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`, backs up an existing file before overwriting it, and prints the next start/status commands.
+
+If you enter the Discord Application/Client ID during setup, the summary also prints the invite URL for that bot. You can generate the same URL any time with:
+
+```bash
+vc bot invite <client-id>
+vc bot invite <client-id> --guild <guild-id>
+```
+
+Discord still requires one Developer Portal application/bot per simultaneous voice room, but this avoids manually building OAuth URLs or permission integers.
+
+### Hermes profile isolation
+
+Each instance gets its own Hermes home at `~/.hermes/profiles/<name>` so that
+memory, MEMORY.md, SOUL.md, and learned skills do not leak across projects.
+
+`vc instance setup <name>` automatically:
+
+- runs `hermes profile create <name> --clone-from default` (carries API keys
+  and model from your current `~/.hermes`; sessions and memory start fresh),
+- sets the new profile's `terminal.cwd` to the instance workdir,
+- seeds `<profile>/SOUL.md` from the wizard's project-context answer,
+- writes `HERMES_HOME=...` into `instances/<name>.env`.
+
+`vc instance start <name>` self-heals: if the env points at a Hermes profile
+dir that no longer exists, the start command recreates it before launching.
+
+Instance names must match `^[a-z0-9][a-z0-9_-]{0,63}$` because Hermes uses the
+name as a directory and config key.
+
+## Minimal generated instance env
+
+```env
+INSTANCE_NAME=my-project
+DISCORD_TOKEN=replace-with-bot-token
+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
+```
+
+Give every instance unique values for log/debug/session files. `HERMES_HOME` and the matching `~/.hermes/profiles/<name>` directory are created automatically by `vc instance setup`. `vc doctor` checks for duplicate tokens, colliding runtime paths, missing profile directories, and `terminal.cwd` mismatches between profile and instance — all 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
+```
+
+`start` runs `./run.sh instances/<name>.env` detached and writes `.run/instances/<name>.pid`.
+
+`stop` sends `SIGTERM`, waits up to 10 seconds, then falls back to `SIGKILL` and removes the pid file.
+
+## Example: two permanent voice rooms
+
+1. Create two Discord applications/bots:
+   - VerbalCoding bot
+   - LLM-Wiki bot
+
+2. Invite both to the server with text and voice permissions:
+   - View Channel
+   - Send Messages
+   - Send Messages in Threads
+   - Read Message History
+   - Use Application Commands
+   - Connect
+   - Speak
+
+   Use `vc bot invite <client-id>` after creating each Discord application to print the exact invite URL with those permissions.
+
+3. Run the setup wizard for each local instance:
+
+```bash
+vc instance setup verbalcoding
+vc instance setup llm-wiki
+```
+
+The wizard writes ignored `instances/verbalcoding.env` and `instances/llm-wiki.env` files with mode `0600`; it also backs up an existing instance env before replacing it. Each run also creates `~/.hermes/profiles/<name>` cloned from your default Hermes home, so the two instances start with the same auth/model but accumulate independent memory and skills as they learn each project.
+
+4. Check config:
+
+```bash
+vc doctor
+```
+
+5. Start both:
+
+```bash
+vc instance start verbalcoding
+vc instance start llm-wiki
+vc instance status
+```
+
+6. Verify logs:
+
+```bash
+tail -n 50 /tmp/verbalcoding-verbalcoding.log
+tail -n 50 /tmp/verbalcoding-llm-wiki.log
+```
+
+Expected log lines:
+
+```text
+Listening in voice channel ... / VerbalCoding
+Listening in voice channel ... / LLM-Wiki
+```
+
+7. Stop both:
+
+```bash
+vc instance stop verbalcoding
+vc instance stop llm-wiki
+```
+
+## Short-term single-bot text/voice binding
+
+If you only have one bot token, use project-session voice binding instead of simultaneous multi-channel residency.
+
+Run this in the target text channel/thread:
+
+```text
+!session attach-voice --voice "LLM-Wiki"
+```
+
+Behavior:
+
+- Binds the selected voice channel to the current text channel/thread.
+- If the current text channel has no project session, creates an ad-hoc isolated session.
+- Voice STT/result/progress/final-answer text routes to that active project transcript target.
+
+To attach an existing named project session:
+
+```text
+!session voice llm-wiki --voice "LLM-Wiki"
+```
+
+This is convenient for routing, but it does not make one bot stay in two voice channels at the same time. Use multiple bot tokens/processes for simultaneous permanent residency.

package/docs/RELEASE.md

@@ -0,0 +1,72 @@
+# VerbalCoding release notes
+
+## Current release candidate
+
+VerbalCoding is a Discord voice bridge for controlling CLI-based coding agents by voice. It is public-release oriented, with macOS / Apple Silicon as the most tested path and best-effort Linux bootstrap support for common package managers.
+
+### Included
+
+- Discord voice receive via Node `@discordjs/voice`.
+- Local Korean STT via `whisper.cpp` + Metal.
+- Edge TTS playback with Korean default voice.
+- Generic CLI harness adapter layer:
+  - Hermes Agent
+  - Claude Code
+  - Codex CLI
+  - Gemini CLI
+  - OpenCode
+  - OpenClaw
+  - custom command
+- Shared voice/text session support for Hermes backend.
+- Long-answer TTS chunking and responsive barge-in.
+- Diff/code/log guardrails so large technical output is not read aloud.
+- Normal and conservative sensitivity modes for indoor vs. noisy/outdoor use.
+- Setup wizard, `.env.example`, `vc doctor` prerequisite checker, and `./scripts/install.sh --yes` bootstrap for OS packages, npm dependencies, Edge TTS helper, and the default whisper.cpp model.
+- Optional verbose progress mode for text-only middle-step updates during long agent work.
+- Always-on JSONL latency metrics plus `!latency` / `!metrics` summary for pipeline optimization.
+- Lower default utterance idle wait (`UTTERANCE_IDLE_MS=2000`) so STT starts about 0.6s sooner after speech ends.
+- Multi-instance Hermes profile isolation: `vc instance setup <name>` auto-clones a Hermes profile to `~/.hermes/profiles/<name>` with the instance workdir, seeds SOUL.md, and writes `HERMES_HOME` into the instance env so per-project memory and skills stay separate; `vc instance start` self-heals a missing profile, and `vc doctor` checks profile-dir presence and `terminal.cwd` consistency.
+
+### Pre-release checklist
+
+Run from the repo root:
+
+```bash
+./scripts/install.sh --yes --no-wizard
+./scripts/docker_ubuntu_smoke.sh   # requires Docker; validates ubuntu:24.04 clean install
+node --check app-node/main.mjs app-node/agent_adapters.mjs app-node/install_config.mjs scripts/install.mjs
+npm test
+PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 python3 -m pytest tests/ -q || [ $? -eq 5 ]  # ok when no Python tests exist
+bash -n run.sh scripts/install.sh scripts/bootstrap_prereqs.sh scripts/docker_ubuntu_smoke.sh
+vc doctor
+git diff --check
+```
+
+Manual smoke test:
+
+1. Start the bridge with `./run.sh`.
+2. Verify log contains `Logged in as Hermes#6718`.
+3. Verify log contains `Listening in voice channel ... / 일반` or the configured default channel.
+4. In Discord, run `!ping`.
+5. In Discord voice, say a short Korean request.
+6. Verify STT transcript, agent response, TTS playback, and barge-in behavior.
+
+### Known requirements
+
+- macOS with Homebrew, or Linux with `apt`, `dnf`, or `pacman` for best-effort bootstrap.
+- `ffmpeg`; installer attempts to install it.
+- `whisper-cli`; installer uses Homebrew on macOS or local `vendor/whisper.cpp` build fallback on Linux.
+- Default model at `models/ggml-small-q5_1.bin`; installer downloads it unless `--skip-model` is used.
+- Edge TTS CLI on `PATH` or local `.venv-tts/bin/edge-tts`; installer creates the local helper when needed.
+- Discord bot token in `.env`, `instances/<name>.env`, `~/.zshrc`, or runtime env.
+- Selected CLI harness installed and authenticated.
+
+### Not for public release yet
+
+Before public release, consider adding:
+
+- GitHub Actions CI.
+- Demo video / GIF.
+- Discord bot setup screenshots.
+- Broader Linux validation on real distributions beyond script-level checks.
+- Security review of all logging paths.