verbalcoding 0.2.12 → 0.2.13

package/docs/i18n/HARNESSES.es.md

@@ -0,0 +1,58 @@
+# Harnesses de agentes de codificación
+
+<p align="center">
+  <a href="../../README.es.md">README</a> ·
+  <a href="README.es.md">Centro de documentación</a> ·
+  <a href="USAGE.es.md">Uso</a> ·
+  <a href="CONFIGURATION.es.md">Configuración</a> ·
+  <a href="TROUBLESHOOTING.es.md">Resolución de problemas</a>
+</p>
+
+VerbalCoding es agnóstico al agente. Lanza el CLI de codificación que tengas instalado una vez por turno de voz, le pasa la transcripción como prompt y reproduce la respuesta. Elige **uno** como predeterminado; el enrutamiento por voz te permite alcanzar los demás dentro de la sesión.
+
+| Harness | Comando por defecto | Reanudación de sesión | Documento específico |
+|---|---|---|---|
+| Hermes Agent | `hermes chat -Q -q` | ✅ (`--resume <id>`) | [HERMES_VOICE.es.md](./HERMES_VOICE.es.md) · [HARNESS_HERMES.es.md](./HARNESS_HERMES.es.md) |
+| Claude Code | `claude -p` | ❌ | [HARNESS_CLAUDE.es.md](./HARNESS_CLAUDE.es.md) |
+| Codex | `codex exec` | ❌ (captura del último mensaje) | [HARNESS_CODEX.es.md](./HARNESS_CODEX.es.md) |
+| Gemini CLI | `gemini -p` | ❌ | [HARNESS_GEMINI.es.md](./HARNESS_GEMINI.es.md) |
+| OpenCode | `opencode run` | ❌ | [HARNESS_OPENCODE.es.md](./HARNESS_OPENCODE.es.md) |
+| OpenClaw | `openclaw run` | ❌ | [HARNESS_OPENCLAW.es.md](./HARNESS_OPENCLAW.es.md) |
+| Aider | `aider --no-pretty --yes-always --message` | ❌ | [HARNESS_AIDER.es.md](./HARNESS_AIDER.es.md) |
+| Cursor CLI | `cursor-agent --print --prompt` | ❌ | [HARNESS_CURSOR.es.md](./HARNESS_CURSOR.es.md) |
+
+## Elige tu agente por defecto
+
+`vc setup` autodetecta los binarios instalados y te deja elegir. Configuración no interactiva:
+
+```bash
+# .env o instance .env
+AGENT_BACKEND=claude              # hermes | claude | codex | gemini | opencode | openclaw | aider | cursor | custom
+```
+
+Cada harness lee su comando de la env del mismo nombre (`HERMES_COMMAND`, `CLAUDE_COMMAND`, etc.). Las envs compartidas (`AGENT_LABEL`, `AGENT_COMMAND`, `AGENT_SESSION_FILE`, `AGENT_WORKDIR`, `AGENT_PROJECT_CONTEXT`, `AGENT_TASK_TIMEOUT_MS`, `AGENT_CHAT_TIMEOUT_MS`, `AGENT_VERBOSE_PROGRESS`) sobreescriben los valores por defecto de cada harness.
+
+## Enrutamiento entre harnesses por voz
+
+Una vez configurado, puedes alcanzar cualquier harness **instalado** sin reiniciar:
+
+- `"ask Codex what it thinks"` — ruta de un solo turno; el siguiente turno vuelve al predeterminado.
+- `"switch to Aider"` — ruta sticky hasta que digas `"back to default"`.
+- Slot `which_agent` del modo plan — el propio agente propone qué backend ejecuta el siguiente plan.
+
+La capa de enrutamiento verifica si el binario está en `PATH` (resolviendo rutas relativas contra el workdir de la sesión de proyecto activa). Si no está instalado, el puente pregunta `"¿Quieres que use el agente por defecto?"` — responde `"yes"` para hacer fallback o `"no"` para cancelar.
+
+Alias reconocidos: `claude` / `claude code`, `codex`, `gemini` / `gemini cli`, `opencode`, `openclaw`, `aider`, `cursor` / `cursor cli`, `hermes`.
+
+## Semánticas compartidas
+
+Todo adaptador respeta:
+
+- **Modo plan por voz** — `"plan it first"` narra un plan, edita por voz, `"approve"` ejecuta contra el harness elegido.
+- **Barge-in** — el corte interrumpe el TTS actual y aborta la tarea del agente. El enrutamiento sticky sobrevive a interrupciones; solo las rutas de un turno se limpian.
+- **Progreso detallado** — `AGENT_VERBOSE_PROGRESS=1` imprime eventos de progreso. Con `SMART_PROGRESS_API_KEY`, un LLM los resume en una frase por lote.
+- **Notificación push** — `NOTIFY_PROVIDER=ntfy|pushover` + `NOTIFY_MIN_TASK_MS` envía push cuando una tarea larga termina y el canal de voz está vacío. Debounce por cuerpo + `NOTIFY_DEBOUNCE_MS`.
+- **Estado por canal** — cada canal de voz mantiene su propio enrutamiento, estado de plan y buffer de elocuciones recientes.
+- **Sesiones de proyecto** — `!session new <name> <workdir>` vincula un canal a un proyecto; los adaptadores (harness, sesión) se cachean y se invalidan al rebind.
+
+Detalles de instalación, autenticación y pitfalls por harness en sus docs respectivos. Referencia completa de env: `docs/CONFIGURATION.es.md`.

package/docs/i18n/HARNESSES.fr.md

@@ -0,0 +1,58 @@
+# Harnesses d'agents de codage
+
+<p align="center">
+  <a href="../../README.fr.md">README</a> ·
+  <a href="README.fr.md">Docs hub</a> ·
+  <a href="USAGE.fr.md">Utilisation</a> ·
+  <a href="CONFIGURATION.fr.md">Configuration</a> ·
+  <a href="TROUBLESHOOTING.fr.md">Dépannage</a>
+</p>
+
+VerbalCoding est agnostique : il pilote le CLI de codage installé chez vous, un appel par tour vocal, en lui passant la transcription comme prompt et en jouant la réponse. Choisissez **un** agent par défaut ; le routage par voix permet d'atteindre les autres en cours de session.
+
+| Harness | Commande par défaut | Reprise de session | Doc dédiée |
+|---|---|---|---|
+| Hermes Agent | `hermes chat -Q -q` | ✅ (`--resume <id>`) | [HERMES_VOICE.fr.md](./HERMES_VOICE.fr.md) · [HARNESS_HERMES.fr.md](./HARNESS_HERMES.fr.md) |
+| Claude Code | `claude -p` | ❌ | [HARNESS_CLAUDE.fr.md](./HARNESS_CLAUDE.fr.md) |
+| Codex | `codex exec` | ❌ (capture du dernier message) | [HARNESS_CODEX.fr.md](./HARNESS_CODEX.fr.md) |
+| Gemini CLI | `gemini -p` | ❌ | [HARNESS_GEMINI.fr.md](./HARNESS_GEMINI.fr.md) |
+| OpenCode | `opencode run` | ❌ | [HARNESS_OPENCODE.fr.md](./HARNESS_OPENCODE.fr.md) |
+| OpenClaw | `openclaw run` | ❌ | [HARNESS_OPENCLAW.fr.md](./HARNESS_OPENCLAW.fr.md) |
+| Aider | `aider --no-pretty --yes-always --message` | ❌ | [HARNESS_AIDER.fr.md](./HARNESS_AIDER.fr.md) |
+| Cursor CLI | `cursor-agent --print --prompt` | ❌ | [HARNESS_CURSOR.fr.md](./HARNESS_CURSOR.fr.md) |
+
+## Choisir l'agent par défaut
+
+`vc setup` détecte les binaires installés et propose un choix. Sans interaction :
+
+```bash
+# .env ou instance .env
+AGENT_BACKEND=claude              # hermes | claude | codex | gemini | opencode | openclaw | aider | cursor | custom
+```
+
+Chaque harness lit sa commande dans l'env homonyme (`HERMES_COMMAND`, `CLAUDE_COMMAND`, etc.). Les envs partagées (`AGENT_LABEL`, `AGENT_COMMAND`, `AGENT_SESSION_FILE`, `AGENT_WORKDIR`, `AGENT_PROJECT_CONTEXT`, `AGENT_TASK_TIMEOUT_MS`, `AGENT_CHAT_TIMEOUT_MS`, `AGENT_VERBOSE_PROGRESS`) surchargent les valeurs par défaut.
+
+## Routage entre harnesses par voix
+
+Une fois configuré, vous atteignez n'importe quel harness **installé** sans redémarrer :
+
+- `"ask Codex what it thinks"` — routage à un tour ; le tour suivant revient au défaut.
+- `"switch to Aider"` — routage sticky jusqu'à `"back to default"`.
+- Slot `which_agent` du mode plan — l'agent propose lui-même quel backend exécute le plan.
+
+Le routeur vérifie la présence du binaire dans `PATH` (les chemins relatifs sont résolus contre le workdir de la session projet active). Sinon, il demande `"Utiliser l'agent par défaut à la place ?"` — `"yes"` pour le fallback, `"no"` pour annuler.
+
+Alias reconnus : `claude` / `claude code`, `codex`, `gemini` / `gemini cli`, `opencode`, `openclaw`, `aider`, `cursor` / `cursor cli`, `hermes`.
+
+## Sémantique partagée
+
+Tous les adaptateurs respectent :
+
+- **Mode plan vocal** — `"plan it first"` narre un plan, édition vocale, `"approve"` exécute via le harness choisi.
+- **Barge-in** — l'interruption coupe le TTS courant et abort la tâche de l'agent. Le routage sticky survit aux interruptions ; seuls les routages à un tour sont effacés.
+- **Progression verbeuse** — `AGENT_VERBOSE_PROGRESS=1` affiche les événements ; avec `SMART_PROGRESS_API_KEY`, un LLM les résume.
+- **Push notification** — `NOTIFY_PROVIDER=ntfy|pushover` + `NOTIFY_MIN_TASK_MS` envoie un push quand une tâche longue se termine et que le canal vocal est vide ; debounce par corps + `NOTIFY_DEBOUNCE_MS`.
+- **État par canal** — chaque canal vocal Discord conserve son routage, son état de plan, son buffer d'énoncés.
+- **Sessions projet** — `!session new <name> <workdir>` lie un canal à un projet ; les adaptateurs (harness, session) sont cachés et invalidés au rebind.
+
+Détails d'installation et pièges par harness dans leurs docs respectifs. Référence env complète : `docs/CONFIGURATION.fr.md`.

package/docs/i18n/HARNESSES.ja.md

@@ -0,0 +1,58 @@
+# コーディングエージェントハーネス
+
+<p align="center">
+  <a href="../../README.ja.md">README</a> ·
+  <a href="README.ja.md">ドキュメントハブ</a> ·
+  <a href="USAGE.ja.md">使い方</a> ·
+  <a href="CONFIGURATION.ja.md">設定</a> ·
+  <a href="TROUBLESHOOTING.ja.md">トラブルシュート</a>
+</p>
+
+VerbalCoding はエージェント非依存です。インストール済みの CLI コーディングエージェントを音声ターンごとに 1 回起動し、STT した発話を prompt として渡し、応答を音声で返します。**1 つ**を既定として選び、音声ルーティングで他のエージェントへ一時的に切り替えます。
+
+| ハーネス | 既定コマンド | セッション再開 | ハーネス別ドキュメント |
+|---|---|---|---|
+| Hermes Agent | `hermes chat -Q -q` | ✅ (`--resume <id>`) | [HERMES_VOICE.ja.md](./HERMES_VOICE.ja.md) · [HARNESS_HERMES.ja.md](./HARNESS_HERMES.ja.md) |
+| Claude Code | `claude -p` | ❌ | [HARNESS_CLAUDE.ja.md](./HARNESS_CLAUDE.ja.md) |
+| Codex | `codex exec` | ❌ (最終メッセージファイル取得) | [HARNESS_CODEX.ja.md](./HARNESS_CODEX.ja.md) |
+| Gemini CLI | `gemini -p` | ❌ | [HARNESS_GEMINI.ja.md](./HARNESS_GEMINI.ja.md) |
+| OpenCode | `opencode run` | ❌ | [HARNESS_OPENCODE.ja.md](./HARNESS_OPENCODE.ja.md) |
+| OpenClaw | `openclaw run` | ❌ | [HARNESS_OPENCLAW.ja.md](./HARNESS_OPENCLAW.ja.md) |
+| Aider | `aider --no-pretty --yes-always --message` | ❌ | [HARNESS_AIDER.ja.md](./HARNESS_AIDER.ja.md) |
+| Cursor CLI | `cursor-agent --print --prompt` | ❌ | [HARNESS_CURSOR.ja.md](./HARNESS_CURSOR.ja.md) |
+
+## 既定エージェントの選択
+
+`vc setup` がインストール済みバイナリを自動検出して選択肢を提示します。非対話設定:
+
+```bash
+# .env または instance .env
+AGENT_BACKEND=claude              # hermes | claude | codex | gemini | opencode | openclaw | aider | cursor | custom
+```
+
+各ハーネスは自分のコマンドを同名の env (`HERMES_COMMAND`, `CLAUDE_COMMAND` など) から読みます。共通 env (`AGENT_LABEL`, `AGENT_COMMAND`, `AGENT_SESSION_FILE`, `AGENT_WORKDIR`, `AGENT_PROJECT_CONTEXT`, `AGENT_TASK_TIMEOUT_MS`, `AGENT_CHAT_TIMEOUT_MS`, `AGENT_VERBOSE_PROGRESS`) は当該ハーネス既定値を上書きします。
+
+## 音声でのルーティング
+
+設定後は再起動なしで**インストール済み**の任意ハーネスへ届きます:
+
+- `"ask Codex what it thinks"` — 単一ターンのみ Codex、次ターンは既定へ復帰。
+- `"switch to Aider"` — sticky ルート、`"back to default"`まで持続。
+- プランモードの `which_agent` スロット — エージェント自身が次のプランの実行先を提案。
+
+ルーティング層はバイナリの `PATH` 存在を確認し(プロジェクトセッションの workdir からの相対パスも解決)、未インストールなら `"既定エージェントで代わりに進める?"` と尋ねます。`"yes"` で既定に fallback、`"no"` でキャンセル。
+
+パーサが認識するエイリアス: `claude` / `claude code`, `codex` / `コーデックス`, `gemini` / `gemini cli` / `ジェミニ`, `opencode`, `openclaw`, `aider`, `cursor` / `cursor cli`, `hermes`.
+
+## 共通動作
+
+全ハーネスアダプタが共通で扱うもの:
+
+- **音声プランモード** — `"plan it first"` でプランを narrate、音声で編集、`"approve"` で選択ハーネスへ実行。
+- **割り込み** — barge-in は現在の TTS を切り、エージェントタスクを abort。sticky ルートは割り込み後も維持、単一ターンルートのみクリア。
+- **詳細進捗** — `AGENT_VERBOSE_PROGRESS=1` (または `"verbose progress on"`) でハーネスが emit する進捗イベントを表示。`SMART_PROGRESS_API_KEY` 設定で LLM 要約器がバッチごとに 1 文に。
+- **プッシュ通知ハンドオフ** — `NOTIFY_PROVIDER=ntfy|pushover` + `NOTIFY_MIN_TASK_MS` を満たし、音声チャンネルが空のときに push。body + `NOTIFY_DEBOUNCE_MS` で debounce。
+- **チャンネル別状態** — Discord 音声チャンネルごとにルーティング・プラン状態・発話リングバッファを保持。
+- **プロジェクトセッション** — `!session new <name> <workdir>` でチャンネルとプロジェクトを束ねる。(ハーネス, セッション) 別アダプタはキャッシュされ rebind 時に無効化。
+
+ハーネス別の install パス、認証、罠は各ドキュメント参照。env リファレンスは `docs/CONFIGURATION.ja.md`。

package/docs/i18n/HARNESSES.ko.md

@@ -0,0 +1,58 @@
+# 코딩 에이전트 하니스
+
+<p align="center">
+  <a href="../../README.ko.md">README</a> ·
+  <a href="README.ko.md">문서 허브</a> ·
+  <a href="USAGE.ko.md">사용법</a> ·
+  <a href="CONFIGURATION.ko.md">설정</a> ·
+  <a href="TROUBLESHOOTING.ko.md">문제 해결</a>
+</p>
+
+VerbalCoding은 에이전트 종속이 아니야. 설치돼 있는 CLI 코딩 에이전트를 voice turn 하나당 한 번씩 실행하고, STT 결과를 prompt로 넘긴 다음 응답을 음성으로 돌려줘. **하나**를 기본 에이전트로 정하고, 음성 라우팅으로 다른 에이전트에 잠깐씩 전환할 수 있어.
+
+| 하니스 | 기본 명령 | 세션 재개 | 하니스별 문서 |
+|---|---|---|---|
+| Hermes Agent | `hermes chat -Q -q` | ✅ (`--resume <id>`) | [HERMES_VOICE.ko.md](./HERMES_VOICE.ko.md) · [HARNESS_HERMES.ko.md](./HARNESS_HERMES.ko.md) |
+| Claude Code | `claude -p` | ❌ | [HARNESS_CLAUDE.ko.md](./HARNESS_CLAUDE.ko.md) |
+| Codex | `codex exec` | ❌ (마지막 메시지 파일 캡처) | [HARNESS_CODEX.ko.md](./HARNESS_CODEX.ko.md) |
+| Gemini CLI | `gemini -p` | ❌ | [HARNESS_GEMINI.ko.md](./HARNESS_GEMINI.ko.md) |
+| OpenCode | `opencode run` | ❌ | [HARNESS_OPENCODE.ko.md](./HARNESS_OPENCODE.ko.md) |
+| OpenClaw | `openclaw run` | ❌ | [HARNESS_OPENCLAW.ko.md](./HARNESS_OPENCLAW.ko.md) |
+| Aider | `aider --no-pretty --yes-always --message` | ❌ | [HARNESS_AIDER.ko.md](./HARNESS_AIDER.ko.md) |
+| Cursor CLI | `cursor-agent --print --prompt` | ❌ | [HARNESS_CURSOR.ko.md](./HARNESS_CURSOR.ko.md) |
+
+## 기본 에이전트 고르기
+
+`vc setup`이 설치된 바이너리를 자동 감지해서 선택지를 보여줘. 비대화형 설정은:
+
+```bash
+# .env 또는 instance .env
+AGENT_BACKEND=claude              # hermes | claude | codex | gemini | opencode | openclaw | aider | cursor | custom
+```
+
+각 하니스는 자기 명령을 같은 이름의 env 변수(`HERMES_COMMAND`, `CLAUDE_COMMAND` 등)에서 읽어. 공통 env (`AGENT_LABEL`, `AGENT_COMMAND`, `AGENT_SESSION_FILE`, `AGENT_WORKDIR`, `AGENT_PROJECT_CONTEXT`, `AGENT_TASK_TIMEOUT_MS`, `AGENT_CHAT_TIMEOUT_MS`, `AGENT_VERBOSE_PROGRESS`)는 해당 하니스의 기본값을 덮어써.
+
+## 음성으로 하니스 사이 라우팅
+
+설정이 끝나면 재시작 없이 **설치돼 있는** 어떤 하니스로든 옮길 수 있어:
+
+- `"코덱스한테 물어봐"` — 이번 턴만 Codex, 다음 턴은 기본 에이전트로 복귀.
+- `"aider로 전환"` — sticky 라우팅, `"기본으로 돌아가"`라고 할 때까지 유지.
+- 플랜 모드의 `which_agent` 슬롯 — 에이전트가 다음 플랜을 어느 백엔드로 돌릴지 직접 제안.
+
+라우팅 레이어는 바이너리가 `PATH`에 있는지 확인하고 (활성 프로젝트 세션의 workdir 기준 상대 경로도 처리), 없으면 `"기본 에이전트로 대신 진행할까?"`라고 물어봐. `"예"`로 답하면 기본 에이전트로 fallback, `"아니오"`로 취소.
+
+파서가 인식하는 별칭: `claude` / `claude code`, `codex` / `코덱스`, `gemini` / `gemini cli` / `제미나이`, `opencode`, `openclaw`, `aider` / `에이더`, `cursor` / `cursor cli`, `hermes` / `헤르메스`.
+
+## 공통 동작
+
+모든 하니스 어댑터가 똑같이 처리하는 것들:
+
+- **음성 플랜 모드** — `"먼저 계획 짜줘"`로 플랜을 만들고, 음성으로 편집한 다음 `"실행"`이라고 하면 선택된 하니스로 실행돼.
+- **Barge-in** — 끼어들기는 현재 TTS를 끊고 에이전트 작업을 abort 시켜. Sticky 라우팅은 interrupt 후에도 유지, 단일 턴 라우팅만 초기화돼.
+- **상세 진행** — `AGENT_VERBOSE_PROGRESS=1` (또는 `"상세 진행 켜"`)로 하니스가 emit하는 진행 이벤트를 출력해. `SMART_PROGRESS_API_KEY`가 있으면 LLM 요약기가 묶음당 한 문장으로 정리.
+- **푸시 알림 핸드오프** — `NOTIFY_PROVIDER=ntfy|pushover` + `NOTIFY_MIN_TASK_MS` 조건 충족 시 긴 작업이 끝나고 음성채널이 비어 있으면 푸시. body + `NOTIFY_DEBOUNCE_MS`로 debounce.
+- **채널별 상태** — 디스코드 음성 채널마다 별도의 라우팅·플랜 상태·발화 링 버퍼.
+- **프로젝트 세션** — `!session new <name> <workdir>`로 채널과 프로젝트를 묶음. (하니스, 세션)별 어댑터는 캐시되고 rebind 시 무효화.
+
+설치 경로, 인증, 함정은 하니스별 문서 참고. env 변수 전체 레퍼런스는 `docs/CONFIGURATION.ko.md`.

package/docs/i18n/HARNESSES.ru.md

@@ -0,0 +1,58 @@
+# Harness-ы для кодинг-агентов
+
+<p align="center">
+  <a href="../../README.ru.md">README</a> ·
+  <a href="README.ru.md">Хаб документации</a> ·
+  <a href="USAGE.ru.md">Использование</a> ·
+  <a href="CONFIGURATION.ru.md">Настройка</a> ·
+  <a href="TROUBLESHOOTING.ru.md">Решение проблем</a>
+</p>
+
+VerbalCoding не привязан к конкретному агенту: он вызывает установленный CLI кодинг-агент один раз на voice turn, передаёт STT-расшифровку как prompt и проигрывает ответ голосом. Выберите **один** агент по умолчанию; голосовая маршрутизация позволит дотянуться до остальных в течение сессии.
+
+| Harness | Команда по умолчанию | Возобновление сессии | Документ |
+|---|---|---|---|
+| Hermes Agent | `hermes chat -Q -q` | ✅ (`--resume <id>`) | [HERMES_VOICE.ru.md](./HERMES_VOICE.ru.md) · [HARNESS_HERMES.ru.md](./HARNESS_HERMES.ru.md) |
+| Claude Code | `claude -p` | ❌ | [HARNESS_CLAUDE.ru.md](./HARNESS_CLAUDE.ru.md) |
+| Codex | `codex exec` | ❌ (захват последнего сообщения в файл) | [HARNESS_CODEX.ru.md](./HARNESS_CODEX.ru.md) |
+| Gemini CLI | `gemini -p` | ❌ | [HARNESS_GEMINI.ru.md](./HARNESS_GEMINI.ru.md) |
+| OpenCode | `opencode run` | ❌ | [HARNESS_OPENCODE.ru.md](./HARNESS_OPENCODE.ru.md) |
+| OpenClaw | `openclaw run` | ❌ | [HARNESS_OPENCLAW.ru.md](./HARNESS_OPENCLAW.ru.md) |
+| Aider | `aider --no-pretty --yes-always --message` | ❌ | [HARNESS_AIDER.ru.md](./HARNESS_AIDER.ru.md) |
+| Cursor CLI | `cursor-agent --print --prompt` | ❌ | [HARNESS_CURSOR.ru.md](./HARNESS_CURSOR.ru.md) |
+
+## Выбор агента по умолчанию
+
+`vc setup` автоматически находит установленные бинарники и предлагает выбор. Без интерактива:
+
+```bash
+# .env или instance .env
+AGENT_BACKEND=claude              # hermes | claude | codex | gemini | opencode | openclaw | aider | cursor | custom
+```
+
+Каждый harness читает свою команду из одноимённой env (`HERMES_COMMAND`, `CLAUDE_COMMAND` и т. д.). Общие env (`AGENT_LABEL`, `AGENT_COMMAND`, `AGENT_SESSION_FILE`, `AGENT_WORKDIR`, `AGENT_PROJECT_CONTEXT`, `AGENT_TASK_TIMEOUT_MS`, `AGENT_CHAT_TIMEOUT_MS`, `AGENT_VERBOSE_PROGRESS`) перекрывают значения по умолчанию.
+
+## Голосовая маршрутизация между harness
+
+После настройки можно дотянуться до любого **установленного** harness без перезапуска:
+
+- `"ask Codex what it thinks"` — маршрут на один turn, следующий turn возвращается к умолчанию.
+- `"switch to Aider"` — sticky-маршрут до `"back to default"`.
+- Слот `which_agent` в plan-mode — агент сам предлагает, какой backend выполнит план.
+
+Маршрутизатор проверяет наличие бинарника в `PATH` (относительные пути резолвятся относительно workdir активной проектной сессии). Если не установлено — мост спрашивает `"Использовать агент по умолчанию?"` — ответьте `"yes"` для fallback или `"no"` для отмены.
+
+Распознаваемые алиасы: `claude` / `claude code`, `codex`, `gemini` / `gemini cli`, `opencode`, `openclaw`, `aider`, `cursor` / `cursor cli`, `hermes`.
+
+## Общая семантика
+
+Все адаптеры соблюдают:
+
+- **Голосовой plan-mode** — `"plan it first"` озвучивает план, голосом правим, `"approve"` запускает на выбранном harness.
+- **Barge-in** — прерывание срезает текущий TTS и abort задачу агента. Sticky-маршрут переживает прерывания; сбрасываются только маршруты на один turn.
+- **Подробный прогресс** — `AGENT_VERBOSE_PROGRESS=1` выводит события прогресса. С `SMART_PROGRESS_API_KEY` LLM-сводщик собирает их в одну фразу на батч.
+- **Push-уведомления** — `NOTIFY_PROVIDER=ntfy|pushover` + `NOTIFY_MIN_TASK_MS` отправляет push, когда длинная задача завершается и голосовой канал пуст. Debounce по телу + `NOTIFY_DEBOUNCE_MS`.
+- **Состояние на канал** — каждый голосовой канал Discord ведёт свою маршрутизацию, состояние плана и буфер последних реплик.
+- **Проектные сессии** — `!session new <name> <workdir>` привязывает канал к проекту; (harness, session) адаптеры кэшируются и инвалидируются при rebind.
+
+Детали установки, авторизации и подводные камни — в документах по каждому harness. Полная справка по env: `docs/CONFIGURATION.ru.md`.

package/docs/i18n/HARNESSES.zh.md

@@ -0,0 +1,58 @@
+# 编码代理 Harness
+
+<p align="center">
+  <a href="../../README.zh.md">README</a> ·
+  <a href="README.zh.md">文档中心</a> ·
+  <a href="USAGE.zh.md">使用</a> ·
+  <a href="CONFIGURATION.zh.md">配置</a> ·
+  <a href="TROUBLESHOOTING.zh.md">排错</a>
+</p>
+
+VerbalCoding 与代理无关。它会驱动你安装的任意 CLI 编码代理:每次语音 turn 启动它一次,把 STT 后的发言作为 prompt 传入,再把回答念回来。选**一个**作为默认,跨代理语音路由让你临时切换到其它代理。
+
+| Harness | 默认命令 | 会话续接 | Harness 专用文档 |
+|---|---|---|---|
+| Hermes Agent | `hermes chat -Q -q` | ✅ (`--resume <id>`) | [HERMES_VOICE.zh.md](./HERMES_VOICE.zh.md) · [HARNESS_HERMES.zh.md](./HARNESS_HERMES.zh.md) |
+| Claude Code | `claude -p` | ❌ | [HARNESS_CLAUDE.zh.md](./HARNESS_CLAUDE.zh.md) |
+| Codex | `codex exec` | ❌ (末条消息文件抓取) | [HARNESS_CODEX.zh.md](./HARNESS_CODEX.zh.md) |
+| Gemini CLI | `gemini -p` | ❌ | [HARNESS_GEMINI.zh.md](./HARNESS_GEMINI.zh.md) |
+| OpenCode | `opencode run` | ❌ | [HARNESS_OPENCODE.zh.md](./HARNESS_OPENCODE.zh.md) |
+| OpenClaw | `openclaw run` | ❌ | [HARNESS_OPENCLAW.zh.md](./HARNESS_OPENCLAW.zh.md) |
+| Aider | `aider --no-pretty --yes-always --message` | ❌ | [HARNESS_AIDER.zh.md](./HARNESS_AIDER.zh.md) |
+| Cursor CLI | `cursor-agent --print --prompt` | ❌ | [HARNESS_CURSOR.zh.md](./HARNESS_CURSOR.zh.md) |
+
+## 选择默认代理
+
+`vc setup` 会自动检测已安装的二进制并让你选择。非交互方式:
+
+```bash
+# .env 或 instance .env
+AGENT_BACKEND=claude              # hermes | claude | codex | gemini | opencode | openclaw | aider | cursor | custom
+```
+
+每个 harness 从对应同名 env (`HERMES_COMMAND`、`CLAUDE_COMMAND` 等) 读取自己的命令。共享 env (`AGENT_LABEL`、`AGENT_COMMAND`、`AGENT_SESSION_FILE`、`AGENT_WORKDIR`、`AGENT_PROJECT_CONTEXT`、`AGENT_TASK_TIMEOUT_MS`、`AGENT_CHAT_TIMEOUT_MS`、`AGENT_VERBOSE_PROGRESS`) 会覆盖各 harness 默认值。
+
+## 通过语音在 harness 之间路由
+
+配置好后无需重启即可路由到任意**已安装**的 harness:
+
+- `"ask Codex what it thinks"` — 单 turn 路由,下一个 turn 自动回默认。
+- `"switch to Aider"` — 粘性路由,直到说 `"back to default"`。
+- 计划模式 `which_agent` 槽 — 代理自身建议下一个计划由哪个后端执行。
+
+路由层会检测二进制是否在 `PATH` (相对路径按活动项目会话的 workdir 解析);若未安装,bridge 会问 `"用默认代理代替进行?"` — 回答 `"yes"` 转默认,`"no"` 取消。
+
+解析器识别的别名: `claude` / `claude code`、`codex` / `科德克斯`、`gemini` / `gemini cli`、`opencode`、`openclaw`、`aider`、`cursor` / `cursor cli`、`hermes`。
+
+## 共享语义
+
+所有 harness 适配器一致遵守的:
+
+- **语音计划模式** — `"plan it first"` 生成计划,语音编辑,`"approve"` 用选定的 harness 执行。
+- **打断** — barge-in 立即切断当前 TTS 并 abort 代理任务。粘性路由在打断后保留,只清除单 turn 路由。
+- **详细进度** — `AGENT_VERBOSE_PROGRESS=1` (或语音命令) 输出 harness 发出的进度事件。配置 `SMART_PROGRESS_API_KEY` 后,LLM 摘要器每批合成一句。
+- **推送通知** — `NOTIFY_PROVIDER=ntfy|pushover` + `NOTIFY_MIN_TASK_MS` 条件成立且语音频道为空时推送。按 body + `NOTIFY_DEBOUNCE_MS` 去抖。
+- **按频道状态** — 每个 Discord 语音频道单独维护路由、计划状态、发言环形缓冲。
+- **项目会话** — `!session new <name> <workdir>` 将频道绑定到项目。(harness, session) 适配器缓存,rebind 时失效。
+
+各 harness 安装路径、认证、坑请见各自文档。env 完整参考: `docs/CONFIGURATION.zh.md`。

package/docs/i18n/HARNESS_AIDER.es.md

@@ -0,0 +1,48 @@
+# Aider — Notas del Harness
+
+<p align="center">
+  <a href="../../README.es.md">README</a> ·
+  <a href="HARNESSES.es.md">Harnesses</a> ·
+  <a href="USAGE.es.md">Uso</a> ·
+  <a href="CONFIGURATION.es.md">Configuración</a>
+</p>
+
+Aider es un CLI de pair-programming centrado en edits directos. VerbalCoding lo invoca con `aider --no-pretty --yes-always --message`, pasando el prompt como valor de `--message`. Cada turno de voz se vuelve una corrida no interactiva de Aider que puede modificar archivos en `AGENT_WORKDIR`.
+
+## Instalación
+
+```bash
+pip install aider-chat
+aider --version
+aider --no-pretty --yes-always --message "list the top-level files"
+```
+
+Aider necesita una API key para el modelo elegido (OpenAI / Anthropic / servidor local). Ver <https://aider.chat>.
+
+## Configuración
+
+```bash
+# .env
+AGENT_BACKEND=aider
+AIDER_COMMAND="aider --no-pretty --yes-always --message"
+AGENT_WORKDIR=/Users/you/code/your-project
+AGENT_PROJECT_CONTEXT="..."
+AGENT_CHAT_TIMEOUT_MS=120000
+AGENT_TASK_TIMEOUT_MS=0
+```
+
+`--no-pretty` quita caracteres de caja de Rich. `--yes-always` mantiene la corrida no interactiva.
+
+## Frases de voz para cambiar a Aider
+
+- en: `"switch to Aider"`, `"ask Aider to ..."`
+- es: `"cambia a Aider"`, `"pásalo a Aider"`
+
+Alias: `aider`.
+
+## Trampas
+
+- **Aider edita ficheros.** A diferencia de Claude / Codex / Gemini bajo `-p`, Aider modifica el árbol de trabajo al responder. Ajusta `AGENT_WORKDIR` con cuidado.
+- **Diffs en salida.** Si se interrumpe el turno, el puente no lee diffs; consulta el canal de texto y `git status`.
+- **Auth.** `OPENAI_API_KEY` / `ANTHROPIC_API_KEY` deben estar en el entorno de Aider; suelen vivir en `instances/<project>.env`.
+- **Estado por canal.** El enrutamiento es por canal de Discord; cambiar a Aider en una sala no afecta a las otras.

package/docs/i18n/HARNESS_AIDER.fr.md

@@ -0,0 +1,48 @@
+# Aider — Notes Harness
+
+<p align="center">
+  <a href="../../README.fr.md">README</a> ·
+  <a href="HARNESSES.fr.md">Harnesses</a> ·
+  <a href="USAGE.fr.md">Utilisation</a> ·
+  <a href="CONFIGURATION.fr.md">Configuration</a>
+</p>
+
+Aider est un CLI de pair-programming centré sur les edits directs. VerbalCoding l'invoque via `aider --no-pretty --yes-always --message`, en passant le prompt comme valeur de `--message`. Chaque tour vocal devient un run Aider non interactif susceptible de modifier des fichiers dans `AGENT_WORKDIR`.
+
+## Installation
+
+```bash
+pip install aider-chat
+aider --version
+aider --no-pretty --yes-always --message "list the top-level files"
+```
+
+Aider requiert la clé API du modèle utilisé (OpenAI / Anthropic / serveur local). Voir <https://aider.chat>.
+
+## Configuration
+
+```bash
+# .env
+AGENT_BACKEND=aider
+AIDER_COMMAND="aider --no-pretty --yes-always --message"
+AGENT_WORKDIR=/Users/you/code/your-project
+AGENT_PROJECT_CONTEXT="..."
+AGENT_CHAT_TIMEOUT_MS=120000
+AGENT_TASK_TIMEOUT_MS=0
+```
+
+`--no-pretty` retire les caractères de cadre Rich. `--yes-always` garde la run non interactive.
+
+## Phrases vocales pour basculer vers Aider
+
+- en: `"switch to Aider"`, `"ask Aider to ..."`
+- fr: `"passe à Aider"`
+
+Alias : `aider`.
+
+## Pièges
+
+- **Aider modifie les fichiers.** Contrairement à Claude/Codex/Gemini en `-p`, Aider touche directement à l'arbre de travail. `AGENT_WORKDIR` doit être bien choisi (généralement le `workdir` d'une session projet).
+- **Diffs dans la sortie.** Si le tour est interrompu, le bridge ne lit pas le diff — utilisez le canal texte et `git status`.
+- **Auth.** `OPENAI_API_KEY` / `ANTHROPIC_API_KEY` doivent être dans l'env d'Aider ; en isolation, mettez-les dans `instances/<project>.env`.
+- **État par canal.** Le routage inter-agents est par canal Discord ; passer à Aider dans un salon n'affecte pas les autres.

package/docs/i18n/HARNESS_AIDER.ja.md

@@ -0,0 +1,50 @@
+# Aider — ハーネスノート
+
+<p align="center">
+  <a href="../../README.ja.md">README</a> ·
+  <a href="HARNESSES.ja.md">ハーネス</a> ·
+  <a href="USAGE.ja.md">使い方</a> ·
+  <a href="CONFIGURATION.ja.md">設定</a>
+</p>
+
+Aider はファイルを直接編集するペアプログラミング AI CLI。VerbalCoding は `aider --no-pretty --yes-always --message` で呼び出し、prompt は `--message` 値として渡されます。音声ターン 1 つが `AGENT_WORKDIR` のファイルを直接書き換え得る非対話 Aider 実行 1 つになります。
+
+## インストール
+
+```bash
+pip install aider-chat
+aider --version
+# 単一メッセージ実行を確認:
+aider --no-pretty --yes-always --message "list the top-level files"
+```
+
+Aider は使用モデルの API キーが必要 (OpenAI / Anthropic / ローカルサーバ)。<https://aider.chat> 参照。
+
+## VerbalCoding 設定
+
+```bash
+# .env
+AGENT_BACKEND=aider
+# 任意
+AIDER_COMMAND="aider --no-pretty --yes-always --message"   # 既定
+AGENT_WORKDIR=/Users/you/code/your-project                 # Aider が編集するディレクトリ
+AGENT_PROJECT_CONTEXT="..."
+AGENT_CHAT_TIMEOUT_MS=120000                               # Aider は時間がかかることが多い
+AGENT_TASK_TIMEOUT_MS=0
+```
+
+`--no-pretty` は Rich のボックス文字を抑え、ストリーム sentencer が詰まらないようにします。`--yes-always` は非対話実行を維持 (Aider が "この diff を適用?" で止まらない)。
+
+## Aider へ切り替える音声表現
+
+- en: `"switch to Aider"`, `"ask Aider to ..."`
+- ja: `"Aider に切り替えて"`, `"Aider に頼んで"`
+
+エイリアス: `aider`。
+
+## 罠
+
+- **Aider はファイルを編集します。** `-p` モードの Claude / Codex / Gemini と異なり、Aider は応答時にワーキングツリーを直接変更。`AGENT_WORKDIR` を慎重に指定 — 通常はプロジェクトセッションの `workdir`。
+- **出力に diff。** Aider はしばしば diff 形式のテキストを出力。ターン中断時は "中断" 通知のみ発話し diff は読み上げません — テキストチャンネルと `git status` で確認。
+- **認証。** `OPENAI_API_KEY` / `ANTHROPIC_API_KEY` を Aider の環境に。インスタンス分離は通常 `instances/<project>.env` を使用。
+- **チャンネル別状態。** クロスエージェントルーティングは Discord チャンネル単位。あるプロジェクトルームで Aider に切り替えても他ルームには影響しません。

package/docs/i18n/HARNESS_AIDER.ko.md

@@ -0,0 +1,50 @@
+# Aider — 하니스 노트
+
+<p align="center">
+  <a href="../../README.ko.md">README</a> ·
+  <a href="HARNESSES.ko.md">하니스</a> ·
+  <a href="USAGE.ko.md">사용법</a> ·
+  <a href="CONFIGURATION.ko.md">설정</a>
+</p>
+
+Aider는 직접 파일 수정에 집중한 페어 프로그래밍 AI CLI야. VerbalCoding은 `aider --no-pretty --yes-always --message`로 호출해 — prompt는 `--message` 값으로 들어가고, voice turn 하나가 `AGENT_WORKDIR`의 파일을 직접 수정할 수 있는 non-interactive Aider 실행 하나가 돼.
+
+## 설치
+
+```bash
+pip install aider-chat
+aider --version
+# 단일 메시지 실행 확인:
+aider --no-pretty --yes-always --message "list the top-level files"
+```
+
+Aider는 사용하는 모델용 API 키가 필요해 (OpenAI / Anthropic / 로컬 서버). <https://aider.chat> 참고.
+
+## VerbalCoding 설정
+
+```bash
+# .env
+AGENT_BACKEND=aider
+# 선택
+AIDER_COMMAND="aider --no-pretty --yes-always --message"   # 기본값
+AGENT_WORKDIR=/Users/you/code/your-project                 # Aider가 편집할 디렉터리
+AGENT_PROJECT_CONTEXT="..."
+AGENT_CHAT_TIMEOUT_MS=120000                               # Aider는 더 오래 걸릴 수 있음
+AGENT_TASK_TIMEOUT_MS=0
+```
+
+`--no-pretty`는 Rich 박스 문자를 제거해서 스트림 sentencer가 안 막혀. `--yes-always`는 실행을 non-interactive로 유지 (Aider가 "이 diff 적용할까요?" 같은 대화 없이 진행).
+
+## Aider로 전환하는 음성 표현
+
+- en: `"switch to Aider"`, `"ask Aider to ..."`
+- ko: `"aider로 전환해줘"`, `"에이더로 전환"`
+
+매처가 받는 별칭: `aider`, `에이더`.
+
+## 함정
+
+- **Aider는 파일을 수정해.** `-p` 모드의 Claude / Codex / Gemini와 달리 Aider는 답변하면서 작업 트리를 직접 바꿔. `AGENT_WORKDIR` 설정을 신중히 — 보통 프로젝트 세션의 `workdir`이 적당.
+- **출력에 diff.** Aider는 diff 모양 텍스트를 자주 emit해. 턴이 interrupt되면 bridge는 "중단됨" 안내만 하고 diff는 음성으로 안 읽어 — 텍스트 채널과 `git status`로 확인해.
+- **인증.** `OPENAI_API_KEY` / `ANTHROPIC_API_KEY`가 Aider 환경에 있어야 해. 인스턴스 격리 설치는 보통 `instances/<project>.env` 사용.
+- **채널별 상태.** 크로스 에이전트 라우팅은 디스코드 채널 기준이라, 한 프로젝트 룸에서 Aider로 전환해도 다른 룸엔 영향 없어.

package/docs/i18n/HARNESS_AIDER.ru.md

@@ -0,0 +1,48 @@
+# Aider — Заметки по harness
+
+<p align="center">
+  <a href="../../README.ru.md">README</a> ·
+  <a href="HARNESSES.ru.md">Harness-ы</a> ·
+  <a href="USAGE.ru.md">Использование</a> ·
+  <a href="CONFIGURATION.ru.md">Настройка</a>
+</p>
+
+Aider — CLI для парного программирования с прямыми правками. VerbalCoding вызывает его через `aider --no-pretty --yes-always --message`, передавая prompt значением `--message`. Каждый voice turn — это один не интерактивный запуск Aider, который может изменять файлы в `AGENT_WORKDIR`.
+
+## Установка
+
+```bash
+pip install aider-chat
+aider --version
+aider --no-pretty --yes-always --message "list the top-level files"
+```
+
+Aider требует API-ключ выбранной модели (OpenAI / Anthropic / локальный сервер). См. <https://aider.chat>.
+
+## Настройка
+
+```bash
+# .env
+AGENT_BACKEND=aider
+AIDER_COMMAND="aider --no-pretty --yes-always --message"
+AGENT_WORKDIR=/Users/you/code/your-project
+AGENT_PROJECT_CONTEXT="..."
+AGENT_CHAT_TIMEOUT_MS=120000
+AGENT_TASK_TIMEOUT_MS=0
+```
+
+`--no-pretty` убирает рамки Rich, чтобы sentencer не подвисал. `--yes-always` держит запуск не интерактивным.
+
+## Голосовые фразы для переключения на Aider
+
+- en: `"switch to Aider"`, `"ask Aider to ..."`
+- ru: `"переключись на Aider"`
+
+Алиасы: `aider`.
+
+## Подводные камни
+
+- **Aider правит файлы.** В отличие от Claude/Codex/Gemini в `-p`, Aider трогает рабочее дерево в момент ответа. Аккуратно выбирайте `AGENT_WORKDIR` (обычно — `workdir` проектной сессии).
+- **Diff в выводе.** При прерывании turn-а мост не зачитывает diff; смотрите текстовый канал и `git status`.
+- **Auth.** `OPENAI_API_KEY` / `ANTHROPIC_API_KEY` должны быть в env Aider; обычно — в `instances/<project>.env`.
+- **Состояние на канал.** Маршрутизация cross-agent — на канал Discord; переключение на Aider в одной комнате не влияет на другие.