verbalcoding 0.2.11 → 0.2.12

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
+```

package/docs/USAGE.md

@@ -1,45 +1,82 @@
 # VerbalCoding Usage Guide
 
-This page holds the operational details that used to make the README too long.
+<!-- 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>
+
+> Operational command reference for the voice bridge.
+>
+> Fast path: `vc setup → vc start → speak or use !ask in Discord`
+<!-- /readme-glow-up:intro -->
+
+This page holds the operational details that should stay out of the README.
 
 ## CLI Commands
 
 ```bash
-vc status                    # show STT language, progress language, and TTS voice
-vc language en               # English STT + English progress/TTS voice
-vc language ko               # Korean STT + Korean progress/TTS voice
-vc language auto             # Whisper auto-detect STT + English progress/TTS voice
-vc restart auto status       # show commit-time voice-bot auto-restart setting
-vc restart auto on           # enable commit-time voice-bot auto-restart
-vc restart auto off          # disable it; this is the default
-vc bot invite CLIENT_ID      # print a Discord invite URL with required permissions
-vc instance status           # list per-instance bridge configs and process status
-vc instance setup NAME       # write instances/NAME.env and create ~/.hermes/profiles/NAME
-vc instance start NAME       # start ./run.sh instances/NAME.env detached
-vc instance stop NAME        # stop a detached instance and remove its pid file
-vc doctor                    # run the redacted doctor check
-npm run mcp                  # run the stdio MCP server
+vc setup                               # guided setup: prerequisites, Discord token, voice channels
+vc setup --yes                         # non-interactive bootstrap/starter config for automation
+vc setup --yes --no-wizard             # dependency/bootstrap only
+vc setup token                         # later update Discord bot token
+vc setup token TOKEN --client-id ID     # non-interactive token/client-id update
+vc setup channels "General,Team Voice" # later update auto-join voice channel names
+vc setup channel "General"             # alias for setup channels
+vc setup voice "General"               # alias for setup channels
+vc bot invite CLIENT_ID                 # print a Discord invite URL with required permissions
+vc status                               # show STT language, progress language, and TTS voice
+vc language en                          # English STT + English progress/TTS voice
+vc language ko                          # Korean STT + Korean progress/TTS voice
+vc language auto                        # Whisper auto-detect STT + English progress/TTS voice
+vc restart auto status                  # show commit-time voice-bot auto-restart setting
+vc restart auto on                      # enable commit-time voice-bot auto-restart
+vc restart auto off                     # disable it; this is the default
+vc instance list                        # list per-instance bridge configs
+vc instance status [NAME]               # show instance process status
+vc instance setup NAME                  # write instances/NAME.env and create ~/.hermes/profiles/NAME
+vc instance start NAME                  # start ./run.sh instances/NAME.env detached
+vc instance stop NAME                   # stop a detached instance and remove its pid file
+vc doctor                               # run the redacted doctor check and supported auto-fixes
+vc start                                # start the default bridge
+npm run mcp                             # run the stdio MCP server from a clone
 ```
 
-Language changes update `.env`; restart the bridge with `./run.sh` or your process manager for them to take effect.
+For npm/global installs, prefer `vc ...` commands. Use `./scripts/install.sh` only from a GitHub clone.
+
+`vc setup token` and `vc setup channels` are safe follow-up commands: they update `.env` in place, preserve unrelated keys, set file mode `0600`, and avoid printing secrets.
+
+Language changes update `.env`; restart the bridge with `vc start`, `./run.sh`, or your process manager for them to take effect.
 
 ## Run Modes
 
 Single-instance bridge:
 
 ```bash
+vc start
+# clone equivalent:
 ./run.sh
 ```
 
 Per-instance bridge using a local override env:
 
 ```bash
+vc instance start my-project
+# clone/debug equivalent:
 ./run.sh instances/my-project.env
-# or
 VERBALCODING_INSTANCE_ENV=instances/my-project.env ./run.sh
 ```
 
-The bot auto-joins the first configured channel name, defaulting to `일반,General,general`.
+The bot auto-joins the first matching configured channel name. Set it with:
+
+```bash
+vc setup channels "VerbalCoding,LLM-Wiki,General"
+```
 
 ## Discord Commands
 
@@ -81,7 +118,7 @@ change voice to Korean female
 switch speaker to English
 ```
 
-The live bridge recognizes these as voice-control commands, updates `config/tts-voices.json`, updates the effective TTS env for the running process, and answers with a short confirmation such as “목소리를 Korean male로 바꿨어.” Use `!voice-test <text>` right after changing it to hear the current backend and voice.
+The live bridge recognizes these as voice-control commands, updates `config/tts-voices.json`, updates the effective TTS env for the running process, and answers with a short confirmation. Use `!voice-test <text>` right after changing it to hear the current backend and voice.
 
 Built-in Edge voice types:
 
@@ -93,27 +130,12 @@ Built-in Edge voice types:
 | `english_male` | `en-US-GuyNeural` |
 | `english_female` | `en-US-AriaNeural` |
 
-For persistent manual config, set `TTS_BACKEND=edge`, `TTS_VOICE_TYPE=<voice-type>`, and optionally `TTS_VOICE=<edge-voice>` in `.env`, or edit `config/tts-voices.json` for custom voice catalogs.
-
-Backend-specific voice knobs:
-
-| Backend | Voice setting | Common choices |
-|---|---|---|
-| Edge | `TTS_VOICE_TYPE`, `TTS_VOICE` | `korean_male`, `korean_female`, `korean_multilingual_male`, `english_male`, `english_female`; any Edge voice from `edge-tts --list-voices` |
-| Supertonic | `SUPERTONIC_VOICE` | `M1`–`M5`, `F1`–`F5`; set `SUPERTONIC_LANGUAGE=ko|en|es|pt|fr` |
-| OpenVoice | `OPENVOICE_REF_AUDIO`, `OPENVOICE_STYLE` | a permitted reference WAV plus style such as `default` |
-| SpeechSwift / CosyVoice | `SPEECHSWIFT_REF_AUDIO`, `SPEECHSWIFT_ENGINE`, `SPEECHSWIFT_SPEAKER` | reference WAV for CosyVoice, or backend-supported speaker/model values |
-
-For Supertonic and local clone backends, use the backend env vars above plus `!voice-test <text>` to audition changes. Voice-command switching currently maps the built-in Edge-style voice types; richer backend catalogs can be added in `config/tts-voices.json`.
-
 ## Long Dictation and Pauses
 
-VerbalCoding waits for an idle window before sending speech to STT. The default `UTTERANCE_IDLE_MS=4500` is intentionally a bit patient so a natural pause in a long instruction does not split the sentence, start an agent turn too early, and then treat the rest as a processing-time interruption.
-
-If you prefer faster short commands, lower it in `.env`; if long Korean dictation is still being split, raise it:
+VerbalCoding waits for an idle window before sending speech to STT. The default `UTTERANCE_IDLE_MS=4500` is intentionally patient so a natural pause in a long instruction does not split the sentence.
 
 ```bash
-UTTERANCE_IDLE_MS="6000"
+UTTERANCE_IDLE_MS="6000"  # safer for long dictation with pauses
 ```
 
 ## Verbose Progress Mode
@@ -128,7 +150,19 @@ Verbose progress is off by default unless `AGENT_VERBOSE_PROGRESS=1` is set. Ena
 🤖 Hermes Agent 응답 수신
 ```
 
-This mode asks the selected CLI harness to emit `VERBALCODING_PROGRESS: ...` lines and summarizes common tool markers from streaming stdout/stderr when available. Secret-looking fields are redacted and progress lines are removed from the final spoken answer.
+Secret-looking fields are redacted and progress lines are removed from the final spoken answer.
+
+## Docker / Container Run Mode
+
+If you run VerbalCoding in Docker and voice auto-join fails with `Cannot perform IP discovery - socket closed`, the likely issue is UDP connectivity, not channel lookup. For Linux Docker Compose:
+
+```yaml
+services:
+  verbalcoding:
+    network_mode: "host"
+```
+
+Remove `ports:` from that service. Docker Desktop for macOS/Windows has different host networking behavior; if UDP voice still fails there, run on the host or in a Linux VM. See [Troubleshooting](TROUBLESHOOTING.md).
 
 ## Latency Metrics
 
@@ -138,8 +172,6 @@ VerbalCoding writes per-turn latency records as JSONL. Default path:
 ./.logs/latency.jsonl
 ```
 
-Each record includes status, total time, voice capture time, utterance idle wait, STT time, agent time, TTS synthesis/playback time, chunk counts, transcript length, answer length, and audio levels where available.
-
 In Discord:
 
 ```text
@@ -154,7 +186,7 @@ The summary uses the latest 200 records: count, average, p95, max, and non-OK st
 ```bash
 node --check app-node/main.mjs
 npm test
-bash -n run.sh scripts/install.sh
+bash -n run.sh scripts/install.sh scripts/bootstrap_prereqs.sh
 vc doctor
 ```
 

package/docs/assets/figures/verbalcoding-flow.svg

@@ -73,6 +73,6 @@
   <text x="594" y="194" fill="#FDE68A" text-anchor="middle" font-family="Inter, ui-sans-serif, system-ui" font-size="15" font-weight="700">Barge-in stays open while the agent is thinking or speaking</text>
 
   <rect x="150" y="348" width="900" height="54" rx="17" fill="#020617" stroke="#1F2937"/>
-  <text x="182" y="382" fill="#A7F3D0" font-family="SFMono-Regular, ui-monospace, monospace" font-size="18">$ vc language ko &amp;&amp; vc instance start my-project</text>
+  <text x="182" y="382" fill="#A7F3D0" font-family="SFMono-Regular, ui-monospace, monospace" font-size="18">$ vc setup → vc doctor → vc start</text>
   <text x="1045" y="382" fill="#64748B" text-anchor="end" font-family="Inter, ui-sans-serif, system-ui" font-size="15">hands-free coding call</text>
 </svg>

package/docs/i18n/CONFIGURATION.es.md

@@ -1,5 +1,30 @@
 # Configuración de VerbalCoding
 
+<!-- readme-glow-up:intro -->
+<p align="center">
+  <a href="../../README.es.md">README</a> ·
+  <a href="README.es.md">Centro de documentación</a> ·
+  <a href="FRESH_INSTALL.es.md">Fresh Install</a> ·
+  <a href="USAGE.es.md">Usage</a> ·
+  <a href="CONFIGURATION.es.md">Configuration</a> ·
+  <a href="TROUBLESHOOTING.es.md">Troubleshooting</a> ·
+  <a href="MULTI_INSTANCE.es.md">Multi-Instance</a>
+</p>
+
+> Ruta rápida: `npm install -g verbalcoding@latest → vc setup → vc doctor → vc start`
+<!-- /readme-glow-up:intro -->
+
+## Flujo setup actualizado
+
+```bash
+npm install -g verbalcoding@latest
+vc setup
+vc doctor
+vc start
+```
+
+No edites `.env` manualmente: usa `vc setup token` para guardar `DISCORD_BOT_TOKEN`/`DISCORD_CLIENT_ID` y `vc setup channels` para guardar `AUTO_JOIN_VOICE_CHANNELS`. Si Docker muestra `Cannot perform IP discovery - socket closed`, usa `network_mode: "host"` en Linux Compose y elimina `ports:`.
+
 ## Asistente de configuración
 
 La configuración de la aplicación/bot de Discord no se vuelve a explicar desde cero aquí de forma intencionada. Usa estas guías originales para los pasos del lado de Discord y luego vuelve a la configuración de VerbalCoding:

package/docs/i18n/CONFIGURATION.fr.md

@@ -1,5 +1,30 @@
 # Configuration de VerbalCoding
 
+<!-- readme-glow-up:intro -->
+<p align="center">
+  <a href="../../README.fr.md">README</a> ·
+  <a href="README.fr.md">Centre de documentation</a> ·
+  <a href="FRESH_INSTALL.fr.md">Fresh Install</a> ·
+  <a href="USAGE.fr.md">Usage</a> ·
+  <a href="CONFIGURATION.fr.md">Configuration</a> ·
+  <a href="TROUBLESHOOTING.fr.md">Troubleshooting</a> ·
+  <a href="MULTI_INSTANCE.fr.md">Multi-Instance</a>
+</p>
+
+> Chemin rapide: `npm install -g verbalcoding@latest → vc setup → vc doctor → vc start`
+<!-- /readme-glow-up:intro -->
+
+## Flux setup actuel
+
+```bash
+npm install -g verbalcoding@latest
+vc setup
+vc doctor
+vc start
+```
+
+Ne modifiez pas `.env` à la main : utilisez `vc setup token` pour enregistrer `DISCORD_BOT_TOKEN`/`DISCORD_CLIENT_ID`, et `vc setup channels` pour `AUTO_JOIN_VOICE_CHANNELS`. Si Docker affiche `Cannot perform IP discovery - socket closed`, utilisez `network_mode: "host"` avec Compose sous Linux et supprimez `ports:`.
+
 ## Assistant de configuration
 
 La configuration du bot/de l'application Discord n'est volontairement pas réexpliquée depuis zéro ici. Utilisez ces guides amont pour les étapes côté Discord, puis revenez à la configuration de VerbalCoding :

package/docs/i18n/CONFIGURATION.ja.md

@@ -1,5 +1,30 @@
 # VerbalCoding 設定
 
+<!-- readme-glow-up:intro -->
+<p align="center">
+  <a href="../../README.ja.md">README</a> ·
+  <a href="README.ja.md">ドキュメントハブ</a> ·
+  <a href="FRESH_INSTALL.ja.md">Fresh Install</a> ·
+  <a href="USAGE.ja.md">Usage</a> ·
+  <a href="CONFIGURATION.ja.md">Configuration</a> ·
+  <a href="TROUBLESHOOTING.ja.md">Troubleshooting</a> ·
+  <a href="MULTI_INSTANCE.ja.md">Multi-Instance</a>
+</p>
+
+> 最短経路: `npm install -g verbalcoding@latest → vc setup → vc doctor → vc start`
+<!-- /readme-glow-up:intro -->
+
+## 最新の setup フロー
+
+```bash
+npm install -g verbalcoding@latest
+vc setup
+vc doctor
+vc start
+```
+
+手動で `.env` を編集せず、`vc setup token` で `DISCORD_BOT_TOKEN`/`DISCORD_CLIENT_ID`、`vc setup channels` で `AUTO_JOIN_VOICE_CHANNELS` を保存してください。Docker で `Cannot perform IP discovery - socket closed` が出る場合、Linux Compose サービスに `network_mode: "host"` を使い、`ports:` を削除します。
+
 ## セットアップウィザード
 
 Discord ボット/アプリケーションのセットアップ手順は、ここでは最初から説明し直しません。Discord 側の手順には次の上流ガイドを使い、その後 VerbalCoding のセットアップに戻ってください:

package/docs/i18n/CONFIGURATION.ko.md

@@ -1,5 +1,30 @@
 # VerbalCoding 설정
 
+<!-- readme-glow-up:intro -->
+<p align="center">
+  <a href="../../README.ko.md">README</a> ·
+  <a href="README.ko.md">문서 허브</a> ·
+  <a href="FRESH_INSTALL.ko.md">Fresh Install</a> ·
+  <a href="USAGE.ko.md">Usage</a> ·
+  <a href="CONFIGURATION.ko.md">Configuration</a> ·
+  <a href="TROUBLESHOOTING.ko.md">Troubleshooting</a> ·
+  <a href="MULTI_INSTANCE.ko.md">Multi-Instance</a>
+</p>
+
+> 빠른 경로: `npm install -g verbalcoding@latest → vc setup → vc doctor → vc start`
+<!-- /readme-glow-up:intro -->
+
+## 최신 setup 흐름
+
+```bash
+npm install -g verbalcoding@latest
+vc setup
+vc doctor
+vc start
+```
+
+수동 `.env` 편집 대신 `vc setup token`으로 `DISCORD_BOT_TOKEN`/`DISCORD_CLIENT_ID`를 저장하고, `vc setup channels`로 `AUTO_JOIN_VOICE_CHANNELS`를 저장하세요. Docker에서 `Cannot perform IP discovery - socket closed`가 보이면 Linux Compose 서비스에 `network_mode: "host"`를 사용하고 `ports:`를 제거하세요.
+
 ## 설정 마법사
 
 Discord 봇/애플리케이션 설정은 여기서 처음부터 다시 설명하지 않습니다. Discord 쪽 단계는 다음 업스트림 가이드를 사용한 뒤 VerbalCoding 설정으로 돌아오세요:

package/docs/i18n/CONFIGURATION.ru.md

@@ -1,5 +1,30 @@
 # Конфигурация VerbalCoding
 
+<!-- readme-glow-up:intro -->
+<p align="center">
+  <a href="../../README.ru.md">README</a> ·
+  <a href="README.ru.md">Центр документации</a> ·
+  <a href="FRESH_INSTALL.ru.md">Fresh Install</a> ·
+  <a href="USAGE.ru.md">Usage</a> ·
+  <a href="CONFIGURATION.ru.md">Configuration</a> ·
+  <a href="TROUBLESHOOTING.ru.md">Troubleshooting</a> ·
+  <a href="MULTI_INSTANCE.ru.md">Multi-Instance</a>
+</p>
+
+> Быстрый путь: `npm install -g verbalcoding@latest → vc setup → vc doctor → vc start`
+<!-- /readme-glow-up:intro -->
+
+## Актуальный setup-процесс
+
+```bash
+npm install -g verbalcoding@latest
+vc setup
+vc doctor
+vc start
+```
+
+Не редактируйте `.env` вручную: используйте `vc setup token` для `DISCORD_BOT_TOKEN`/`DISCORD_CLIENT_ID` и `vc setup channels` для `AUTO_JOIN_VOICE_CHANNELS`. Если Docker показывает `Cannot perform IP discovery - socket closed`, в Linux Compose используйте `network_mode: "host"` и удалите `ports:`.
+
 ## Мастер настройки
 
 Настройка Discord-бота/приложения намеренно не объясняется здесь с нуля. Используйте эти исходные руководства для шагов на стороне Discord, затем вернитесь к настройке VerbalCoding:

package/docs/i18n/CONFIGURATION.zh.md

@@ -1,5 +1,30 @@
 # VerbalCoding 配置
 
+<!-- readme-glow-up:intro -->
+<p align="center">
+  <a href="../../README.zh.md">README</a> ·
+  <a href="README.zh.md">文档中心</a> ·
+  <a href="FRESH_INSTALL.zh.md">Fresh Install</a> ·
+  <a href="USAGE.zh.md">Usage</a> ·
+  <a href="CONFIGURATION.zh.md">Configuration</a> ·
+  <a href="TROUBLESHOOTING.zh.md">Troubleshooting</a> ·
+  <a href="MULTI_INSTANCE.zh.md">Multi-Instance</a>
+</p>
+
+> 最快路径: `npm install -g verbalcoding@latest → vc setup → vc doctor → vc start`
+<!-- /readme-glow-up:intro -->
+
+## 最新 setup 流程
+
+```bash
+npm install -g verbalcoding@latest
+vc setup
+vc doctor
+vc start
+```
+
+不要手动编辑 `.env`；使用 `vc setup token` 保存 `DISCORD_BOT_TOKEN`/`DISCORD_CLIENT_ID`，使用 `vc setup channels` 保存 `AUTO_JOIN_VOICE_CHANNELS`。如果 Docker 中出现 `Cannot perform IP discovery - socket closed`，请在 Linux Compose 服务中使用 `network_mode: "host"` 并移除 `ports:`。
+
 ## 设置向导
 
 这里有意不从头重新解释 Discord 机器人/应用设置。请先使用这些上游指南完成 Discord 侧步骤，然后回到 VerbalCoding 设置：

package/docs/i18n/FRESH_INSTALL.es.md

@@ -1,5 +1,30 @@
 # Instalación limpia
 
+<!-- readme-glow-up:intro -->
+<p align="center">
+  <a href="../../README.es.md">README</a> ·
+  <a href="README.es.md">Centro de documentación</a> ·
+  <a href="FRESH_INSTALL.es.md">Fresh Install</a> ·
+  <a href="USAGE.es.md">Usage</a> ·
+  <a href="CONFIGURATION.es.md">Configuration</a> ·
+  <a href="TROUBLESHOOTING.es.md">Troubleshooting</a> ·
+  <a href="MULTI_INSTANCE.es.md">Multi-Instance</a>
+</p>
+
+> Ruta rápida: `npm install -g verbalcoding@latest → vc setup → vc doctor → vc start`
+<!-- /readme-glow-up:intro -->
+
+## Flujo setup actualizado
+
+```bash
+npm install -g verbalcoding@latest
+vc setup
+vc doctor
+vc start
+```
+
+No edites `.env` manualmente: usa `vc setup token` para guardar `DISCORD_BOT_TOKEN`/`DISCORD_CLIENT_ID` y `vc setup channels` para guardar `AUTO_JOIN_VOICE_CHANNELS`. Si Docker muestra `Cannot perform IP discovery - socket closed`, usa `network_mode: "host"` en Linux Compose y elimina `ports:`.
+
 Esta guía es para una instalación pública limpia. Evita suposiciones locales y usa el instalador para inicializar todo lo posible.
 
 ## 1. Instala la CLI
@@ -19,7 +44,7 @@ npx verbalcoding setup --yes
 Si usaste `npm install -g`, continúa con:
 
 ```bash
-vc setup --yes
+vc setup
 ```
 
 Ruta de clonación de GitHub para colaboradores:
@@ -35,7 +60,7 @@ cd VerbalCoding
 En una instalación npm, no ejecutes `./scripts/install.sh` directamente; no hay un checkout del repositorio en tu directorio actual. Usa en su lugar el wrapper CLI empaquetado:
 
 ```bash
-vc setup --yes
+vc setup
 ```
 
 `vc setup` ejecuta el `scripts/install.sh` incluido dentro del paquete npm instalado. Usa `./scripts/install.sh --yes` solo cuando estés dentro de un clon de GitHub:

package/docs/i18n/FRESH_INSTALL.fr.md

@@ -1,5 +1,30 @@
 # Installation propre
 
+<!-- readme-glow-up:intro -->
+<p align="center">
+  <a href="../../README.fr.md">README</a> ·
+  <a href="README.fr.md">Centre de documentation</a> ·
+  <a href="FRESH_INSTALL.fr.md">Fresh Install</a> ·
+  <a href="USAGE.fr.md">Usage</a> ·
+  <a href="CONFIGURATION.fr.md">Configuration</a> ·
+  <a href="TROUBLESHOOTING.fr.md">Troubleshooting</a> ·
+  <a href="MULTI_INSTANCE.fr.md">Multi-Instance</a>
+</p>
+
+> Chemin rapide: `npm install -g verbalcoding@latest → vc setup → vc doctor → vc start`
+<!-- /readme-glow-up:intro -->
+
+## Flux setup actuel
+
+```bash
+npm install -g verbalcoding@latest
+vc setup
+vc doctor
+vc start
+```
+
+Ne modifiez pas `.env` à la main : utilisez `vc setup token` pour enregistrer `DISCORD_BOT_TOKEN`/`DISCORD_CLIENT_ID`, et `vc setup channels` pour `AUTO_JOIN_VOICE_CHANNELS`. Si Docker affiche `Cannot perform IP discovery - socket closed`, utilisez `network_mode: "host"` avec Compose sous Linux et supprimez `ports:`.
+
 Ce guide couvre une installation publique propre. Il évite les hypothèses propres à une machine locale et utilise l'installateur pour amorcer autant d'éléments que possible.
 
 ## 1. Installer la CLI
@@ -19,7 +44,7 @@ npx verbalcoding setup --yes
 Si vous avez utilisé `npm install -g`, continuez avec :
 
 ```bash
-vc setup --yes
+vc setup
 ```
 
 Chemin de clonage GitHub pour les contributeurs :
@@ -35,7 +60,7 @@ cd VerbalCoding
 Pour une installation npm, n'exécutez pas `./scripts/install.sh` directement : il n'y a pas de checkout du dépôt dans votre répertoire courant. Utilisez plutôt l'enveloppe CLI empaquetée :
 
 ```bash
-vc setup --yes
+vc setup
 ```
 
 `vc setup` exécute le `scripts/install.sh` inclus dans le paquet npm installé. N'utilisez `./scripts/install.sh --yes` que lorsque vous êtes dans un clone GitHub :

package/docs/i18n/FRESH_INSTALL.ja.md

@@ -1,5 +1,30 @@
 # 新規インストール
 
+<!-- readme-glow-up:intro -->
+<p align="center">
+  <a href="../../README.ja.md">README</a> ·
+  <a href="README.ja.md">ドキュメントハブ</a> ·
+  <a href="FRESH_INSTALL.ja.md">Fresh Install</a> ·
+  <a href="USAGE.ja.md">Usage</a> ·
+  <a href="CONFIGURATION.ja.md">Configuration</a> ·
+  <a href="TROUBLESHOOTING.ja.md">Troubleshooting</a> ·
+  <a href="MULTI_INSTANCE.ja.md">Multi-Instance</a>
+</p>
+
+> 最短経路: `npm install -g verbalcoding@latest → vc setup → vc doctor → vc start`
+<!-- /readme-glow-up:intro -->
+
+## 最新の setup フロー
+
+```bash
+npm install -g verbalcoding@latest
+vc setup
+vc doctor
+vc start
+```
+
+手動で `.env` を編集せず、`vc setup token` で `DISCORD_BOT_TOKEN`/`DISCORD_CLIENT_ID`、`vc setup channels` で `AUTO_JOIN_VOICE_CHANNELS` を保存してください。Docker で `Cannot perform IP discovery - socket closed` が出る場合、Linux Compose サービスに `network_mode: "host"` を使い、`ports:` を削除します。
+
 このガイドは、クリーンな公開インストール向けです。ローカル環境だけに依存する前提を避け、インストーラーで可能な限りブートストラップします。
 
 ## 1. CLI をインストールする
@@ -19,7 +44,7 @@ npx verbalcoding setup --yes
 `npm install -g` を使った場合は、続けて次を実行します:
 
 ```bash
-vc setup --yes
+vc setup
 ```
 
 コントリビューター向けの GitHub クローン手順:
@@ -35,7 +60,7 @@ cd VerbalCoding
 npm インストールでは、現在のディレクトリにリポジトリのチェックアウトがないため、`./scripts/install.sh` を直接実行しないでください。代わりにパッケージ済み CLI ラッパーを使います:
 
 ```bash
-vc setup --yes
+vc setup
 ```
 
 `vc setup` は、インストール済み npm パッケージ内の `scripts/install.sh` を実行します。`./scripts/install.sh --yes` は GitHub クローン内にいる場合だけ使ってください: