verbalcoding 0.2.11 → 0.2.12

package/docs/FRESH_INSTALL.md

@@ -1,116 +1,142 @@
 # 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.
+<!-- readme-glow-up:intro -->
+<p align="center">
+  <a href="../README.md">README</a> ·
+  <a href="README.md">Docs hub</a> ·
+  <a href="FRESH_INSTALL.md">Fresh Install</a> ·
+  <a href="USAGE.md">Usage</a> ·
+  <a href="CONFIGURATION.md">Configuration</a> ·
+  <a href="TROUBLESHOOTING.md">Troubleshooting</a> ·
+  <a href="MULTI_INSTANCE.md">Multi-Instance</a>
+</p>
 
-## 1. Install the CLI
+> Clean install path for humans first, automation second.
+>
+> Fast path: `npm install -g verbalcoding@latest → vc setup → vc doctor → vc start`
+<!-- /readme-glow-up:intro -->
 
-Recommended npm path:
+This guide is for a clean public install. It avoids local-only assumptions and uses the `vc` CLI to bootstrap as much as possible. Windows is not supported yet.
 
-```bash
-npm install -g verbalcoding
-```
+## 1. Install the CLI and run guided setup
 
-Or run the published package directly:
+Recommended npm path for humans:
 
 ```bash
-npx verbalcoding setup --yes
+npm install -g verbalcoding@latest
+vc setup
 ```
 
-If you used `npm install -g`, continue with:
+`vc setup` bootstraps supported local prerequisites, then asks for the Discord bot token, application/client ID, auto-join voice channel names, transcript target, agent backend, and voice/TTS settings. Keep the Discord Developer Portal open while it runs.
+
+Automation/CI path:
 
 ```bash
+npm install -g verbalcoding@latest
 vc setup --yes
+vc setup token <bot-token> --client-id <discord-client-id>
+vc setup channels "General,Team Voice"
 ```
 
+Use `--yes` only when you need non-interactive bootstrap/starter config. It cannot stop and wait for you to create a Discord application, so token/channel setup remains a follow-up step in that mode.
+
 Contributor GitHub clone path:
 
 ```bash
 git clone https://github.com/ca1773130n/VerbalCoding.git
 cd VerbalCoding
-./scripts/install.sh --yes
+./scripts/install.sh
 ```
 
-## 2. Bootstrap dependencies and run the setup wizard
-
-For an npm install, do not run `./scripts/install.sh` directly; there is no repository checkout in your current directory. Use the packaged CLI wrapper instead:
+For npm/global installs, use `vc ...` commands. Do not run `./scripts/install.sh` unless you are inside a repository clone.
 
-```bash
-vc setup --yes
-```
+## 2. What setup bootstraps
 
-`vc setup` runs the `scripts/install.sh` bundled inside the installed npm package. Only use `./scripts/install.sh --yes` when you are inside a GitHub clone:
+`vc setup` runs the bootstrap bundled in the npm package and writes `.env`. It can install or prepare:
 
-```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.
+- npm dependencies when `node_modules/` is missing,
+- `ffmpeg`, Node/npm, Python venv support, build tools, and `whisper-cli` where supported,
+- the default `models/ggml-small-q5_1.bin` whisper.cpp model,
+- a local `.venv-tts` Edge TTS helper,
+- the short `vc` shell command when running from a clone.
 
 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 |
+| Debian/Ubuntu | `apt-get`; handles NodeSource npm conflicts and can locally build whisper.cpp |
+| Fedora/RHEL | `dnf`; local whisper.cpp build fallback |
+| Arch | `pacman`; local whisper.cpp build fallback |
+| Windows | Not supported yet |
 
 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
+vc setup --yes --skip-system                 # skip OS package installation
+vc setup --yes --skip-model                  # skip default STT model download
+vc setup --yes --skip-edge-tts               # skip local Edge TTS helper
+./scripts/install.sh --yes --no-wizard       # clone-only non-interactive equivalent
 ```
 
-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 values collected by setup
 
-## 3. Discord application setup
-
-Read the upstream Discord bot setup guides first if this is your first bot:
+Read the upstream Discord bot setup guides if this is your first bot:
 
 - Hermes Agent Discord messaging 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>
 
-Those pages show how to create a Discord application, add a bot user, enable privileged intents, and invite it to a server. VerbalCoding uses the same Discord bot setup, then adds voice receive, STT, CLI-agent execution, and TTS playback on top.
+During `vc setup`:
 
-1. Create a Discord application and bot in the Discord Developer Portal.
+1. Create a Discord application/bot in the 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:
+3. Paste the bot token when asked for `DISCORD_BOT_TOKEN`.
+4. Paste the application/client ID when asked; setup can print the invite command.
+5. Enter the real voice channel names the bot should auto-join.
+
+Invite URL helper:
 
 ```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.
+If you skipped a value or need to rotate it later, update only that part:
+
+```bash
+vc setup token
+vc setup token <bot-token> --client-id <discord-client-id>
+vc setup channels "VerbalCoding,LLM-Wiki,General"
+```
+
+`vc setup token` updates `DISCORD_BOT_TOKEN` and optional `DISCORD_CLIENT_ID`; `vc setup channels` updates `AUTO_JOIN_VOICE_CHANNELS`. Both preserve unrelated `.env` values, set mode `0600`, and do not print secrets back.
 
-## 4. Verify
+## 4. Auto-join voice channel names
+
+Use the exact Discord voice channel names:
+
+```bash
+vc setup channels
+vc setup channels "General,Team Voice"
+vc setup channel "General"
+vc setup voice "General"
+```
+
+Restart the bridge after changing channel names.
+
+## 5. Verify
 
 ```bash
 vc doctor
 ```
 
-`vc doctor` is redacted: it reports missing tokens/commands/models without printing secret values. When fixable local prerequisites are missing (`ffmpeg`, `whisper-cli`, the default model, or Edge TTS helper), it automatically reruns the packaged bootstrap first. Fix any remaining `✗` items, then rerun it.
+`vc doctor` is redacted: it reports missing tokens/commands/models without printing secret values. On supported macOS/Linux installs it attempts to auto-fix installable prerequisites first, including `ffmpeg`, `whisper-cli`/model, Edge TTS helper, and Hermes CLI for the default Hermes backend. Use this opt-out if you only want diagnosis:
+
+```bash
+VERBALCODING_DOCTOR_INSTALL_HERMES=0 vc doctor
+```
 
 Expected success includes:
 
@@ -126,9 +152,9 @@ Expected success includes:
 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`.
+If `DISCORD_BOT_TOKEN` is missing, run `vc setup token`. If no configured channel is found, run `vc setup channels "<actual voice channel name>"`.
 
-## 5. Run the single default bot
+## 6. Run the single default bot
 
 ```bash
 vc start
@@ -154,7 +180,25 @@ In Discord:
 
 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
+## 7. Docker and containers
+
+Discord text/gateway login uses TCP/WebSocket, but Discord voice also needs UDP. If `vc start` logs this, the channel was found but voice UDP discovery failed:
+
+```text
+Cannot perform IP discovery - socket closed
+```
+
+On Linux Docker Compose, use host networking for the service running `vc start`:
+
+```yaml
+services:
+  verbalcoding:
+    network_mode: "host"
+```
+
+Remove any `ports:` block from that service when using host networking. On Docker Desktop for macOS/Windows, host networking behaves differently; if UDP voice still fails, run VerbalCoding directly on the host or in a Linux VM. See [Troubleshooting](TROUBLESHOOTING.md).
+
+## 8. Project-per-room setup
 
 For one permanent bot per project voice room, create one Discord application per project, then:
 
@@ -167,7 +211,7 @@ 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
+## 9. Optional OpenVoice setup
 
 OpenVoice voice cloning is optional. Keep `TTS_BACKEND=edge` for a fresh public install. To enable OpenVoice later:
 
@@ -181,7 +225,7 @@ python3 integrations/openvoice/synth.py --openvoice-dir vendor/OpenVoice --ref-a
 
 Then set `TTS_BACKEND=openvoice`, run `vc doctor`, and test `!voice-test <text>` in Discord.
 
-## 8. Clean clone smoke test for maintainers
+## 10. Clean clone smoke test for maintainers
 
 Fast host-only smoke test:
 
@@ -196,12 +240,10 @@ 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.
+This validates bootstrap and doctor behavior in a clean container. It does not connect to Discord voice; use a real Linux host/VM for end-to-end voice UDP testing.

package/docs/HERMES_VOICE.md

@@ -0,0 +1,65 @@
+# Hermes Built-in Voice vs VerbalCoding
+
+<!-- readme-glow-up:intro -->
+<p align="center">
+  <a href="../README.md">README</a> ·
+  <a href="README.md">Docs hub</a> ·
+  <a href="USAGE.md">Usage</a> ·
+  <a href="CONFIGURATION.md">Configuration</a> ·
+  <a href="TROUBLESHOOTING.md">Troubleshooting</a>
+</p>
+
+> Hermes already supports Discord voice channels. VerbalCoding is the workflow layer for people who want a coding-agent phone call, not just the baseline voice loop.
+<!-- /readme-glow-up:intro -->
+
+## What Hermes already does
+
+Hermes Agent has built-in Discord voice-channel support through the Discord gateway. After the bot is in your server, slash commands such as `/voice join` or `/voice channel` can join the voice channel you are currently in. Hermes can then transcribe speech with Whisper/STT and speak replies back through TTS providers such as Edge TTS, ElevenLabs, OpenAI, or other configured providers.
+
+For basic live voice chat, this is enough:
+
+```text
+Discord VC → Hermes STT → Hermes agent → TTS → Discord VC playback
+```
+
+If that is your whole requirement, use Hermes built-in voice mode first.
+
+## What VerbalCoding adds
+
+VerbalCoding keeps the same high-level loop, but makes it a coding-workflow runtime around CLI agents.
+
+| Area | Hermes built-in voice | VerbalCoding |
+|---|---|---|
+| Primary goal | General Hermes conversation in a Discord VC | Phone-call-style coding workflow with CLI agents |
+| Commands | `/voice join`, `/voice channel`, `/voice leave`, `/voice tts` | `vc setup`, `vc start`, `!join`, `!ask`, `!session`, `!verbose`, `!latency`, multi-instance commands |
+| Backend | Hermes Agent | Hermes Agent, Claude Code, Codex, Gemini CLI, OpenCode, OpenClaw, or custom command |
+| Session model | Normal Hermes gateway session | Project/session routing, voice-channel bindings, shared voice + `!ask` text context where supported |
+| Speech UX | Baseline STT + TTS | Tuned utterance windows, language presets, transcript cleanup, text mirrors, voice tests |
+| Interruption | Basic voice playback behavior | Barge-in rules that stop playback without accidentally killing an active agent task |
+| Long coding tasks | Generic agent response | Progress/status prompts, verbose tool-progress summaries, diff/log suppression for TTS |
+| Operations | Hermes gateway setup and config | `vc doctor` auto-fixes, redacted diagnostics, latency metrics, Docker UDP guidance, multi-bot/project rooms |
+
+## When to choose which
+
+Use **Hermes built-in voice** when you want:
+
+- one bot in one Discord voice channel;
+- simple speak → transcribe → answer → speak-back behavior;
+- the official Hermes gateway path with minimal extra software;
+- Hermes-only sessions and tools.
+
+Use **VerbalCoding** when you want:
+
+- voice and text to cooperate around a coding project;
+- multiple agent backends, not only Hermes;
+- project-specific Discord rooms or multiple bot instances;
+- Korean/English language presets and runtime voice controls;
+- careful barge-in behavior during long agent work;
+- spoken progress without reading giant diffs, stack traces, or logs aloud;
+- operational debugging with `vc doctor`, latency summaries, and container voice-network guidance.
+
+## Honest positioning
+
+VerbalCoding should not be described as “adding Discord voice to Hermes from scratch.” Hermes already has that baseline. A better description is:
+
+> VerbalCoding is a Discord voice workflow layer for CLI coding agents. It can use Hermes as the default backend, while adding project routing, interruption semantics, progress UX, diagnostics, and backend switching for long-running software work.

package/docs/MULTI_INSTANCE.md

@@ -1,5 +1,21 @@
 # Multi-instance VerbalCoding
 
+<!-- readme-glow-up:intro -->
+<p align="center">
+  <a href="../README.md">README</a> ·
+  <a href="README.md">Docs hub</a> ·
+  <a href="FRESH_INSTALL.md">Fresh Install</a> ·
+  <a href="USAGE.md">Usage</a> ·
+  <a href="CONFIGURATION.md">Configuration</a> ·
+  <a href="TROUBLESHOOTING.md">Troubleshooting</a> ·
+  <a href="MULTI_INSTANCE.md">Multi-Instance</a>
+</p>
+
+> Run one isolated Discord voice bridge per project room.
+>
+> Fast path: `vc instance setup NAME → vc bot invite CLIENT_ID → vc instance start NAME`
+<!-- /readme-glow-up:intro -->
+
 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.

package/docs/README.md

@@ -0,0 +1,49 @@
+# VerbalCoding docs
+
+<p align="center">
+  <a href="../README.md">README</a> ·
+  <a href="./i18n/README.ko.md">한국어</a> ·
+  <a href="./i18n/README.ja.md">日本語</a> ·
+  <a href="./i18n/README.zh.md">中文</a> ·
+  <a href="./i18n/README.es.md">Español</a> ·
+  <a href="./i18n/README.fr.md">Français</a> ·
+  <a href="./i18n/README.ru.md">Русский</a>
+</p>
+
+This is the detailed manual behind the compact README. Start with the fresh install guide if you are setting up a real Discord voice bot for the first time.
+
+## Fast path
+
+```bash
+npm install -g verbalcoding@latest
+vc setup
+vc doctor
+vc start
+```
+
+## Guides
+
+| Guide | Use it when you need |
+|---|---|
+| [Fresh Install](FRESH_INSTALL.md) | A clean npm/global install, Discord app setup, first bot invite, and first voice run. |
+| [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. |
+| [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. |
+
+## Localized guide sets
+
+| Language | Docs index |
+|---|---|
+| Korean | [docs/i18n/README.ko.md](i18n/README.ko.md) |
+| Japanese | [docs/i18n/README.ja.md](i18n/README.ja.md) |
+| Chinese | [docs/i18n/README.zh.md](i18n/README.zh.md) |
+| Spanish | [docs/i18n/README.es.md](i18n/README.es.md) |
+| French | [docs/i18n/README.fr.md](i18n/README.fr.md) |
+| Russian | [docs/i18n/README.ru.md](i18n/README.ru.md) |
+
+## Contributor note
+
+Use `vc ...` commands in user-facing docs. Keep `./scripts/...` commands for source-checkout contributor flows only.

package/docs/RELEASE.md

@@ -1,13 +1,29 @@
 # VerbalCoding release notes
 
+<!-- readme-glow-up:intro -->
+<p align="center">
+  <a href="../README.md">README</a> ·
+  <a href="README.md">Docs hub</a> ·
+  <a href="FRESH_INSTALL.md">Fresh Install</a> ·
+  <a href="USAGE.md">Usage</a> ·
+  <a href="CONFIGURATION.md">Configuration</a> ·
+  <a href="TROUBLESHOOTING.md">Troubleshooting</a> ·
+  <a href="MULTI_INSTANCE.md">Multi-Instance</a>
+</p>
+
+> Release-facing capability list and verification checklist.
+>
+> Fast path: `npm pack --dry-run → npm test → vc doctor → manual Discord smoke test`
+<!-- /readme-glow-up:intro -->
+
 ## 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.
+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. Windows is not supported yet.
 
 ### Included
 
 - Discord voice receive via Node `@discordjs/voice`.
-- Local Korean STT via `whisper.cpp` + Metal.
+- Local Korean STT via `whisper.cpp` + Metal or local Linux build fallback.
 - Edge TTS playback with Korean default voice.
 - Generic CLI harness adapter layer:
   - Hermes Agent
@@ -21,12 +37,14 @@ VerbalCoding is a Discord voice bridge for controlling CLI-based coding agents b
 - 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.
-- npm package install path: `npm install -g verbalcoding`, `vc setup --yes`, and `vc start`.
+- Public npm setup path: `npm install -g verbalcoding@latest`, guided `vc setup`, `vc doctor`, and `vc start`; `vc setup --yes`, `vc setup token`, and `vc setup channels` remain available for automation or later updates.
+- `vc doctor` redacted prerequisite checker with supported auto-fixes for local media/STT/TTS prerequisites and Hermes CLI on macOS/Linux.
+- Discord onboarding helpers: `vc bot invite <client-id>` plus token/client-id registration through `vc setup token`.
+- Auto-join channel configuration through `vc setup channels`, `vc setup channel`, and `vc setup voice`.
 - 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.
-- More patient utterance idle wait (`UTTERANCE_IDLE_MS=4500`) so long spoken instructions with natural pauses are not split into a partial prompt plus ignored processing-time speech.
-- 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.
+- Always-on JSONL latency metrics plus `!latency` / `!metrics` summary.
+- More patient utterance idle wait (`UTTERANCE_IDLE_MS=4500`) so long spoken instructions with natural pauses are not split too early.
+- 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.
 
 ### Pre-release checklist
 
@@ -35,7 +53,7 @@ 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
+node --check app-node/main.mjs app-node/agent_adapters.mjs app-node/install_config.mjs scripts/install.mjs scripts/cli.mjs scripts/doctor.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
@@ -46,22 +64,27 @@ git diff --check
 
 Manual smoke test:
 
-1. Start the bridge with `vc start` or `./run.sh`.
-2. Verify log contains `Logged in as <bot-name>`.
-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.
+1. Configure the app with `vc setup token` and `vc setup channels "<voice-channel>"`.
+2. Start the bridge with `vc start` or `./run.sh`.
+3. Verify log contains `Logged in as <bot-name>`.
+4. Verify log contains `Listening in voice channel ... / <configured channel>`.
+5. In Discord, run `!ping`.
+6. In Discord voice, say a short Korean request.
+7. Verify STT transcript, agent response, TTS playback, and barge-in behavior.
+
+Container smoke note: Docker script checks install quality, not Discord voice UDP. For end-to-end voice in containers, Linux host networking is usually required.
 
 ### 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.
+- `ffmpeg`; setup/doctor attempts to install it.
+- `whisper-cli`; setup uses Homebrew on macOS or local `vendor/whisper.cpp` build fallback on Linux.
+- Default model at `models/ggml-small-q5_1.bin`; setup downloads it unless `--skip-model` is used.
+- Edge TTS CLI on `PATH` or local `.venv-tts/bin/edge-tts`; setup creates the local helper when needed.
+- Discord bot token registered with `vc setup token` or present in `.env`, `instances/<name>.env`, `~/.zshrc`, or runtime env.
+- Auto-join voice channels registered with `vc setup channels` or present in `AUTO_JOIN_VOICE_CHANNELS`.
 - Selected CLI harness installed and authenticated.
+- For containerized Discord voice, UDP egress must work; Linux `network_mode: "host"` is the recommended Docker Compose setting.
 
 ### Not for public release yet
 

package/docs/ROADMAP.md

@@ -0,0 +1,38 @@
+# VerbalCoding Roadmap — 2026 H1 Differentiation Push
+
+> Reframe: from "Discord bridge for Hermes" → **the voice layer for any coding agent — with real barge-in, streaming latency, and the agents you already use.**
+
+This roadmap covers five differentiation phases that separate VerbalCoding from Hermes' built-in `/voice` (shipped Mar 2026, ~2 months old, no barge-in, Hermes-only, 2.5–9s practical latency).
+
+## Phase Plans
+
+| # | 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) |
+
+## Sequencing rationale
+
+1. **Phase 2 first** — adapter polish + Aider/Cursor + auto-detection. Foundational and unlocks marketing claim "any coding agent".
+2. **Phase 1** — extend the existing `tts_prefetch.mjs` to consume streaming stdout. Big perceived-latency win.
+3. **Phase 6** — replaces regex pattern matching with semantic summarization. Demo moment.
+4. **Phase 7** — voice plan mode. UX feature, depends on adapter capability flags from Phase 2.
+5. **Phase 10** — push notification handoff. Independent; ship after the core is tighter.
+
+## Differentiation claims this roadmap unlocks
+
+- **True barge-in** with smart resume (extend existing `barge_in.mjs`).
+- **Streaming pipeline** so first audio plays before the agent finishes thinking (Hermes Phase-4 wishlist).
+- **Agent-agnostic** — Hermes, Claude Code, Codex, Gemini, OpenCode, OpenClaw, Aider, Cursor CLI, custom.
+- **Smart narration** — describes intent, not file names.
+- **Voice plan mode** — narrate plan, edit by voice (`"skip step 3"`).
+- **Phone-down mode** — push notification when long task completes with voice summary.
+
+## Non-goals (for this cycle)
+
+- 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).