verbalcoding 0.2.12 → 0.2.13

package/docs/HARNESS_HERMES.md

@@ -0,0 +1,57 @@
+# Hermes Agent — Harness Notes
+
+<p align="center">
+  <a href="../README.md">README</a> ·
+  <a href="HARNESSES.md">Harnesses</a> ·
+  <a href="USAGE.md">Usage</a> ·
+  <a href="CONFIGURATION.md">Configuration</a>
+</p>
+
+Hermes Agent is VerbalCoding's default backend — it is the one harness with a real session-resume contract, so chat across turns retains context cleanly. For positioning vs Hermes' built-in `/voice` slash command, see [HERMES_VOICE.md](./HERMES_VOICE.md).
+
+## Install
+
+Follow the upstream Hermes Agent install guide: <https://hermes-agent.nousresearch.com>.
+
+Verify the CLI works directly first:
+
+```bash
+hermes chat -Q -q "hello"
+```
+
+## Configure VerbalCoding
+
+```bash
+# .env
+AGENT_BACKEND=hermes
+# optional overrides
+HERMES_COMMAND="hermes chat -Q -q"           # default
+HERMES_HOME=/Users/you/.hermes               # per-instance Hermes home
+HERMES_PROJECT_CONTEXT="Project session: ..."
+HERMES_TASK_TIMEOUT_MS=0                     # 0 = no limit
+HERMES_CHAT_TIMEOUT_MS=45000
+HERMES_WORKDIR=/Users/you/code/your-project
+```
+
+The session file lives at `<repo>/.verbalcoding-session` by default (override with `HERMES_SESSION_FILE`).
+
+## Session resume
+
+Hermes is the only built-in adapter with session resume. After each successful turn the adapter writes the new `session_id` to disk and prepends `--resume <id>` to the next call. `!session reset` (or `!reset-session`) clears that file.
+
+If a turn aborts before Hermes emits `session_id:` on stderr, the adapter also reads the Hermes session JSON at `~/.hermes/sessions/session_<id>.json` to recover the last assistant message.
+
+## Verbose progress
+
+In verbose mode the adapter drops Hermes' `-Q` quiet flag so stdout streams `┊ <emoji> <tool>` previews. These get summarized into one-line progress events (file reads, web search, terminal). Without verbose, only the final boxed answer plays.
+
+## Voice phrases to switch TO Hermes
+
+- en: `"switch to Hermes"`, `"ask Hermes ..."`
+- ko: `"헤르메스로 전환"`, `"헤르메스한테 물어봐"`
+
+## Gotchas
+
+- The TTS prefix on cross-agent handoff uses the localized label: `"Hermes says: "` / `"헤르메스: "`.
+- `HERMES_HOME` is the most common per-project isolation knob; per-instance `.env` typically sets `HERMES_HOME=/Users/you/.hermes/profiles/<project>`.
+- If verbose progress is on and Hermes still finishes with an empty box (timed out), the adapter scrapes the session JSON for the final assistant text before giving up.

package/docs/HARNESS_OPENCLAW.md

@@ -0,0 +1,44 @@
+# OpenClaw — Harness Notes
+
+<p align="center">
+  <a href="../README.md">README</a> ·
+  <a href="HARNESSES.md">Harnesses</a> ·
+  <a href="USAGE.md">Usage</a> ·
+  <a href="CONFIGURATION.md">Configuration</a>
+</p>
+
+OpenClaw is an open-source terminal coding agent. VerbalCoding drives it through `openclaw run`.
+
+## Install
+
+Follow the upstream OpenClaw install guide. Confirm:
+
+```bash
+openclaw run "hello"
+```
+
+## Configure VerbalCoding
+
+```bash
+# .env
+AGENT_BACKEND=openclaw
+# optional
+OPENCLAW_COMMAND="openclaw run"             # default
+AGENT_PROJECT_CONTEXT="..."
+AGENT_WORKDIR=/Users/you/code/your-project
+AGENT_CHAT_TIMEOUT_MS=45000
+AGENT_TASK_TIMEOUT_MS=0
+```
+
+## Voice phrases to switch TO OpenClaw
+
+- en: `"switch to OpenClaw"`, `"ask OpenClaw ..."`, `"switch to open claw"`
+- ko: `"openclaw로 전환"`
+
+The matcher accepts `openclaw` and `open claw`.
+
+## Gotchas
+
+- **No session resume** in the default command. Add a resume flag via `OPENCLAW_COMMAND` if your build supports one.
+- **Verbose progress.** Same as OpenCode — keyword-based labels unless `SMART_PROGRESS_API_KEY` is configured for the LLM summarizer.
+- **Naming clash.** Both the parser alias `openclaw` and the user-facing label `OpenClaw` are distinct from `claude` / `claude code`; the strict-mode router won't conflate them.

package/docs/HARNESS_OPENCODE.md

@@ -0,0 +1,44 @@
+# OpenCode — Harness Notes
+
+<p align="center">
+  <a href="../README.md">README</a> ·
+  <a href="HARNESSES.md">Harnesses</a> ·
+  <a href="USAGE.md">Usage</a> ·
+  <a href="CONFIGURATION.md">Configuration</a>
+</p>
+
+OpenCode is an open-source terminal coding agent. VerbalCoding drives it through `opencode run`.
+
+## Install
+
+Follow the upstream OpenCode install guide. Confirm:
+
+```bash
+opencode run "hello"
+```
+
+## Configure VerbalCoding
+
+```bash
+# .env
+AGENT_BACKEND=opencode
+# optional
+OPENCODE_COMMAND="opencode run"             # default
+AGENT_PROJECT_CONTEXT="..."
+AGENT_WORKDIR=/Users/you/code/your-project
+AGENT_CHAT_TIMEOUT_MS=45000
+AGENT_TASK_TIMEOUT_MS=0
+```
+
+## Voice phrases to switch TO OpenCode
+
+- en: `"switch to OpenCode"`, `"ask OpenCode ..."`, `"switch to open code"`
+- ko: `"opencode로 전환"`, `"오픈코드로 전환"`
+
+The matcher accepts `opencode` and `open code`.
+
+## Gotchas
+
+- **No session resume** in the default command. If your OpenCode build supports a resume flag, append it via `OPENCODE_COMMAND="opencode run --resume"` (the adapter passes the prompt as the final positional arg).
+- **Model choice.** Append `--model` flags via `OPENCODE_COMMAND` if your OpenCode build expects them.
+- **Verbose progress.** Whatever events OpenCode prints on stdout/stderr get keyword-matched (file reads, web search, terminal); without `SMART_PROGRESS_API_KEY` the bridge falls back to those raw labels.

package/docs/README.md

@@ -29,6 +29,7 @@ vc start
 | [Usage](USAGE.md) | CLI commands, Discord commands, run modes, voice changes, progress, and latency metrics. |
 | [Hermes Voice vs VerbalCoding](HERMES_VOICE.md) | What Hermes built-in Discord voice already does and what VerbalCoding adds. |
 | [Configuration](CONFIGURATION.md) | `.env`, agent backends, MCP server, TTS backends, and operational settings. |
+| [TTS Backends](TTS_BACKENDS.md) | Optional local/cloud TTS backends, aliases, latency observations, and Mac mini caveats. |
 | [Troubleshooting](TROUBLESHOOTING.md) | Docker UDP, voice join failures, missing token/channel checks, and doctor behavior. |
 | [Multi-Instance](MULTI_INSTANCE.md) | One permanent Discord voice bot per project room with isolated Hermes profiles. |
 | [Release Notes](RELEASE.md) | Current capabilities, verification checklist, and pre-public-release gaps. |

package/docs/ROADMAP.md

@@ -8,11 +8,11 @@ This roadmap covers five differentiation phases that separate VerbalCoding from
 
 | # | Phase | Status | Plan |
 |---|---|---|---|
-| 1 | Streaming end-to-end pipeline | designed | [phase1-streaming-pipeline.md](./superpowers/plans/2026-05-13-phase1-streaming-pipeline.md) |
-| 2 | Agent-agnostic adapter completion | partial → designed | [phase2-agent-adapters.md](./superpowers/plans/2026-05-13-phase2-agent-adapters.md) |
-| 6 | Smart progress summarization | designed | [phase6-smart-progress.md](./superpowers/plans/2026-05-13-phase6-smart-progress.md) |
-| 7 | Voice plan mode | designed | [phase7-voice-plan-mode.md](./superpowers/plans/2026-05-13-phase7-voice-plan-mode.md) |
-| 10 | Push notification handoff | designed | [phase10-push-notifications.md](./superpowers/plans/2026-05-13-phase10-push-notifications.md) |
+| 1 | Streaming end-to-end pipeline | shipped | [phase1-streaming-pipeline.md](./superpowers/plans/2026-05-13-phase1-streaming-pipeline.md) |
+| 2 | Agent-agnostic adapter completion | shipped (incl. cross-agent voice routing) | [phase2-agent-adapters.md](./superpowers/plans/2026-05-13-phase2-agent-adapters.md), [cross-agent-voice-transfer.md](./superpowers/plans/2026-05-14-cross-agent-voice-transfer.md) |
+| 6 | Smart progress summarization | shipped | [phase6-smart-progress.md](./superpowers/plans/2026-05-13-phase6-smart-progress.md) |
+| 7 | Voice plan mode | shipped (incl. `which_agent` slot) | [phase7-voice-plan-mode.md](./superpowers/plans/2026-05-13-phase7-voice-plan-mode.md) |
+| 10 | Push notification handoff | shipped | [phase10-push-notifications.md](./superpowers/plans/2026-05-13-phase10-push-notifications.md) |
 
 ## Sequencing rationale
 
@@ -36,3 +36,18 @@ This roadmap covers five differentiation phases that separate VerbalCoding from
 - PSTN bridge / actual phone calls (Phase 4 of the broader pitch; deferred).
 - Local-first one-flag preset (Phase 5; deferred but trivial follow-up).
 - Multi-agent in one VC with distinct voices (Phase 3; needs Phase 2 to land first).
+
+## What's next (2026 H2 candidates)
+
+The differentiation push above shipped — the foundation is in. Candidate next phases, not yet planned:
+
+| # | Candidate | Why | Status |
+|---|---|---|---|
+| 11 | Push-to-talk and wake-word v2 | Reduce false barge-ins in shared rooms; pair with hardware push-to-talk via a Discord overlay or a key-binding companion. | candidate |
+| 12 | Multi-user voice in one VC | Each speaker resolves to a distinct routing/session; per-speaker plan-mode and decision answers. Builds on the per-channel routing state. | candidate |
+| 13 | Output voice cloning per agent | Distinct voices per backend (e.g. Codex gets a different TTS voice than Claude Code); piggybacks on the existing voice-clone capture flow. | candidate |
+| 14 | Latency benchmarking + regression gate | Codify the latency_metrics output into a benchmark harness + CI threshold so any regression in STT/agent/TTS stages is caught. | candidate |
+| 15 | Phone-app companion (deferred) | The push-handoff notification deeplinks back to Discord today; a thin phone app or PWA could replay a redacted transcript on demand. | candidate |
+| 16 | Voice-clone reference auto-detect | Detect that an OpenVoice/FireRedTTS reference sample is missing and propose `!voice-clone capture` proactively when the user selects a clone-only backend. | candidate |
+
+These aren't sequenced yet. Phases 11/12/14 are the highest-leverage if the goal is making the bridge feel solid in shared rooms; 13/16 are quality-of-life on top of the existing voice stack.

package/docs/TTS_BACKENDS.md

@@ -0,0 +1,227 @@
+# TTS backends and latency notes
+
+This document captures the current VerbalCoding TTS backends, the live-selection rules, and the latency caveats observed while testing on the current Mac mini.
+
+## Current test machine
+
+Observed host for these notes:
+
+- Machine: Mac mini, Apple M4
+- Memory: 16 GB
+- OS: macOS 26.3 / Darwin 25.3.0 arm64
+- Workload caveat: several measurements were taken while other heavy local processes or model-training jobs could be active. Treat local neural TTS timings as operational observations, not clean benchmarks.
+
+## Operational rule
+
+Edge TTS is the default safe live backend. Local neural backends are optional and should normally fall back to Edge for progress prompts unless explicitly enabled with each backend's `*_PROGRESS=1` setting.
+
+When a user explicitly asks to switch to a specific backend, update both:
+
+```bash
+TTS_BACKEND=<backend>
+TTS_VOICE_TYPE=<voice-type>
+```
+
+and `config/tts-voices.json`:
+
+```json
+{
+  "currentBackend": "<backend>",
+  "currentVoiceType": "<voice-type>"
+}
+```
+
+The runtime re-reads voice config, so changing only `.env` can be overridden.
+
+### Fallback notice
+
+When a non-Edge backend fails to synthesize (model missing, runtime crash, timeout, install error), the bridge silently re-routes that utterance through Edge so the user still hears a response. The first time this happens for each backend in a session, VerbalCoding posts a one-shot warning to the active Discord text channel and speaks the same message ("`<backend>` synthesis failed; using Edge for the rest of this session." / "`<backend>` 음성 생성에 실패해서 이번 세션은 Edge로 진행할게."). Subsequent failures for the same backend stay silent.
+
+If you see the warning, check `vc doctor` and the backend's venv/model install — the bridge will keep using Edge until the next `vc start`.
+
+## Supported backends
+
+| Backend | Purpose | Default path / command | Live-call suitability | Notes |
+|---|---|---|---|---|
+| `edge` | Free cloud TTS baseline | `edge-tts` | Best current default | Korean and English voices, fast enough for phone-call mode, progress cache works well. |
+| `openvoice` | Reference-sample voice cloning | `integrations/openvoice/synth.py` | Experimental | Requires permitted reference audio. Progress falls back to Edge unless `OPENVOICE_PROGRESS=1`. |
+| `speechswift` | Apple Silicon local CosyVoice / Qwen3 wrapper | `audio speak ...` | Experimental | CosyVoice is usable for demos but not as responsive as Edge; Qwen3 path is much slower. |
+| `supertonic` | Local Supertonic CLI wrapper | `supertonic tts ...` | Experimental | Supports voice IDs such as `M1`; falls back to Edge on failure. |
+| `omnivoice` | OmniVoice local reference/design voice | `.venv-omnivoice/bin/python integrations/omnivoice/synth.py` | Experimental | Startup/model load can feel hung. Keep Edge for live mode unless explicitly testing. |
+| `qwen3tts` | Qwen3 TTS via `audio` CLI | `audio speak --engine qwen3 ...` | Slow experimental | Correct backend name is `qwen3tts` / alias `qwen3`; do not use old `q13` aliases. |
+| `mlxaudio` | MLX Audio Qwen3 wrapper | `.venv-mlxaudio/bin/python integrations/mlxaudio/synth.py` | Experimental | Uses MLX Qwen3 model defaults; validate actual audible output, not only file existence. |
+| `neuttsair` | NeuTTS-Air English reference cloning | `.venv-neuttsair/bin/python integrations/neuttsair/synth.py` | Too slow for current live use | English-only in practice. Q4 GGUF lowers latency but still felt unusably slow under contention. |
+| `fireredtts2` | FireRedTTS-2 prompt-reference backend | `./.local/bin/fireredtts2` | Slow experimental | Can stall restart/final TTS long enough to feel broken. Honor explicit user selection, but report slowness instead of silently reverting. |
+| FireRedTTS-2 MLX helper | Apple Silicon FireRed LLM-port experiment | `integrations/fireredtts2/synth_mlx.py` | Not wired as canonical backend yet | Ports the FireRed LLM token generator to MLX/Metal while keeping RedCodec in Torch; intended to avoid upstream Torch Qwen hangs/slowness. |
+| `mossttsnano` | OpenMOSS / MOSS-TTS-Nano PyTorch backend | `.venv-mossttsnano/bin/python vendor/MOSS-TTS-Nano/infer.py` | Very slow experimental | On macOS use Python 3.11 venv and `--disable-wetext-processing`. |
+| `mossttsnano_mlx` | MOSS-TTS-Nano hybrid MLX port | `.venv-mossttsnano/bin/python integrations/mossttsnano_mlx/synth.py` | Active experiment, not live default | Native MLX generator, KV cache, and persistent JSON-line worker were added. Still verify audibility and tokenizer/model parity. |
+
+## Backend aliases
+
+Accepted aliases normalize to canonical backend names:
+
+| Alias examples | Canonical backend |
+|---|---|
+| `qwen3`, `qwen3-tts`, `qtts` | `qwen3tts` |
+| `mlx`, `mlx-audio`, `qwen3-mlx` | `mlxaudio` |
+| `neutts`, `neutts-air`, `neu tts air` | `neuttsair` |
+| `firered`, `fireredtts`, `firered-tts-2` | `fireredtts2` |
+| `moss`, `moss-tts`, `mossnano`, `openmoss` | `mossttsnano` |
+| `moss-mlx`, `mossttsnano-mlx`, `openmoss-mlx` | `mossttsnano_mlx` |
+
+## Observed latency
+
+### End-to-end voice loop log
+
+From `.logs/latency.jsonl`, 160 successful voice turns were available. These measure the whole Discord voice loop, not just TTS:
+
+| Stage | Median | P90 | Min | Max |
+|---|---:|---:|---:|---:|
+| STT | 3.81 s | 4.60 s | 0.75 s | 23.70 s |
+| Agent call | 16.90 s | 209.74 s | 5.58 s | 825.90 s |
+| TTS synth | 3.98 s | 12.77 s | 0.72 s | 760.73 s |
+| TTS playback | 19.50 s | 47.16 s | 0.99 s | 90.36 s |
+| TTS total | 23.14 s | 62.28 s | 1.90 s | 782.89 s |
+| Voice capture | 11.66 s | 30.02 s | 3.20 s | 109.10 s |
+| Utterance idle wait | 2.60 s | 4.50 s | 2.60 s | 4.54 s |
+| Total turn | 69.06 s | 289.56 s | 20.99 s | 905.24 s |
+
+Interpretation:
+
+- Long perceived latency is often not only TTS. Agent work and spoken playback length dominate many turns.
+- A high TTS-synth max indicates local/experimental TTS can stall badly under load or fallback paths.
+- Playback time is real audio duration, so long answers sound slow even if synthesis is fast.
+- The idle wait is intentionally a few seconds to avoid cutting off Korean phone-call utterances.
+
+### Local neural TTS observations
+
+| Backend / mode | Observed behavior on this Mac mini | Practical conclusion |
+|---|---|---|
+| Edge TTS | Usually low seconds for chunks; reliable enough for current live mode. | Keep as default/fallback. |
+| SpeechSwift CosyVoice CLI | About 6.9 s wall time for a 1.68 s Korean sample after warm-up. | Demo-capable, but sluggish for conversation. |
+| SpeechSwift audio-server | Warm short Korean requests varied around 4.5-7.7 s and sometimes hung. | Not safe as the always-on live backend yet. |
+| SpeechSwift/Qwen3 | About 62.5 s wall time, first chunk around 47.6 s in prior testing. | Too slow for live phone-call mode. |
+| NeuTTS Air | Produced valid WAVs, but felt unusably slow while the machine was under unrelated GPU/model load. | English-only experiment; use Edge for live answers. |
+| FireRedTTS-2 | Can be slow enough that restart/final TTS appears stalled. Timeout is 180 s by default. | Useful to test, but report slowness clearly. |
+| FireRedTTS-2 MLX helper | Added as an Apple Silicon experiment that moves the LLM token generator to MLX/Metal and keeps RedCodec encode/decode in Torch. | Not a production backend yet; verify dependencies, imports, generated frames, and decoded volume before wiring it to `TTS_BACKEND`. |
+| MOSS-TTS-Nano PyTorch | Works as an OpenMOSS path but is very slow on macOS. | Keep as correctness baseline, not live default. |
+| MOSS-TTS-Nano MLX | Added native generator, sampling fixes, KV cache, and persistent worker; can reduce repeated startup overhead. | Still experimental; verify audible volume and parity before live use. |
+
+## MOSS-TTS-Nano MLX status
+
+Recent implementation work added:
+
+- `integrations/mossttsnano_mlx/convert.py` for conversion experiments.
+- `integrations/mossttsnano_mlx/gpt2_mlx.py` for a native MLX GPT2-like generator.
+- `integrations/mossttsnano_mlx/synth.py` for the hybrid synthesis path.
+- `integrations/mossttsnano_mlx/worker.py` for a persistent JSON-line worker.
+- `MOSSTTSNANO_MLX_WORKER=1` to keep the worker hot between requests.
+- KV cache and sampling-semantics fixes in the MLX generator.
+
+Known caution:
+
+- A generated WAV is not enough. Check audibility with playback or `ffmpeg volumedetect`.
+- Near-silent or strange audio usually means model/tokenizer/audio-code parity is still wrong.
+- Keep the PyTorch MOSS path as a reference until MLX parity is proven.
+
+## Configuration examples
+
+### Safe live default
+
+```bash
+TTS_BACKEND=edge
+TTS_VOICE_TYPE=korean_male
+TTS_VOICE=ko-KR-InJoonNeural
+TTS_RATE=+10%
+```
+
+### Qwen3 TTS preset
+
+```bash
+TTS_BACKEND=qwen3tts
+TTS_VOICE_TYPE=korean_preset
+QWEN3TTS_COMMAND=audio
+QWEN3TTS_MODE=custom
+QWEN3TTS_MODEL=customVoice
+QWEN3TTS_LANGUAGE=korean
+QWEN3TTS_SPEAKER=sohee
+QWEN3TTS_PROGRESS=0
+```
+
+### NeuTTS Air English experiment
+
+```bash
+TTS_BACKEND=neuttsair
+TTS_VOICE_TYPE=cloned_reference
+VOICE_LANGUAGE=en
+STT_LANGUAGE=en
+WHISPER_CPP_LANGUAGE=en
+NEUTTSAIR_PYTHON=./.venv-neuttsair/bin/python
+NEUTTSAIR_SCRIPT=integrations/neuttsair/synth.py
+NEUTTSAIR_BACKBONE_REPO=neuphonic/neutts-air-q4-gguf
+NEUTTSAIR_CODEC_REPO=neuphonic/neucodec
+NEUTTSAIR_PROGRESS=0
+```
+
+### FireRedTTS-2 experiment
+
+```bash
+TTS_BACKEND=fireredtts2
+TTS_VOICE_TYPE=prompt_reference
+FIREREDTTS2_COMMAND=./.local/bin/fireredtts2
+FIREREDTTS2_PRETRAINED_DIR=./pretrained_models/FireRedTTS2
+FIREREDTTS2_PROMPT_AUDIO=./voice-samples/user-reference.wav
+FIREREDTTS2_PROGRESS=0
+```
+
+### MOSS-TTS-Nano PyTorch experiment
+
+```bash
+TTS_BACKEND=mossttsnano
+TTS_VOICE_TYPE=prompt_reference
+MOSSTTSNANO_COMMAND=./.venv-mossttsnano/bin/python
+MOSSTTSNANO_SCRIPT=vendor/MOSS-TTS-Nano/infer.py
+MOSSTTSNANO_CHECKPOINT=OpenMOSS-Team/MOSS-TTS-Nano
+MOSSTTSNANO_PROMPT_AUDIO=./voice-samples/user-reference.wav
+MOSSTTSNANO_PROGRESS=0
+```
+
+### MOSS-TTS-Nano MLX worker experiment
+
+```bash
+TTS_BACKEND=mossttsnano_mlx
+TTS_VOICE_TYPE=prompt_reference
+MOSSTTSNANO_MLX_PYTHON=./.venv-mossttsnano/bin/python
+MOSSTTSNANO_MLX_SCRIPT=integrations/mossttsnano_mlx/synth.py
+MOSSTTSNANO_MLX_WORKER=1
+MOSSTTSNANO_MLX_WORKER_SCRIPT=integrations/mossttsnano_mlx/worker.py
+MOSSTTSNANO_TORCH_DEVICE=cpu
+MOSSTTSNANO_TORCH_DTYPE=float32
+MOSSTTSNANO_PROMPT_AUDIO=./voice-samples/user-reference.wav
+MOSSTTSNANO_MLX_PROGRESS=0
+```
+
+## How to benchmark safely
+
+Use a quiet machine, short fixed text, and separate synthesis from playback:
+
+```bash
+vc doctor
+node --test app-node/tts_backends.test.mjs app-node/tts_settings.test.mjs app-node/tts_voice_config.test.mjs
+```
+
+For live logs, compare these fields in `.logs/latency.jsonl`:
+
+- `stt_ms`: speech-to-text time.
+- `agent_ms`: CLI agent time.
+- `tts_synth_ms`: time to synthesize audio files.
+- `tts_play_ms`: time spent playing generated audio.
+- `total_ms`: full turn time.
+
+When testing local neural backends, also verify:
+
+```bash
+ffmpeg -i output.wav -af volumedetect -f null -
+```
+
+A non-empty file can still be inaudible or near-silent.

package/docs/USAGE.md

@@ -107,6 +107,28 @@ Then use `vc bot invite CLIENT_ID` to generate the VerbalCoding-specific invite
 
 Voice equivalents such as “외부 모드”, “보수 모드”, “실내”, “기본 감도”, and clear stop phrases like “잠깐”, “멈춰”, “그만” are handled by the bridge. You can also say “상세 진행 켜” / “상세 진행 꺼” to toggle verbose progress by voice.
 
+## Cross-agent voice routing
+
+VerbalCoding can route a single turn (or the rest of the session) to a different installed CLI agent without restarting.
+
+| Voice phrase (en) | Voice phrase (ko) | Behavior |
+|---|---|---|
+| `ask Codex what it thinks` | `코덱스한테 물어봐` | Single-turn route to Codex; next utterance returns to the default. |
+| `switch to Aider` | `aider로 전환` | Sticky route — every following utterance goes to Aider. |
+| `back to default` | `기본으로 돌아가` | Restore the default agent (`AGENT_BACKEND` / `vc setup` selection). |
+| `let Claude finish this` | — | Treated as sticky route to Claude Code. |
+
+Recognized aliases: `hermes`, `claude` / `claude code`, `codex` / `코덱스`, `gemini` / `gemini cli` / `제미나이`, `opencode`, `openclaw`, `aider` / `에이더`, `cursor` / `cursor cli`.
+
+Behaviors on top:
+
+- **Missing-binary fallback** — if the requested backend's binary is not on `PATH` (resolved against the active project session's workdir when applicable), the bridge asks "Want me to use the default agent instead?" Answer "yes" / "예" to retry on the default; "no" / "아니오" to cancel.
+- **TTS prefix on backend change** — when the active backend changes between turns, the spoken answer is prefixed (`Codex says: …` / `코덱스: …`). No prefix on stable backends.
+- **Cross-agent context handoff** — the routed agent receives a prompt block containing the prior agent label, recent voice utterances (last 4), and the most recently resolved plan decisions, so it doesn't restart cold.
+- **Plan-mode `which_agent` slot** — plans can include a `which_agent` decision listing CLI options (e.g. `codex, aider, claude, gemini, opencode, openclaw, cursor, hermes`); the user's voice answer selects which agent executes that plan.
+- **Per-channel state** — routing is scoped per Discord channel; switching agents in one project room does not affect others.
+- **Sticky survives interrupts** — barge-in or aborted turns keep a sticky route intact; only single-turn routes are cleared.
+
 ## Changing the Voice
 
 `vc language ko|en|auto` changes STT language, progress language, and the matching default TTS voice together. If you only want to change the speaker/voice while the bridge is running, say it in Discord voice:

package/docs/i18n/AGENTS.es.md

@@ -0,0 +1,34 @@
+# Guía del repositorio (español)
+
+> Este fichero es un resumen en español de [`AGENTS.md`](../../AGENTS.md). Las reglas formales viven en el inglés original.
+
+VerbalCoding es un puente de voz Discord para agentes de codificación. El runtime es la implementación Node en `app-node/`, lanzada vía `run.sh` o el CLI `vc`.
+
+## Desarrollo
+
+- En docs y ejemplos prefiere `vc ...` sobre `npm run vc -- ...`.
+- Los secretos locales viven en `.env` o `instances/*.env`; nunca commits con tokens Discord, IDs de canal, ficheros de sesión, muestras de voz, pesos de modelo, virtualenvs, logs ni cachés.
+- Edita ficheros fuente, no artefactos generados.
+- Ejemplos públicos: usa placeholders para rutas locales, IDs de usuario, IDs Discord y tokens.
+
+## Verificación
+
+Antes de marcar un cambio como completo, ejecuta:
+
+```bash
+npm test
+```
+
+## Layout de módulos
+
+Detalle en [`AGENTS.md`](../../AGENTS.md). Módulos clave:
+
+- `main.mjs` — dispatcher Discord / voz / agente
+- `agent_routing.mjs` — enrutamiento entre agentes por voz
+- `plan_mode.mjs` — modo plan por voz (slot `which_agent`)
+- `session_ontology.mjs` — grafo tipado por canal (handoff)
+- `research_mode.mjs` — comando `"research X"`
+
+## Bloque gestionado
+
+HarnessSync sincroniza las reglas de `CLAUDE.md` dentro de `AGENTS.md`. No edites manualmente ese bloque.

package/docs/i18n/AGENTS.fr.md

@@ -0,0 +1,34 @@
+# Guide du dépôt (français)
+
+> Ce fichier est un résumé français de [`AGENTS.md`](../../AGENTS.md). Les règles formelles restent dans l'original anglais.
+
+VerbalCoding est un pont vocal Discord pour les agents de codage. Le runtime est l'implémentation Node sous `app-node/`, lancée via `run.sh` ou le CLI `vc`.
+
+## Développement
+
+- Dans les docs et exemples, préférez `vc ...` à `npm run vc -- ...`.
+- Les secrets locaux vivent dans `.env` ou `instances/*.env`; ne commitez jamais de vrais tokens Discord, IDs de salon, fichiers de session, échantillons vocaux, poids de modèle, virtualenvs, logs ni caches.
+- Modifiez les fichiers source, pas les artefacts générés.
+- Exemples publics-safe : placeholders pour chemins locaux, IDs utilisateur, IDs Discord, tokens.
+
+## Vérification
+
+Avant de signaler un changement comme terminé, exécutez:
+
+```bash
+npm test
+```
+
+## Cartographie des modules
+
+Détail dans [`AGENTS.md`](../../AGENTS.md). Modules clés :
+
+- `main.mjs` — dispatcher Discord / voix / agent
+- `agent_routing.mjs` — routage inter-agent par voix
+- `plan_mode.mjs` — mode plan vocal (slot `which_agent`)
+- `session_ontology.mjs` — graphe typé par salon (handoff)
+- `research_mode.mjs` — commande `"research X"`
+
+## Bloc géré
+
+HarnessSync synchronise les règles de `CLAUDE.md` dans `AGENTS.md`. Ne pas éditer manuellement ce bloc.

package/docs/i18n/AGENTS.ja.md

@@ -0,0 +1,34 @@
+# リポジトリガイドライン (日本語)
+
+> 本ファイルは [`AGENTS.md`](../../AGENTS.md) の日本語要約です。正式なルールは英語の本文を参照してください。
+
+VerbalCoding はコーディングエージェント向けの Discord 音声ブリッジです。実装は `app-node/` 配下の Node 実装で、`run.sh` または `vc` CLI 経由で起動します。
+
+## 開発
+
+- ドキュメント / サンプルでは `vc ...` を `npm run vc -- ...` より優先してください。
+- ローカルシークレットは `.env` または `instances/*.env` に置き、実 Discord トークン、チャンネル ID、セッションファイル、音声サンプル、モデル重み、venv、ログ、キャッシュ出力はコミットしないでください。
+- 自動生成物ではなくソースファイルを編集してください。
+- サンプルは公開しても安全な値で。ローカルパス、ユーザー ID、Discord ID、トークンはプレースホルダで。
+
+## 検証
+
+コード変更を完了とする前に Node テストを走らせてください:
+
+```bash
+npm test
+```
+
+## モジュール構成
+
+詳細は [`AGENTS.md`](../../AGENTS.md) を参照。主要モジュール:
+
+- `main.mjs` — Discord / 音声 / エージェントのディスパッチャ
+- `agent_routing.mjs` — 音声主導のクロスエージェントルーティング
+- `plan_mode.mjs` — 音声プランモード(`which_agent` スロット)
+- `session_ontology.mjs` — チャネル単位の typed graph(handoff 用)
+- `research_mode.mjs` — `"research X"` 音声コマンドパイプライン
+
+## 管理ブロック
+
+HarnessSync が `AGENTS.md` に `CLAUDE.md` のルールを同期します。当該ブロックは編集しないでください。

package/docs/i18n/AGENTS.ko.md

@@ -0,0 +1,34 @@
+# 저장소 가이드라인 (한국어)
+
+> 이 파일은 [`AGENTS.md`](../../AGENTS.md)의 한국어 요약입니다. 정식 규칙은 원본 영어 문서를 따라주세요.
+
+VerbalCoding은 코딩 에이전트용 Discord 음성 브릿지입니다. 실제 런타임은 `app-node/` 하위 Node 구현체이고, `run.sh` 또는 `vc` CLI로 실행합니다.
+
+## 개발
+
+- 문서·예제에서는 `npm run vc -- ...` 보다 `vc ...` 형태를 우선 사용합니다.
+- 로컬 비밀은 `.env` 또는 `instances/*.env`에만 두고 절대 커밋하지 마세요. 실제 Discord 토큰, 채널 ID, 세션 파일, 음성 샘플, 모델 가중치, 가상환경, 로그, 캐시 출력도 마찬가지입니다.
+- 생성물/런타임 산출물 대신 소스 파일을 수정합니다.
+- 예제는 공개 안전한 값으로 유지합니다. 로컬 경로, 사용자 ID, Discord ID, 토큰은 플레이스홀더로.
+
+## 검증
+
+코드 변경을 완료로 보고하기 전에 Node 테스트 스위트를 실행하세요:
+
+```bash
+npm test
+```
+
+## 모듈 맵
+
+자세한 내용은 [`AGENTS.md`](../../AGENTS.md)를 참고하세요. 핵심 모듈:
+
+- `main.mjs` — Discord/음성/에이전트 디스패처
+- `agent_routing.mjs` — 음성 기반 크로스 에이전트 라우팅
+- `plan_mode.mjs` — 음성 플랜 모드 (which_agent 슬롯)
+- `session_ontology.mjs` — 채널별 타입드 그래프 (cross-agent 핸드오프 컨텍스트)
+- `research_mode.mjs` — `"리서치 X"` 음성 명령 파이프라인
+
+## 관리되는 영역
+
+HarnessSync가 `AGENTS.md`에 `CLAUDE.md`의 규칙을 자동 동기화합니다. 그 블록은 손대지 마세요.

package/docs/i18n/AGENTS.ru.md

@@ -0,0 +1,34 @@
+# Руководство по репозиторию (русский)
+
+> Этот файл — русское резюме [`AGENTS.md`](../../AGENTS.md). Формальные правила — в оригинале на английском.
+
+VerbalCoding — голосовой мост Discord для кодинг-агентов. Рантайм — Node-реализация в `app-node/`, запускается через `run.sh` или CLI `vc`.
+
+## Разработка
+
+- В документации и примерах предпочитайте `vc ...`, а не `npm run vc -- ...`.
+- Локальные секреты — в `.env` или `instances/*.env`. Не коммитьте реальные Discord-токены, channel ID, session-файлы, голосовые сэмплы, веса моделей, venv, логи, кеши.
+- Правьте исходные файлы, а не сгенерированные артефакты.
+- Примеры — публично-безопасные: плейсхолдеры для локальных путей, user ID, Discord ID, токенов.
+
+## Проверка
+
+Перед тем как считать изменения готовыми, запустите:
+
+```bash
+npm test
+```
+
+## Карта модулей
+
+Подробности в [`AGENTS.md`](../../AGENTS.md). Ключевые модули:
+
+- `main.mjs` — диспетчер Discord / голос / агенты
+- `agent_routing.mjs` — голосовая маршрутизация между агентами
+- `plan_mode.mjs` — голосовой plan-mode (слот `which_agent`)
+- `session_ontology.mjs` — типизированный граф на канал (handoff)
+- `research_mode.mjs` — голосовая команда `"research X"`
+
+## Управляемый блок
+
+HarnessSync синхронизирует правила из `CLAUDE.md` в управляемый блок `AGENTS.md`. Не редактируйте этот блок вручную.

package/docs/i18n/AGENTS.zh.md

@@ -0,0 +1,34 @@
+# 仓库指南 (中文)
+
+> 本文是 [`AGENTS.md`](../../AGENTS.md) 的中文摘要。正式规则以英文原文为准。
+
+VerbalCoding 是面向编码代理的 Discord 语音桥。运行时位于 `app-node/`,通过 `run.sh` 或 `vc` CLI 启动。
+
+## 开发
+
+- 文档与示例优先使用 `vc ...` 形式,而不是 `npm run vc -- ...`。
+- 本地密钥放在 `.env` 或 `instances/*.env`,不要提交真实 Discord token、频道 ID、会话文件、语音样本、模型权重、虚拟环境、日志、缓存。
+- 修改源文件而非自动生成物。
+- 示例保持公开安全:本地路径、用户 ID、Discord ID、token 用占位符替代。
+
+## 验证
+
+报告完成前请运行 Node 测试:
+
+```bash
+npm test
+```
+
+## 模块布局
+
+详情见 [`AGENTS.md`](../../AGENTS.md)。核心模块:
+
+- `main.mjs` — Discord / 语音 / 代理调度器
+- `agent_routing.mjs` — 语音驱动的跨代理路由
+- `plan_mode.mjs` — 语音 plan 模式 (`which_agent` 槽)
+- `session_ontology.mjs` — 按频道的类型图 (用于 handoff)
+- `research_mode.mjs` — `"research X"` 语音命令流程
+
+## 托管区域
+
+HarnessSync 会把 `CLAUDE.md` 的规则同步进 `AGENTS.md` 的托管块,请勿手动修改该块。