ai-browser-bridge 0.2.0 → 0.4.0

package/README.es.md

@@ -1,33 +1,34 @@
 <p align="center">
-  <img src="assets/hero.png" alt="chatgpt-local-bridge — controla una sesión de ChatGPT en el navegador desde tu terminal mediante un puente MCP aislado" width="640" />
+  <img src="assets/hero.png" alt="ai-browser-bridge — controla ChatGPT, Gemini, Claude, DeepSeek, Grok, Perplexity y Flow desde tu terminal mediante Chrome" width="640" />
 </p>
 
-# chatgpt-local-bridge
+# ai-browser-bridge
 
 [English](README.md) · [עברית](README.he.md) · **Español** · [中文](README.zh.md)
 
 ![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)
-![Node](https://img.shields.io/badge/node-%E2%89%A520-339933?logo=node.js&logoColor=white)
+![Node](https://img.shields.io/badge/node-%E2%89%A522-339933?logo=node.js&logoColor=white)
 ![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178C6?logo=typescript&logoColor=white)
 ![Playwright](https://img.shields.io/badge/Playwright-browser-2EAD33?logo=playwright&logoColor=white)
 ![MCP](https://img.shields.io/badge/MCP-connector-000000)
 
 ---
 
-> Controla una conversación real de ChatGPT en el navegador desde tu terminal y dale un conjunto reducido y aislado (sandbox) de herramientas locales del repositorio vía MCP — sin entregarle nunca una shell.
+> Controla conversaciones reales de ChatGPT o Gemini desde tu terminal y ofrece a ChatGPT un conjunto reducido de herramientas locales del repositorio vía MCP — sin entregarle nunca una shell.
 
 ## Por qué existe
 
 ChatGPT rinde mejor en el navegador: el estado real de la cuenta, el selector de modelos, la edición de mensajes, la regeneración y el historial de conversación se mantienen intactos. Programar rinde mejor en la terminal, donde archivos, pruebas, diffs y parches se inspeccionan y modifican directamente.
 
-`chatgpt-local-bridge` conecta esas dos superficies. Un prompt en la terminal controla tu sesión existente de ChatGPT en el navegador, y ChatGPT puede acceder al repositorio actual mediante un pequeño conjunto de **herramientas MCP validadas** — `grep`, `read`, `apply_patch`, `run_tests`, `git_diff` — en lugar de acceso directo a la shell. Tú permaneces en un único flujo de terminal; ChatGPT conserva su interfaz real.
+`ai-browser-bridge` conecta esas dos superficies. Un prompt en la terminal controla tu sesión existente del proveedor en el navegador, y ChatGPT puede acceder al repositorio actual mediante un pequeño conjunto de **herramientas MCP validadas** — `grep`, `read`, `apply_patch`, `run_tests`, `git_diff` — en lugar de acceso directo a la shell. Tú permaneces en un único flujo de terminal; el proveedor conserva su interfaz real.
 
 ## Características
 
-- **ChatGPT desde la terminal** — envía prompts y recibe respuestas sin salir de la shell; la conversación real del navegador es la fuente de verdad.
+- **Nueve proveedores, un comando** — ChatGPT, Gemini, Claude, DeepSeek, Grok, Perplexity, Duck.ai, Arena y Google Flow. Selecciona uno con `--provider` o consulta varios en paralelo.
+- **Diseñado para agentes** — `bridge ask … --json` ofrece una interfaz no interactiva estable, y `bridge serve` expone herramientas MCP salientes.
 - **Herramientas locales en sandbox vía MCP** — cada operación de archivo se valida contra la raíz del repositorio seleccionado; sin shell arbitraria, solo comandos de prueba en lista blanca.
 - **Acciones del navegador como comandos** — `/resume`, `/new`, `/model`, `/rewind`, `/stop`, `/context`, `/diff`, `/compact` y más.
-- **Sesiones y transcripciones locales por repositorio** — cada ejecución se registra en `<repo>/.bridge/` y se exporta como Markdown, JSON o JSONL.
+- **Sesiones, transcripciones y descargas en la raíz del repositorio** — las ejecuciones persistentes usan siempre `<repo>/.bridge/`, incluso cuando se inician desde un subdirectorio.
 - **Controles de seguridad** — modos de permiso (`read-only` / `ask` / `auto`) y checkpoints automáticos de archivos alrededor de cada parche.
 - **Convenciones del proyecto** — comandos personalizados además de `AGENTS.md` / `CLAUDE.md` se envían a ChatGPT en las ejecuciones de `/task`.
 - **Un editor real** — historial de prompts, búsqueda inversa, cola de prompts y autocompletado de menciones `@file`.
@@ -54,8 +55,8 @@ Cuatro capas, cada una con un solo trabajo:
 | Capa | Tecnología | Responsabilidad |
 |------|------------|-----------------|
 | **CLI** | Ink / React | Interfaz de terminal: panel de mensajes, barra de estado, menciones `@file`, comandos `/`. |
-| **Navegador** | Playwright + Chrome DevTools Protocol | Controla la pestaña real de ChatGPT y captura respuestas. Los selectores están aislados en `src/browser/chatgpt-page.ts` para que los cambios de UI sean fáciles de arreglar. |
-| **Servidor MCP** | MCP SDK + Zod | Expone las herramientas locales del repositorio a ChatGPT como handlers validados por esquema y en sandbox. |
+| **Navegador** | Playwright + Chrome DevTools Protocol | Se conecta a Chrome mediante el puerto de depuración y reutiliza un único perfil compartido. Los adaptadores viven en `src/features/providers/`. |
+| **Servidor MCP** | MCP SDK + Effect Schema | Expone herramientas locales validadas y aisladas a ChatGPT, Claude y Grok. |
 | **Túnel** | Cloudflare Tunnel (`cloudflared`) | Da al servidor MCP local una URL HTTPS pública temporal que el conector de ChatGPT puede alcanzar — sin despliegue. |
 
 **¿Por qué un túnel?** El conector MCP de ChatGPT llama a las herramientas por HTTPS, pero el servidor de herramientas se ejecuta en tu máquina. En lugar de desplegar nada, el bridge levanta un túnel efímero de Cloudflare (`*.trycloudflare.com`) frente al puerto local y sincroniza esa URL `…/mcp` con la app de ChatGPT al iniciar. (ngrok resolvería el mismo problema de alcance; se usa `cloudflared` de Cloudflare porque sus túneles rápidos no requieren cuenta ni token.)
@@ -65,36 +66,48 @@ Cuatro capas, cada una con un solo trabajo:
 **Requisitos previos**
 
 - **macOS** — Chrome se inicia desde `/Applications/Google Chrome.app`, y los ayudantes de portapapeles/procesos usan `pbcopy`/`lsof`.
-- **Node.js ≥ 20** y **pnpm** (el repo fija `pnpm@10.14.0`).
-- **Google Chrome** — el bridge controla un perfil real de Chrome.
-- **`cloudflared`** *(opcional)* — solo necesario para que ChatGPT llame a herramientas locales. Sin él la TUI igual funciona. Instala con `brew install cloudflared`.
+- **Node.js ≥ 22** y **pnpm** (el repo fija `pnpm@10.14.0`).
+- **Google Chrome o Chrome for Testing** — el bridge reutiliza un perfil global compartido en `~/.ai-browser-bridge/chrome-profile`.
+- **`cloudflared`** *(opcional)* — necesario para que ChatGPT, Claude o Grok llamen a herramientas locales. Sin él la TUI sigue funcionando. Instala con `brew install cloudflared`.
 
 **Instalar y construir**
 
 ```bash
-git clone https://github.com/YosefHayim/chatgpt-local-bridge.git
-cd chatgpt-local-bridge
+git clone https://github.com/YosefHayim/ai-browser-bridge.git
+cd ai-browser-bridge
 pnpm install
 pnpm build
 ```
 
-**Inicia sesión una vez y luego ejecuta**
+**Inicia Chrome una vez y luego ejecuta**
 
 ```bash
-# Abre el perfil aislado de Chrome del bridge e inicia sesión en ChatGPT (persiste entre ejecuciones)
-node dist/bridge.js login
+# Abre el perfil compartido de Chrome del bridge; inicia sesión si hace falta
+node dist/bridge.js chrome start
 
 # Lanza la interfaz de terminal sobre el repositorio donde ChatGPT trabajará
 node dist/bridge.js --repo /path/to/your/project
 ```
 
-¿Prefieres un comando `bridge` global? Ejecuta `pnpm link --global` tras construir, y usa `bridge`, `bridge login`, `bridge ask "…"`, etc.
+¿Prefieres un comando `bridge` global? Ejecuta `pnpm link --global` tras construir, y usa `bridge`, `bridge chrome start`, `bridge ask "…"`, etc.
+
+## Agentes y proveedores
+
+`bridge ask` puede consultar un proveedor o distribuir la misma pregunta entre varios. Las respuestas se devuelven por proveedor y los fallos parciales no descartan los resultados correctos.
+
+```bash
+bridge ask --provider claude --json "resume este repositorio"
+bridge ask --provider claude,deepseek,grok --json "compara estos enfoques"
+bridge serve
+```
+
+`bridge serve` ofrece `ask` y `search_conversations` por MCP stdio. ChatGPT, Claude y Grok pueden usar el conector MCP entrante; Gemini, DeepSeek, Perplexity, Duck.ai y Arena funcionan como chats web, y Flow funciona como superficie de generación de vídeo.
 
 ## Dónde se guarda el estado
 
-Todo el estado del bridge para un proyecto se escribe **dentro de ese proyecto**, bajo `<repo>/.bridge/`. En el primer uso, el bridge escribe `.bridge/.gitignore` con un único `*`. Eso hace que git ignore **todo** lo que hay en el directorio — incluidas las transcripciones y las cookies de inicio de sesión — de modo que nada pueda llegar a un commit, aunque viva dentro del repositorio. Tanto `git add -A` como `git add .bridge/` lo omiten; solo un `git add -f` explícito podría forzarlo. El archivo se reafirma en cada ejecución, así que borrarlo o manipularlo se cura automáticamente.
+Todo el estado del bridge para un proyecto se escribe bajo `<repo>/.bridge/` en la raíz canónica del árbol de trabajo Git. Iniciar el bridge desde un subdirectorio sigue usando esa única raíz; un directorio explícito que no pertenece a Git sigue siendo su propia raíz. El bridge no crea ni administra `.bridge/.gitignore`; esa política pertenece al repositorio de destino.
 
-> La configuración escrita por el usuario y destinada a aplicarse a **todos** los repositorios sigue en tu directorio home: comandos personalizados en `~/.chatgpt-local-bridge/commands/*.md` y hooks de usuario en `~/.chatgpt-local-bridge/hooks.json`.
+> La configuración escrita por el usuario y destinada a aplicarse a **todos** los repositorios vive en tu directorio home: comandos personalizados en `~/.ai-browser-bridge/commands/*.md` y hooks de usuario en `~/.ai-browser-bridge/hooks.json`.
 
 ## Permisos y checkpoints
 
@@ -111,10 +124,10 @@ Todo el estado del bridge para un proyecto se escribe **dentro de ese proyecto**
 ```bash
 pnpm test          # vitest run
 pnpm typecheck     # tsc --noEmit
-pnpm verify:push   # typecheck + test + build (ejecutar antes de push)
+pnpm verify:push   # Biome + typecheck + tests + build + controles estructurales
 ```
 
-La cobertura se centra en las rutas sensibles a la seguridad — validación de sandbox, resolución de rutas locales del repositorio, la auto-exclusión de `.bridge/`, los almacenes de sesiones/checkpoints, permisos y conteo de contexto.
+La cobertura se centra en las rutas sensibles a la seguridad — validación de sandbox, resolución de la raíz canónica del repositorio, los almacenes de sesiones/checkpoints, permisos y conteo de contexto.
 
 ## Soporte de Google Flow
 
@@ -130,7 +143,7 @@ Más allá de generar, el bridge controla el **ciclo de vida de recursos** compl
 
 ```bash
 bridge flow clips                        # lista los clips del proyecto actual (id + URL descargable)
-bridge flow download                     # descarga el mp4 de cada clip en ./downloads/flow (o --id <clipId...>)
+bridge flow download                     # descarga los mp4 en <repo>/.bridge/downloads/flow
 bridge flow reuse   --id <clipId>        # vuelve a añadir un clip al prompt como entrada ("Add to prompt")
 bridge flow extend  --id <clipId>        # añade un clip a una escena ("Add to scene" de Flow)
 bridge flow rename  --id <clipId> --name "hero shot"
@@ -162,12 +175,12 @@ Los agentes sin acceso a shell obtienen el mismo ciclo de vida como **herramient
 
 Flow requiere un plan **Google AI Pro/Ultra**. Como los renders de Veo tardan minutos, `--provider flow` espera una respuesta mucho más tiempo que los proveedores de chat.
 
-**Mantenimiento de selectores:** los selectores de Flow fueron **verificados en vivo (LIVE-VERIFIED)** contra un editor de proyecto con sesión iniciada. Si Google cambia la UI, vuelve a capturarlos con `node src/scripts/dev/captureProviderSelectors.mjs`, luego actualiza [`src/config/providersConfig.ts`](src/config/providersConfig.ts); la generación vive en [`src/features/providers/flow/flowPage.ts`](src/features/providers/flow/flowPage.ts) y el CRUD de recursos en [`src/features/providers/flow/flowAssets.ts`](src/features/providers/flow/flowAssets.ts).
+**Mantenimiento de selectores:** los selectores de Flow fueron **verificados en vivo (LIVE-VERIFIED)** contra un editor de proyecto con sesión iniciada. Si Google cambia la UI, vuelve a capturarlos con `node scripts/dev/captureProviderSelectors.mjs`, luego actualiza [`src/config.ts`](src/config.ts); la generación vive en [`src/features/providers/flow/flowPage.ts`](src/features/providers/flow/flowPage.ts) y el CRUD de recursos en [`src/features/providers/flow/flowAssets.ts`](src/features/providers/flow/flowAssets.ts).
 
 ## Limitaciones
 
 - **Solo macOS** por ahora (ruta de Chrome fija y ayudantes `pbcopy`/`lsof`).
-- Los selectores del navegador de ChatGPT pueden romperse cuando cambia la UI web; los arreglos están localizados en la capa del navegador.
+- Los selectores de los proveedores pueden romperse cuando cambian sus interfaces web; los arreglos están localizados en sus adaptadores.
 - El uso de contexto es una **estimación** — el navegador no expone el conteo exacto de tokens del servidor.
 - El túnel de Cloudflare requiere `cloudflared` instalado.
 - Local-first por diseño; no es un servicio multiusuario alojado.

package/README.he.md

@@ -1,33 +1,34 @@
 <p align="center">
-  <img src="assets/hero.png" alt="chatgpt-local-bridge — drive a ChatGPT browser session from your terminal over a sandboxed MCP bridge" width="640" />
+  <img src="assets/hero.png" alt="ai-browser-bridge — drive ChatGPT, Gemini, Claude, DeepSeek, Grok, Perplexity, and Flow from your terminal through Chrome" width="640" />
 </p>
 
-# chatgpt-local-bridge
+# ai-browser-bridge
 
 [English](README.md) · **עברית** · [Español](README.es.md) · [中文](README.zh.md)
 
 ![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)
-![Node](https://img.shields.io/badge/node-%E2%89%A520-339933?logo=node.js&logoColor=white)
+![Node](https://img.shields.io/badge/node-%E2%89%A522-339933?logo=node.js&logoColor=white)
 ![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178C6?logo=typescript&logoColor=white)
 ![Playwright](https://img.shields.io/badge/Playwright-browser-2EAD33?logo=playwright&logoColor=white)
 ![MCP](https://img.shields.io/badge/MCP-connector-000000)
 
 <div dir="rtl">
 
-> הפעילו שיחת ChatGPT אמיתית מהדפדפן ישירות מהטרמינל, ותנו לה גישה מצומצמת ומבוקרת (sandbox) לכלי הריפו המקומי דרך MCP — בלי למסור לה אף פעם גישת shell.
+> הפעילו שיחות ChatGPT או Gemini אמיתיות מהדפדפן ישירות מהטרמינל, ותנו ל-ChatGPT גישה מצומצמת ומבוקרת לכלי הריפו המקומי דרך MCP — בלי למסור לו גישת shell.
 
 ## למה זה קיים
 
 ‏ChatGPT נמצא בשיאו בדפדפן — מצב החשבון האמיתי, בורר המודלים, עריכת הודעות, רגנרציה והיסטוריית השיחה נשמרים במלואם. פיתוח קוד נמצא בשיאו בטרמינל, שם בודקים ומשנים קבצים, טסטים, diffs ו-patches ישירות.
 
-‏`chatgpt-local-bridge` מחבר בין שני המשטחים האלה. שורת פקודה בטרמינל מפעילה את שיחת ה-ChatGPT הקיימת שלכם בדפדפן, ו-ChatGPT יכול לגשת לריפו הנוכחי דרך מספר מצומצם של **כלי MCP מאומתים** — `grep`, `read`, `apply_patch`, `run_tests`, `git_diff` — במקום גישת shell חופשית. אתם נשארים בתהליך עבודה אחד בטרמינל; ל-ChatGPT נשאר ה-UI האמיתי שלו.
+‏`ai-browser-bridge` מחבר בין שני המשטחים האלה. שורת פקודה בטרמינל מפעילה את שיחת הספק הקיימת בדפדפן, ו-ChatGPT יכול לגשת לריפו הנוכחי דרך מספר מצומצם של **כלי MCP מאומתים** — `grep`, `read`, `apply_patch`, `run_tests`, `git_diff` — במקום גישת shell חופשית. אתם נשארים בתהליך עבודה אחד בטרמינל; לספק נשאר ה-UI האמיתי שלו.
 
 ## יכולות
 
-- **הפעלת ChatGPT מהטרמינל** — שולחים פרומפטים ומקבלים תשובות בלי לעזוב את ה-shell; שיחת הדפדפן האמיתית היא מקור האמת.
+- **תשעה ספקים, פקודה אחת** — ChatGPT, Gemini, Claude, DeepSeek, Grok, Perplexity, Duck.ai, Arena ו-Google Flow. בוחרים ספק עם `--provider` או שולחים לכמה ספקים במקביל.
+- **בנוי לסוכנים** — ‏`bridge ask … --json` מספק ממשק לא-אינטראקטיבי יציב, ו-`bridge serve` חושף כלי MCP יוצאים.
 - **כלים מקומיים ב-sandbox דרך MCP** — כל פעולת קובץ מאומתת מול שורש הריפו הנבחר; אין shell חופשי, רק פקודות טסט מאושרות מראש.
 - **פעולות דפדפן כפקודות** — ‏`/resume`, `/new`, `/model`, `/rewind`, `/stop`, `/context`, `/diff`, `/compact` ועוד.
-- **סשנים ותמלולים מקומיים לריפו** — כל הרצה נשמרת תחת `<repo>/.bridge/` וניתנת לייצוא כ-Markdown, JSON או JSONL.
+- **סשנים, תמלולים והורדות בשורש הריפו** — הרצות מתמשכות משתמשות תמיד ב-`<repo>/.bridge/`, גם כשהן מופעלות מתיקיית משנה.
 - **בקרות בטיחות** — מצבי הרשאה (`read-only` / `ask` / `auto`) ו-checkpoints אוטומטיים של קבצים סביב כל patch.
 - **מוסכמות פרויקט** — פקודות מותאמות אישית וגם `AGENTS.md` / `CLAUDE.md` מוזנים ל-ChatGPT בהרצות `/task`.
 - **קומפוזר אמיתי** — היסטוריית פרומפטים, חיפוש לאחור, תור פרומפטים, והשלמה אוטומטית לאזכורי `@file`.
@@ -58,8 +59,8 @@
 | שכבה | טכנולוגיה | אחריות |
 |------|-----------|--------|
 | **CLI** | Ink / React | ממשק טרמינל: חלונית הודעות, שורת סטטוס, אזכורי `@file`, פקודות `/`. |
-| **דפדפן** | Playwright + Chrome DevTools Protocol | מפעיל את לשונית ה-ChatGPT האמיתית ולוכד תשובות. הסלקטורים מבודדים ב-`src/browser/chatgpt-page.ts` כך ששינויי UI קלים לתיקון. |
-| **שרת MCP** | MCP SDK + Zod | חושף את כלי הריפו המקומיים ל-ChatGPT כ-handlers מאומתי-סכמה ומוגני-sandbox. |
+| **דפדפן** | Playwright + Chrome DevTools Protocol | מתחבר ל-Chrome דרך פורט הדיבוג ומשתמש בפרופיל bridge משותף יחיד. מתאמי הספקים נמצאים ב-`src/features/providers/`. |
+| **שרת MCP** | MCP SDK + Effect Schema | חושף כלים מקומיים מאומתים ומוגני-sandbox ל-ChatGPT, Claude ו-Grok. |
 | **מנהרה** | Cloudflare Tunnel (`cloudflared`) | מעניק לשרת ה-MCP המקומי כתובת HTTPS ציבורית זמנית שה-connector של ChatGPT יכול להגיע אליה — ללא פריסה. |
 
 **למה בכלל מנהרה?** ה-connector של ChatGPT קורא לכלים דרך HTTPS, אבל שרת הכלים רץ על המחשב שלכם. במקום לפרוס משהו, ה-bridge מקים מנהרת Cloudflare זמנית (`*.trycloudflare.com`) מול הפורט המקומי ומסנכרן את כתובת ה-`…/mcp` הזו אל אפליקציית ChatGPT בעת ההפעלה. (‏ngrok היה פותר את אותה בעיית נגישות; נבחר `cloudflared` של Cloudflare מכיוון שמנהרות ה-quick שלו אינן דורשות חשבון או טוקן.)
@@ -69,30 +70,30 @@
 **דרישות מקדימות**
 
 - **macOS** — ‏Chrome מופעל מ-`/Applications/Google Chrome.app`, ועוזרי הלוח/תהליכים משתמשים ב-`pbcopy`/`lsof`.
-- **Node.js ≥ 20** ו-**pnpm** (הריפו מקבע `pnpm@10.14.0`).
-- **Google Chrome** — ה-bridge מפעיל פרופיל Chrome אמיתי.
-- **`cloudflared`** *(אופציונלי)* — נדרש רק כדי ש-ChatGPT יקרא לכלים מקומיים. בלעדיו ה-TUI עדיין רץ. התקנה: `brew install cloudflared`.
+- **Node.js ≥ 22** ו-**pnpm** (הריפו מקבע `pnpm@10.14.0`).
+- **Google Chrome או Chrome for Testing** — ה-bridge משתמש בפרופיל גלובלי משותף ב-`~/.ai-browser-bridge/chrome-profile`.
+- **`cloudflared`** *(אופציונלי)* — נדרש כדי ש-ChatGPT, Claude או Grok יקראו לכלים מקומיים. בלעדיו ה-TUI עדיין רץ. התקנה: `brew install cloudflared`.
 
 **התקנה ובנייה**
 
 </div>
 
 ```bash
-git clone https://github.com/YosefHayim/chatgpt-local-bridge.git
-cd chatgpt-local-bridge
+git clone https://github.com/YosefHayim/ai-browser-bridge.git
+cd ai-browser-bridge
 pnpm install
 pnpm build
 ```
 
 <div dir="rtl">
 
-**התחברו פעם אחת, ואז הריצו**
+**הפעילו את Chrome פעם אחת, ואז הריצו**
 
 </div>
 
 ```bash
-# פתיחת פרופיל ה-Chrome המבודד של ה-bridge והתחברות ל-ChatGPT (נשמר בין הרצות)
-node dist/bridge.js login
+# פתיחת פרופיל ה-Chrome המשותף של ה-bridge; התחברו אם צריך
+node dist/bridge.js chrome start
 
 # הפעלת ממשק הטרמינל מול הריפו שבו ChatGPT יעבוד
 node dist/bridge.js --repo /path/to/your/project
@@ -100,13 +101,29 @@ node dist/bridge.js --repo /path/to/your/project
 
 <div dir="rtl">
 
-מעדיפים פקודת `bridge` גלובלית? הריצו `pnpm link --global` אחרי הבנייה, ואז השתמשו ב-`bridge`, `bridge login`, `bridge ask "…"` וכו'.
+מעדיפים פקודת `bridge` גלובלית? הריצו `pnpm link --global` אחרי הבנייה, ואז השתמשו ב-`bridge`, `bridge chrome start`, `bridge ask "…"` וכו'.
+
+## סוכנים וספקים
+
+‏`bridge ask` יכול לפנות לספק יחיד או לשלוח את אותה שאלה לכמה ספקים. התשובות מוחזרות לפי ספק, וכשל חלקי אינו מוחק תוצאות תקינות.
+
+</div>
+
+```bash
+bridge ask --provider claude --json "summarize this repo"
+bridge ask --provider claude,deepseek,grok --json "compare these approaches"
+bridge serve
+```
+
+<div dir="rtl">
+
+‏`bridge serve` חושף את `ask` ואת `search_conversations` דרך MCP stdio. ‏ChatGPT, Claude ו-Grok יכולים להשתמש ב-connector נכנס; Gemini, DeepSeek, Perplexity, Duck.ai ו-Arena פועלים כשיחות web, ו-Flow פועל כממשק יצירת וידאו.
 
 ## איפה נשמר המצב (state)
 
-כל מצב ה-bridge של פרויקט נכתב **בתוך אותו פרויקט**, תחת `<repo>/.bridge/`. בשימוש הראשון נכתב `.bridge/.gitignore` המכיל `*` בודד. זה גורם ל-git להתעלם מ**כל** מה שבתיקייה — כולל התמלולים ועוגיות ההתחברות — כך ששום דבר לא יכול להיכנס ל-commit, למרות שהוא נמצא בתוך הריפו. גם `git add -A` וגם `git add .bridge/` מדלגים עליו; רק `git add -f` מפורש יכול לעקוף. הקובץ נכתב מחדש בכל הרצה, כך שמחיקה או שינוי שלו מתרפאים אוטומטית.
+כל מצב ה-bridge של פרויקט נכתב תחת `<repo>/.bridge/` בשורש הקנוני של עץ העבודה של Git. גם הפעלה מתיקיית משנה משתמשת באותו שורש יחיד; תיקייה מפורשת שאינה חלק מ-Git נשארת השורש של עצמה. ה-bridge אינו יוצר או מנהל `.bridge/.gitignore`; מדיניות ההתעלמות שייכת לריפו היעד.
 
-> תצורה שנכתבת על ידי המשתמש ומיועדת לחול על **כל** הריפואים נשמרת עדיין בתיקיית הבית: פקודות מותאמות ב-`~/.chatgpt-local-bridge/commands/*.md` ו-hooks ברמת המשתמש ב-`~/.chatgpt-local-bridge/hooks.json`.
+> תצורה שנכתבת על ידי המשתמש ומיועדת לחול על **כל** הריפואים נשמרת בתיקיית הבית: פקודות מותאמות ב-`~/.ai-browser-bridge/commands/*.md` ו-hooks ברמת המשתמש ב-`~/.ai-browser-bridge/hooks.json`.
 
 ## הרשאות ו-checkpoints
 
@@ -129,12 +146,12 @@ node dist/bridge.js --repo /path/to/your/project
 ```bash
 pnpm test          # vitest run
 pnpm typecheck     # tsc --noEmit
-pnpm verify:push   # typecheck + test + build (להריץ לפני push)
+pnpm verify:push   # Biome + typecheck + tests + build + בדיקות מבנה
 ```
 
 <div dir="rtl">
 
-הכיסוי מתמקד בנתיבים רגישי-בטיחות — אימות sandbox, רזולוציית נתיבים מקומיים לריפו, מנגנון ההתעלמות העצמית של `.bridge/`, מאגרי הסשנים/checkpoints, הרשאות וספירת הקשר.
+הכיסוי מתמקד בנתיבים רגישי-בטיחות — אימות sandbox, זיהוי השורש הקנוני של הריפו, מאגרי הסשנים/checkpoints, הרשאות וספירת הקשר.
 
 ## תמיכה ב-Google Flow
 
@@ -156,7 +173,7 @@ bridge ask --provider flow "same scene, dawn light" --attach ref1.png ref2.png
 
 ```bash
 bridge flow clips                        # הצגת הקליפים בפרויקט הנוכחי (id + כתובת ניתנת-להורדה)
-bridge flow download                     # הורדת ה-mp4 של כל קליפ אל ./downloads/flow (או --id <clipId...>)
+bridge flow download                     # הורדת הקליפים אל <repo>/.bridge/downloads/flow
 bridge flow reuse   --id <clipId>        # הוספת קליפ בחזרה לפרומפט כקלט ("Add to prompt")
 bridge flow extend  --id <clipId>        # הוספת קליפ לסצנה ("Add to scene" של Flow)
 bridge flow rename  --id <clipId> --name "hero shot"
@@ -190,12 +207,12 @@ bridge flow project-delete --yes         # מחיקה לצמיתות של הפר
 
 ‏Flow דורש תוכנית **Google AI Pro/Ultra**. מכיוון שרינדור ב-Veo אורך דקות, `--provider flow` ממתין לתשובה הרבה יותר זמן מספקי הצ'אט.
 
-**תחזוקת סלקטורים:** הסלקטורים של Flow **אומתו בזמן אמת (LIVE-VERIFIED)** מול עורך פרויקט מחובר. אם Google משנה את ה-UI, בצעו לכידה מחדש עם `node src/scripts/dev/captureProviderSelectors.mjs`, ואז עדכנו את [`src/config/providersConfig.ts`](src/config/providersConfig.ts); היצירה נמצאת ב-[`src/features/providers/flow/flowPage.ts`](src/features/providers/flow/flowPage.ts) וה-CRUD של הנכסים ב-[`src/features/providers/flow/flowAssets.ts`](src/features/providers/flow/flowAssets.ts).
+**תחזוקת סלקטורים:** הסלקטורים של Flow **אומתו בזמן אמת (LIVE-VERIFIED)** מול עורך פרויקט מחובר. אם Google משנה את ה-UI, בצעו לכידה מחדש עם `node scripts/dev/captureProviderSelectors.mjs`, ואז עדכנו את [`src/config.ts`](src/config.ts); היצירה נמצאת ב-[`src/features/providers/flow/flowPage.ts`](src/features/providers/flow/flowPage.ts) וה-CRUD של הנכסים ב-[`src/features/providers/flow/flowAssets.ts`](src/features/providers/flow/flowAssets.ts).
 
 ## מגבלות
 
 - **macOS בלבד** כיום (נתיב Chrome קשיח ועוזרי `pbcopy`/`lsof`).
-- סלקטורים של ChatGPT עלולים להישבר כשממשק הווב משתנה; התיקונים ממוקדים בשכבת הדפדפן.
+- סלקטורים של ספקים עלולים להישבר כשממשקי הווב משתנים; התיקונים ממוקדים במתאמים שלהם.
 - ניצול ההקשר הוא **הערכה** — הדפדפן אינו חושף ספירת טוקנים מדויקת מצד השרת.
 - מנהרת Cloudflare דורשת `cloudflared` מותקן.
 - מקומי-תחילה מעיצובו; אינו שירות רב-משתמשים מאוחסן.

package/README.md

@@ -9,7 +9,7 @@
 **English** · [עברית](README.he.md) · [Español](README.es.md) · [中文](README.zh.md)
 
 ![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)
-![Node](https://img.shields.io/badge/node-%E2%89%A520-339933?logo=node.js&logoColor=white)
+![Node](https://img.shields.io/badge/node-%E2%89%A522-339933?logo=node.js&logoColor=white)
 ![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178C6?logo=typescript&logoColor=white)
 ![Playwright](https://img.shields.io/badge/Playwright-browser-2EAD33?logo=playwright&logoColor=white)
 ![MCP](https://img.shields.io/badge/MCP-connector-000000)
@@ -25,11 +25,11 @@ ChatGPT is at its best in the browser — real account state, the model picker,
 ## Features
 
 - **Terminal-driven ChatGPT** — send prompts and stream replies without leaving the shell; the real browser conversation stays the source of truth.
-- **Seven providers, one command** — `chatgpt`, `gemini`, `claude`, `deepseek`, `grok`, `perplexity`, plus `flow` (Google's Veo video studio — a generation surface, not a chat). Pick one with `--provider`, or **fan out** across several (`--provider claude,deepseek,grok`) and get every reply keyed by provider in one call.
+- **Nine providers, one command** — `chatgpt`, `gemini`, `claude`, `deepseek`, `grok`, `perplexity`, `duck` ([Duck.ai](https://duck.ai/chat)), `arena` ([Arena](https://arena.ai/code/direct) — Direct/Battle/Agent/Side-by-Side + model picker), plus `flow` (Google's Veo video studio — a generation surface, not a chat). Pick one with `--provider`, or **fan out** across several (`--provider claude,deepseek,duck`) and get every reply keyed by provider in one call.
 - **Built for agents** — a stable non-interactive `bridge ask … --json` contract (never hangs in a pipe) plus an outbound MCP `ask` tool, so any agent can drive a web chat.
 - **Sandboxed local tools over MCP** — every file operation is validated against the selected repo root; no arbitrary shell, allowlisted test commands only.
 - **Browser actions as commands** — `/resume`, `/new`, `/model`, `/rewind`, `/stop`, `/context`, `/diff`, `/compact`, and more.
-- **Repo-local sessions & transcripts when needed** — TUI and tool-enabled runs persist under `<repo>/.bridge/`; plain `bridge ask` stays stateless and only reuses the shared Chrome profile.
+- **Repo-root sessions, transcripts, and downloads** — TUI and tool-enabled runs persist under the Git working-tree root's `<repo>/.bridge/`, even when launched from a nested directory; plain `bridge ask` stays stateless and only reuses the shared Chrome profile.
 - **Safety controls** — permission modes (`read-only` / `ask` / `auto`) and automatic file checkpoints around every patch.
 - **Project conventions** — custom commands plus `AGENTS.md` / `CLAUDE.md` are fed to ChatGPT for `/task` runs.
 - **A real composer** — prompt history, reverse search, queued prompts, and `@file` mention autocomplete.
@@ -57,7 +57,7 @@ Four layers, each with one job:
 |-------|------|----------------|
 | **CLI** | Ink / React | Terminal UI: message pane, status line, `@file` mentions, `/commands`. |
 | **Browser** | Playwright + Chrome DevTools Protocol | Attaches to Chrome on the debug port and reuses one shared bridge Chrome profile. Lifecycle/status/cache code lives in `src/features/browser/`; provider selectors live under `src/features/providers/<name>/`. |
-| **MCP server** | MCP SDK + Zod | Exposes the local repo tools to ChatGPT, Claude, and Grok as schema-validated, sandboxed handlers. |
+| **MCP server** | MCP SDK + Effect Schema | Exposes the local repo tools to ChatGPT, Claude, and Grok as schema-validated, sandboxed handlers. |
 | **Tunnel** | Cloudflare Tunnel (`cloudflared`) | Gives the local MCP server a temporary public HTTPS URL that provider connectors can reach — no deployment required. |
 
 **Why a tunnel at all?** Provider MCP connectors call tools over HTTPS, but the tool server runs on your machine. Rather than deploy anything, the bridge spins up an ephemeral Cloudflare Tunnel (`*.trycloudflare.com`) in front of the local port and syncs that Streamable HTTP `…/mcp` URL into the provider app on startup. (ngrok would solve the same reachability problem; Cloudflare's `cloudflared` is used because its quick tunnels need no account or auth token. Grok's UI may show an `/sse` example — the bridge registers `/mcp` because cloudflared quick tunnels do not support SSE.)
@@ -67,7 +67,7 @@ Four layers, each with one job:
 **Prerequisites**
 
 - **macOS** — Chrome is launched with the macOS `open` command, and clipboard/process helpers use `pbcopy`/`lsof`.
-- **Node.js ≥ 20** and **pnpm** (the repo pins `pnpm@10.14.0`).
+- **Node.js ≥ 22** and **pnpm** (the repo pins `pnpm@10.14.0`).
 - **Google Chrome or Chrome for Testing** — the bridge drives one shared bridge profile through a debug port. Sign in once in that bridge-launched window; every repo reuses it.
 - **`cloudflared`** *(optional; ChatGPT, Claude, Grok)* — only needed for those providers to call local MCP tools. Without it the TUI still runs. Install with `brew install cloudflared`.
 
@@ -140,12 +140,14 @@ node dist/bridge.js ask "hello" --provider gemini --repo /path/to/project
 
 ```text
 refactor the CLI input flow in @src/features/terminal/tui/App.tsx
-compare @src/features/store/fileResolver.ts with @src/features/store/fileResolver.test.ts
+compare @src/features/store/fileMentions.ts with @src/features/store/fileMentions.test.ts
 ```
 
 Paths that escape the repo root are skipped; files over 100 KB are summarized rather than inlined.
 
-**Conversation search** — `bridge chat search "query" --json` searches ChatGPT history through the shared conversation catalog. Add `--open` to navigate the browser to the best match.
+**Conversation search** — `bridge chat search "query" --json` opens ChatGPT's Search UI,
+selects Chats, and returns matching Conversations across titles and message content. It scrolls
+the result overlay up to `--limit`; add `--open` to navigate the browser to the best match.
 
 ## Agents & fan-out
 
@@ -186,11 +188,10 @@ The `ask` tool takes `{ prompt, providers?, timeoutSeconds? }` and returns each
 
 ## Where state lives
 
-Persistent bridge state for a project is written **inside that project**, under `<repo>/.bridge/`:
+Persistent bridge state is written under the canonical Git working-tree root's `<repo>/.bridge/`. The bridge resolves both `--repo` and the launch directory to that root, so nested launches cannot create competing state or download folders. An explicit non-Git directory remains its own root.
 
 ```text
 <repo>/.bridge/
-├── .gitignore        # a single "*", written automatically — see below
 ├── config.json       # per-repo settings (includes `provider`: chatgpt | gemini)
 ├── sessions/<id>/    # metadata.json + append-only events.jsonl transcript
 ├── logs/<date>.jsonl # prompts, replies, and MCP tool-call summaries
@@ -202,7 +203,7 @@ Persistent bridge state for a project is written **inside that project**, under
 
 Plain `bridge ask` and `bridge chrome start` do not create repo-local state; they only reuse the shared Chrome profile. The bridge creates `<repo>/.bridge/` for persistent TUI sessions, tool-enabled asks (`bridge ask --tools`), checkpoints, exports, screenshots, or default attachment downloads.
 
-When repo-local state is needed, the bridge writes `.bridge/.gitignore` containing a single `*`. That makes git ignore **everything** in the directory — session transcripts, logs, downloads, screenshots, and checkpoints — so none of it can be committed, even though it lives inside the repo. Chrome cookies for bridge-driven sessions stay in the shared bridge profile under `~/.ai-browser-bridge/chrome-profile`, not under `.bridge/`. `git add -A` and `git add .bridge/` both skip bridge state; only an explicit `git add -f` could override. The file is re-asserted on persistent runs, so deleting or tampering with it heals automatically.
+The bridge does not create or manage `.bridge/.gitignore`; ignore policy belongs to the target repository. Chrome cookies for bridge-driven sessions stay in the shared bridge profile under `~/.ai-browser-bridge/chrome-profile`, not under `.bridge/`.
 
 > User-authored config meant to apply across **all** repos lives in your home directory: custom commands in `~/.ai-browser-bridge/commands/*.md` and user-level hooks in `~/.ai-browser-bridge/hooks.json`.
 
@@ -225,10 +226,10 @@ The package was renamed to **`ai-browser-bridge`**. Global user config moved fro
 ```bash
 pnpm test          # vitest run
 pnpm typecheck     # tsc --noEmit
-pnpm verify:push   # biome ci + typecheck + test + build + check:class-api + check:tsdoc + check:boundaries
+pnpm verify:push   # Biome + style mirror + typecheck + test + build + boundary/compatibility checks
 ```
 
-Coverage focuses on the safety-sensitive paths — sandbox validation, repo-local path resolution, the `.bridge/` self-ignore guard, session/checkpoint stores, permissions, and context counting.
+Coverage focuses on the safety-sensitive paths — sandbox validation, canonical repo-root resolution, session/checkpoint stores, permissions, and context counting.
 
 ## Gemini web support
 
@@ -257,6 +258,27 @@ For full MCP on Gemini, use the official [Gemini API Remote MCP](https://ai.goog
 
 **Selector maintenance:** when Google changes the Gemini web UI, fix selectors only in [`src/features/providers/gemini/geminiPage.ts`](src/features/providers/gemini/geminiPage.ts).
 
+## Arena.ai support
+
+The bridge drives **[Arena](https://arena.ai/code/direct)** (LMSYS) with a dedicated adapter for the mode menu and model picker:
+
+| Mode | `--model` token | URL |
+|------|-----------------|-----|
+| **Direct** (default) | `direct` | `/code/direct` — one model |
+| **Battle Mode** | `battle` | `/code` — Option A/B (dual reply when both finish) |
+| **Agent Mode** | `agent` | `/agent` — agent shell (best-effort) |
+| **Side by Side** | `side` / `sbs` | `/text/side-by-side` — pick two models |
+
+```bash
+bridge chrome start --provider arena
+bridge ask --provider arena "build a todo app"                          # Direct + Max
+bridge ask --provider arena --model glm-5.1 "reply with pong"           # pick a model
+bridge ask --provider arena --model battle "compare two approaches"     # dual Option A/B
+bridge ask --provider arena --model direct/gemini-3-flash "hello"       # mode + model
+```
+
+Model search matches the in-UI picker (Search models + Text/Code/Image/Search tabs). Battle turns on Code Arena can take minutes (full site builds) — raise `--timeout` if needed. No MCP connector on Arena.
+
 ## Google Flow support
 
 The bridge can also drive **[Google Labs Flow](https://labs.google/fx/tools/flow)** — Google's Veo-powered AI video studio — with the same Playwright/CDP pattern. Flow is different in kind from the chat providers: it is a **generation** surface, so a "reply" is a rendered **clip** and attachments are **ingredients** (reference images).
@@ -271,7 +293,7 @@ Beyond generating, the bridge drives Flow's full **asset lifecycle** through `br
 
 ```bash
 bridge flow clips                        # list clips in the current project (id + fetchable URL)
-bridge flow download                     # download every clip's mp4 to ./downloads/flow (or --id <clipId...>)
+bridge flow download                     # download every clip's mp4 to <repo>/.bridge/downloads/flow
 bridge flow reuse   --id <clipId>        # add a clip back to the prompt as input ("Add to prompt")
 bridge flow extend  --id <clipId>        # add a clip to a scene (Flow's "Add to scene")
 bridge flow rename  --id <clipId> --name "hero shot"
@@ -303,7 +325,7 @@ Agents without shell access get the same lifecycle as **`flow_*` MCP tools** ove
 
 Flow requires a **Google AI Pro/Ultra** plan. Because Veo renders take minutes, `--provider flow` waits far longer for a response than the chat providers do.
 
-**Selector maintenance:** Flow's selectors were **LIVE-VERIFIED** against a signed-in project editor. If Google changes the UI, recapture with `node src/scripts/dev/captureProviderSelectors.mjs`, then update [`src/config/providersConfig.ts`](src/config/providersConfig.ts); generation lives in [`src/features/providers/flow/flowPage.ts`](src/features/providers/flow/flowPage.ts) and asset CRUD in [`src/features/providers/flow/flowAssets.ts`](src/features/providers/flow/flowAssets.ts).
+**Selector maintenance:** Flow's selectors were **LIVE-VERIFIED** against a signed-in project editor. If Google changes the UI, recapture with `node scripts/dev/captureProviderSelectors.mjs`, then update [`src/config.ts`](src/config.ts); generation lives in [`src/features/providers/flow/flowPage.ts`](src/features/providers/flow/flowPage.ts) and asset CRUD in [`src/features/providers/flow/flowAssets.ts`](src/features/providers/flow/flowAssets.ts).
 
 ## Limitations