verbalcoding 0.2.11 → 0.2.13

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/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,50 @@
+# 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. |
+| [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. |
+
+## 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,53 @@
+# 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 | 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
+
+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).
+
+## 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/TROUBLESHOOTING.md

@@ -0,0 +1,126 @@
+# VerbalCoding Troubleshooting
+
+<!-- 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>
+
+> Fast diagnosis for Discord voice, Docker UDP, tokens, channels, and doctor checks.
+>
+> Fast path: `vc doctor → check channel names → check UDP/permissions`
+<!-- /readme-glow-up:intro -->
+
+## `Cannot perform IP discovery - socket closed`
+
+This usually means the bot logged into Discord and found a voice channel, but Discord voice UDP discovery failed.
+
+Typical log sequence:
+
+```text
+Logged in as <bot-name>
+auto-join failed; trying next configured voice channel <server> <channel> AbortError: The operation was aborted
+voice connection error Error: Cannot perform IP discovery - socket closed
+No auto-join channel found or reachable ... attempted <server>/<channel>
+```
+
+Interpretation:
+
+| Log signal | Meaning |
+|---|---|
+| `Logged in as ...` | Token and Discord gateway login worked. |
+| `attempted <server>/<channel>` | Channel lookup worked; names are probably correct. |
+| `AbortError` after ~30s | Voice connection did not become ready in time. |
+| `Cannot perform IP discovery - socket closed` | UDP voice discovery failed, often because Docker/firewall/NAT blocked UDP. |
+
+Fixes:
+
+1. Try outside Docker first to isolate container networking.
+2. On Linux Docker Compose, use host networking:
+
+```yaml
+services:
+  verbalcoding:
+    network_mode: "host"
+```
+
+3. Remove `ports:` from the same service. Host networking and port publishing should not be combined.
+4. Check host firewall, cloud security group, VPN, proxy, or corporate network policies for outbound UDP blocking.
+5. On Docker Desktop for macOS/Windows, host networking behaves differently. If voice UDP still fails, run VerbalCoding directly on macOS/Linux host or in a Linux VM.
+
+## `No auto-join channel found or reachable`
+
+First confirm the configured names:
+
+```bash
+vc setup channels "VerbalCoding,LLM-Wiki,General"
+vc doctor
+vc start
+```
+
+If the log includes `attempted Server/Channel`, the channel was found and the remaining issue is reachability, permissions, or UDP voice transport. If the log has no attempted channel, update the channel names exactly as they appear in Discord.
+
+## Missing Discord token
+
+Run:
+
+```bash
+vc setup token
+# or:
+vc setup token <bot-token> --client-id <discord-client-id>
+vc doctor
+```
+
+Do not paste real tokens into issues, logs, screenshots, or docs. `vc doctor` redacts configured token values.
+
+## Bot invited but cannot speak or send text
+
+Verify Discord permissions on the exact channel/thread/voice room:
+
+- View Channel
+- Send Messages
+- Send Messages in Threads
+- Read Message History
+- Use Application Commands
+- Connect
+- Speak
+
+Channel-level overwrites can deny access even when the bot has server-level permissions.
+
+## Text delivery warning
+
+```text
+sendText missing transcript channel id; text not delivered
+```
+
+Voice can still work. This means `TRANSCRIPT_CHANNEL_ID` is unset, so restart/final/progress text cannot be mirrored to Discord text. Rerun setup or set a transcript text channel/thread ID.
+
+## Docker Compose host networking
+
+Equivalent of `docker run --network=host`:
+
+```yaml
+services:
+  verbalcoding:
+    network_mode: "host"
+```
+
+Notes:
+
+- Linux Docker: this is the most useful fix for Discord voice UDP issues.
+- Docker Desktop macOS/Windows: host networking is limited/different; test on the host or a Linux VM if voice still fails.
+- Do not include `ports:` for that service when using `network_mode: "host"`.
+
+## Doctor auto-fix behavior
+
+`vc doctor` may install or repair local prerequisites on supported macOS/Linux installs. It does not create Discord secrets or authenticate external agent CLIs for you.
+
+```bash
+vc doctor
+VERBALCODING_DOCTOR_INSTALL_HERMES=0 vc doctor  # skip Hermes CLI auto-install
+```