@babtab/relay 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -4,6 +4,55 @@ All notable changes to the public npm package `@babtab/relay`
 are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
 and [Semantic Versioning](https://semver.org/).
 
+## [Unreleased]
+
+### 0.2.0 — automatic local onboarding (release candidate)
+
+- MCP-owned `stdio` bridge starts / reuses a local relay, reconnects after owner
+  exit, and stores credentials under `~/.babtab/` instead of the working directory.
+- Local `setup` now writes stdio config before any relay or browser connection
+  exists. Remote `--relay-url` setup keeps the HTTP pairing flow.
+- Tool discovery is immediate; browser calls remain gated by explicit pairing,
+  token scopes, and expiry. Interrupted actions are never replayed automatically.
+- Extension adds an Add to Cursor link, agent-first onboarding, and an alarm to
+  restore opted-in connections after service-worker suspension.
+- Publish `@babtab/relay@0.2.0` before releasing extension 0.2.0; its install
+  links and setup commands deliberately pin that version.
+
+
+## [0.1.1] — 2026-09-29
+
+### Security and compatibility
+
+- Device WebSockets now authenticate before registering or approving pairings.
+  The extension generates a 256-bit device credential and a `dev_v2_` ID derived
+  from its SHA-256 hash; the secret is sent in the first socket frame, not the URL.
+  **Update the relay and extension together and re-pair existing agents.**
+- The relay binds `127.0.0.1` by default. Remote deployments must explicitly set
+  `HOST` and provide TLS. WebSocket clients enforce tool scopes on every request;
+  revocation closes existing connections.
+
+### Fixed
+
+- Invalid JSON bodies/envelopes no longer crash the relay; shutdown closes active
+  devices and rejects pending requests within a bounded grace period.
+- MCP screenshots return image content; oversized text responses retain valid JSON.
+- TOML setup replaces nested headers safely, validates output, and atomically
+  writes the backed-up config. Values outside babtab are preserved; comments and
+  formatting may be normalized by the TOML serializer.
+
+### Added
+
+- `setup` subcommand: `npx -y @babtab/relay setup --target <id> --port <n> --device <id>`
+  pairs with the relay (human approves the 6-digit code in the Side Panel)
+  and writes the harness MCP config automatically — no hand-editing JSON.
+  13 targets: cursor, claude-code (via `claude mcp add`), windsurf, copilot,
+  copilot-insiders, codex (TOML), pi (curl probe), claude-desktop + antigravity
+  (mcp-remote stdio bridge), devin, kimi, hermes (YAML), manual.
+  Existing configs are merged (siblings preserved), JSONC comments tolerated,
+  previous file kept as `.bak`, remote relays via `--relay-url`.
+- `npx -y @babtab/relay help` and `setup --list-targets`.
+
 ## [0.1.0] — 2026-09-28
 
 Initial public release. Run the local bridge without cloning the monorepo:

package/LICENSE

@@ -175,18 +175,7 @@
 
    END OF TERMS AND CONDITIONS
 
-   APPENDIX: How to apply the Apache License to your work.
-
-      To apply the Apache License to your work, attach the following
-      boilerplate notice, with the fields enclosed by brackets "[]"
-      replaced with your own identifying information. (Don't include
-      the brackets!)  The text should be enclosed in the appropriate
-      comment syntax for the file format. We also recommend that a
-      file or class name and description of purpose be included on the
-      same "printed page" as the copyright notice for easier
-      identification within third-party archives.
-
-   Copyright [yyyy] [name of copyright owner]
+   Copyright 2026 Babtab contributors.
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

package/README.es.md

@@ -7,7 +7,17 @@
 
 El **servidor relay local** para la extensión Babtab de Chrome: conecta tu agente de IA (Cursor / Pi / Claude Code / …) con tu Chrome real.
 
-Las extensiones MV3 no pueden escuchar en un puerto, así que este pequeño programa actúa como puente. Se ejecuta en `localhost`, por lo que el tráfico nunca sale de tu máquina. El relay solo reenvía mensajes — **no puede ver el contenido de tus páginas**.
+Las extensiones MV3 no pueden escuchar en un puerto, así que este pequeño programa actúa como puente. Se ejecuta en `localhost`, por lo que el tráfico nunca sale de tu máquina. El relay reenvía solicitudes y resultados solo en memoria (incluidas observaciones de página y capturas); no almacena el contenido de las páginas.
+
+## Instalación recomendada (0.2.0)
+
+Requiere Node.js 20+. Instala la extensión desde Chrome Web Store y pulsa **Add to Cursor** en Babtab. Confirma y activa Babtab en Cursor, vuelve a Chrome y pulsa **Approve**. Tu herramienta de IA inicia el relay automáticamente; no necesitas mantener una terminal abierta. Para otras herramientas, usa **Other AI tools / install with a command**.
+
+Detén el relay manual anterior antes de cambiar. Consulta la [guía actualizada](README.md). Las instrucciones siguientes corresponden a la conexión HTTP manual.
+
+## Actualización a conexiones de dispositivo autenticadas
+
+Actualiza el relay y la extensión juntos, recarga la extensión, reconecta en el Side Panel y repite el paso 2 para cada agente. La extensión genera un nuevo ID de dispositivo `dev_v2_`; los tokens vinculados a IDs anteriores ya no controlan la nueva conexión. El relay ahora se vincula explícitamente a `127.0.0.1`. En despliegues remotos debes configurar `HOST` y usar TLS (`wss://` / `https://`) para proteger las credenciales en tránsito.
 
 ## Cómo se conecta (3 roles)
 
@@ -52,27 +62,32 @@ BABTAB_TOKEN_FILE=~/.babtab/relay-tokens.json npx @babtab/relay
 ### Paso 3: Conecta la extensión al relay
 
 1. Abre cualquier sitio web en Chrome, haz clic en el icono de Babtab para abrir el **Side Panel**
-2. La Relay URL ya viene con `ws://127.0.0.1:3000` — déjala así
+2. Paso 1: confirma el puerto (por defecto `3000`, debe coincidir con el relay) — sin escribir URLs
 3. Haz clic en **"Save & Connect" (Guardar y conectar)**
 
 Esto registra tu Chrome como un dispositivo en el relay.
+(¿Relay remoto en un VPS? Usa *Advanced: custom Relay URL* en el mismo paso.)
 
 ### Paso 4: Conecta tu agente de IA al relay (ejemplo con Cursor)
 
-1. En la misma página del Side Panel, elige tu agente → haz clic en **"Copy config" (Copiar configuración)**
-2. Pégalo en `mcpServers` dentro de `~/.cursor/mcp.json` (o en el `.cursor/mcp.json` del proyecto para un solo proyecto):
-
-```json
-{
-  "mcpServers": {
-    "babtab": {
-      "url": "http://127.0.0.1:3000/mcp",
-      "headers": { "Authorization": "Bearer el-token-que-acabas-de-obtener" }
-    }
-  }
-}
+1. En la misma página del Side Panel, paso 2 → haz clic en **Cursor** → copia el comando de una línea:
+
+```bash
+npx -y @babtab/relay setup --target cursor --relay-url http://127.0.0.1:3000 --device <tu-device-id>
 ```
 
+2. Pégalo en cualquier terminal y ejecútalo. Mostrará un código de emparejamiento
+   de 6 dígitos — apruébalo en el banner superior del Side Panel.
+3. Listo: el comando escribe `babtab` en `~/.cursor/mcp.json` por ti
+   (conserva las entradas existentes y guarda el archivo anterior como `.bak`).
+   Recarga MCP en Cursor (Settings → MCP) y el panel mostrará `Controlled by: cursor`.
+
+Valores `--target` soportados: `cursor`, `claude-code`, `windsurf`, `copilot`,
+`copilot-insiders`, `codex`, `pi`, `claude-desktop`, `antigravity`, `devin`,
+`kimi`, `hermes`, `manual`. `npx -y @babtab/relay setup --help` muestra todos los
+comandos (`--list-targets` imprime una línea lista por harness). ¿Sin terminal a mano?
+El paso 2 también ofrece *Pair & copy JSON manually* como alternativa.
+
 3. Cuando el panel muestre `Controlled by: cursor`, ya estás conectado.
 
 Una frase para verificar (pídesela a tu agente):
@@ -81,10 +96,10 @@ Una frase para verificar (pídesela a tu agente):
 
 ## Preguntas frecuentes
 
-- **¿"Guardar y conectar" no hace nada?** Revisa primero que la terminal del relay muestre `listening`, y confirma que la URL sea `ws://127.0.0.1:3000` con el puerto correcto.
-- **¿Caducó el código de emparejamiento?** Los códigos duran poco — pulsa "Copiar configuración" de nuevo.
-- **¿Quieres un token nuevo?** Repetir el paso 4 genera un token nuevo; recuerda actualizar `mcp.json`.
-- **¿Agente y Chrome en máquinas distintas?** (Avanzado) Pon el relay en un VPS y cambia la Relay URL del Side Panel a tu `wss://…`. El flujo es el mismo.
+- **¿"Guardar y conectar" no hace nada?** Revisa primero que la terminal del relay muestre `listening`, y confirma que el puerto del paso 1 coincida con el del relay.
+- **¿Caducó el código de emparejamiento?** Los códigos duran poco — vuelve a ejecutar el comando setup.
+- **¿Quieres un token nuevo?** Repetir el comando setup genera un token nuevo y reescribe la config (se conserva el `.bak` anterior).
+- **¿Agente y Chrome en máquinas distintas?** (Avanzado) Pon el relay en un VPS, usa *Advanced: custom Relay URL* en el paso 1 del Side Panel con tu `wss://…` y pasa `--relay-url https://…` al comando setup. El flujo es el mismo.
 
 ## Privacidad
 

package/README.hi.md

@@ -7,7 +7,17 @@
 
 Babtab Chrome एक्सटेंशन के लिए **लोकल relay सर्वर**: यह आपके AI एजेंट (Cursor / Pi / Claude Code / …) को आपके असली Chrome से जोड़ता है।
 
-MV3 एक्सटेंशन स्वयं किसी पोर्ट पर listen नहीं कर सकते, इसलिए यह छोटा प्रोग्राम bridge का काम करता है। यह `localhost` पर चलता है, इसलिए ट्रैफ़िक आपकी मशीन से बाहर कभी नहीं जाता। Relay सिर्फ़ संदेश आगे बढ़ाता है — **यह आपकी पेज सामग्री नहीं देख सकता**।
+MV3 एक्सटेंशन स्वयं किसी पोर्ट पर listen नहीं कर सकते, इसलिए यह छोटा प्रोग्राम bridge का काम करता है। यह `localhost` पर चलता है, इसलिए ट्रैफ़िक आपकी मशीन से बाहर कभी नहीं जाता। Relay अनुरोध और परिणाम सिर्फ़ मेमोरी में आगे बढ़ाता है (पेज अवलोकन और स्क्रीनशॉट सहित); यह पेज सामग्री को store नहीं करता।
+
+## अनुशंसित सेटअप (0.2.0)
+
+Node.js 20+ आवश्यक है। Chrome Web Store से एक्सटेंशन इंस्टॉल करें और Babtab में **Add to Cursor** दबाएँ। Cursor में जोड़ने और सक्षम करने की पुष्टि करें, फिर Chrome में लौटकर **Approve** दबाएँ। AI टूल Relay को अपने आप शुरू करता है; टर्मिनल खुला रखने की जरूरत नहीं है। अन्य टूल के लिए **Other AI tools / install with a command** चुनें।
+
+बदलने से पहले पुराना मैन्युअल Relay बंद करें। [नवीनतम गाइड](README.md) देखें। नीचे दिए गए निर्देश मैन्युअल HTTP कनेक्शन के लिए हैं।
+
+## प्रमाणित डिवाइस कनेक्शन पर अपग्रेड
+
+Relay और एक्सटेंशन दोनों को एक साथ अपडेट करें, एक्सटेंशन reload करें, Side Panel में फिर से connect करें, और हर एजेंट के लिए चरण 2 दोहराएँ। एक्सटेंशन नई `dev_v2_` डिवाइस ID बनाता है; पुरानी ID से जुड़े टोकन नया कनेक्शन नियंत्रित नहीं कर सकते। Relay अब स्पष्ट रूप से सिर्फ़ `127.0.0.1` पर bind होता है। रिमोट डिप्लॉयमेंट में `HOST` सेट करें और ट्रांज़िट में क्रेडेंशियल की सुरक्षा के लिए TLS (`wss://` / `https://`) इस्तेमाल करें।
 
 ## यह कैसे जुड़ता है (3 भूमिकाएँ)
 
@@ -52,27 +62,32 @@ BABTAB_TOKEN_FILE=~/.babtab/relay-tokens.json npx @babtab/relay
 ### चरण 3: एक्सटेंशन को relay से जोड़ें
 
 1. Chrome में कोई भी वेबसाइट खोलें, Babtab टूलबार आइकन पर क्लिक करके **Side Panel** खोलें
-2. Relay URL में पहले से `ws://127.0.0.1:3000` भरा है — वैसे ही रहने दें
+2. चरण 1: पोर्ट की पुष्टि करें (डिफ़ॉल्ट `3000`, relay से मेल खाना चाहिए) — URL टाइप करने की ज़रूरत नहीं
 3. "Save & Connect" पर क्लिक करें
 
 इससे आपका Chrome relay पर एक device के रूप में पंजीकृत हो जाता है।
+(VPS पर रिमोट relay? उसी चरण में *Advanced: custom Relay URL* इस्तेमाल करें।)
 
 ### चरण 4: AI एजेंट को relay से जोड़ें (Cursor उदाहरण सहित)
 
-1. Side Panel के उसी पेज पर अपना एजेंट चुनें → "Copy config" पर क्लिक करें
-2. `~/.cursor/mcp.json` के `mcpServers` में paste करें (सिर्फ़ एक प्रोजेक्ट हेतु हो तो उस प्रोजेक्ट की `.cursor/mcp.json` में):
-
-```json
-{
-  "mcpServers": {
-    "babtab": {
-      "url": "http://127.0.0.1:3000/mcp",
-      "headers": { "Authorization": "Bearer अभी-मिला-टोकन" }
-    }
-  }
-}
+1. Side Panel के उसी पेज पर चरण 2 → **Cursor** पर क्लिक करें → एक-पंक्ति कमांड copy करें:
+
+```bash
+npx -y @babtab/relay setup --target cursor --relay-url http://127.0.0.1:3000 --device <आपकी-device-id>
 ```
 
+2. किसी भी टर्मिनल में paste करके चलाएँ। 6-अंकीय पेयरिंग कोड दिखेगा —
+   Side Panel के ऊपर banner में **Approve** करें।
+3. हो गया: कमांड आपके लिए `~/.cursor/mcp.json` में `babtab` लिख देता है
+   (मौजूदा entries सुरक्षित, पुरानी फ़ाइल `.bak` के रूप में रहती है)। Cursor में MCP
+   reload करें (Settings → MCP) और पैनल में `Controlled by: cursor` दिखेगा।
+
+समर्थित `--target` मान: `cursor`, `claude-code`, `windsurf`, `copilot`,
+`copilot-insiders`, `codex`, `pi`, `claude-desktop`, `antigravity`, `devin`,
+`kimi`, `hermes`, `manual`। सभी कमांड हेतु `npx -y @babtab/relay setup --help` चलाएँ
+(`--list-targets` हर harness हेतु तैयार पंक्ति print करता है)। टर्मिनल उपलब्ध न हो?
+चरण 2 में *Pair & copy JSON manually* विकल्प भी है।
+
 3. जब पैनल में `Controlled by: cursor` दिखे, तो कनेक्शन हो गया।
 
 सत्यापन हेतु एक वाक्य (अपने एजेंट से कहें):
@@ -81,10 +96,10 @@ BABTAB_TOKEN_FILE=~/.babtab/relay-tokens.json npx @babtab/relay
 
 ## अक्सर पूछे जाने वाले प्रश्न
 
-- **"Save & Connect" दबाने पर कुछ नहीं होता?** पहले relay टर्मिनल में `listening` देखें, फिर पुष्टि करें कि URL `ws://127.0.0.1:3000` है और पोर्ट मेल खाता है।
-- **पेयरिंग कोड समाप्त हो गया?** कोड थोड़ी देर ही चलते हैं — "Copy config" दोबारा दबाएँ।
-- **नया टोकन चाहिए?** चरण 4 दोहराने पर नया टोकन मिलता है; `mcp.json` अपडेट करना न भूलें।
-- **एजेंट और Chrome अलग मशीनों पर हैं?** (उन्नत) Relay को VPS पर रखें और Side Panel की Relay URL को अपने `wss://…` पर बदल दें। प्रक्रिया वही रहती है।
+- **"Save & Connect" दबाने पर कुछ नहीं होता?** पहले relay टर्मिनल में `listening` देखें, फिर पुष्टि करें कि चरण 1 का पोर्ट relay के पोर्ट से मेल खाता है।
+- **पेयरिंग कोड समाप्त हो गया?** कोड थोड़ी देर ही चलते हैं — setup कमांड दोबारा चलाएँ।
+- **नया टोकन चाहिए?** setup कमांड दोहराने पर नया टोकन मिलता है और कॉन्फ़िग फिर से लिखी जाती है (पुरानी `.bak` बनी रहती है)।
+- **एजेंट और Chrome अलग मशीनों पर हैं?** (उन्नत) Relay को VPS पर रखें, Side Panel चरण 1 में *Advanced: custom Relay URL* में अपना `wss://…` भरें और setup कमांड में `--relay-url https://…` जोड़ें। प्रक्रिया वही रहती है।
 
 ## गोपनीयता
 

package/README.ja.md

@@ -7,7 +7,17 @@
 
 Babtab Chrome 拡張機能のための**ローカル中継サーバー**です。あなたの AI エージェント（Cursor / Pi / Claude Code / …）を、実際の Chrome につなぎます。
 
-MV3 の拡張機能は自分でポートを listen できないため、この小さなプログラムが橋渡しをします。`localhost` 上で動作するので、通信が PC の外に出ることはありません。Relay は転送だけを行い、**ページの内容を見ることはできません**。
+MV3 の拡張機能は自分でポートを listen できないため、この小さなプログラムが橋渡しをします。`localhost` 上で動作するので、通信が PC の外に出ることはありません。Relay はリクエストと結果をメモリ上でのみ転送します（ページ観測やスクリーンショットを含みます）。ページ内容を保存することはありません。
+
+## 推奨セットアップ（0.2.0）
+
+Node.js 20+ が必要です。Chrome ウェブストアから拡張機能をインストールし、Babtab の **Add to Cursor** を押します。Cursor で追加・有効化し、Chrome に戻って **Approve** を押してください。Relay は AI ツールが自動起動するため、ターミナルを開いたままにする必要はありません。ほかの AI ツールは **Other AI tools / install with a command** から設定できます。
+
+旧版の手動 Relay を終了してから切り替えてください。詳細は [最新ガイド](README.md) を参照してください。以下は手動 HTTP 接続用の手順です。
+
+## デバイス認証へのアップグレード
+
+Relay と拡張機能を一緒に更新し、拡張機能を再読み込みして Side Panel で再接続したうえで、各エージェントについてステップ 2 を再実行してください。拡張機能は新しい `dev_v2_` デバイス ID を生成します。古い ID に紐づくトークンでは新しい接続を操作できません。Relay は明示的に `127.0.0.1` にバインドするようになりました。リモート配置では `HOST` を指定し、TLS（`wss://`／`https://`）で転送中の認証情報を保護してください。
 
 ## 接続方法（3つの役割）
 
@@ -52,28 +62,30 @@ BABTAB_TOKEN_FILE=~/.babtab/relay-tokens.json npx @babtab/relay
 ### ステップ 3：拡張機能を Relay に接続する
 
 1. Chrome で任意のサイトを開き、ツールバーの Babtab アイコンをクリックして **Side Panel** を開く
-2. Relay URL にはデフォルトで `ws://127.0.0.1:3000` が入力済みなので、そのまま
+2. ステップ 1 でポートを確認するだけです（デフォルト `3000`、Relay と一致させること）。URL の入力は不要です
 3. **"Save & Connect"（保存して接続）**をクリック
 
 この手順で、あなたの Chrome が Relay 上のデバイスとして登録されます。
+（VPS 上のリモート Relay を使う場合も、同じステップ内の *Advanced: custom Relay URL* で対応できます。）
 
 ### ステップ 4：AI エージェントを Relay に接続する（Cursor の例）
 
-1. Side Panel の同じページでエージェントを選択 → **"Copy config"（設定をコピー）**をクリック
-2. `~/.cursor/mcp.json` の `mcpServers` に貼り付け（単一プロジェクト専用にする場合は当該プロジェクトの `.cursor/mcp.json`）：
-
-```json
-{
-  "mcpServers": {
-    "babtab": {
-      "url": "http://127.0.0.1:3000/mcp",
-      "headers": { "Authorization": "Bearer 取得したトークン" }
-    }
-  }
-}
+1. Side Panel の同じページでステップ 2 → **Cursor** をクリック → ワンライナーのコマンドをコピーします：
+
+```bash
+npx -y @babtab/relay setup --target cursor --relay-url http://127.0.0.1:3000 --device <あなたのデバイスID>
 ```
 
-3. パネルに `Controlled by: cursor` と表示されたら接続完了です。
+2. 任意のターミナルに貼り付けて実行します。6 桁のペアリングコードが表示されるので、Side Panel 上部のバナーで **Approve（承認）**します。
+3. 完了です。コマンドが `~/.cursor/mcp.json` に `babtab` を自動で書き込みます
+   （既存のエントリは保持され、変更前のファイルは `.bak` として残ります）。Cursor で MCP をリロード
+   （Settings → MCP）すると、パネルに `Controlled by: cursor` と表示されます。
+
+サポートされている `--target`：`cursor`、`claude-code`、`windsurf`、`copilot`、
+`copilot-insiders`、`codex`、`pi`、`claude-desktop`、`antigravity`、`devin`、
+`kimi`、`hermes`、`manual`。`npx -y @babtab/relay setup --help` ですべての
+コマンドを確認できます（`--list-targets` で各ハーネス用の完成済みコマンドを一覧表示）。
+ターミナルが使えない環境では、ステップ 2 の *Pair & copy JSON manually* で手動貼り付けに戻れます。
 
 動作確認の一言（エージェントに依頼）：
 
@@ -81,10 +93,10 @@ BABTAB_TOKEN_FILE=~/.babtab/relay-tokens.json npx @babtab/relay
 
 ## よくある質問
 
-- **"Save & Connect"を押しても反応がない？** まず Relay のターミナルに `listening` と表示されているか確認し、URL が `ws://127.0.0.1:3000` でポートが一致しているか確認してください。
-- **ペアリングコードの有効期限が切れた？** コードの有効期間は短いので、"Copy config"をもう一度押してください。
-- **トークンを変えたい？** ステップ 4 を再実行すると新しいトークンが発行されます。`mcp.json` の更新をお忘れなく。
-- **エージェントと Chrome が別マシン？**（応用）Relay を VPS 上に置き、Side Panel の Relay URL を `wss://…` に変更するだけです。手順は同じです。
+- **"Save & Connect"を押しても反応がない？** まず Relay のターミナルに `listening` と表示されているか確認し、ステップ 1 のポートが Relay のポートと一致しているか確認してください。
+- **ペアリングコードの有効期限が切れた？** コードの有効期間は短いので、setup コマンドを再実行してください。
+- **トークンを変えたい？** setup コマンドを再実行すると新しいトークンが発行され、設定も自動で書き換えられます（旧ファイルは `.bak` として残ります）。
+- **エージェントと Chrome が別マシン？**（応用）Relay を VPS 上に置き、Side Panel ステップ 1 の *Advanced: custom Relay URL* に `wss://…` を設定し、setup コマンドに `--relay-url https://…` を付けるだけです。手順は同じです。
 
 ## プライバシー
 

package/README.ko.md

@@ -7,7 +7,17 @@
 
 Babtab Chrome 확장 프로그램을 위한 **로컬 중계 서버**입니다. AI 에이전트(Cursor / Pi / Claude Code / …)를 실제 Chrome에 연결해 줍니다.
 
-MV3 확장 프로그램은 스스로 포트를 listen 할 수 없기 때문에, 이 작은 프로그램이 다리 역할을 합니다. `localhost`에서 동작하므로 트래픽이 컴퓨터 밖으로 나가지 않습니다. Relay는 전달만 담당하며, **페이지 내용을 볼 수 없습니다**.
+MV3 확장 프로그램은 스스로 포트를 listen 할 수 없기 때문에, 이 작은 프로그램이 다리 역할을 합니다. `localhost`에서 동작하므로 트래픽이 컴퓨터 밖으로 나가지 않습니다. Relay는 요청과 결과를 메모리에서만 전달합니다(페이지 관찰 및 스크린샷 포함). 페이지 내용을 저장하지 않습니다.
+
+## 권장 설치 방법 (0.2.0)
+
+Node.js 20+가 필요합니다. Chrome 웹 스토어에서 확장 프로그램을 설치하고 Babtab의 **Add to Cursor**를 누르세요. Cursor에서 추가 / 활성화한 뒤 Chrome으로 돌아와 **Approve**를 누르세요. AI 도구가 Relay를 자동으로 실행하므로 터미널을 계속 열어 둘 필요가 없습니다. 다른 도구는 **Other AI tools / install with a command**에서 설정할 수 있습니다.
+
+전환 전에 기존 수동 Relay를 종료하세요. 자세한 내용은 [최신 가이드](README.md)를 참조하세요. 아래는 수동 HTTP 연결용 절차입니다.
+
+## 인증된 디바이스 연결로 업그레이드
+
+Relay와 확장 프로그램을 함께 업데이트하고, 확장 프로그램을 새로고침한 뒤 Side Panel에서 다시 연결한 다음, 각 에이전트마다 2단계를 다시 실행하세요. 확장 프로그램이 새 `dev_v2_` 디바이스 ID를 생성합니다. 이전 ID에 연결된 토큰으로는 새 연결을 제어할 수 없습니다. Relay는 이제 명시적으로 `127.0.0.1`에만 바인딩됩니다. 원격 배포에서는 `HOST`를 직접 설정하고 TLS(`wss://` / `https://`)로 전송 중 인증 정보를 보호하세요.
 
 ## 연결 방식 (3가지 역할)
 
@@ -52,27 +62,31 @@ BABTAB_TOKEN_FILE=~/.babtab/relay-tokens.json npx @babtab/relay
 ### 3단계: 확장 프로그램을 Relay에 연결
 
 1. Chrome에서 아무 웹사이트나 열고, 툴바의 Babtab 아이콘을 클릭해 **Side Panel** 열기
-2. Relay URL에는 기본값 `ws://127.0.0.1:3000`이 이미 입력되어 있으니 그대로 두기
+2. 1단계에서 포트만 확인(기본값 `3000`, Relay와 일치해야 함) — URL 입력 불필요
 3. **"Save & Connect" (저장 후 연결)** 클릭
 
 이 단계에서 내 Chrome이 Relay의 디바이스 하나로 등록됩니다.
+(VPS의 원격 Relay를 쓰는 경우에도 같은 단계의 *Advanced: custom Relay URL*에서 설정할 수 있습니다.)
 
 ### 4단계: AI 에이전트를 Relay에 연결 (Cursor 예시)
 
-1. Side Panel 같은 페이지에서 에이전트 선택 → **"Copy config" (설정 복사)** 클릭
-2. `~/.cursor/mcp.json`의 `mcpServers`에 붙여넣기(단일 프로젝트 전용으로 쓰려면 해당 프로젝트의 `.cursor/mcp.json`):
-
-```json
-{
-  "mcpServers": {
-    "babtab": {
-      "url": "http://127.0.0.1:3000/mcp",
-      "headers": { "Authorization": "Bearer 발급받은-토큰" }
-    }
-  }
-}
+1. Side Panel 같은 페이지에서 2단계 → **Cursor** 클릭 → 한 줄 명령어를 복사:
+
+```bash
+npx -y @babtab/relay setup --target cursor --relay-url http://127.0.0.1:3000 --device <내-디바이스-ID>
 ```
 
+2. 아무 터미널에 붙여넣어 실행. 6자리 페어링 코드가 표시되면 Side Panel 상단 배너에서 **Approve(승인)** 클릭.
+3. 완료: 명령어가 `~/.cursor/mcp.json`에 `babtab`을 자동으로 기록합니다
+   (기존 항목은 유지, 이전 파일은 `.bak`으로 백업). Cursor에서 MCP를 새로고침하면
+   (Settings → MCP) 패널에 `Controlled by: cursor`가 표시됩니다.
+
+지원하는 `--target`: `cursor`, `claude-code`, `windsurf`, `copilot`,
+`copilot-insiders`, `codex`, `pi`, `claude-desktop`, `antigravity`, `devin`,
+`kimi`, `hermes`, `manual`. `npx -y @babtab/relay setup --help`에서 전체 명령어 확인 가능
+(`--list-targets`는 하네스별 완성형 명령어를 한 번에 출력). 터미널을 쓸 수 없는 환경에서는
+2단계의 *Pair & copy JSON manually*로 수동 붙여넣기로 돌아갈 수 있습니다.
+
 3. 패널에 `Controlled by: cursor`가 표시되면 연결 완료.
 
 동작 확인용 한 마디(에이전트에게 요청):
@@ -81,10 +95,10 @@ BABTAB_TOKEN_FILE=~/.babtab/relay-tokens.json npx @babtab/relay
 
 ## 자주 묻는 질문
 
-- **"Save & Connect"을 눌러도 반응이 없어요.** 먼저 Relay 터미널에 `listening`이 표시되는지 확인하고, URL이 `ws://127.0.0.1:3000`인지, 포트가 일치하는지 확인하세요.
-- **페어링 코드가 만료됐어요.** 코드 유효 시간이 짧으니 "Copy config"을 다시 눌러주세요.
-- **토큰을 바꾸고 싶어요.** 4단계를 다시 실행하면 새 토큰이 발급됩니다. `mcp.json` 업데이트를 잊지 마세요.
-- **에이전트와 Chrome이 서로 다른 컴퓨터에 있어요.** (고급) Relay를 VPS에 올리고 Side Panel의 Relay URL을 `wss://…`로 바꾸면 됩니다. 과정은 동일합니다.
+- **"Save & Connect"을 눌러도 반응이 없어요.** 먼저 Relay 터미널에 `listening`이 표시되는지 확인하고, 1단계의 포트가 Relay 포트와 일치하는지 확인하세요.
+- **페어링 코드가 만료됐어요.** 코드 유효 시간이 짧으니 setup 명령어를 다시 실행해 주세요.
+- **토큰을 바꾸고 싶어요.** setup 명령어를 다시 실행하면 새 토큰이 발급되고 설정도 자동으로 다시 기록됩니다(이전 파일은 `.bak`으로 유지).
+- **에이전트와 Chrome이 서로 다른 컴퓨터에 있어요.** (고급) Relay를 VPS에 올리고, Side Panel 1단계의 *Advanced: custom Relay URL*에 `wss://…`를 설정한 뒤 setup 명령어에 `--relay-url https://…`를 붙이면 됩니다. 과정은 동일합니다.
 
 ## 개인정보 보호
 

package/README.md

@@ -7,84 +7,53 @@
 
 The **local relay server** for the Babtab Chrome extension: it connects your AI agent (Cursor / Pi / Claude Code / …) to your real Chrome.
 
-MV3 extensions cannot listen on a port, so this tiny program acts as the bridge. It runs on `localhost`, so traffic never leaves your machine. The relay only forwards messages — **it cannot see your page content**.
+MV3 extensions cannot listen on a port, so this tiny program acts as the bridge. It runs on `localhost`, so traffic never leaves your machine. The relay forwards requests and results in memory, including page observations and screenshots; it does not persist page content.
 
-## How it connects (3 roles)
+## Quick start (0.2.0)
 
-```text
-AI agent (Cursor / Pi …) ←→ Relay (local :3000) ←→ Chrome extension (with Side Panel)
-   connects via MCP config     forwarding + pairing only    does the real work in your tabs
-```
-
-## Quick start (no clone, no install)
-
-### Step 1: Install the Chrome extension
-
-`chrome://extensions` → enable **Developer mode** → **Load unpacked** → select the `dist` folder.
-
-> Once published on the Chrome Web Store, this step becomes "install from the store".
-
-### Step 2: Start the relay (pick one, same result)
+Requires Node.js 20+ and the matching Babtab extension. Install the extension from the **Chrome Web Store**; Developer mode is for local development only.
 
-```bash
-# A. Have Node 20+? No install needed, just run:
-npx @babtab/relay
-
-# B. No Node? Download the binary for your OS from GitHub Releases:
-./babtab-relay-darwin-arm64   # e.g. macOS Apple Silicon
-```
+1. Open Babtab in Chrome and click **Add to Cursor**.
+2. Confirm Add / Enable in Cursor. Cursor starts the local bridge automatically.
+3. Return to Babtab and **Approve** the first connection.
+4. On a regular website, ask your agent: **Use babtab to observe the current tab**. Approve site access in Babtab if asked.
 
-You're up when you see (default port `3000`):
+No separate relay command or terminal window is needed. Keep Chrome open.
+The first npm download requires internet access. Pairing credentials are stored in `~/.babtab/`, independent of your working directory.
 
-```text
-[babtab-relay] listening on http://127.0.0.1:3000
-```
+### Other AI tools
 
-Advanced (custom port / token file location):
+Open **Other AI tools / install with a command**, choose your tool and copy its personalized command:
 
 ```bash
-PORT=3001 npx @babtab/relay
-BABTAB_TOKEN_FILE=~/.babtab/relay-tokens.json npx @babtab/relay
+npx -y @babtab/relay@0.2.0 setup --target windsurf --port 3000 --device <device-id-from-extension>
 ```
 
-> `npx` doesn't install anything — it downloads and runs once. Closing the terminal stops the relay.
-
-### Step 3: Connect the extension to the relay
+Run once, enable / reload MCP in your AI tool, then approve in Chrome. Setup preserves other servers and backs up existing config files. Supported automatic targets: Cursor, Claude Code, Windsurf, Copilot, Codex, Claude Desktop, Antigravity, Devin, Kimi and Hermes. Pi / Manual use the advanced HTTP flow.
 
-1. Open any website in Chrome, click the Babtab toolbar icon to open the **Side Panel**
-2. Relay URL is pre-filled with `ws://127.0.0.1:3000` — leave it
-3. Click **"Save & Connect"**
+### How automatic startup works
 
-This registers your Chrome as a device on the relay.
+Your MCP client launches `babtab-relay stdio --device … --client … --port 3000`. The bridge starts or reuses the loopback relay. Tool discovery works before approval; browser operations require an explicitly approved token. Multiple clients share the relay; a remaining client takes over if its owner exits. In-flight actions interrupted by shutdown return an error and are never replayed automatically.
 
-### Step 4: Connect your AI agent to the relay (Cursor as example)
+Credentials live in `~/.babtab/` (override with `BABTAB_DATA_DIR`). The extension reconnects after browser / MCP restarts. Explicit **Disconnect** stops automatic reconnection until you reconnect.
 
-1. On the same Side Panel page, pick your agent → click **"Copy config"**
-2. Paste into `mcpServers` in `~/.cursor/mcp.json` (or the project's `.cursor/mcp.json` for single-project use):
+### Upgrading from 0.1.x
 
-```json
-{
-  "mcpServers": {
-    "babtab": {
-      "url": "http://127.0.0.1:3000/mcp",
-      "headers": { "Authorization": "Bearer the-token-you-just-got" }
-    }
-  }
-}
-```
+Stop the manually started relay, update the extension and add your AI tool again. Approve once to pair with the new managed credentials. Port conflicts or an older relay are reported without sending credentials to the conflicting service. Choose a different port under **Advanced connection settings** and reinstall the MCP entry if needed.
 
-3. When the panel shows `Controlled by: cursor`, you're connected.
+### Advanced: manual or remote relay
 
-One sentence to verify (ask your agent):
+`npx @babtab/relay` still starts a standalone HTTP relay. In the extension, open **Advanced connection settings**, set the port / URL and use **Save & Connect**. Manual HTTP config generation remains available.
 
-> Use browser_observe to look at the tabs open in my Chrome, then tell me their titles and URLs.
+Standalone token storage uses `BABTAB_TOKEN_FILE` or `./data/relay-tokens.json` relative to the launch directory. Remote relays need an explicit `HOST` and TLS (`wss://` / `https://`). Use `setup --target <tool> --relay-url https://… --device <id>` after the relay and extension are connected.
 
-## FAQ
+### Troubleshooting
 
-- **"Save & Connect" does nothing?** Check the relay terminal for `listening` first, then confirm the URL is `ws://127.0.0.1:3000` with a matching port.
-- **Pairing code expired?** Codes are short-lived — just hit "Copy config" again.
-- **Want a new token?** Re-running step 4 issues a new token; remember to update `mcp.json`.
-- **Agent and Chrome on different machines?** (Advanced) Put the relay on a VPS and change the Side Panel's Relay URL to your `wss://…`. The flow stays the same.
+- **Cursor did not open?** Use the setup command under the button, then reload / enable MCP.
+- **No pairing request?** Check that Node 20+ / `npx` is on your AI tool's PATH and Babtab is enabled. Keep the Chrome panel open. The MCP server's stderr logs explain startup problems.
+- **Pairing expired?** Keep the AI tool running; it requests a new code automatically.
+- **Connection stopped?** Reopen your AI tool and Chrome. If you explicitly disconnected, press Reconnect in Babtab.
+- **Lost / revoked credentials?** Approve the new pairing request; the bridge never bypasses browser approval.
 
 ## Privacy
 

package/README.pt-BR.md

@@ -7,7 +7,17 @@
 
 O **servidor relay local** para a extensão Babtab do Chrome: conecta seu agente de IA (Cursor / Pi / Claude Code / …) ao seu Chrome de verdade.
 
-Extensões MV3 não conseguem escutar em uma porta, então este programinha age como ponte. Roda em `localhost`, por isso o tráfego nunca sai da sua máquina. O relay só encaminha mensagens — **não consegue ver o conteúdo das suas páginas**.
+Extensões MV3 não conseguem escutar em uma porta, então este programinha age como ponte. Roda em `localhost`, por isso o tráfego nunca sai da sua máquina. O relay encaminha solicitações e resultados apenas em memória (incluindo observações de página e capturas); não armazena o conteúdo das páginas.
+
+## Instalação recomendada (0.2.0)
+
+Requer Node.js 20+. Instale a extensão pela Chrome Web Store e clique em **Add to Cursor** no Babtab. Confirme e ative no Cursor, volte ao Chrome e clique em **Approve**. A ferramenta de IA inicia o relay automaticamente; não é preciso manter um terminal aberto. Para outras ferramentas, use **Other AI tools / install with a command**.
+
+Encerre o relay manual anterior antes de mudar. Consulte o [guia atualizado](README.md). As instruções abaixo são para conexão HTTP manual.
+
+## Atualização para conexões de dispositivo autenticadas
+
+Atualize o relay e a extensão juntos, recarregue a extensão, reconecte no Side Panel e repita o passo 2 para cada agente. A extensão gera um novo ID de dispositivo `dev_v2_`; tokens vinculados a IDs anteriores não controlam mais a nova conexão. O relay agora se vincula explicitamente a `127.0.0.1`. Em implantações remotas, configure `HOST` e use TLS (`wss://` / `https://`) para proteger as credenciais em trânsito.
 
 ## Como se conecta (3 papéis)
 
@@ -52,27 +62,32 @@ BABTAB_TOKEN_FILE=~/.babtab/relay-tokens.json npx @babtab/relay
 ### Passo 3: Conecte a extensão ao relay
 
 1. Abra qualquer site no Chrome, clique no ícone do Babtab para abrir o **Side Panel**
-2. A Relay URL já vem preenchida com `ws://127.0.0.1:3000` — deixe assim
+2. Passo 1: confirme a porta (padrão `3000`, precisa ser igual à do relay) — sem digitar URLs
 3. Clique em **"Save & Connect" (Salvar e conectar)**
 
 Isso registra seu Chrome como um dispositivo no relay.
+(Relay remoto num VPS? Use *Advanced: custom Relay URL* no mesmo passo.)
 
 ### Passo 4: Conecte seu agente de IA ao relay (exemplo com Cursor)
 
-1. Na mesma página do Side Panel, escolha seu agente → clique em **"Copy config" (Copiar configuração)**
-2. Cole em `mcpServers` dentro de `~/.cursor/mcp.json` (ou no `.cursor/mcp.json` do projeto para uso em um só projeto):
-
-```json
-{
-  "mcpServers": {
-    "babtab": {
-      "url": "http://127.0.0.1:3000/mcp",
-      "headers": { "Authorization": "Bearer o-token-que-voce-acabou-de-obter" }
-    }
-  }
-}
+1. Na mesma página do Side Panel, passo 2 → clique em **Cursor** → copie o comando de uma linha:
+
+```bash
+npx -y @babtab/relay setup --target cursor --relay-url http://127.0.0.1:3000 --device <seu-device-id>
 ```
 
+2. Cole em qualquer terminal e execute. Ele mostra um código de pareamento de
+   6 dígitos — aprove no banner no topo do Side Panel.
+3. Pronto: o comando escreve `babtab` em `~/.cursor/mcp.json` para você
+   (preserva as entradas existentes e guarda o arquivo anterior como `.bak`).
+   Recarregue o MCP no Cursor (Settings → MCP) e o painel mostra `Controlled by: cursor`.
+
+Valores `--target` suportados: `cursor`, `claude-code`, `windsurf`, `copilot`,
+`copilot-insiders`, `codex`, `pi`, `claude-desktop`, `antigravity`, `devin`,
+`kimi`, `hermes`, `manual`. `npx -y @babtab/relay setup --help` mostra todos os
+comandos (`--list-targets` imprime uma linha pronta por harness). Sem terminal à mão?
+O passo 2 também oferece *Pair & copy JSON manually* como alternativa.
+
 3. Quando o painel mostrar `Controlled by: cursor`, está conectado.
 
 Uma frase para verificar (peça ao seu agente):
@@ -81,10 +96,10 @@ Uma frase para verificar (peça ao seu agente):
 
 ## Perguntas frequentes
 
-- **"Salvar e conectar" não faz nada?** Confira primeiro se o terminal do relay mostra `listening`, depois confirme que a URL é `ws://127.0.0.1:3000` com a porta certa.
-- **Código de pareamento expirou?** Os códigos duram pouco — clique em "Copiar configuração" de novo.
-- **Quer um token novo?** Repetir o passo 4 gera um token novo; lembre-se de atualizar o `mcp.json`.
-- **Agente e Chrome em máquinas diferentes?** (Avançado) Coloque o relay num VPS e troque a Relay URL do Side Panel para o seu `wss://…`. O fluxo é o mesmo.
+- **"Salvar e conectar" não faz nada?** Confira primeiro se o terminal do relay mostra `listening`, depois confirme que a porta do passo 1 é igual à do relay.
+- **Código de pareamento expirou?** Os códigos duram pouco — rode o comando setup de novo.
+- **Quer um token novo?** Repetir o comando setup gera um token novo e reescreve a config (mantém o `.bak` anterior).
+- **Agente e Chrome em máquinas diferentes?** (Avançado) Coloque o relay num VPS, use *Advanced: custom Relay URL* no passo 1 do Side Panel com o seu `wss://…` e passe `--relay-url https://…` ao comando setup. O fluxo é o mesmo.
 
 ## Privacidade