@babtab/relay 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -4,6 +4,41 @@ 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.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,11 @@
 
 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.
+
+## 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 +56,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 --port 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 +90,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,11 @@
 
 Babtab Chrome एक्सटेंशन के लिए **लोकल relay सर्वर**: यह आपके AI एजेंट (Cursor / Pi / Claude Code / …) को आपके असली Chrome से जोड़ता है।
 
-MV3 एक्सटेंशन स्वयं किसी पोर्ट पर listen नहीं कर सकते, इसलिए यह छोटा प्रोग्राम bridge का काम करता है। यह `localhost` पर चलता है, इसलिए ट्रैफ़िक आपकी मशीन से बाहर कभी नहीं जाता। Relay सिर्फ़ संदेश आगे बढ़ाता है — **यह आपकी पेज सामग्री नहीं देख सकता**।
+MV3 एक्सटेंशन स्वयं किसी पोर्ट पर listen नहीं कर सकते, इसलिए यह छोटा प्रोग्राम bridge का काम करता है। यह `localhost` पर चलता है, इसलिए ट्रैफ़िक आपकी मशीन से बाहर कभी नहीं जाता। Relay अनुरोध और परिणाम सिर्फ़ मेमोरी में आगे बढ़ाता है (पेज अवलोकन और स्क्रीनशॉट सहित); यह पेज सामग्री को store नहीं करता।
+
+## प्रमाणित डिवाइस कनेक्शन पर अपग्रेड
+
+Relay और एक्सटेंशन दोनों को एक साथ अपडेट करें, एक्सटेंशन reload करें, Side Panel में फिर से connect करें, और हर एजेंट के लिए चरण 2 दोहराएँ। एक्सटेंशन नई `dev_v2_` डिवाइस ID बनाता है; पुरानी ID से जुड़े टोकन नया कनेक्शन नियंत्रित नहीं कर सकते। Relay अब स्पष्ट रूप से सिर्फ़ `127.0.0.1` पर bind होता है। रिमोट डिप्लॉयमेंट में `HOST` सेट करें और ट्रांज़िट में क्रेडेंशियल की सुरक्षा के लिए TLS (`wss://` / `https://`) इस्तेमाल करें।
 
 ## यह कैसे जुड़ता है (3 भूमिकाएँ)
 
@@ -52,27 +56,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 --port 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 +90,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,11 @@
 
 Babtab Chrome 拡張機能のための**ローカル中継サーバー**です。あなたの AI エージェント（Cursor / Pi / Claude Code / …）を、実際の Chrome につなぎます。
 
-MV3 の拡張機能は自分でポートを listen できないため、この小さなプログラムが橋渡しをします。`localhost` 上で動作するので、通信が PC の外に出ることはありません。Relay は転送だけを行い、**ページの内容を見ることはできません**。
+MV3 の拡張機能は自分でポートを listen できないため、この小さなプログラムが橋渡しをします。`localhost` 上で動作するので、通信が PC の外に出ることはありません。Relay はリクエストと結果をメモリ上でのみ転送します（ページ観測やスクリーンショットを含みます）。ページ内容を保存することはありません。
+
+## デバイス認証へのアップグレード
+
+Relay と拡張機能を一緒に更新し、拡張機能を再読み込みして Side Panel で再接続したうえで、各エージェントについてステップ 2 を再実行してください。拡張機能は新しい `dev_v2_` デバイス ID を生成します。古い ID に紐づくトークンでは新しい接続を操作できません。Relay は明示的に `127.0.0.1` にバインドするようになりました。リモート配置では `HOST` を指定し、TLS（`wss://`／`https://`）で転送中の認証情報を保護してください。
 
 ## 接続方法（3つの役割）
 
@@ -52,28 +56,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 --port 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 +87,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,11 @@
 
 Babtab Chrome 확장 프로그램을 위한 **로컬 중계 서버**입니다. AI 에이전트(Cursor / Pi / Claude Code / …)를 실제 Chrome에 연결해 줍니다.
 
-MV3 확장 프로그램은 스스로 포트를 listen 할 수 없기 때문에, 이 작은 프로그램이 다리 역할을 합니다. `localhost`에서 동작하므로 트래픽이 컴퓨터 밖으로 나가지 않습니다. Relay는 전달만 담당하며, **페이지 내용을 볼 수 없습니다**.
+MV3 확장 프로그램은 스스로 포트를 listen 할 수 없기 때문에, 이 작은 프로그램이 다리 역할을 합니다. `localhost`에서 동작하므로 트래픽이 컴퓨터 밖으로 나가지 않습니다. Relay는 요청과 결과를 메모리에서만 전달합니다(페이지 관찰 및 스크린샷 포함). 페이지 내용을 저장하지 않습니다.
+
+## 인증된 디바이스 연결로 업그레이드
+
+Relay와 확장 프로그램을 함께 업데이트하고, 확장 프로그램을 새로고침한 뒤 Side Panel에서 다시 연결한 다음, 각 에이전트마다 2단계를 다시 실행하세요. 확장 프로그램이 새 `dev_v2_` 디바이스 ID를 생성합니다. 이전 ID에 연결된 토큰으로는 새 연결을 제어할 수 없습니다. Relay는 이제 명시적으로 `127.0.0.1`에만 바인딩됩니다. 원격 배포에서는 `HOST`를 직접 설정하고 TLS(`wss://` / `https://`)로 전송 중 인증 정보를 보호하세요.
 
 ## 연결 방식 (3가지 역할)
 
@@ -52,27 +56,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 --port 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 +89,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,7 +7,15 @@
 
 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.
+
+## Upgrading to authenticated device connections
+
+Update the relay and extension together, reload the extension, reconnect in the
+Side Panel, and run Step 2 again for each agent. The extension creates a new
+`dev_v2_` device ID; tokens paired to older IDs do not control the new connection.
+The relay now binds `127.0.0.1` explicitly. A remote deployment must opt in with
+`HOST` and use TLS (`wss://` / `https://`) to protect credentials in transit.
 
 ## How it connects (3 roles)
 
@@ -52,39 +60,42 @@ BABTAB_TOKEN_FILE=~/.babtab/relay-tokens.json npx @babtab/relay
 ### Step 3: Connect the extension to the relay
 
 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
+2. Step 1: confirm the port (default `3000`, must match the relay) — no URL typing needed
 3. Click **"Save & Connect"**
 
 This registers your Chrome as a device on the relay.
+(Remote relay on a VPS? Use *Advanced: custom Relay URL* in the same step.)
 
 ### Step 4: Connect your AI agent to the relay (Cursor as example)
 
-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):
-
-```json
-{
-  "mcpServers": {
-    "babtab": {
-      "url": "http://127.0.0.1:3000/mcp",
-      "headers": { "Authorization": "Bearer the-token-you-just-got" }
-    }
-  }
-}
+1. On the same Side Panel page, Step 2 → click **Cursor** → copy the one-line command:
+
+```bash
+npx -y @babtab/relay setup --target cursor --port 3000 --device <your-device-id>
 ```
 
-3. When the panel shows `Controlled by: cursor`, you're connected.
+2. Paste it into any terminal and run it. It shows a 6-digit pairing code —
+   approve it on the banner at the top of the Side Panel.
+3. Done: the command writes `babtab` into `~/.cursor/mcp.json` for you
+   (existing entries preserved, previous file kept as `.bak`). Reload MCP in
+   Cursor (Settings → MCP) and the panel shows `Controlled by: cursor`.
 
 One sentence to verify (ask your agent):
 
 > Use browser_observe to look at the tabs open in my Chrome, then tell me their titles and URLs.
 
+Supported `--target` values: `cursor`, `claude-code`, `windsurf`, `copilot`,
+`copilot-insiders`, `codex`, `pi`, `claude-desktop`, `antigravity`, `devin`,
+`kimi`, `hermes`, `manual`. Run `npx -y @babtab/relay setup --help` for all
+commands (`--list-targets` prints one ready line per harness). No terminal at
+hand? Step 2 also offers *Pair & copy JSON manually* as a fallback.
+
 ## FAQ
 
-- **"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.
+- **"Save & Connect" does nothing?** Check the relay terminal for `listening` first, then confirm the Step 1 port matches the relay's port.
+- **Pairing code expired?** Codes are short-lived — just re-run the setup command.
+- **Want a new token?** Re-running the setup command issues a new token and rewrites the config (old `.bak` kept).
+- **Agent and Chrome on different machines?** (Advanced) Put the relay on a VPS, use *Advanced: custom Relay URL* in Side Panel Step 1 with your `wss://…`, and pass `--relay-url https://…` to the setup command. The flow stays the same.
 
 ## Privacy
 

package/README.pt-BR.md

@@ -7,7 +7,11 @@
 
 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.
+
+## 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 +56,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 --port 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 +90,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
 

package/README.zh-TW.md

@@ -7,7 +7,14 @@
 
 Babtab Chrome 擴充功能的**本機中轉伺服器**：把你的 AI Agent（Cursor / Pi / Claude Code / …）接到你真正的 Chrome 上。
 
-MV3 擴充功能自己不能 listen port，所以需要這支小程式當橋樑。跑在 `localhost`，流量不出你的電腦；Relay 只負責轉發，**看不到你的頁面內容**。
+MV3 擴充功能自己不能 listen port，所以需要這支小程式當橋樑。跑在 `localhost`，流量不出你的電腦；Relay 會在記憶體中轉發請求與結果（包含頁面觀察及截圖），不會儲存頁面內容。
+
+## 升級裝置驗證
+
+請一起更新 Relay 與擴充功能，重新載入擴充功能、在 Side Panel 重新連線，
+再為每個 Agent 執行一次步驟 2 配對。擴充功能會產生新的 `dev_v2_` 裝置 ID；
+舊 ID 的 token 無法控制新連線。Relay 現在明確只監聽 `127.0.0.1`；
+遠端部署需自行設定 `HOST`，並使用 TLS（`wss://`／`https://`）保護傳輸憑證。
 
 ## 連線方式（3 個角色）
 
@@ -52,39 +59,41 @@ 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：確認 port（預設 `3000`，要跟 Relay 一致）即可，不用手打 URL
 3. 按 **"Save & Connect"**
 
 這一步是把你的 Chrome 註冊成 Relay 上的一台 device。
+（Relay 在遠端 VPS？同一步有 *Advanced: custom Relay URL* 可填。）
 
 ### 步驟 4：AI Agent 連上 Relay（以 Cursor 為例）
 
-1. 在 Side Panel 同一頁選你的 Agent → 按 **"Copy config"**
-2. 貼到 `~/.cursor/mcp.json` 的 `mcpServers`（只想給單一專案用，就放該專案的 `.cursor/mcp.json`）：
-
-```json
-{
-  "mcpServers": {
-    "babtab": {
-      "url": "http://127.0.0.1:3000/mcp",
-      "headers": { "Authorization": "Bearer 剛拿到的token" }
-    }
-  }
-}
+1. 在 Side Panel 同一頁，步驟 2 → 按 **Cursor** → 複製那行指令：
+
+```bash
+npx -y @babtab/relay setup --target cursor --port 3000 --device <你的deviceId>
 ```
 
-3. Panel 出現 `Controlled by: cursor` 就通了。
+2. 貼到任意終端機執行，會顯示 6 位配對碼 → 回到 Side Panel 在頂部橫條按 **Approve**。
+3. 完成：指令會自動把 `babtab` 寫進 `~/.cursor/mcp.json`
+  （原有內容保留，舊檔留一份 `.bak`）。去 Cursor 重載 MCP（Settings → MCP），
+   Panel 出現 `Controlled by: cursor` 就通了。
 
 驗證一句話（在 Agent 裡下）：
 
 > 用 browser_observe 看我現在 Chrome 開的分頁，然後告訴我標題和網址
 
+支援的 `--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 的現成指令）。沒終端機的環境，
+步驟 2 也有 *Pair & copy JSON manually* 可退回手動貼上。
+
 ## 常見問題
 
-- **按 "Save & Connect"沒反應？** 先看 Relay 終端機有沒有 `listening`，再確認 URL 是 `ws://127.0.0.1:3000` 且 port 跟 Relay 一致。
-- **配對碼過期？** 配對碼只有短暫有效，超時就重新按一次 "Copy config"。
-- **想換 token？** 重跑一次步驟 4 會產生新 token，記得同步更新 `mcp.json`。
-- **Agent 跟 Chrome 不在同一台電腦？**（進階）把 Relay 放到 VPS 上，Side Panel 的 Relay URL 改成你的 `wss://…` 即可，流程不變。
+- **按 "Save & Connect"沒反應？** 先看 Relay 終端機有沒有 `listening`，再確認步驟 1 的 port 跟 Relay 一致。
+- **配對碼過期？** 配對碼只有短暫有效，超時就重跑一次 setup 指令。
+- **想換 token？** 重跑一次 setup 指令會產生新 token 並重寫設定（舊檔留 `.bak`）。
+- **Agent 跟 Chrome 不在同一台電腦？**（進階）把 Relay 放到 VPS 上，Side Panel 步驟 1 用 *Advanced: custom Relay URL* 填 `wss://…`，setup 指令加 `--relay-url https://…` 即可，流程不變。
 
 ## 隱私說明