iframer-toolkit 0.10.6 → 0.11.0

package/dist/mcp-server.cjs

@@ -112,8 +112,8 @@ function isPidAlive(pid) {
   try {
     process.kill(pid, 0);
     return true;
-  } catch {
-    return false;
+  } catch (e) {
+    return e.code === "EPERM";
   }
 }
 function readServerInfo() {
@@ -208,7 +208,6 @@ var LocalServerManager = class {
       const env = {
         ...process.env,
         PORT: String(port),
-        IFRAMER_MODE: "local",
         IFRAMER_DATA_DIR: dataDir
       };
       if (process.env.IFRAMER_SECRET) {
@@ -223,8 +222,12 @@ var LocalServerManager = class {
       const child = (0, import_child_process.spawn)(command, args, {
         env,
         stdio: ["ignore", logFd, logFd],
-        detached: true
+        detached: true,
+        // On Windows a detached child otherwise gets its own console window,
+        // and closing that window kills the server.
+        windowsHide: true
       });
+      child.on("error", (e) => console.error(`[iframer] could not start the local server: ${e.message}`));
       child.unref();
       import_fs3.default.closeSync(logFd);
       const deadline = Date.now() + STARTUP_TIMEOUT_MS;
@@ -374,9 +377,7 @@ function getErrorMessage(err2) {
 
 // src/mcp/helpers.ts
 var log2 = createLogger("mcp");
-var BASE_URL = process.env.IFRAMER_URL || "http://localhost:3021";
 var IFRAMER_SECRET = process.env.IFRAMER_SECRET;
-var IFRAMER_MODE = process.env.IFRAMER_MODE;
 var LOCAL_TOKEN = getLocalToken();
 var localServer = new LocalServerManager();
 async function ensureLocalServer() {
@@ -388,19 +389,6 @@ function authHeaders(secret) {
   if (key) headers["x-api-key"] = key;
   return headers;
 }
-async function apiPost(endpoint, body) {
-  const res = await fetch(`${BASE_URL}${endpoint}`, {
-    method: "POST",
-    headers: authHeaders(),
-    body: body ? JSON.stringify(body) : void 0,
-    signal: AbortSignal.timeout(18e4)
-  });
-  return res.json();
-}
-async function apiGet(endpoint) {
-  const res = await fetch(`${BASE_URL}${endpoint}`, { headers: authHeaders(), signal: AbortSignal.timeout(3e4) });
-  return res.json();
-}
 async function localApiPost(endpoint, body, timeoutMs = 18e4) {
   await ensureLocalServer();
   const url = localServer.getBaseUrl();
@@ -424,15 +412,6 @@ async function localApiDelete(endpoint) {
   const res = await fetch(`${url}${endpoint}`, { method: "DELETE", headers: authHeaders(LOCAL_TOKEN), signal: AbortSignal.timeout(3e4) });
   return res.json();
 }
-async function isDockerRunning() {
-  try {
-    const res = await fetch(`${BASE_URL}/health`, { signal: AbortSignal.timeout(3e3) });
-    const data = await res.json();
-    return data.ok === true;
-  } catch {
-    return false;
-  }
-}
 async function resolveScreenshotPath(url) {
   try {
     if (url.startsWith("file://")) {
@@ -448,7 +427,7 @@ async function resolveScreenshotPath(url) {
     const fs10 = await import("fs");
     const dir = import_path5.default.join(import_os3.default.tmpdir(), "iframer-screenshots", "screenshots");
     fs10.mkdirSync(dir, { recursive: true });
-    const filePath = import_path5.default.join(dir, `docker-${Date.now()}.jpg`);
+    const filePath = import_path5.default.join(dir, `screenshot-${Date.now()}.jpg`);
     fs10.writeFileSync(filePath, buf);
     return filePath;
   } catch {
@@ -467,7 +446,7 @@ function defaultFile() {
   return import_path6.default.join(getDataDir(), "domain-modes.json");
 }
 var TTL_DAYS = 14;
-var ESCALATION_LADDER = ["headless", "docker-headful", "binary-headful"];
+var ESCALATION_LADDER = ["headless", "binary-headful"];
 var DomainModeStore = class {
   data = {};
   filePath;
@@ -572,8 +551,6 @@ function registerStatusTool(server2) {
     async () => {
       try {
         const status = {};
-        const dockerRunning = await isDockerRunning();
-        status.dockerApi = dockerRunning;
         try {
           const localHealth = await localApiGet("/health");
           status.localServer = localHealth.ok;
@@ -591,13 +568,6 @@ function registerStatusTool(server2) {
           if (inst.instances && inst.instances.length) status.liveInstances = inst.instances;
         } catch {
         }
-        if (dockerRunning) {
-          try {
-            const sessionData = await apiGet("/interactive/status");
-            status.dockerSession = sessionData.active ? { active: true, noVncUrl: sessionData.noVncUrl } : { active: false };
-          } catch {
-          }
-        }
         try {
           const credData = await localApiGet("/credentials");
           status.credentials = credData.domains || [];
@@ -659,18 +629,18 @@ var import_zod3 = require("zod");
 var import_zod2 = require("zod");
 var stepSchema = import_zod2.z.discriminatedUnion("type", [
   import_zod2.z.object({ type: import_zod2.z.literal("navigate"), url: import_zod2.z.string(), waitUntil: import_zod2.z.string().optional() }),
-  import_zod2.z.object({ type: import_zod2.z.literal("click"), selector: import_zod2.z.string() }),
-  import_zod2.z.object({ type: import_zod2.z.literal("fill"), selector: import_zod2.z.string(), value: import_zod2.z.string().describe("Sets an input/textarea's value. Framework-aware: fires the React-safe native setter + input/change/blur, so controlled forms (React, react-hook-form, Formik, Vue) register the value AND mark the field touched. This is the fix for 'I filled the field but submit says it's still empty' \u2014 always use fill for form fields, not evaluate.") }),
+  import_zod2.z.object({ type: import_zod2.z.literal("click"), selector: import_zod2.z.string().describe("An @e ref from snapshot/find, an @a: anchor, or plain CSS. Text selectors (text=, :has-text(), :text-is()) are rejected: use a find step for text, then click its @e ref.") }),
+  import_zod2.z.object({ type: import_zod2.z.literal("fill"), selector: import_zod2.z.string(), value: import_zod2.z.string().describe("Sets an input/textarea's value. Framework-aware: fires the React-safe native setter + input/change/blur, so controlled forms (React, react-hook-form, Formik, Vue) register the value AND mark the field touched. This is the fix for 'I filled the field but submit says it's still empty' \u2014 always use fill for form fields, not evaluate."), force: import_zod2.z.boolean().optional().describe("Bypass the honeypot guard. fill refuses fields no human can reach (offscreen/clipped/transparent) \u2014 only set this when you are certain the field is real.") }),
   import_zod2.z.object({ type: import_zod2.z.literal("human-click"), selector: import_zod2.z.string().optional(), x: import_zod2.z.number().optional(), y: import_zod2.z.number().optional() }),
   import_zod2.z.object({ type: import_zod2.z.literal("right-click"), selector: import_zod2.z.string().optional(), x: import_zod2.z.number().optional(), y: import_zod2.z.number().optional() }),
-  import_zod2.z.object({ type: import_zod2.z.literal("human-type"), selector: import_zod2.z.string(), value: import_zod2.z.string(), skipClick: import_zod2.z.boolean().optional().describe("Skip the click-to-focus and type into the already-focused element. Use for editors that blur on a synthetic click (e.g. Draft.js). Either way, typing aborts safely if the target isn't actually focused."), speed: import_zod2.z.enum(["slow", "normal", "fast"]).optional().describe("Typing speed. 'normal' (~130ms/char, realistic, default), 'fast' (~45ms/char) for long non-sensitive text, 'slow' for extra realism.") }),
+  import_zod2.z.object({ type: import_zod2.z.literal("human-type"), selector: import_zod2.z.string(), value: import_zod2.z.string(), skipClick: import_zod2.z.boolean().optional().describe("Skip the click-to-focus and type into the already-focused element. Use for editors that blur on a synthetic click (e.g. Draft.js). Either way, typing aborts safely if the target isn't actually focused."), speed: import_zod2.z.enum(["slow", "normal", "fast"]).optional().describe("Typing speed. 'normal' (~130ms/char, realistic, default), 'fast' (~45ms/char) for long non-sensitive text, 'slow' for extra realism."), clear: import_zod2.z.boolean().optional().describe("Replace the field's existing text instead of appending to it.") }),
   import_zod2.z.object({ type: import_zod2.z.literal("evaluate"), expression: import_zod2.z.string() }),
   import_zod2.z.object({ type: import_zod2.z.literal("extract"), expression: import_zod2.z.string() }),
   import_zod2.z.object({ type: import_zod2.z.literal("wait"), ms: import_zod2.z.number() }),
   import_zod2.z.object({ type: import_zod2.z.literal("wait-for"), selector: import_zod2.z.string(), timeout: import_zod2.z.number().optional() }),
   import_zod2.z.object({ type: import_zod2.z.literal("scroll"), deltaY: import_zod2.z.number().optional(), selector: import_zod2.z.string().optional().describe("Scroll within this element instead of the window"), human: import_zod2.z.boolean().optional().describe("Real eased wheel events instead of an instant jump (slower, less bot-obvious)") }),
   import_zod2.z.object({ type: import_zod2.z.literal("select"), selector: import_zod2.z.string(), value: import_zod2.z.string().describe("Option value to pick in a <select> \u2014 native selection, real change events (never set .value via evaluate)") }),
-  import_zod2.z.object({ type: import_zod2.z.literal("keyboard"), key: import_zod2.z.string(), meta: import_zod2.z.boolean().optional(), ctrl: import_zod2.z.boolean().optional(), shift: import_zod2.z.boolean().optional(), alt: import_zod2.z.boolean().optional() }),
+  import_zod2.z.object({ type: import_zod2.z.literal("keyboard"), key: import_zod2.z.string(), meta: import_zod2.z.boolean().optional().describe("Cmd/Ctrl+A selects all in every mode. Other Cmd/Ctrl shortcuts are rejected in extension mode (the relay drops them)."), ctrl: import_zod2.z.boolean().optional(), shift: import_zod2.z.boolean().optional(), alt: import_zod2.z.boolean().optional() }),
   import_zod2.z.object({ type: import_zod2.z.literal("read"), selector: import_zod2.z.string().optional().describe("Element to read text from (CSS or @e ref); omit for the whole body"), maxChars: import_zod2.z.number().optional().describe("Cap returned text length (default 6000)") }),
   import_zod2.z.object({ type: import_zod2.z.literal("upload"), selector: import_zod2.z.string().describe("The <input type=file> (CSS, @e ref, or @a anchor)"), files: import_zod2.z.array(import_zod2.z.string()).describe("Absolute local file path(s) on this machine") }),
   import_zod2.z.object({ type: import_zod2.z.literal("paste"), selector: import_zod2.z.string().optional().describe("Field to paste the OS clipboard into; omit for the focused element. Reliable via CDP insertText where a \u2318V keyboard step isn't.") }),
@@ -706,8 +676,8 @@ A captcha is blocking this run. Use the "recaptcha" step with an action:
   {type:"recaptcha", action:"click"}               \u2192 click the "I'm not a robot" checkbox
   {type:"recaptcha", action:"answer", tiles:[...]} \u2192 select tiles + verify + re-check (handles refreshing grids)
   {type:"recaptcha", action:"select"|"verify"}     \u2192 manual tile-select / submit, if you need finer control
-  {type:"recaptcha", action:"solve"}               \u2192 automatic vision solve (docker-headful)
-Or {type:"solve-captcha"} for one-shot auto-detect + solve.
+  {type:"recaptcha", action:"solve"}               \u2192 automatic vision solve (needs ANTHROPIC_API_KEY)
+Or {type:"solve-captcha"} for one-shot auto-detect + solve (needs ANTHROPIC_API_KEY).
 In binary-headful mode, prefer asking the user to solve it in the visible window.`;
 function captchaBlocked(data) {
   if (data.error?.errorType === "captcha-unsolvable") return true;
@@ -783,6 +753,13 @@ ${api.domain} (${api.baseUrl})`);
       }
     }
   }
+  const serverErrors = (data.results || []).flatMap((r) => r.serverErrors || []);
+  if (serverErrors.length > 0) {
+    lines.push("\n--- Server errors (HTTP >= 400) ---");
+    for (const se of serverErrors) {
+      lines.push(`  [step ${se.stepIndex}] ${se.method} ${se.url} \u2192 ${se.status}${se.body ? `: ${se.body}` : ""}`);
+    }
+  }
   if (data.error) {
     lines.push("\n--- Failure ---");
     if (typeof data.error === "string") {
@@ -793,6 +770,10 @@ ${api.domain} (${api.baseUrl})`);
       lines.push(`Message: ${data.error.message}`);
       lines.push(`Retryable: ${data.error.retryable}`);
       if (data.error.suggestion) lines.push(`Suggestion: ${data.error.suggestion}`);
+      const atFailure = serverErrors.filter((se) => se.stepIndex === data.error?.failedAtStep);
+      for (const se of atFailure) {
+        lines.push(`Server responded: ${se.method} ${se.url} \u2192 ${se.status}${se.body ? `: ${se.body}` : ""}`);
+      }
       if (data.error.pageState?.url) lines.push(`URL at failure: ${data.error.pageState.url}`);
     }
   }
@@ -828,8 +809,8 @@ Returns: ok, completedSteps, output for snapshot/find/read/extract steps, obstac
         screenshotAfterEach: import_zod3.z.boolean().optional().describe("Take a screenshot after every step (expensive)"),
         continueOnObstacle: import_zod3.z.boolean().optional().describe("Try to auto-resolve obstacles (default: true)"),
         continueOnError: import_zod3.z.boolean().optional().describe("Continue past failing steps (default: false)"),
-        captureApi: import_zod3.z.boolean().optional().describe("Record all API calls (XHR/fetch) the page makes."),
-        mode: import_zod3.z.enum(["headless", "binary-headful", "docker-headful", "extension"]).optional().describe("DO NOT SET unless the user explicitly requests a mode \u2014 iframer auto-selects and auto-escalates. 'extension' drives a real-Chrome tab (requires options.tabId from the `tabs` tool)."),
+        captureApi: import_zod3.z.boolean().optional().describe("Record all API calls (XHR/fetch) the page makes. Also surfaces every HTTP >= 400 response per step \u2014 turn it on when a form submit fails with only a vague on-page message, to read the server's real answer."),
+        mode: import_zod3.z.enum(["headless", "binary-headful", "extension"]).optional().describe("DO NOT SET unless the user explicitly requests a mode \u2014 iframer auto-selects and auto-escalates. 'extension' drives a real-Chrome tab (requires options.tabId from the `tabs` tool)."),
         autoEscalate: import_zod3.z.boolean().optional().describe("Auto-retry with a stronger mode if blocked (default: true)"),
         instanceId: import_zod3.z.string().optional().describe("Named parallel browser (default 'default') \u2014 distinct ids drive several browsers at once, each with its own session state."),
         tabId: import_zod3.z.number().optional().describe("mode='extension': the real-Chrome tab id to drive (from the `tabs` tool)."),
@@ -839,6 +820,13 @@ Returns: ok, completedSteps, output for snapshot/find/read/extract steps, obstac
     },
     async (params) => {
       try {
+        let runWithMode2 = function(mode) {
+          return localApiPost("/execute", {
+            steps,
+            options: { ...params.options, mode: mode || void 0 }
+          });
+        };
+        var runWithMode = runWithMode2;
         const steps = normalizeSteps(params.steps);
         if (params.options?.mode === "extension") {
           const tabId = params.options?.tabId;
@@ -862,43 +850,9 @@ Returns: ok, completedSteps, output for snapshot/find/read/extract steps, obstac
           if (!extResult.ok) return { content: content2, isError: true };
           return { content: content2 };
         }
-        const dockerRunning = await isDockerRunning();
-        async function runWithMode(mode) {
-          if (mode === "docker-headful") {
-            if (!dockerRunning) {
-              return {
-                ok: false,
-                completedSteps: 0,
-                totalSteps: steps.length,
-                results: [],
-                finalState: { url: "", title: "" },
-                obstacles: [],
-                durationMs: 0,
-                modeUsed: "docker-headful",
-                error: {
-                  failedAtStep: 0,
-                  failedStep: steps[0],
-                  errorType: "action-failed",
-                  message: "docker-headful mode was requested but the Docker API is not reachable.",
-                  pageState: { url: "", title: "" },
-                  suggestion: "Start Docker with `bun run start:docker`, or omit options.mode.",
-                  retryable: false
-                }
-              };
-            }
-            return apiPost("/execute", {
-              steps,
-              options: { ...params.options, mode: "docker-headful", autoEscalate: false }
-            });
-          }
-          return localApiPost("/execute", {
-            steps,
-            options: { ...params.options, mode: mode || void 0 }
-          });
-        }
         let execResult;
         try {
-          execResult = await runWithMode(params.options?.mode);
+          execResult = await runWithMode2(params.options?.mode);
         } catch (execErr) {
           const msg = execErr instanceof Error ? execErr.message : String(execErr);
           const isCrash = /ECONNREFUSED|ECONNRESET|EPIPE|socket hang up|fetch failed/i.test(msg);
@@ -909,7 +863,7 @@ Returns: ok, completedSteps, output for snapshot/find/read/extract steps, obstac
             } catch {
             }
             try {
-              execResult = await runWithMode(params.options?.mode);
+              execResult = await runWithMode2(params.options?.mode);
             } catch (retryErr) {
               return err(
                 `Browser server crashed and retry also failed.
@@ -925,14 +879,8 @@ Call \`session restart\` to reset, then retry.`
         }
         const requestedMode = params.options?.mode;
         if (!execResult.ok && execResult.error?.errorType === "bot-blocked" && params.options?.autoEscalate !== false && !requestedMode) {
-          const escalation = ["docker-headful", "binary-headful"];
-          for (const nextMode of escalation) {
-            if (nextMode === "docker-headful" && !dockerRunning) continue;
-            log2.info(`Auto-escalating to ${nextMode}`);
-            execResult = await runWithMode(nextMode);
-            if (execResult.ok) break;
-            if (execResult.error?.errorType !== "bot-blocked") break;
-          }
+          log2.info("Auto-escalating to binary-headful");
+          execResult = await runWithMode2("binary-headful");
         }
         const lines = formatExecuteResult(execResult);
         let screenshotUrl = null;
@@ -980,7 +928,7 @@ During capture, drive the site like a user (open the inbox, send a message\u2026
         staleTimeoutMs: import_zod4.z.number().optional().describe("Override the 20s stale-state timeout per step"),
         continueOnObstacle: import_zod4.z.boolean().optional().describe("Try to auto-resolve obstacles (default: true)"),
         continueOnError: import_zod4.z.boolean().optional().describe("Continue past failing steps (default: false)"),
-        mode: import_zod4.z.enum(["headless", "binary-headful", "docker-headful", "extension"]).optional().describe("Mode override. 'extension' captures a tab already open in the user's real Chrome (requires options.tabId from `tabs`)."),
+        mode: import_zod4.z.enum(["headless", "binary-headful", "extension"]).optional().describe("Mode override. 'extension' captures a tab already open in the user's real Chrome (requires options.tabId from `tabs`)."),
         tabId: import_zod4.z.number().optional().describe("mode='extension': the real-Chrome tab id (from `tabs`)."),
         clientId: import_zod4.z.string().optional().describe("mode='extension': owning profile's clientId when the tab is ambiguous.")
       }).optional()
@@ -993,7 +941,6 @@ During capture, drive the site like a user (open the inbox, send a message\u2026
           options: { ...params.options, captureApi: true }
         };
         const mode = params.options?.mode;
-        const dockerRunning = await isDockerRunning();
         let captureResult;
         if (mode === "extension") {
           if (typeof params.options?.tabId !== "number") {
@@ -1005,8 +952,6 @@ During capture, drive the site like a user (open the inbox, send a message\u2026
             steps,
             options: { ...params.options, captureApi: true }
           });
-        } else if (mode === "docker-headful" && dockerRunning) {
-          captureResult = await apiPost("/execute", execParams);
         } else {
           captureResult = await localApiPost("/execute", execParams);
         }
@@ -1203,6 +1148,23 @@ stop: save cookies/localStorage and close the browser \u2014 ALWAYS call when br
     },
     async ({ action, mode, urls, instanceId, outputDir }) => {
       try {
+        const SPAWNS_BROWSER = ["capture-start", "capture-stop", "get-cookies", "get-auth"];
+        let resolvedMode = mode;
+        if (SPAWNS_BROWSER.includes(action) && !mode) {
+          const live = await localApiGet("/instances").catch(() => ({ instances: [] }));
+          const match = (live.instances || []).find((i) => i.instanceId === (instanceId || "default"));
+          if (match) {
+            if (match.mode === "headless" || match.mode === "binary-headful") resolvedMode = match.mode;
+          } else {
+            const ext = await localApiGet("/extension/status").catch(() => ({ connected: false }));
+            if (ext.connected) {
+              return err(
+                `'${action}' would launch a new browser window, but the iframer extension is connected \u2014 you are probably driving a real Chrome tab. Read that tab instead: execute with options.mode="extension" and options.tabId (from the \`tabs\` tool). If you really want a separate browser, pass mode explicitly. Nothing was launched.`
+              );
+            }
+          }
+        }
+        mode = resolvedMode;
         if (action === "stop") {
           const result = await localApiPost("/interactive/stop").catch(() => ({ ok: true, sessionSaved: false }));
           return { content: [{ type: "text", text: `Session stopped. State saved: ${result.sessionSaved ?? false}` }] };
@@ -1225,13 +1187,6 @@ stop: save cookies/localStorage and close the browser \u2014 ALWAYS call when br
               parts.push(`Local restart failed: ${e instanceof Error ? e.message : String(e)}`);
             }
           }
-          try {
-            if (await isDockerRunning()) {
-              await apiPost("/browser/restart");
-              parts.push("Docker browser restarted.");
-            }
-          } catch {
-          }
           parts.push("Credentials and knowledge cache are untouched. Next execute launches a fresh browser.");
           return { content: [{ type: "text", text: parts.join(" ") }] };
         }
@@ -2063,18 +2018,7 @@ function safeJsonLen(v) {
 }
 
 // src/mcp/server.ts
-var IS_DEV = process.env.IFRAMER_URL?.includes("localhost") || process.env.IFRAMER_URL?.includes("127.0.0.1");
-var INSTRUCTIONS = IS_DEV ? `iframer-dev \u2014 local development instance of iframer (connects to ${BASE_URL}).
-
-CRITICAL RULES:
-1. NEVER ask the user "do you have credentials?". Call credentials action=list and read the response.
-2. NEVER ask the user for passwords in chat. Use credentials action=store (secure form) or the CLI fallback.
-3. DO NOT present options when you can just act. Check credentials, execute, show results.
-4. If execute fails, read the error. It tells you exactly what happened and where.
-5. Call "session" action=stop when done to save session state.
-
-CAPTCHA: Use the "solve-captcha" step \u2014 auto-detects reCAPTCHA/hCaptcha and solves with vision AI.
-REVERSE ENGINEERING: Use the "reverse-engineer" tool when the user asks to capture/map APIs.` : `iframer \u2014 browser access for AI agents when normal methods fail.
+var INSTRUCTIONS = `iframer \u2014 browser access for AI agents when normal methods fail.
 
 CRITICAL RULES:
 1. NEVER ask "do you have credentials?". Call credentials action=list and read the response.
@@ -2091,7 +2035,7 @@ If headless detects Imperva or Akamai, immediately stop headless and pivot to he
 
 BROWSER MODES: Don't specify options.mode \u2014 iframer auto-selects and auto-escalates (headless \u2192 binary-headful). Only set a mode if the user explicitly asks.
 
-CAPTCHA: In binary-headful mode, ask the user to solve it in the visible window. In docker-headful mode, use the "solve-captcha" step.
+CAPTCHA: In binary-headful mode, ask the user to solve it in the visible window. Otherwise try the "solve-captcha" step (best effort, needs ANTHROPIC_API_KEY).
 
 REVERSE ENGINEERING: Use the "reverse-engineer" tool when the user asks to capture/map/save API endpoints.`;
 var server = new import_mcp.McpServer(

package/extension/README.md

@@ -81,22 +81,24 @@ build` instead; `iframer update` detects that and says so.)
 ## Pair it (one time, zero copying)
 
 ```sh
-iframer install extension
+iframer install extension chrome
 ```
 
-then restart the browser. That installs a Chrome **native-messaging host**
+on macOS, Linux or Windows. That installs a Chrome **native-messaging host**
 (locked to this extension's pinned ID) that hands the extension the pairing
 token straight from `~/.iframer/secret` — every profile and every Chromium-family
 browser (Chrome, Brave, Edge, …) pairs itself, and re-pairs automatically after
-a reinstall or a rotated secret. No copying, ever.
+a reinstall or a rotated secret. No copying, ever. The command also tests the
+host and starts the local server, and tells you if either one fails.
 
 Manual fallback (host not installed): click the iframer toolbar icon → paste the
-token from `cat ~/.iframer/secret` → **Save & connect**.
+output of `iframer extension token` → **Save & connect**.
 
-Either way the dot turns green when it finds the running iframer server (it
-scans ports 3022–3042 on `127.0.0.1`; the server allocates its port from the
-same window). The token is the same machine-local secret the iframer CLI/MCP
-already use. It is only ever sent to `127.0.0.1`.
+Either way the dot turns green only once the running iframer server has accepted
+the token (the host locates the server; without a host the extension scans ports
+3022–3042 on `127.0.0.1`, the window the server allocates its port from). The
+token is the same machine-local secret the iframer CLI/MCP already use. It is
+only ever sent to `127.0.0.1`.
 
 ## Use it