verbalcoding 0.2.12 → 0.2.13

package/docs/i18n/HARNESS_CODEX.ru.md

@@ -0,0 +1,55 @@
+# Codex — Заметки по 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>
+
+Codex CLI — терминальный кодинг-агент OpenAI. VerbalCoding вызывает его через `codex exec`. Поскольку `codex exec` пишет финальный текст ассистента во временный файл при `--output-last-message <path>`, адаптер вставляет этот флаг автоматически и читает ответ из файла, даже если stdout шумный.
+
+## Установка
+
+```bash
+npm install -g @openai/codex
+codex login                     # либо OPENAI_API_KEY для headless
+codex exec "hello"
+```
+
+## Настройка
+
+```bash
+# .env
+AGENT_BACKEND=codex
+CODEX_COMMAND="codex exec"
+AGENT_PROJECT_CONTEXT="Что делаем, что уже решено."
+AGENT_WORKDIR=/Users/you/code/your-project
+AGENT_CHAT_TIMEOUT_MS=45000
+AGENT_TASK_TIMEOUT_MS=0
+```
+
+`AGENT_SESSION_FILE` не используется (Codex `exec` stateless).
+
+## Захват вывода
+
+Для Codex адаптер:
+
+1. Создаёт временный путь `verbalcoding-codex-last-<pid>-<ts>.txt` в `os.tmpdir()`.
+2. Вставляет `--output-last-message <path>` прямо перед последним позиционным аргументом.
+3. После запуска читает этот файл как авторитетный ответ (приоритетнее stdout).
+4. Удаляет временный файл.
+
+Даже если Codex льёт tool-use в stdout, в голос идёт ответ из захваченного файла.
+
+## Голосовые фразы для переключения на Codex
+
+- en: `"switch to Codex"`, `"ask Codex what it thinks"`
+- ru: `"переключись на Codex"`, `"спроси Codex"`
+
+## Подводные камни
+
+- **Долгие задачи.** Ставьте `AGENT_TASK_TIMEOUT_MS=0` под кодогенерацию на минуты. `signal.aborted` уважается — barge-in режет чисто.
+- **Нет возобновления.** Передавайте контекст через `AGENT_PROJECT_CONTEXT`, после смены маршрута — блок hand-off.
+- **Защита от patch-вывода.** Если turn прерван во время diff, мост не зачитывает diff и отправляет в текстовый канал.
+- **Авторизация.** 401 идёт как non-zero exit; fallback на дефолт, если Codex не был дефолтом.

package/docs/i18n/HARNESS_CODEX.zh.md

@@ -0,0 +1,56 @@
+# Codex — Harness 说明
+
+<p align="center">
+  <a href="../../README.zh.md">README</a> ·
+  <a href="HARNESSES.zh.md">Harness</a> ·
+  <a href="USAGE.zh.md">使用</a> ·
+  <a href="CONFIGURATION.zh.md">配置</a>
+</p>
+
+Codex CLI 是 OpenAI 的终端编码代理。VerbalCoding 通过 `codex exec` 驱动。`codex exec` 在带 `--output-last-message <path>` 时会把最终助手文本写到临时文件,适配器会自动插入此标志,并从文件可靠读取答案,即便 stdout 嘈杂。
+
+## 安装
+
+```bash
+npm install -g @openai/codex
+codex login              # 或 headless 设 OPENAI_API_KEY
+codex exec "hello"
+```
+
+## VerbalCoding 配置
+
+```bash
+# .env
+AGENT_BACKEND=codex
+# 可选
+CODEX_COMMAND="codex exec"                      # 默认
+AGENT_PROJECT_CONTEXT="工作内容与已定事项。"
+AGENT_WORKDIR=/Users/you/code/your-project
+AGENT_CHAT_TIMEOUT_MS=45000
+AGENT_TASK_TIMEOUT_MS=0
+```
+
+`AGENT_SESSION_FILE` 未使用 (Codex `exec` 跨调用无状态)。
+
+## 输出抓取
+
+针对 Codex,适配器:
+
+1. 在 `os.tmpdir()` 下生成临时路径 `verbalcoding-codex-last-<pid>-<ts>.txt`。
+2. 在最终 prompt 实参前插入 `--output-last-message <path>`。
+3. 运行后读取该文件作为权威答案 (优先于 stdout)。
+4. 删除临时文件。
+
+即使 Codex 在 stdout 输出工具使用记录,语音回答仍来自抓取文件。
+
+## 切到 Codex 的语音表述
+
+- en: `"switch to Codex"`、`"ask Codex what it thinks"`
+- zh: `"切到 Codex"`、`"问 Codex"`
+
+## 坑
+
+- **长任务。** 长达分钟级的代码生成需要 `AGENT_TASK_TIMEOUT_MS=0`。适配器尊重 `signal.aborted`,barge-in 切得干净。
+- **无会话续接。** 用 `AGENT_PROJECT_CONTEXT` 传递上下文,路由变化后的连续性靠跨代理 handoff 块。
+- **patch 输出安全。** 中断时若 Codex 正发 diff,bridge 不会朗读 diff,只播报 "已中断" 并提示查看文本频道。
+- **认证。** OpenAI 后端 401 以非零退出;非默认后端时 fallback 提示改用默认代理。

package/docs/i18n/HARNESS_CURSOR.es.md

@@ -0,0 +1,42 @@
+# Cursor CLI — 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>
+
+Cursor CLI (`cursor-agent`) es el agente de terminal de Cursor. VerbalCoding lo invoca con `cursor-agent --print --prompt`, pasando la transcripción como valor de `--prompt`. `--print` mantiene la corrida no interactiva.
+
+## Instalación
+
+```bash
+cursor-agent --print --prompt "hello"
+```
+
+## Configuración
+
+```bash
+# .env
+AGENT_BACKEND=cursor                                       # alias 'cursor-cli' aceptado
+CURSOR_COMMAND="cursor-agent --print --prompt"
+AGENT_PROJECT_CONTEXT="..."
+AGENT_WORKDIR=/Users/you/code/your-project
+AGENT_CHAT_TIMEOUT_MS=45000
+AGENT_TASK_TIMEOUT_MS=0
+```
+
+## Frases de voz para cambiar a Cursor
+
+- en: `"switch to Cursor"`, `"switch to cursor cli"`, `"switch to cursor agent"`
+- es: `"cambia a Cursor"`
+
+Alias: `cursor`, `cursor cli`, `cursor-cli`, `cursor agent`, `cursor-agent`.
+
+## Trampas
+
+- **Posición del prompt.** `--prompt` espera el valor a continuación; el constructor de argv coloca la transcripción al final, así que `CURSOR_COMMAND` debe terminar en `--prompt`.
+- **Efectos colaterales del editor.** Cursor CLI puede tocar ficheros de estado en el cwd; aísla con `AGENT_WORKDIR`.
+- **Sin reanudación.** `AGENT_PROJECT_CONTEXT` + bloque de handoff para continuidad.
+- **Patch safety.** Si se interrumpe en medio de un diff, no se lee en voz.

package/docs/i18n/HARNESS_CURSOR.fr.md

@@ -0,0 +1,42 @@
+# Cursor CLI — 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>
+
+Cursor CLI (`cursor-agent`) est l'agent terminal de Cursor. VerbalCoding l'invoque via `cursor-agent --print --prompt`, en passant la transcription comme valeur de `--prompt`. `--print` maintient le run non interactif.
+
+## Installation
+
+```bash
+cursor-agent --print --prompt "hello"
+```
+
+## Configuration
+
+```bash
+# .env
+AGENT_BACKEND=cursor                                       # alias 'cursor-cli' accepté
+CURSOR_COMMAND="cursor-agent --print --prompt"
+AGENT_PROJECT_CONTEXT="..."
+AGENT_WORKDIR=/Users/you/code/your-project
+AGENT_CHAT_TIMEOUT_MS=45000
+AGENT_TASK_TIMEOUT_MS=0
+```
+
+## Phrases vocales pour basculer vers Cursor
+
+- en: `"switch to Cursor"`, `"switch to cursor cli"`, `"switch to cursor agent"`
+- fr: `"passe à Cursor"`
+
+Alias : `cursor`, `cursor cli`, `cursor-cli`, `cursor agent`, `cursor-agent`.
+
+## Pièges
+
+- **Position du prompt.** `--prompt` attend la valeur juste après ; le builder argv place la transcription en dernier, donc `CURSOR_COMMAND` doit se terminer par `--prompt`.
+- **Effets de bord éditeur.** Cursor CLI peut toucher des fichiers d'état dans le cwd ; isolez via `AGENT_WORKDIR`.
+- **Pas de reprise.** `AGENT_PROJECT_CONTEXT` + bloc de handoff pour la continuité.
+- **Patch safety.** Aucune lecture vocale du diff en cas d'interruption.

package/docs/i18n/HARNESS_CURSOR.ja.md

@@ -0,0 +1,45 @@
+# Cursor CLI — ハーネスノート
+
+<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>
+
+Cursor CLI (`cursor-agent`) は Cursor のターミナルエージェント。VerbalCoding は `cursor-agent --print --prompt` で呼び出し、STT 結果を prompt 値として渡します。`--print` は非対話実行を維持。
+
+## インストール
+
+上流 Cursor CLI インストールガイドに従い、確認:
+
+```bash
+cursor-agent --print --prompt "hello"
+```
+
+## VerbalCoding 設定
+
+```bash
+# .env
+AGENT_BACKEND=cursor                                       # 'cursor-cli' エイリアス可
+# 任意
+CURSOR_COMMAND="cursor-agent --print --prompt"             # 既定
+AGENT_PROJECT_CONTEXT="..."
+AGENT_WORKDIR=/Users/you/code/your-project
+AGENT_CHAT_TIMEOUT_MS=45000
+AGENT_TASK_TIMEOUT_MS=0
+```
+
+## Cursor へ切り替える音声表現
+
+- en: `"switch to Cursor"`, `"ask Cursor ..."`, `"switch to cursor cli"`, `"switch to cursor agent"`
+- ja: `"Cursor に切り替えて"`, `"Cursor に聞いて"`
+
+エイリアス: `cursor`, `cursor cli`, `cursor-cli`, `cursor agent`, `cursor-agent`。
+
+## 罠
+
+- **prompt 位置。** `--prompt` は値を後続させるため、VerbalCoding の shell 認識 argv ビルダーが STT 結果を最後の positional 引数に置きます。`CURSOR_COMMAND` は `--prompt` で終わる必要あり。
+- **エディタ副作用。** Cursor CLI はワーキングディレクトリに cursor 関連状態ファイルを書く可能性。音声専用フローで意外な場合は分離プロジェクトディレクトリを `AGENT_WORKDIR` に設定。
+- **セッション再開なし。** ターン間連続性は `AGENT_PROJECT_CONTEXT` と、他ハーネスから戻る際のクロスエージェントハンドオフブロックに依存。
+- **patch 安全策。** Cursor が diff 中に中断された場合、bridge は diff を読み上げません。

package/docs/i18n/HARNESS_CURSOR.ko.md

@@ -0,0 +1,45 @@
+# Cursor CLI — 하니스 노트
+
+<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>
+
+Cursor CLI(`cursor-agent`)는 Cursor의 터미널 에이전트. VerbalCoding은 `cursor-agent --print --prompt`로 호출하면서 STT 결과를 prompt 값으로 넘겨. `--print`는 실행을 non-interactive로 유지.
+
+## 설치
+
+상위 Cursor CLI 설치 가이드를 따르고 확인:
+
+```bash
+cursor-agent --print --prompt "hello"
+```
+
+## VerbalCoding 설정
+
+```bash
+# .env
+AGENT_BACKEND=cursor                                       # 'cursor-cli' 별칭도 허용
+# 선택
+CURSOR_COMMAND="cursor-agent --print --prompt"             # 기본값
+AGENT_PROJECT_CONTEXT="..."
+AGENT_WORKDIR=/Users/you/code/your-project
+AGENT_CHAT_TIMEOUT_MS=45000
+AGENT_TASK_TIMEOUT_MS=0
+```
+
+## Cursor로 전환하는 음성 표현
+
+- en: `"switch to Cursor"`, `"ask Cursor ..."`, `"switch to cursor cli"`, `"switch to cursor agent"`
+- ko: `"커서로 전환"`, `"cursor한테 물어봐"`
+
+매처가 받는 별칭: `cursor`, `cursor cli`, `cursor-cli`, `cursor agent`, `cursor-agent`.
+
+## 함정
+
+- **Prompt 위치.** `--prompt`는 값을 뒤에 받는데, VerbalCoding의 shell-aware argv 빌더가 STT 결과를 마지막 positional 인자로 두니까 `CURSOR_COMMAND`는 `--prompt`로 끝나야 해.
+- **에디터 부수 효과.** Cursor CLI는 working directory에 cursor 관련 상태 파일을 만질 수 있어. 음성 전용 흐름에선 놀랍게 느껴질 수 있으니 격리된 프로젝트 디렉터리로 `AGENT_WORKDIR`를 지정해.
+- **세션 재개 없음.** 턴 사이 연속성은 `AGENT_PROJECT_CONTEXT` + 다른 하니스에서 돌아올 때의 크로스 에이전트 핸드오프 블록에 의존.
+- **Patch 안전장치.** Cursor가 diff를 반환 중 interrupt되면 bridge는 diff를 음성으로 안 읽어.

package/docs/i18n/HARNESS_CURSOR.ru.md

@@ -0,0 +1,42 @@
+# Cursor CLI — Заметки по 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>
+
+Cursor CLI (`cursor-agent`) — терминальный агент Cursor. VerbalCoding вызывает его через `cursor-agent --print --prompt`, передавая расшифровку значением `--prompt`. `--print` держит запуск не интерактивным.
+
+## Установка
+
+```bash
+cursor-agent --print --prompt "hello"
+```
+
+## Настройка
+
+```bash
+# .env
+AGENT_BACKEND=cursor                                       # алиас 'cursor-cli' принимается
+CURSOR_COMMAND="cursor-agent --print --prompt"
+AGENT_PROJECT_CONTEXT="..."
+AGENT_WORKDIR=/Users/you/code/your-project
+AGENT_CHAT_TIMEOUT_MS=45000
+AGENT_TASK_TIMEOUT_MS=0
+```
+
+## Голосовые фразы для переключения на Cursor
+
+- en: `"switch to Cursor"`, `"switch to cursor cli"`, `"switch to cursor agent"`
+- ru: `"переключись на Cursor"`
+
+Алиасы: `cursor`, `cursor cli`, `cursor-cli`, `cursor agent`, `cursor-agent`.
+
+## Подводные камни
+
+- **Позиция prompt-а.** `--prompt` ждёт значение сразу после; argv-сборщик ставит расшифровку последним позиционным аргументом, поэтому `CURSOR_COMMAND` должна заканчиваться на `--prompt`.
+- **Побочные эффекты редактора.** Cursor CLI может трогать cursor-файлы состояния в cwd; изолируйте через `AGENT_WORKDIR`.
+- **Нет возобновления.** Непрерывность — через `AGENT_PROJECT_CONTEXT` и блок hand-off.
+- **Patch-safety.** При прерывании в момент diff мост не зачитывает diff.

package/docs/i18n/HARNESS_CURSOR.zh.md

@@ -0,0 +1,42 @@
+# Cursor CLI — Harness 说明
+
+<p align="center">
+  <a href="../../README.zh.md">README</a> ·
+  <a href="HARNESSES.zh.md">Harness</a> ·
+  <a href="USAGE.zh.md">使用</a> ·
+  <a href="CONFIGURATION.zh.md">配置</a>
+</p>
+
+Cursor CLI (`cursor-agent`) 是 Cursor 的终端代理。VerbalCoding 通过 `cursor-agent --print --prompt` 驱动,将 STT 结果作为 prompt 值传入。`--print` 保证非交互。
+
+## 安装
+
+```bash
+cursor-agent --print --prompt "hello"
+```
+
+## VerbalCoding 配置
+
+```bash
+# .env
+AGENT_BACKEND=cursor                                       # 也接受 'cursor-cli'
+CURSOR_COMMAND="cursor-agent --print --prompt"             # 默认
+AGENT_PROJECT_CONTEXT="..."
+AGENT_WORKDIR=/Users/you/code/your-project
+AGENT_CHAT_TIMEOUT_MS=45000
+AGENT_TASK_TIMEOUT_MS=0
+```
+
+## 切到 Cursor 的语音表述
+
+- en: `"switch to Cursor"`、`"switch to cursor cli"`、`"switch to cursor agent"`
+- zh: `"切到 Cursor"`
+
+别名: `cursor`、`cursor cli`、`cursor-cli`、`cursor agent`、`cursor-agent`。
+
+## 坑
+
+- **prompt 位置。** `--prompt` 期待紧随其后的值。VerbalCoding 的 shell-aware argv 构造器将 STT 结果作为末尾 positional 参数,因此 `CURSOR_COMMAND` 必须以 `--prompt` 结尾。
+- **编辑器副作用。** Cursor CLI 可能在工作目录写 cursor 相关状态文件;纯语音流中若不希望如此,把 `AGENT_WORKDIR` 指向隔离目录。
+- **无会话续接。** 用 `AGENT_PROJECT_CONTEXT` 维持连续性,从其它 harness 切回时还有跨代理 handoff 块兜底。
+- **patch 安全。** Cursor 在 diff 期间被中断时,bridge 不朗读 diff。

package/docs/i18n/HARNESS_GEMINI.es.md

@@ -0,0 +1,44 @@
+# Gemini CLI — 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>
+
+Gemini CLI es el agente de codificación de terminal de Google. VerbalCoding lo invoca con `gemini -p`. Cada turno de voz es una invocación; no hay reanudación entre llamadas.
+
+## Instalación
+
+Sigue la guía oficial de Gemini CLI. Confirma:
+
+```bash
+gemini -p "hello"
+```
+
+## Configuración
+
+```bash
+# .env
+AGENT_BACKEND=gemini
+GEMINI_COMMAND="gemini -p"
+AGENT_PROJECT_CONTEXT="..."
+AGENT_WORKDIR=/Users/you/code/your-project
+AGENT_CHAT_TIMEOUT_MS=45000
+AGENT_TASK_TIMEOUT_MS=0
+```
+
+## Frases de voz para cambiar a Gemini
+
+- en: `"switch to Gemini"`, `"ask Gemini ..."`, `"switch to Gemini CLI"`
+- es: `"cambia a Gemini"`, `"pregunta a Gemini"`
+
+Alias: `gemini`, `gemini cli`, `gemini-cli`.
+
+## Trampas
+
+- **Sin reanudación.** Misma estrategia que Claude/Codex: `AGENT_PROJECT_CONTEXT` + bloque de handoff.
+- **Respuestas largas.** Gemini a veces devuelve respuestas estructuradas grandes; el sentencer las parte en frases TTSables. Las cercas de código se eliminan del audio (el canal de texto sí trae el código).
+- **API key.** Si Gemini sale con error de auth, el puente reporta; el fallback ofrece el agente por defecto.
+- **Progreso detallado.** Gemini no emite previos al estilo `┊` de Hermes; el progreso detallado depende del summarizer LLM.

package/docs/i18n/HARNESS_GEMINI.fr.md

@@ -0,0 +1,44 @@
+# Gemini CLI — 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>
+
+Gemini CLI est l'agent terminal de Google. VerbalCoding l'invoque via `gemini -p`. Un tour vocal = un appel ; pas de reprise entre appels.
+
+## Installation
+
+Suivez le guide officiel, puis vérifiez :
+
+```bash
+gemini -p "hello"
+```
+
+## Configuration
+
+```bash
+# .env
+AGENT_BACKEND=gemini
+GEMINI_COMMAND="gemini -p"
+AGENT_PROJECT_CONTEXT="..."
+AGENT_WORKDIR=/Users/you/code/your-project
+AGENT_CHAT_TIMEOUT_MS=45000
+AGENT_TASK_TIMEOUT_MS=0
+```
+
+## Phrases vocales pour basculer vers Gemini
+
+- en: `"switch to Gemini"`, `"ask Gemini ..."`, `"switch to Gemini CLI"`
+- fr: `"passe à Gemini"`, `"demande à Gemini"`
+
+Alias : `gemini`, `gemini cli`, `gemini-cli`.
+
+## Pièges
+
+- **Pas de reprise.** Même stratégie que Claude/Codex : `AGENT_PROJECT_CONTEXT` + bloc de handoff.
+- **Réponses longues.** Gemini renvoie parfois de grands blocs structurés ; le sentencer les découpe. Les blocs de code sont retirés de la voix (canal texte conserve le code).
+- **Clé API.** Une erreur d'auth ressort en exit non-nul ; fallback proposé si Gemini n'était pas le défaut.
+- **Progression verbeuse.** Gemini ne sort pas de previews `┊` à la Hermes ; la progression dépend principalement du summarizer LLM.

package/docs/i18n/HARNESS_GEMINI.ja.md

@@ -0,0 +1,45 @@
+# Gemini CLI — ハーネスノート
+
+<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>
+
+Gemini CLI は Google のターミナルコーディングエージェント。VerbalCoding は `gemini -p` で呼び出します。音声ターン 1 つにつき 1 invocation、呼び出し間のセッション再開はありません。
+
+## インストール
+
+上流 Gemini CLI インストールガイドに従い、確認:
+
+```bash
+gemini -p "hello"
+```
+
+## VerbalCoding 設定
+
+```bash
+# .env
+AGENT_BACKEND=gemini
+# 任意
+GEMINI_COMMAND="gemini -p"                  # 既定。--model, --debug 追加可
+AGENT_PROJECT_CONTEXT="..."
+AGENT_WORKDIR=/Users/you/code/your-project
+AGENT_CHAT_TIMEOUT_MS=45000
+AGENT_TASK_TIMEOUT_MS=0
+```
+
+## Gemini へ切り替える音声表現
+
+- en: `"switch to Gemini"`, `"ask Gemini ..."`, `"switch to Gemini CLI"`
+- ja: `"Gemini に切り替えて"`, `"Gemini に聞いて"`
+
+エイリアス: `gemini`, `gemini cli`, `gemini-cli`, `ジェミニ`。
+
+## 罠
+
+- **セッション再開なし。** Claude / Codex と同様の連続性戦略: `AGENT_PROJECT_CONTEXT` とクロスエージェントハンドオフブロックに依存。
+- **長い応答。** Gemini が大きな構造化応答を返すことがあります。ストリーム sentencer が TTS 可能な文に分割。コードフェンスは音声から除外 (テキストチャンネルには全文)。
+- **API キー。** Gemini が認証エラーで非零 exit すると bridge がメッセージを報告。既定外なら fallback プロンプトが既定エージェントへの retry 提案。
+- **詳細進捗。** Gemini の stdout は Hermes の `┊` 形式ではないため、詳細進捗は主に smart-progress LLM 要約器に依存。

package/docs/i18n/HARNESS_GEMINI.ko.md

@@ -0,0 +1,45 @@
+# Gemini CLI — 하니스 노트
+
+<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>
+
+Gemini CLI는 구글의 터미널 코딩 에이전트. VerbalCoding은 `gemini -p`로 호출해. voice turn 하나가 invocation 한 번이고, 호출 간 세션 재개는 없어.
+
+## 설치
+
+상위 Gemini CLI 설치 가이드를 따라줘. 확인:
+
+```bash
+gemini -p "hello"
+```
+
+## VerbalCoding 설정
+
+```bash
+# .env
+AGENT_BACKEND=gemini
+# 선택
+GEMINI_COMMAND="gemini -p"                  # 기본값. 필요하면 --model, --debug 추가
+AGENT_PROJECT_CONTEXT="..."
+AGENT_WORKDIR=/Users/you/code/your-project
+AGENT_CHAT_TIMEOUT_MS=45000
+AGENT_TASK_TIMEOUT_MS=0
+```
+
+## Gemini로 전환하는 음성 표현
+
+- en: `"switch to Gemini"`, `"ask Gemini ..."`, `"switch to Gemini CLI"`
+- ko: `"제미나이로 전환"`, `"gemini한테 물어봐"`
+
+매처가 받는 별칭: `gemini`, `gemini cli`, `gemini-cli`, `제미나이`.
+
+## 함정
+
+- **세션 재개 없음.** Claude / Codex와 같은 연속성 전략: `AGENT_PROJECT_CONTEXT` + 크로스 에이전트 핸드오프 블록 의존.
+- **긴 응답.** Gemini는 가끔 큰 구조화 응답을 반환하는데, 스트림 sentencer가 TTS 가능한 문장으로 잘라줘. 코드 펜스는 음성에서 제외 (텍스트 채널에는 코드 포함 전체 답변).
+- **API 키.** Gemini가 인증 오류로 non-zero exit하면 bridge가 메시지를 보고. 기본 에이전트가 아닐 때 크로스 에이전트 fallback 프롬프트가 기본 에이전트로 재시도 제안.
+- **상세 진행.** Gemini stdout은 Hermes의 `┊` 스타일 미리보기 포맷이 아니라서 상세 진행은 주로 smart-progress LLM 요약기에 의존해.

package/docs/i18n/HARNESS_GEMINI.ru.md

@@ -0,0 +1,44 @@
+# Gemini CLI — Заметки по 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>
+
+Gemini CLI — терминальный кодинг-агент Google. VerbalCoding вызывает его через `gemini -p`. Один turn — один вызов; возобновления между вызовами нет.
+
+## Установка
+
+Следуйте официальному гайду, затем проверьте:
+
+```bash
+gemini -p "hello"
+```
+
+## Настройка
+
+```bash
+# .env
+AGENT_BACKEND=gemini
+GEMINI_COMMAND="gemini -p"
+AGENT_PROJECT_CONTEXT="..."
+AGENT_WORKDIR=/Users/you/code/your-project
+AGENT_CHAT_TIMEOUT_MS=45000
+AGENT_TASK_TIMEOUT_MS=0
+```
+
+## Голосовые фразы для переключения на Gemini
+
+- en: `"switch to Gemini"`, `"ask Gemini ..."`, `"switch to Gemini CLI"`
+- ru: `"переключись на Gemini"`, `"спроси Gemini"`
+
+Алиасы: `gemini`, `gemini cli`, `gemini-cli`.
+
+## Подводные камни
+
+- **Нет возобновления.** Та же стратегия, что у Claude/Codex: `AGENT_PROJECT_CONTEXT` + блок hand-off.
+- **Длинные ответы.** Gemini иногда возвращает большие структуры; sentencer режет их на TTS-фразы. Код-блоки убираются из голоса (в текстовом канале остаются).
+- **API key.** Ошибка авторизации — non-zero exit; fallback на дефолт, если Gemini не был дефолтом.
+- **Подробный прогресс.** У Gemini нет превью в стиле `┊` Hermes — прогресс в основном даёт LLM-сводщик.

package/docs/i18n/HARNESS_GEMINI.zh.md

@@ -0,0 +1,45 @@
+# Gemini CLI — Harness 说明
+
+<p align="center">
+  <a href="../../README.zh.md">README</a> ·
+  <a href="HARNESSES.zh.md">Harness</a> ·
+  <a href="USAGE.zh.md">使用</a> ·
+  <a href="CONFIGURATION.zh.md">配置</a>
+</p>
+
+Gemini CLI 是 Google 的终端编码代理。VerbalCoding 通过 `gemini -p` 驱动。每个语音 turn 一次调用;调用间无内建会话续接。
+
+## 安装
+
+参考上游 Gemini CLI 指引,确认:
+
+```bash
+gemini -p "hello"
+```
+
+## VerbalCoding 配置
+
+```bash
+# .env
+AGENT_BACKEND=gemini
+# 可选
+GEMINI_COMMAND="gemini -p"                  # 默认,可加 --model、--debug
+AGENT_PROJECT_CONTEXT="..."
+AGENT_WORKDIR=/Users/you/code/your-project
+AGENT_CHAT_TIMEOUT_MS=45000
+AGENT_TASK_TIMEOUT_MS=0
+```
+
+## 切到 Gemini 的语音表述
+
+- en: `"switch to Gemini"`、`"ask Gemini ..."`、`"switch to Gemini CLI"`
+- zh: `"切到 Gemini"`、`"问 Gemini"`
+
+别名: `gemini`、`gemini cli`、`gemini-cli`。
+
+## 坑
+
+- **无会话续接。** 与 Claude / Codex 同样的连续性策略: 依赖 `AGENT_PROJECT_CONTEXT` 与跨代理 handoff 块。
+- **长回答。** Gemini 偶尔返回大块结构化响应;流式 sentencer 会切分成 TTS 可读句。代码围栏从语音剥离 (文本频道仍含完整代码)。
+- **API 密钥。** Gemini 因鉴权失败非零退出时,bridge 会报告消息;非默认后端时 fallback 提示。
+- **详细进度。** Gemini stdout 不是 Hermes `┊` 风格,详细进度主要依赖 smart-progress LLM 摘要。