verbalcoding 0.2.0

package/docs/i18n/README.ru.md

@@ -0,0 +1,121 @@
+# VerbalCoding
+
+<p align="center">
+  <strong>Общайтесь с CLI-агентами для программирования голосом в Discord — почти как по телефону.</strong>
+</p>
+
+<p align="center">
+  <a href="../../README.md">English</a> ·
+  <a href="README.ko.md">한국어</a> ·
+  <a href="README.ja.md">日本語</a> ·
+  <a href="README.zh.md">中文</a> ·
+  <a href="README.es.md">Español</a> ·
+  <a href="README.fr.md">Français</a> ·
+  <a href="README.ru.md">Русский</a>
+</p>
+
+<p align="center">
+  <img alt="Node.js" src="https://img.shields.io/badge/Node.js-20%2B-339933?logo=node.js&logoColor=white">
+  <img alt="Discord" src="https://img.shields.io/badge/Discord-voice%20bridge-5865F2?logo=discord&logoColor=white">
+  <img alt="STT" src="https://img.shields.io/badge/STT-whisper.cpp-7C3AED">
+  <img alt="TTS" src="https://img.shields.io/badge/TTS-Edge%20%7C%20OpenVoice%20%7C%20Supertonic%20%7C%20SpeechSwift-0EA5E9">
+</p>
+
+<p align="center">
+  <img src="../assets/figures/verbalcoding-flow.svg" alt="VerbalCoding voice-to-agent flow" width="860">
+</p>
+
+## Why
+
+VerbalCoding превращает голосовой канал Discord в hands-free панель управления агентами для разработки. Скажите задачу, дайте CLI-агенту выполнить работу и получите краткий голосовой ответ — с текстовыми транскриптами, событиями прогресса и защитой от зачитывания длинного кода или логов.
+
+## Возможности
+
+| Что есть | Почему это удобно |
+|---|---|
+| Голосовое управление прежде всего | Управляйте Hermes Agent, Claude Code, Codex, Gemini CLI, OpenCode, OpenClaw или своим CLI голосом. |
+| Локальный voice loop | Голос Discord → STT `whisper.cpp` → агент → фрагментированное TTS-воспроизведение. |
+| Общий контекст голоса и текста | Голосовые реплики и `!ask` могут использовать одну и ту же поддерживаемую сессию агента. |
+| Barge-in и режимы чувствительности | Естественно перебивайте воспроизведение и переключайте normal/conservative режимы. |
+| Многоязычные voice presets | `vc language ko/en/auto` одновременно меняет STT, язык прогресса и TTS-голос. |
+| Изоляция комнат по проектам | Отдельный bot, Hermes profile, сессия, память и логи для каждого проекта. |
+
+## Быстрый старт
+
+```bash
+git clone git@github.com:ca1773130n/VerbalCoding.git
+cd VerbalCoding
+./scripts/install.sh
+vc doctor
+./run.sh
+```
+
+## Как это работает
+
+```mermaid
+flowchart LR
+  A[Discord voice] --> B["@discordjs/voice"]
+  B --> C[PCM cleanup + gates]
+  C --> D["whisper.cpp STT"]
+  D --> E["CLI agent adapter"]
+  E --> F["Concise answer"]
+  F --> G["Chunked TTS"]
+  G --> H["Discord playback"]
+```
+
+## Поддерживаемые agent-бэкенды
+
+| Backend | Default command | Session support |
+|---|---:|---|
+| Hermes Agent | `hermes chat -Q -q` | Resume, verbose progress, cancellation, final-answer recovery |
+| Claude Code | `claude -p` | CLI session file support through adapter defaults |
+| Codex CLI | `codex exec` | CLI session file support through adapter defaults |
+| Gemini CLI | `gemini -p` | CLI session file support through adapter defaults |
+| OpenCode | `opencode run` | CLI session file support through adapter defaults |
+| OpenClaw | `openclaw run` | CLI session file support through adapter defaults |
+| Custom | `AGENT_COMMAND` | Bring your own non-interactive command |
+
+## Подробнее
+
+| Guide | What you get |
+|---|---|
+| [Fresh Install](../FRESH_INSTALL.md) | Чистая установка, загрузка модели, первый запуск |
+| [Usage Guide](../USAGE.md) | CLI-команды, команды Discord, режим прогресса, метрики задержек |
+| [Configuration](../CONFIGURATION.md) | .env, agent-бэкенды, MCP, TTS и эксплуатационные заметки |
+| [Multi-Instance](../MULTI_INSTANCE.md) | Постоянная голосовая комната Discord для каждого проекта |
+| [Release Notes](../RELEASE.md) | Текущие возможности и pre-release checklist |
+
+## Карта команд
+
+```bash
+vc status
+vc language ko|en|auto
+vc bot invite CLIENT_ID
+vc instance setup NAME
+vc instance start NAME
+vc doctor
+```
+
+## Требования
+
+| Layer | Default |
+|---|---|
+| Runtime | Node.js 20+, npm |
+| Audio | `ffmpeg` |
+| STT | `whisper.cpp` / `whisper-cli` |
+| Discord | Bot token, Message Content intent, voice permissions |
+| Agent | At least one authenticated CLI harness, Hermes Agent by default |
+| Platform focus | macOS / Apple Silicon currently gets the most testing |
+
+## Участие
+
+```bash
+node --check app-node/main.mjs
+npm test
+bash -n run.sh scripts/install.sh
+vc doctor
+```
+
+## Статус
+
+VerbalCoding is public-release oriented but still early. Demo video/GIF, broader Linux notes, and a formal license file are still TODOs.

package/docs/i18n/README.zh.md

@@ -0,0 +1,121 @@
+# VerbalCoding
+
+<p align="center">
+  <strong>通过 Discord 语音像打电话一样控制 CLI 编程 Agent。</strong>
+</p>
+
+<p align="center">
+  <a href="../../README.md">English</a> ·
+  <a href="README.ko.md">한국어</a> ·
+  <a href="README.ja.md">日本語</a> ·
+  <a href="README.zh.md">中文</a> ·
+  <a href="README.es.md">Español</a> ·
+  <a href="README.fr.md">Français</a> ·
+  <a href="README.ru.md">Русский</a>
+</p>
+
+<p align="center">
+  <img alt="Node.js" src="https://img.shields.io/badge/Node.js-20%2B-339933?logo=node.js&logoColor=white">
+  <img alt="Discord" src="https://img.shields.io/badge/Discord-voice%20bridge-5865F2?logo=discord&logoColor=white">
+  <img alt="STT" src="https://img.shields.io/badge/STT-whisper.cpp-7C3AED">
+  <img alt="TTS" src="https://img.shields.io/badge/TTS-Edge%20%7C%20OpenVoice%20%7C%20Supertonic%20%7C%20SpeechSwift-0EA5E9">
+</p>
+
+<p align="center">
+  <img src="../assets/figures/verbalcoding-flow.svg" alt="VerbalCoding voice-to-agent flow" width="860">
+</p>
+
+## Why
+
+VerbalCoding 把 Discord 语音频道变成面向编程 Agent 的免手动控制台。你可以直接说出需求，让 CLI Agent 工作，再听到简洁的语音回答；同时保留文字记录、进度事件，并避免把大段代码或日志读出来。
+
+## 亮点
+
+| 能力 | 价值 |
+|---|---|
+| 语音优先的 Agent 控制 | 用语音控制 Hermes Agent、Claude Code、Codex、Gemini CLI、OpenCode、OpenClaw 或自定义 CLI。 |
+| 本地优先语音闭环 | Discord 语音捕获 → `whisper.cpp` STT → Agent → 分段 TTS 播放。 |
+| 语音 + 文本共享上下文 | 在支持的 Agent 中，语音轮次和 `!ask` 文本命令可复用同一会话。 |
+| 打断与灵敏度模式 | 可自然打断播放，并在普通/保守灵敏度之间切换。 |
+| 多语言语音预设 | 用 `vc language ko/en/auto` 同步切换 STT、进度语言和 TTS 声音。 |
+| 按项目隔离的多房间 | 每个项目房间使用独立 Bot、Hermes profile、会话、记忆和日志。 |
+
+## 快速开始
+
+```bash
+git clone git@github.com:ca1773130n/VerbalCoding.git
+cd VerbalCoding
+./scripts/install.sh
+vc doctor
+./run.sh
+```
+
+## 工作原理
+
+```mermaid
+flowchart LR
+  A[Discord voice] --> B["@discordjs/voice"]
+  B --> C[PCM cleanup + gates]
+  C --> D["whisper.cpp STT"]
+  D --> E["CLI agent adapter"]
+  E --> F["Concise answer"]
+  F --> G["Chunked TTS"]
+  G --> H["Discord playback"]
+```
+
+## 支持的 Agent 后端
+
+| Backend | Default command | Session support |
+|---|---:|---|
+| Hermes Agent | `hermes chat -Q -q` | Resume, verbose progress, cancellation, final-answer recovery |
+| Claude Code | `claude -p` | CLI session file support through adapter defaults |
+| Codex CLI | `codex exec` | CLI session file support through adapter defaults |
+| Gemini CLI | `gemini -p` | CLI session file support through adapter defaults |
+| OpenCode | `opencode run` | CLI session file support through adapter defaults |
+| OpenClaw | `openclaw run` | CLI session file support through adapter defaults |
+| Custom | `AGENT_COMMAND` | Bring your own non-interactive command |
+
+## 了解更多
+
+| Guide | What you get |
+|---|---|
+| [Fresh Install](../FRESH_INSTALL.md) | 干净克隆安装、模型下载、首次运行 |
+| [Usage Guide](../USAGE.md) | CLI 命令、Discord 命令、进度模式、延迟指标 |
+| [Configuration](../CONFIGURATION.md) | .env、Agent 后端、MCP、TTS 后端、运维说明 |
+| [Multi-Instance](../MULTI_INSTANCE.md) | 每个项目一个常驻 Discord 语音房间 |
+| [Release Notes](../RELEASE.md) | 当前能力与发布前检查清单 |
+
+## 常用命令
+
+```bash
+vc status
+vc language ko|en|auto
+vc bot invite CLIENT_ID
+vc instance setup NAME
+vc instance start NAME
+vc doctor
+```
+
+## 要求
+
+| Layer | Default |
+|---|---|
+| Runtime | Node.js 20+, npm |
+| Audio | `ffmpeg` |
+| STT | `whisper.cpp` / `whisper-cli` |
+| Discord | Bot token, Message Content intent, voice permissions |
+| Agent | At least one authenticated CLI harness, Hermes Agent by default |
+| Platform focus | macOS / Apple Silicon currently gets the most testing |
+
+## 贡献
+
+```bash
+node --check app-node/main.mjs
+npm test
+bash -n run.sh scripts/install.sh
+vc doctor
+```
+
+## 状态
+
+VerbalCoding is public-release oriented but still early. Demo video/GIF, broader Linux notes, and a formal license file are still TODOs.

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "verbalcoding",
+  "version": "0.2.0",
+  "description": "Discord voice bridge for CLI coding agents.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ca1773130n/VerbalCoding.git"
+  },
+  "homepage": "https://github.com/ca1773130n/VerbalCoding#readme",
+  "bugs": {
+    "url": "https://github.com/ca1773130n/VerbalCoding/issues"
+  },
+  "keywords": [
+    "discord",
+    "voice",
+    "coding-agent",
+    "cli",
+    "speech-to-text",
+    "tts",
+    "whisper"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "vc": "scripts/cli.mjs",
+    "verbalcoding": "scripts/cli.mjs",
+    "verbalcoding-mcp": "scripts/mcp-server.mjs"
+  },
+  "files": [
+    "app-node/",
+    "docs/",
+    "scripts/*.mjs",
+    "scripts/*.sh",
+    "scripts/*.py",
+    "run.sh",
+    ".env.example",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node app-node/main.mjs",
+    "setup": "node scripts/install.mjs",
+    "doctor": "node scripts/doctor.mjs",
+    "vc": "node scripts/cli.mjs",
+    "mcp": "node scripts/mcp-server.mjs",
+    "test": "node --test app-node/*.test.mjs"
+  },
+  "dependencies": {
+    "@discordjs/opus": "^0.10.0",
+    "@discordjs/voice": "^0.19.2",
+    "discord.js": "^14.26.3",
+    "prism-media": "^1.3.5",
+    "wav": "^1.0.2"
+  }
+}

package/run.sh

@@ -0,0 +1,82 @@
+#!/usr/bin/env bash
+set -euo pipefail
+cd "$(dirname "$0")"
+
+# Node @discordjs/voice receiver is the active implementation. The earlier Python
+# discord-ext-voice-recv path produced corrupted PCM on this Mac/Discord setup.
+mkdir -p /tmp/verbalcoding-node-debug
+export NODE_AUDIO_DEBUG_DIR="${NODE_AUDIO_DEBUG_DIR:-/tmp/verbalcoding-node-debug}"
+export MIN_UTTERANCE_SECONDS="${MIN_UTTERANCE_SECONDS:-1.0}"
+export SUBSCRIBE_AFTER_SILENCE_MS="${SUBSCRIBE_AFTER_SILENCE_MS:-2200}"
+export UTTERANCE_IDLE_MS="${UTTERANCE_IDLE_MS:-2600}"
+export MIN_MEAN_VOLUME_DB="${MIN_MEAN_VOLUME_DB:--35}"
+export MIN_MAX_VOLUME_DB="${MIN_MAX_VOLUME_DB:--18}"
+export TTS_RATE="${TTS_RATE:-+10%}"
+export TTS_MAX_CHARS="${TTS_MAX_CHARS:-495}"
+export HERMES_TASK_TIMEOUT_MS="${HERMES_TASK_TIMEOUT_MS:-0}"
+export HERMES_CHAT_TIMEOUT_MS="${HERMES_CHAT_TIMEOUT_MS:-45000}"
+
+INSTANCE_ENV="${VERBALCODING_INSTANCE_ENV:-${1:-}}"
+if [ -n "$INSTANCE_ENV" ] && [ ! -f "$INSTANCE_ENV" ]; then
+  echo "instance env file not found: $INSTANCE_ENV" >&2
+  exit 2
+fi
+
+# In instance mode, the launcher passes isolated runtime defaults in the
+# process environment. Source the shared .env for non-secret/common defaults,
+# but do not let it replace the instance launcher defaults or token.
+LAUNCH_BRIDGE_LOG_PATH="${BRIDGE_LOG_PATH:-}"
+LAUNCH_NODE_AUDIO_DEBUG_DIR="${NODE_AUDIO_DEBUG_DIR:-}"
+LAUNCH_PROJECT_SESSIONS_FILE="${PROJECT_SESSIONS_FILE:-}"
+LAUNCH_HERMES_SESSION_FILE="${HERMES_SESSION_FILE:-}"
+LAUNCH_HERMES_HOME="${HERMES_HOME:-}"
+LAUNCH_VERBALCODING_INSTANCE_NAME="${VERBALCODING_INSTANCE_NAME:-}"
+LAUNCH_VERBALCODING_INSTANCE_ENV="${VERBALCODING_INSTANCE_ENV:-}"
+if [ -f .env ]; then
+  set -a
+  # shellcheck disable=SC1091
+  source ./.env
+  set +a
+fi
+if [ -n "$INSTANCE_ENV" ]; then
+  [ -n "$LAUNCH_BRIDGE_LOG_PATH" ] && export BRIDGE_LOG_PATH="$LAUNCH_BRIDGE_LOG_PATH"
+  [ -n "$LAUNCH_NODE_AUDIO_DEBUG_DIR" ] && export NODE_AUDIO_DEBUG_DIR="$LAUNCH_NODE_AUDIO_DEBUG_DIR"
+  [ -n "$LAUNCH_PROJECT_SESSIONS_FILE" ] && export PROJECT_SESSIONS_FILE="$LAUNCH_PROJECT_SESSIONS_FILE"
+  [ -n "$LAUNCH_HERMES_SESSION_FILE" ] && export HERMES_SESSION_FILE="$LAUNCH_HERMES_SESSION_FILE"
+  [ -n "$LAUNCH_HERMES_HOME" ] && export HERMES_HOME="$LAUNCH_HERMES_HOME"
+  [ -n "$LAUNCH_VERBALCODING_INSTANCE_NAME" ] && export VERBALCODING_INSTANCE_NAME="$LAUNCH_VERBALCODING_INSTANCE_NAME"
+  [ -n "$LAUNCH_VERBALCODING_INSTANCE_ENV" ] && export VERBALCODING_INSTANCE_ENV="$LAUNCH_VERBALCODING_INSTANCE_ENV"
+  unset DISCORD_BOT_TOKEN DISCORD_TOKEN
+  set -a
+  # shellcheck disable=SC1090
+  source "$INSTANCE_ENV"
+  set +a
+fi
+
+mkdir -p "$NODE_AUDIO_DEBUG_DIR"
+
+if [ "${TTS_BACKEND:-}" = "speechswift" ] && [ "${SPEECHSWIFT_MODE:-cli}" = "server" ]; then
+  export SPEECHSWIFT_SERVER_HOST="${SPEECHSWIFT_SERVER_HOST:-127.0.0.1}"
+  export SPEECHSWIFT_SERVER_PORT="${SPEECHSWIFT_SERVER_PORT:-18080}"
+  export SPEECHSWIFT_SERVER_URL="${SPEECHSWIFT_SERVER_URL:-http://${SPEECHSWIFT_SERVER_HOST}:${SPEECHSWIFT_SERVER_PORT}}"
+  if command -v audio-server >/dev/null 2>&1; then
+    if ! curl -fsS --max-time 1 "${SPEECHSWIFT_SERVER_URL%/}/health" >/dev/null 2>&1; then
+      mkdir -p .logs
+      audio-server --host "$SPEECHSWIFT_SERVER_HOST" --port "$SPEECHSWIFT_SERVER_PORT" >> .logs/speechswift-audio-server.log 2>&1 &
+      export SPEECHSWIFT_SERVER_PID="$!"
+      for _ in 1 2 3 4 5; do
+        curl -fsS --max-time 1 "${SPEECHSWIFT_SERVER_URL%/}/health" >/dev/null 2>&1 && break
+        sleep 1
+      done
+    fi
+  else
+    echo "speech-swift server mode requested but audio-server was not found; TTS will fall back if server calls fail" >&2
+  fi
+fi
+export PYTHONUNBUFFERED=1
+
+if [ ! -d node_modules ]; then
+  npm install
+fi
+
+exec node app-node/main.mjs

package/scripts/bootstrap_prereqs.sh

@@ -0,0 +1,193 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+cd "$ROOT"
+
+ASSUME_YES=0
+SKIP_SYSTEM=0
+SKIP_MODEL=0
+SKIP_EDGE_TTS=0
+
+for arg in "$@"; do
+  case "$arg" in
+    -y|--yes) ASSUME_YES=1 ;;
+    --skip-system) SKIP_SYSTEM=1 ;;
+    --skip-model) SKIP_MODEL=1 ;;
+    --skip-edge-tts) SKIP_EDGE_TTS=1 ;;
+    -h|--help)
+      cat <<'USAGE'
+Usage: scripts/bootstrap_prereqs.sh [--yes] [--skip-system] [--skip-model] [--skip-edge-tts]
+
+Installs public-release prerequisites where possible:
+  - Node/npm package dependencies
+  - ffmpeg
+  - whisper.cpp / whisper-cli
+  - default whisper.cpp model
+  - local Edge TTS CLI in .venv-tts when edge-tts is not already available
+
+System package installation supports macOS Homebrew and common Linux package managers
+(apt, dnf, pacman). Linux whisper.cpp is built locally under vendor/whisper.cpp if no
+package-manager whisper-cli is available.
+USAGE
+      exit 0
+      ;;
+  esac
+done
+
+log() { printf '==> %s\n' "$*"; }
+warn() { printf 'Warning: %s\n' "$*" >&2; }
+has_cmd() { command -v "$1" >/dev/null 2>&1; }
+confirm() {
+  if [ "$ASSUME_YES" = "1" ]; then return 0; fi
+  printf '%s [y/N]: ' "$1" >&2
+  read -r answer
+  case "$answer" in y|Y|yes|YES) return 0 ;; *) return 1 ;; esac
+}
+run_sudo() {
+  if [ "$(id -u)" = "0" ]; then "$@"; else sudo "$@"; fi
+}
+
+install_node_modules() {
+  if [ ! -d node_modules ]; then
+    log 'Installing npm dependencies'
+    npm install
+  else
+    log 'npm dependencies already installed'
+  fi
+}
+
+install_system_macos() {
+  if ! has_cmd brew; then
+    warn 'Homebrew is not installed. Install it from https://brew.sh, then rerun this script.'
+    return 1
+  fi
+  local packages=()
+  has_cmd node || packages+=(node)
+  has_cmd npm || packages+=(node)
+  has_cmd ffmpeg || packages+=(ffmpeg)
+  has_cmd whisper-cli || packages+=(whisper-cpp)
+  if [ "${#packages[@]}" -gt 0 ]; then
+    log "Installing Homebrew packages: ${packages[*]}"
+    brew install "${packages[@]}"
+  else
+    log 'System packages already available'
+  fi
+}
+
+install_system_linux_packages() {
+  if has_cmd apt-get; then
+    log 'Installing Linux packages with apt-get'
+    run_sudo apt-get update
+    run_sudo apt-get install -y curl ca-certificates git python3 python3-venv python3-pip build-essential cmake pkg-config ffmpeg nodejs npm
+  elif has_cmd dnf; then
+    log 'Installing Linux packages with dnf'
+    run_sudo dnf install -y curl ca-certificates git python3 python3-pip gcc gcc-c++ make cmake pkgconf-pkg-config ffmpeg nodejs npm
+  elif has_cmd pacman; then
+    log 'Installing Linux packages with pacman'
+    run_sudo pacman -Sy --needed --noconfirm curl ca-certificates git python python-pip base-devel cmake pkgconf ffmpeg nodejs npm
+  else
+    warn 'No supported Linux package manager found. Install node/npm, ffmpeg, python3, git, cmake, and a C++ toolchain manually.'
+    return 1
+  fi
+}
+
+install_whisper_cpp_linux() {
+  if has_cmd whisper-cli; then
+    log 'whisper-cli already available'
+    return 0
+  fi
+  local bin_dir="$ROOT/.local/bin"
+  local src_dir="$ROOT/vendor/whisper.cpp"
+  mkdir -p "$bin_dir" "$ROOT/vendor"
+  if [ ! -d "$src_dir/.git" ]; then
+    log 'Cloning whisper.cpp under vendor/whisper.cpp'
+    git clone --depth 1 https://github.com/ggml-org/whisper.cpp.git "$src_dir"
+  fi
+  log 'Building whisper.cpp locally'
+  cmake -S "$src_dir" -B "$src_dir/build" -DCMAKE_BUILD_TYPE=Release
+  cmake --build "$src_dir/build" --config Release -j "$(getconf _NPROCESSORS_ONLN 2>/dev/null || echo 2)"
+  local candidate=""
+  for path in "$src_dir/build/bin/whisper-cli" "$src_dir/build/examples/main/whisper-cli" "$src_dir/build/main"; do
+    if [ -x "$path" ]; then candidate="$path"; break; fi
+  done
+  if [ -z "$candidate" ]; then
+    warn 'Built whisper.cpp but could not find whisper-cli binary. Check vendor/whisper.cpp/build.'
+    return 1
+  fi
+  ln -sf "$candidate" "$bin_dir/whisper-cli"
+  log "Installed local whisper-cli shim: $bin_dir/whisper-cli"
+  export PATH="$bin_dir:$PATH"
+}
+
+install_system_deps() {
+  if [ "$SKIP_SYSTEM" = "1" ]; then
+    log 'Skipping system package installation'
+    return 0
+  fi
+  case "$(uname -s)" in
+    Darwin) install_system_macos ;;
+    Linux)
+      install_system_linux_packages || true
+      install_whisper_cpp_linux || true
+      ;;
+    *) warn "Unsupported OS $(uname -s). Install node/npm, ffmpeg, and whisper-cli manually." ;;
+  esac
+}
+
+install_edge_tts() {
+  if [ "$SKIP_EDGE_TTS" = "1" ]; then
+    log 'Skipping Edge TTS helper installation'
+    return 0
+  fi
+  if has_cmd edge-tts; then
+    log 'edge-tts already available'
+    return 0
+  fi
+  if [ -x "$ROOT/.venv-tts/bin/edge-tts" ]; then
+    log 'Local edge-tts venv already available'
+    return 0
+  fi
+  if ! has_cmd python3; then
+    warn 'python3 not found; skipping local edge-tts install'
+    return 1
+  fi
+  log 'Installing local edge-tts helper in .venv-tts'
+  python3 -m venv "$ROOT/.venv-tts"
+  "$ROOT/.venv-tts/bin/python" -m pip install --upgrade pip >/dev/null
+  "$ROOT/.venv-tts/bin/python" -m pip install edge-tts
+}
+
+download_model() {
+  if [ "$SKIP_MODEL" = "1" ]; then
+    log 'Skipping whisper.cpp model download'
+    return 0
+  fi
+  local model="$ROOT/models/ggml-small-q5_1.bin"
+  if [ -s "$model" ]; then
+    log 'Default whisper.cpp model already exists'
+    return 0
+  fi
+  if ! has_cmd curl; then
+    warn 'curl not found; cannot download whisper.cpp model automatically'
+    return 1
+  fi
+  mkdir -p "$ROOT/models"
+  log 'Downloading default whisper.cpp Korean-capable model'
+  curl -L --fail --retry 3 -o "$model.tmp" \
+    https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-small-q5_1.bin
+  mv "$model.tmp" "$model"
+}
+
+if [ "$SKIP_SYSTEM" != "1" ] && [ "$ASSUME_YES" != "1" ]; then
+  if ! confirm 'Install missing system prerequisites when supported?'; then
+    SKIP_SYSTEM=1
+  fi
+fi
+
+install_system_deps
+install_edge_tts || true
+install_node_modules
+download_model || true
+
+log 'Prerequisite bootstrap complete. Run `vc doctor` after setup to verify.'