cdp-toolkit 1.10.0 → 2.0.0

package/dist/cli.js

@@ -5396,6 +5396,252 @@ async function connectBidiSessionUrl(wsUrl, opts = {}) {
   return conn;
 }
 
+// src/bidi/session-lease.ts
+import { mkdir as mkdir12, readFile as readFile8, unlink as unlink5, writeFile as writeFile9 } from "node:fs/promises";
+import { join as join10 } from "node:path";
+var DEFAULT_SESSION_WAIT_MS = 1e4;
+var DEFAULT_POLL_MS = 250;
+function safeEndpoint(endpoint) {
+  return endpoint.replace(/[^A-Za-z0-9._-]/g, "_");
+}
+function sessionSlotFile(endpoint) {
+  return join10(leaseDir(), `ff-session-${safeEndpoint(endpoint)}.json`);
+}
+function sessionWaitMs() {
+  const raw = Number(process.env.CDP_FIREFOX_SESSION_WAIT_MS);
+  return Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_SESSION_WAIT_MS;
+}
+
+class SessionSlotBusyError extends Error {
+  endpoint;
+  holderPid;
+  holderLabel;
+  constructor(endpoint, holder) {
+    const who = holder ? `'${holder.label}' (pid ${holder.pid})` : "another live process";
+    super(`Firefox BiDi session slot for endpoint '${endpoint}' is held by ${who}. ` + `Firefox serves exactly ONE WebDriver-BiDi session per browser instance, and this slot is held ` + `by a LIVE process, so it cannot be taken. Wait for that process to release it and retry, or point ` + `this server at a different endpoint/browser.`);
+    this.name = "SessionSlotBusyError";
+    this.endpoint = endpoint;
+    if (holder) {
+      this.holderPid = holder.pid;
+      this.holderLabel = holder.label;
+    }
+  }
+}
+async function readSessionSlot(endpoint) {
+  let raw;
+  try {
+    raw = await readFile8(sessionSlotFile(endpoint), "utf8");
+  } catch (err) {
+    if (err.code === "ENOENT")
+      return;
+    throw err;
+  }
+  try {
+    const rec = JSON.parse(raw);
+    if (typeof rec?.pid === "number" && typeof rec?.endpoint === "string" && typeof rec?.label === "string") {
+      return rec;
+    }
+  } catch {}
+  return;
+}
+async function acquireSessionSlot(endpoint, opts) {
+  const waitMs = opts.waitMs ?? sessionWaitMs();
+  const pollMs = opts.pollMs !== undefined && opts.pollMs > 0 ? opts.pollMs : DEFAULT_POLL_MS;
+  const createdAt = opts.now ?? Date.now();
+  const file = sessionSlotFile(endpoint);
+  const record2 = {
+    endpoint,
+    pid: process.pid,
+    label: opts.label,
+    createdAt
+  };
+  if (opts.marionettePort !== undefined)
+    record2.marionettePort = opts.marionettePort;
+  const handle = { endpoint, pid: process.pid, createdAt };
+  const payload = JSON.stringify(record2);
+  await mkdir12(leaseDir(), { recursive: true });
+  const deadline = Date.now() + waitMs;
+  const maxAttempts = Math.max(100, Math.ceil(waitMs / pollMs) + 100);
+  let attempts = 0;
+  let lastLiveHolder;
+  while (true) {
+    if (attempts >= maxAttempts)
+      throw new SessionSlotBusyError(endpoint, lastLiveHolder);
+    attempts++;
+    try {
+      await writeFile9(file, payload, { flag: "wx" });
+      return { handle };
+    } catch (err) {
+      if (err.code !== "EEXIST")
+        throw err;
+    }
+    const holder = await readSessionSlot(endpoint);
+    if (!holder)
+      continue;
+    if (!isPidAlive(holder.pid)) {
+      await unlink5(file).catch(() => {
+        return;
+      });
+      try {
+        await writeFile9(file, payload, { flag: "wx" });
+        return { handle, staleHolder: holder };
+      } catch (err) {
+        if (err.code !== "EEXIST")
+          throw err;
+        continue;
+      }
+    }
+    lastLiveHolder = holder;
+    const remaining = deadline - Date.now();
+    if (remaining <= 0)
+      throw new SessionSlotBusyError(endpoint, holder);
+    await sleep2(Math.min(pollMs, remaining));
+  }
+}
+async function releaseSessionSlot(handle) {
+  const current = await readSessionSlot(handle.endpoint);
+  if (!current)
+    return { released: false };
+  if (current.pid !== process.pid || current.createdAt !== handle.createdAt)
+    return { released: false };
+  await unlink5(sessionSlotFile(handle.endpoint)).catch(() => {
+    return;
+  });
+  return { released: true };
+}
+function sleep2(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// src/bidi/marionette.ts
+import { Socket } from "node:net";
+var DEFAULT_MARIONETTE_PORT = 2828;
+var DEFAULT_TIMEOUT_MS3 = 4000;
+var HOST = "127.0.0.1";
+var COLON = 58;
+var DELETE_SESSION_FRAME = encodeFrame([0, 1, "WebDriver:DeleteSession", {}]);
+function defaultMarionettePort() {
+  const raw = Number(process.env.CDP_FIREFOX_MARIONETTE_PORT);
+  return Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_MARIONETTE_PORT;
+}
+function encodeFrame(json) {
+  const body = Buffer.from(JSON.stringify(json), "utf8");
+  const prefix = Buffer.from(`${body.length}:`, "ascii");
+  return Buffer.concat([prefix, body]);
+}
+
+class MarionetteProtocolError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "MarionetteProtocolError";
+  }
+}
+
+class FrameDecoder {
+  buf = Buffer.alloc(0);
+  push(chunk) {
+    this.buf = this.buf.length === 0 ? chunk : Buffer.concat([this.buf, chunk]);
+  }
+  next() {
+    const colon = this.buf.indexOf(COLON);
+    if (colon === -1) {
+      this.assertDigitsPrefix(this.buf.length);
+      return;
+    }
+    if (colon === 0)
+      throw new MarionetteProtocolError("empty frame length prefix");
+    this.assertDigitsPrefix(colon);
+    const len = Number.parseInt(this.buf.toString("ascii", 0, colon), 10);
+    const start = colon + 1;
+    const end = start + len;
+    if (this.buf.length < end)
+      return;
+    const payload = this.buf.toString("utf8", start, end);
+    this.buf = this.buf.subarray(end);
+    try {
+      return JSON.parse(payload);
+    } catch {
+      throw new MarionetteProtocolError(`frame body was not valid JSON (${len} bytes): ${payload.slice(0, 80)}`);
+    }
+  }
+  assertDigitsPrefix(upTo) {
+    for (let i = 0;i < upTo; i++) {
+      const b = this.buf[i];
+      if (b < 48 || b > 57) {
+        throw new MarionetteProtocolError(`non-digit byte 0x${b.toString(16)} in frame length prefix`);
+      }
+    }
+  }
+}
+function isSlotFreedReply(frame) {
+  if (!Array.isArray(frame))
+    return false;
+  const err = frame[2];
+  if (err === null)
+    return true;
+  if (typeof err === "object" && err !== null && err.error === "invalid session id") {
+    return true;
+  }
+  return false;
+}
+function forceClearOrphanSession(marionettePort, opts = {}) {
+  const timeoutMs = opts.timeoutMs !== undefined && Number.isFinite(opts.timeoutMs) && opts.timeoutMs > 0 ? opts.timeoutMs : DEFAULT_TIMEOUT_MS3;
+  return new Promise((resolve) => {
+    if (!Number.isFinite(marionettePort) || marionettePort <= 0 || marionettePort > 65535) {
+      resolve(false);
+      return;
+    }
+    const sock = new Socket;
+    const decoder = new FrameDecoder;
+    let settled = false;
+    let handshakeSeen = false;
+    let commandSent = false;
+    const settle = (value) => {
+      if (settled)
+        return;
+      settled = true;
+      clearTimeout(timer);
+      sock.removeAllListeners();
+      sock.destroy();
+      resolve(value);
+    };
+    const timer = setTimeout(() => settle(false), timeoutMs);
+    if (typeof timer.unref === "function")
+      timer.unref();
+    sock.on("error", () => settle(false));
+    sock.on("close", () => settle(false));
+    sock.on("data", (chunk) => {
+      if (settled)
+        return;
+      try {
+        decoder.push(chunk);
+        for (;; ) {
+          const frame = decoder.next();
+          if (frame === undefined)
+            break;
+          if (!handshakeSeen) {
+            handshakeSeen = true;
+            continue;
+          }
+          settle(isSlotFreedReply(frame));
+          return;
+        }
+        if (handshakeSeen && !commandSent) {
+          commandSent = true;
+          sock.write(DELETE_SESSION_FRAME);
+        }
+      } catch {
+        settle(false);
+      }
+    });
+    try {
+      sock.connect(marionettePort, HOST);
+    } catch {
+      settle(false);
+    }
+  });
+}
+
 // src/bidi/snapshot.ts
 var STAMP_ATTR = "data-cdp-uid";
 async function takeStampedSnapshot(evaluate) {
@@ -5774,6 +6020,9 @@ function mapBidiError(e) {
       return driverError2("timeout", e.message);
     if (!code && /(disposed|not open|connection closed)/i.test(e.message))
       return driverError2("disconnected", e.message);
+    if (/NS_ERROR_FILE_ACCESS_DENIED/i.test(e.message)) {
+      return driverError2("page-error", `${e.message} — the browser process was not allowed to open this file:// path. For a snap- or AppArmor-confined Firefox (Ubuntu default) that is kernel-level and no preference fixes it: serve the directory over a local http server (e.g. python3 -m http.server) and navigate to the http://127.0.0.1:<port>/ URL instead. If this Firefox was launched by cdp-toolkit and still fails, please report it at https://github.com/sblattj/cdp-toolkit/issues.`);
+    }
     return driverError2("page-error", e.message);
   }
   return driverError2("page-error", e instanceof Error ? e.message : String(e));
@@ -5972,6 +6221,22 @@ var BIDI_CAPABILITIES = new Set([
   "locate.xpath"
 ]);
 var connections = new Map;
+var slotHandles = new Map;
+var connecting = new Map;
+async function releaseSlotOnDialFailure(endpoint, owned) {
+  if (owned)
+    return;
+  const h = slotHandles.get(endpoint);
+  if (h) {
+    await releaseSessionSlot(h).catch(() => {
+      return;
+    });
+    slotHandles.delete(endpoint);
+  }
+}
+function orphanNotClearedError(endpoint) {
+  return driverError2("disconnected", `Firefox holds an orphaned WebDriver BiDi session on ${endpoint} that could not be auto-cleared. ` + `Marionette recovery needs Firefox launched with --marionette (default port 2828, or set ` + `CDP_FIREFOX_MARIONETTE_PORT); otherwise restart Firefox to free the slot. (A client killed without ` + `session.end can leave a session Firefox does not reap.)`);
+}
 async function getConnection(endpoint, timeoutMs) {
   const existing = connections.get(endpoint);
   if (existing && existing.isOpen) {
@@ -5980,17 +6245,68 @@ async function getConnection(endpoint, timeoutMs) {
   }
   if (existing)
     connections.delete(endpoint);
-  const conn = await connectBidiSessionUrl(endpoint, {
-    ...timeoutMs !== undefined ? { timeoutMs } : {},
-    capabilities: { alwaysMatch: { unhandledPromptBehavior: { default: "ignore" } } }
-  }).catch((e) => {
-    if (e instanceof BidiError && /maximum number of active sessions/i.test(e.message)) {
-      throw driverError2("disconnected", `Firefox already has an active WebDriver BiDi session on ${endpoint}; it allows only one. ` + `Close the other client, or restart Firefox, then retry. (A previously killed client can leave a ` + `session that Firefox does not reap.)`);
+  const inflight = connecting.get(endpoint);
+  if (inflight) {
+    const conn = await inflight;
+    conn.retain();
+    return conn;
+  }
+  const create = (async () => {
+    const mport = defaultMarionettePort();
+    const owned = slotHandles.has(endpoint);
+    if (!owned) {
+      let acq;
+      try {
+        acq = await acquireSessionSlot(endpoint, { label: defaultLabel(), marionettePort: mport });
+      } catch (e) {
+        if (e instanceof SessionSlotBusyError) {
+          const who = e.holderLabel ? `'${e.holderLabel}' (pid ${e.holderPid})` : "another live process";
+          throw driverError2("disconnected", `Firefox's single WebDriver BiDi session on ${endpoint} is held by a LIVE process ${who}. ` + `Firefox serves exactly ONE BiDi session per browser instance, so this server cannot take it ` + `while that process is running. Wait for it to release the session and retry, or point this ` + `server at a different endpoint/browser.`);
+        }
+        throw e;
+      }
+      slotHandles.set(endpoint, acq.handle);
+      if (acq.staleHolder) {
+        await forceClearOrphanSession(acq.staleHolder.marionettePort ?? mport);
+      }
     }
-    throw e;
-  });
-  connections.set(endpoint, conn);
-  return conn;
+    const dialOpts = {
+      ...timeoutMs !== undefined ? { timeoutMs } : {},
+      capabilities: { alwaysMatch: { unhandledPromptBehavior: { default: "ignore" } } }
+    };
+    let conn;
+    try {
+      conn = await connectBidiSessionUrl(endpoint, dialOpts);
+    } catch (e) {
+      if (e instanceof BidiError && /maximum number of active sessions/i.test(e.message)) {
+        const cleared = await forceClearOrphanSession(mport);
+        if (!cleared) {
+          await releaseSlotOnDialFailure(endpoint, owned);
+          throw orphanNotClearedError(endpoint);
+        }
+        try {
+          conn = await connectBidiSessionUrl(endpoint, dialOpts);
+        } catch (e2) {
+          await releaseSlotOnDialFailure(endpoint, owned);
+          if (e2 instanceof BidiError && /maximum number of active sessions/i.test(e2.message)) {
+            throw orphanNotClearedError(endpoint);
+          }
+          throw e2;
+        }
+      } else {
+        await releaseSlotOnDialFailure(endpoint, owned);
+        throw e;
+      }
+    }
+    connections.set(endpoint, conn);
+    return conn;
+  })();
+  connecting.set(endpoint, create);
+  try {
+    return await create;
+  } finally {
+    connecting.delete(endpoint);
+  }
 }
 var bidiBeaconScripts = new Map;
 async function safeTitle(conn, contextId) {
@@ -6103,7 +6419,10 @@ class BidiPageDriver {
     const sendOpts = opts.timeoutMs !== undefined ? { timeoutMs: opts.timeoutMs } : {};
     try {
       if (reload) {
-        const r2 = await this.conn.send("browsingContext.reload", { context: this.contextId, ignoreCache: opts.ignoreCache === true, wait }, sendOpts);
+        if (opts.ignoreCache === true) {
+          throw driverError2("unsupported", "navigate: ignoreCache:true (hard reload) is not supported on the Firefox WebDriver-BiDi backend — Firefox rejects the ignoreCache argument outright. A plain reload (reload:true, no ignoreCache) works.");
+        }
+        const r2 = await this.conn.send("browsingContext.reload", { context: this.contextId, wait }, sendOpts);
         return { url: r2.url, contextId: this.contextId, reloaded: true, waitedFor: waitUntil };
       }
       if (history) {
@@ -6756,14 +7075,27 @@ class BidiBrowserDriver {
       if (key.startsWith(`${this.endpoint}:`))
         bidiBeaconScripts.delete(key);
     }
+    connecting.delete(this.endpoint);
     const conn = connections.get(this.endpoint);
-    if (!conn)
+    if (!conn) {
+      await this.releaseSessionSlotIfHeld();
       return;
+    }
     connections.delete(this.endpoint);
     await conn.send("session.end", {}).catch(() => {
       return;
     });
     conn.dispose();
+    await this.releaseSessionSlotIfHeld();
+  }
+  async releaseSessionSlotIfHeld() {
+    const h = slotHandles.get(this.endpoint);
+    if (!h)
+      return;
+    await releaseSessionSlot(h).catch(() => {
+      return;
+    });
+    slotHandles.delete(this.endpoint);
   }
 }
 function createFirefoxDriver(port, opts) {
@@ -6775,10 +7107,10 @@ function createFirefoxDriverForEndpoint(wsUrl, opts) {
 
 // src/bidi/launch.ts
 import { spawn as spawn3 } from "node:child_process";
-import { existsSync, mkdtempSync, rmSync } from "node:fs";
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { createConnection, createServer } from "node:net";
 import { tmpdir } from "node:os";
-import { join as join10 } from "node:path";
+import { join as join11 } from "node:path";
 function resolveBinary() {
   const candidates = [
     process.env.FIREFOX_BIN,
@@ -6852,11 +7184,37 @@ function waitForExit(proc, deadlineMs) {
     });
   });
 }
+var LAUNCH_USER_JS_PREFS = {
+  "remote.prefs.recommended": true,
+  "security.fileuri.strict_origin_policy": false,
+  "dom.file.createInChild": true
+};
+function writeLaunchUserJs(profilePath) {
+  const target = join11(profilePath, "user.js");
+  const existing = existsSync(target) ? readFileSync(target, "utf8") : "";
+  const present = new Set;
+  for (const line of existing.split(`
+`)) {
+    const m = /^user_pref\("([^"]+)"\s*,/.exec(line.trim());
+    if (m)
+      present.add(m[1]);
+  }
+  const additions = Object.entries(LAUNCH_USER_JS_PREFS).filter(([k]) => !present.has(k)).map(([k, v]) => `user_pref("${k}", ${JSON.stringify(v)});`);
+  const content = (existing.length > 0 ? existing.replace(/\n*$/, `
+`) : "") + additions.join(`
+`) + (additions.length > 0 ? `
+` : "");
+  if (content !== existing)
+    writeFileSync(target, content, "utf-8");
+  return content;
+}
 async function launchFirefox(opts = {}) {
   const binary = resolveBinary();
   const port = await pickPort(opts.port);
   const isThrowaway = opts.profilePath === undefined;
-  const profilePath = opts.profilePath ?? mkdtempSync(join10(tmpdir(), "cdp-toolkit-ff-profile-"));
+  const profilePath = opts.profilePath ?? mkdtempSync(join11(tmpdir(), "cdp-toolkit-ff-profile-"));
+  if (isThrowaway)
+    writeLaunchUserJs(profilePath);
   const args = ["--profile", profilePath, "--remote-debugging-port", String(port), "--no-remote"];
   if (opts.headless)
     args.push("--headless");
@@ -7210,21 +7568,21 @@ var FIREFOX_TOOLS = {
 var MANIFEST = [
   {
     name: "list_pages",
-    description: "Enumerate browser page targets (GET /json/list); page-type tabs only unless all=true. Each entry carries its targetId plus an origin field: 'agent' means this toolkit created it (also carries the creating label/createdAt, and stays 'agent' after the lease is released or the creator dies, making stray agent tabs findable), 'unknown' means no creation record - it never says 'human', the honest word for any tab it did not create; a record that exists but won't read adds originUnreadable. An entry under an active, readable lease also carries a 'lease' object {label,pid,idleMs,expiresAt,stale}, with idleMs and expiresAt computed fresh every call (never off disk), independent of probe. Under CDP_REQUIRE_LEASE this call also reaps abandoned agent tabs into an additive reaped array - but a lease reads reclaimable the moment its TTL elapses, while the tab is CLOSED only after a further grace (CDP_REAP_GRACE_MS, default 2700000ms/45min, so 60min total after last use); a dead-pid lease is reaped at once, a tab with no lease never. With probe, each page-type entry also gets 'responsive' (and humanActiveMs where human input is seen); both are absent, never false/null, without probe.",
+    description: "List browser page targets; optionally include non-page targets and probe responsiveness.",
     inputSchema: {
       type: "object",
       properties: {
         lease: {
           type: "string",
-          description: "Lease token from claim_page. Omit for a tab this process holds; required for a tab held by another process or one claimed explicitly. Auto-acquired under CDP_REQUIRE_LEASE (then pass target, not lease). See server instructions."
+          description: "Lease token; omit for a tab this process already holds. See server instructions."
         },
         all: {
           type: "boolean",
-          description: "Include non-page targets (service/shared workers, background pages); default false lists page-type tabs only."
+          description: "Include non-page targets."
         },
         probe: {
           type: "boolean",
-          description: "Ping each page-type renderer before returning, one bounded 500ms check per target and never more, so a wedged tab can't stall the listing. Adds 'responsive' (false on timeout/exception/unreachable, never an error for the whole call) and, where the same round trip finds human input, humanActiveMs. Default false. On a backend that cannot answer the ping, responsive is absent too (not false)."
+          description: "Probe renderer responsiveness."
         }
       },
       required: [],
@@ -7233,29 +7591,29 @@ var MANIFEST = [
   },
   {
     name: "new_page",
-    description: "Open a new browser tab via Target.createTarget and return {targetId,url}. Defaults to about:blank; navigation is not awaited here (use navigate_page to load and wait).",
+    description: "Open a browser tab, optionally claim it; navigation is not awaited.",
     inputSchema: {
       type: "object",
       properties: {
         lease: {
           type: "string",
-          description: "Lease token from claim_page. Omit for a tab this process holds; required for a tab held by another process or one claimed explicitly. Auto-acquired under CDP_REQUIRE_LEASE (then pass target, not lease). See server instructions."
+          description: "Lease token; omit for a tab this process already holds. See server instructions."
         },
         url: {
           type: "string",
-          description: "URL to open in the new tab; defaults to about:blank."
+          description: "URL value."
         },
         claim: {
           type: "boolean",
-          description: "Claim the new tab atomically and return a lease token alongside {targetId,url}. Under CDP_REQUIRE_LEASE the tab is claimed and a lease returned even without claim:true; claim:true makes it an EXPLICIT lease that demands its token on every later call, even from this process. Default false."
+          description: "Claim the new tab."
         },
         label: {
           type: "string",
-          description: "Agent label recorded on the lease when the tab is claimed; surfaced in conflict errors and list_leases. Defaults to pid-<pid>."
+          description: "Agent lease label."
         },
         ttlMs: {
           type: "number",
-          description: "How long a claimed lease survives without use before it is reclaimable. Defaults to CDP_LEASE_TTL_MS, else 900000 (15min); every checked call refreshes it. Ignored when not claiming."
+          description: "Lease TTL in milliseconds."
         }
       },
       required: [],
@@ -7264,17 +7622,17 @@ var MANIFEST = [
   },
   {
     name: "close_page",
-    description: "Close a page target via Target.closeTarget. Requires an explicit, resolvable target; errors rather than guessing when the selector matches nothing.",
+    description: "Close a selected page; target must resolve explicitly.",
     inputSchema: {
       type: "object",
       properties: {
         lease: {
           type: "string",
-          description: "Lease token from claim_page. Omit for a tab this process holds; required for a tab held by another process or one claimed explicitly. Auto-acquired under CDP_REQUIRE_LEASE (then pass target, not lease). See server instructions."
+          description: "Lease token; omit for a tab this process already holds. See server instructions."
         },
         target: {
           type: "string",
-          description: "Page selector: 'active' (default), 'index:N', 'url:<substr>', 'title:<substr>', 'label:<name>', or a 32-hex '<targetId>'. Grammar: see server instructions."
+          description: "Page selector (index:/url:/title:/label:/targetId, default active); grammar in server instructions."
         }
       },
       required: [
@@ -7285,17 +7643,17 @@ var MANIFEST = [
   },
   {
     name: "select_page",
-    description: "Activate/focus a page target via Target.activateTarget and persist its bare targetId to the selected-state file (CDP_STATE_DIR/selected). Requires an explicit, resolvable target.",
+    description: "Focus a selected page and persist it as active; target must resolve explicitly.",
     inputSchema: {
       type: "object",
       properties: {
         lease: {
           type: "string",
-          description: "Lease token from claim_page. Omit for a tab this process holds; required for a tab held by another process or one claimed explicitly. Auto-acquired under CDP_REQUIRE_LEASE (then pass target, not lease). See server instructions."
+          description: "Lease token; omit for a tab this process already holds. See server instructions."
         },
         target: {
           type: "string",
-          description: "Page selector: 'active' (default), 'index:N', 'url:<substr>', 'title:<substr>', 'label:<name>', or a 32-hex '<targetId>'. Grammar: see server instructions."
+          description: "Page selector (index:/url:/title:/label:/targetId, default active); grammar in server instructions."
         }
       },
       required: [
@@ -7306,25 +7664,25 @@ var MANIFEST = [
   },
   {
     name: "navigate_page",
-    description: "Navigate a target page to a URL (Page.navigate), reload it (reload:true), OR go back/forward in its session history (history:'back'|'forward'), then wait for the load milestone with a bounded timeout so a wedged renderer can't hang. Exactly one of url / reload / history per call. Returns {url,frameId,waitedFor} (plus reloaded:true on a reload, traversed:'back'|'forward' on a history move); waitUntil supports 'load'|'domcontentloaded' only (no 'networkidle'), and there is no auto-snapshot of the new page. Pass reload:true with ignoreCache:true for a hard reload that refetches every subresource (e.g. to pick up a freshly-deployed, non-content-hashed bundle the HTTP cache would serve stale).",
+    description: "Navigate, reload, or traverse page history; choose exactly one operation.",
     inputSchema: {
       type: "object",
       properties: {
         lease: {
           type: "string",
-          description: "Lease token from claim_page. Omit for a tab this process holds; required for a tab held by another process or one claimed explicitly. Auto-acquired under CDP_REQUIRE_LEASE (then pass target, not lease). See server instructions."
+          description: "Lease token; omit for a tab this process already holds. See server instructions."
         },
         target: {
           type: "string",
-          description: "Page selector: 'active' (default), 'index:N', 'url:<substr>', 'title:<substr>', 'label:<name>', or a 32-hex '<targetId>'. Grammar: see server instructions."
+          description: "Page selector (index:/url:/title:/label:/targetId, default active); grammar in server instructions."
         },
         url: {
           type: "string",
-          description: "Destination URL to navigate to. Required unless reload:true."
+          description: "URL value."
         },
         reload: {
           type: "boolean",
-          description: "Reload the current page (Page.reload) instead of navigating to url. Default false."
+          description: "Reload before capture."
         },
         history: {
           type: "string",
@@ -7332,11 +7690,11 @@ var MANIFEST = [
             "back",
             "forward"
           ],
-          description: "Traverse this tab's session history instead of loading a url: 'back' and 'forward' are the browser's Back and Forward buttons. Mutually exclusive with 'url' and 'reload' — passing two of the three is refused by name, not resolved by precedence. Works on BOTH backends and waits for the same load milestone as an ordinary navigation. Going back from the first entry, or forward from the last, is an ERROR naming the direction — never a silent no-op. The result carries traversed:'back'|'forward' alongside the resulting url."
+          description: "History direction."
         },
         ignoreCache: {
           type: "boolean",
-          description: "On reload, bypass the HTTP cache (hard reload) so subresources are refetched. Ignored unless reload:true. Default false."
+          description: "Bypass cache on reload."
         },
         waitUntil: {
           type: "string",
@@ -7344,11 +7702,11 @@ var MANIFEST = [
             "load",
             "domcontentloaded"
           ],
-          description: "Which load milestone to wait for. Defaults to 'load'. No 'networkidle' support."
+          description: "Load milestone."
         },
         timeoutMs: {
           type: "number",
-          description: "Override the navigation timeout in milliseconds."
+          description: "Timeout in milliseconds."
         }
       },
       additionalProperties: false
@@ -7356,29 +7714,29 @@ var MANIFEST = [
   },
   {
     name: "wait_for",
-    description: "Poll the target until the substring appears in document.body.innerText (Runtime.evaluate on a fixed interval), or throw on timeout. Text-substring only -- no aria/role/selector or event variants; throws rather than returning {found:false}.",
+    description: "Wait for a text substring in document.body.innerText; timeout throws.",
     inputSchema: {
       type: "object",
       properties: {
         lease: {
           type: "string",
-          description: "Lease token from claim_page. Omit for a tab this process holds; required for a tab held by another process or one claimed explicitly. Auto-acquired under CDP_REQUIRE_LEASE (then pass target, not lease). See server instructions."
+          description: "Lease token; omit for a tab this process already holds. See server instructions."
         },
         target: {
           type: "string",
-          description: "Page selector: 'active' (default), 'index:N', 'url:<substr>', 'title:<substr>', 'label:<name>', or a 32-hex '<targetId>'. Grammar: see server instructions."
+          description: "Page selector (index:/url:/title:/label:/targetId, default active); grammar in server instructions."
         },
         text: {
           type: "string",
-          description: "Substring to wait for in document.body.innerText. Required."
+          description: "Text substring."
         },
         timeoutMs: {
           type: "number",
-          description: "Total time budget in ms. Default 15000."
+          description: "Timeout in milliseconds."
         },
         pollMs: {
           type: "number",
-          description: "Poll interval in ms. Default 250."
+          description: "Polling interval in milliseconds."
         }
       },
       required: [
@@ -7389,37 +7747,37 @@ var MANIFEST = [
   },
   {
     name: "evaluate_script",
-    description: "Run arbitrary JavaScript in the target's main-world context over raw CDP and return the evaluated value (returnByValue). With no 'args', 'expression' is a raw expression; with 'args' it must be a function literal (arrow or classic) invoked on globalThis with args passed positionally. A thrown exception surfaces as an error; non-serializable returns (DOM nodes, functions) come back as their CDP description string. savePath writes the value to a JSON file instead -- the response then carries only {path,bytes,type,target} and the value never appears in it, the way to read a credential (a JWT/session token from localStorage) without putting the secret in the transcript. This is the one tool that EVALUATES inside an MV3 extension's background SERVICE WORKER rather than OBSERVING it (Chrome, Capability 'worker.targets'): a worker: target reads chrome.storage.local, chrome.runtime and the worker's own globals directly, with an idle-evicted worker started first (see 'wake').",
+    description: "Evaluate JavaScript in a page or Chrome worker; args require a function literal.",
     inputSchema: {
       type: "object",
       properties: {
         lease: {
           type: "string",
-          description: "Lease token from claim_page. Omit for a tab this process holds; required for a tab held by another process or one claimed explicitly. Auto-acquired under CDP_REQUIRE_LEASE (then pass target, not lease). See server instructions."
+          description: "Lease token; omit for a tab this process already holds. See server instructions."
         },
         target: {
           type: "string",
-          description: "Page selector: 'active' (default), 'index:N', 'url:<substr>', 'title:<substr>', 'label:<name>', '<targetId>'; plus 'worker:<substring>' to reach a service/shared worker (e.g. an MV3 extension background worker). The worker: arm is CHROME-ONLY (Capability 'worker.targets'). Grammar: see server instructions."
+          description: "Page selector (index:/url:/title:/label:/targetId, default active); grammar in server instructions."
         },
         wake: {
           type: "boolean",
-          description: "Worker targets only, when starting a capture. Default true: an idle-evicted MV3 service worker exists in no target listing, so it is started first (ServiceWorker.startWorker) and re-confirmed; false fails fast. Rejected on a page target, a bare target id, or a read-only call. See server instructions."
+          description: "Wake worker before capture."
         },
         expression: {
           type: "string",
-          description: "JavaScript to run. Evaluated as an expression when 'args' is omitted; must be a function literal (arrow or classic) whose parameters receive 'args' when provided. REQUIRED -- the code always goes in this key, never in 'function', 'code', 'js', 'script', 'fn' or 'body'; a call using one of those is rejected with an error naming the wrong key."
+          description: "JavaScript expression or function."
         },
         awaitPromise: {
           type: "boolean",
-          description: "Await the result if it is a Promise. Default true."
+          description: "Await Promise results."
         },
         args: {
           type: "array",
-          description: "Positional JSON-serializable arguments passed to the expression (treated as a function). No live element/page handle is bound."
+          description: "Positional JSON arguments."
         },
         savePath: {
           type: "string",
-          description: "Write the evaluated value to this file as JSON and KEEP IT OUT OF THE RESPONSE: the result is {path,bytes,type,target} only, with no copy, preview or truncation of the value -- read credentials without putting them in a transcript. An absolute path (starting with /) is used as-is; a relative path resolves under the artifact dir (/tmp/cdp-toolkit); missing parents are created. Omit to get the value back inline."
+          description: "Output file path."
         }
       },
       required: [
@@ -7430,29 +7788,29 @@ var MANIFEST = [
   },
   {
     name: "list_cookies",
-    description: "Read the target page's cookie store INCLUDING httpOnly cookies, which document.cookie (and therefore evaluate_script) cannot see. Page-scoped, not browser-wide: returns cookies of the resolved tab, so point at a page on the site you want. Each cookie carries name, value, domain, path, expires (Unix seconds, -1 for a session cookie), size, httpOnly, secure, sameSite ('strict'|'lax'|'none'|'default'), session. Filter with 'domain' and/or 'name'. Pass 'savePath' to write the array to a JSON file instead: the response is then {path,bytes,count,target} with no cookie value in any form, the way to capture a session cookie without putting the credential in the transcript.",
+    description: "Read cookies for a selected page, including httpOnly values; savePath keeps values out of the response.",
     inputSchema: {
       type: "object",
       properties: {
         lease: {
           type: "string",
-          description: "Lease token from claim_page. Omit for a tab this process holds; required for a tab held by another process or one claimed explicitly. Auto-acquired under CDP_REQUIRE_LEASE (then pass target, not lease). See server instructions."
+          description: "Lease token; omit for a tab this process already holds. See server instructions."
         },
         target: {
           type: "string",
-          description: "Page selector: 'active' (default), 'index:N', 'url:<substr>', 'title:<substr>', 'label:<name>', or a 32-hex '<targetId>'. Grammar: see server instructions."
+          description: "Page selector (index:/url:/title:/label:/targetId, default active); grammar in server instructions."
         },
         domain: {
           type: "string",
-          description: "Keep only cookies for this domain. A leading dot is ignored on both sides and subdomains match too, so 'example.test' matches '.example.test' and 'app.example.test'. No wildcards."
+          description: "Cookie domain."
         },
         name: {
           type: "string",
-          description: "Keep only the cookie with exactly this name. Exact match, not a substring."
+          description: "Cookie name."
         },
         savePath: {
           type: "string",
-          description: "Write the cookie array here as JSON and KEEP THE VALUES OUT OF THE RESPONSE: the result is {path,bytes,count,target} only, with no preview or truncation of any value. An absolute path (starting with /) is used as-is; a relative path resolves under the artifact dir (/tmp/cdp-toolkit); missing parents are created. Omit to get the cookies back inline."
+          description: "Output file path."
         }
       },
       required: [],
@@ -7461,49 +7819,49 @@ var MANIFEST = [
   },
   {
     name: "set_cookie",
-    description: "Write one cookie into the target page's cookie store, INCLUDING httpOnly or secure cookies that document.cookie (and therefore evaluate_script) cannot create. Either 'url' or 'domain' is REQUIRED: the call is refused when neither is given, rather than guessing the page origin. The response is {set:true,target} and never echoes the value back. A 'set:true' is earned, not assumed: Chrome raises an error when it declines the cookie (a domain the url does not belong to, a secure cookie on an insecure origin, an oversized value). On Firefox 'domain' is derived from 'url' when only the url was given (BiDi has no url parameter), and a url with no host such as about:blank or a data URL is an error, not a silent no-op. Read the result back with list_cookies when you need proof.",
+    description: "Set one page cookie, including httpOnly or secure flags; provide url or domain.",
     inputSchema: {
       type: "object",
       properties: {
         lease: {
           type: "string",
-          description: "Lease token from claim_page. Omit for a tab this process holds; required for a tab held by another process or one claimed explicitly. Auto-acquired under CDP_REQUIRE_LEASE (then pass target, not lease). See server instructions."
+          description: "Lease token; omit for a tab this process already holds. See server instructions."
         },
         target: {
           type: "string",
-          description: "Page selector: 'active' (default), 'index:N', 'url:<substr>', 'title:<substr>', 'label:<name>', or a 32-hex '<targetId>'. Grammar: see server instructions."
+          description: "Page selector (index:/url:/title:/label:/targetId, default active); grammar in server instructions."
         },
         name: {
           type: "string",
-          description: "Cookie name. Required and non-empty."
+          description: "Cookie name."
         },
         value: {
           type: "string",
-          description: "Cookie value. Required. It is not echoed back in the response."
+          description: "Cookie value."
         },
         url: {
           type: "string",
-          description: "URL the cookie is set for, e.g. 'https://example.com/'. Chrome derives domain, path and secure from it; Firefox derives only the domain from its host. Give this or 'domain'."
+          description: "URL value."
         },
         domain: {
           type: "string",
-          description: "Cookie domain, e.g. 'example.com' or '.example.com' for subdomains. Give this or 'url'. When both are given, this wins on Firefox and Chrome applies its own url plus domain consistency rule."
+          description: "Cookie domain."
         },
         path: {
           type: "string",
-          description: "Cookie path, passed through exactly as given and NOT defaulted to '/': with a 'url' Chrome derives the path from it, so an invented default here would widen a cookie you meant to scope narrowly."
+          description: "Cookie path."
         },
         expires: {
           type: "number",
-          description: "Expiry as Unix time in SECONDS, matching what list_cookies reports. Omit for a session cookie, which is what both backends do when no expiry is supplied."
+          description: "Expiry Unix time in seconds."
         },
         httpOnly: {
           type: "boolean",
-          description: "Set the httpOnly flag, making the cookie invisible to document.cookie. Only a protocol write like this one can create such a cookie."
+          description: "Set HttpOnly flag."
         },
         secure: {
           type: "boolean",
-          description: "Set the secure flag. Chrome declines a secure cookie on an insecure origin, and that refusal surfaces as an error."
+          description: "Set Secure flag."
         },
         sameSite: {
           type: "string",
@@ -7513,7 +7871,7 @@ var MANIFEST = [
             "none",
             "default"
           ],
-          description: "SameSite attribute, lowercase, matching what list_cookies reports. 'default' means the attribute is not set at all."
+          description: "SameSite attribute."
         }
       },
       required: [
@@ -7525,33 +7883,33 @@ var MANIFEST = [
   },
   {
     name: "delete_cookies",
-    description: "Delete the named cookie from the target page's cookie store, httpOnly cookies included. Both 'name' and one of 'url' or 'domain' are REQUIRED: without a site constraint it would delete by name across the whole partition, so it is refused with an error instead. Narrow further with 'path'. The response is {deleted:true,target} and carries NO count, because neither protocol reports how many cookies it removed and a number here would be invented; call list_cookies before and after for a real count. 'deleted:true' means the backend accepted and performed the deletion, not that a matching cookie existed, since deleting an absent cookie succeeds on both backends.",
+    description: "Delete a named page cookie; provide name and url or domain.",
     inputSchema: {
       type: "object",
       properties: {
         lease: {
           type: "string",
-          description: "Lease token from claim_page. Omit for a tab this process holds; required for a tab held by another process or one claimed explicitly. Auto-acquired under CDP_REQUIRE_LEASE (then pass target, not lease). See server instructions."
+          description: "Lease token; omit for a tab this process already holds. See server instructions."
         },
         target: {
           type: "string",
-          description: "Page selector: 'active' (default), 'index:N', 'url:<substr>', 'title:<substr>', 'label:<name>', or a 32-hex '<targetId>'. Grammar: see server instructions."
+          description: "Page selector (index:/url:/title:/label:/targetId, default active); grammar in server instructions."
         },
         name: {
           type: "string",
-          description: "Exact cookie name to delete. Required and non-empty. No wildcards: this removes a named cookie, not a swathe of them."
+          description: "Cookie name."
         },
         url: {
           type: "string",
-          description: "Delete cookies matching this URL, e.g. 'https://example.com/'. Give this or 'domain'. On Firefox only the host is used, because BiDi's filter has no url field."
+          description: "URL value."
         },
         domain: {
           type: "string",
-          description: "Delete cookies with this exact domain. Give this or 'url'."
+          description: "Cookie domain."
         },
         path: {
           type: "string",
-          description: "Narrow the deletion to cookies with this exact path. Omit to match any path allowed by the other constraints."
+          description: "Cookie path."
         }
       },
       required: [
@@ -7562,21 +7920,21 @@ var MANIFEST = [
   },
   {
     name: "take_snapshot",
-    description: "Captures the page's accessibility tree as an indented text tree, each line prefixed [uid] (a CDP backendDOMNodeId). Every interaction tool (click/hover/fill/etc.) resolves that uid via DOM.resolveNode — run this first to discover uids to act on.",
+    description: "Capture the page accessibility tree with interaction UIDs.",
     inputSchema: {
       type: "object",
       properties: {
         lease: {
           type: "string",
-          description: "Lease token from claim_page. Omit for a tab this process holds; required for a tab held by another process or one claimed explicitly. Auto-acquired under CDP_REQUIRE_LEASE (then pass target, not lease). See server instructions."
+          description: "Lease token; omit for a tab this process already holds. See server instructions."
         },
         target: {
           type: "string",
-          description: "Page selector: 'active' (default), 'index:N', 'url:<substr>', 'title:<substr>', 'label:<name>', or a 32-hex '<targetId>'. Grammar: see server instructions."
+          description: "Page selector (index:/url:/title:/label:/targetId, default active); grammar in server instructions."
         },
         interactiveOnly: {
           type: "boolean",
-          description: "When true, emit only interactive/meaningful nodes as a flat list; default false returns the full hierarchical tree."
+          description: "Only interactive nodes."
         }
       },
       required: [],
@@ -7585,25 +7943,25 @@ var MANIFEST = [
   },
   {
     name: "click",
-    description: "Click an element via a synthetic mouse press/release at its scrolled-into-view center. Give exactly one of uid or selector. modifiers (Alt/Control/Meta/Shift) throws on the Firefox backend — use --browser chrome for a modifier-click. clickCount:3 triple-clicks (selects a line/paragraph in most editors).",
+    description: "Click an element by UID or CSS selector; provide exactly one.",
     inputSchema: {
       type: "object",
       properties: {
         lease: {
           type: "string",
-          description: "Lease token from claim_page. Omit for a tab this process holds; required for a tab held by another process or one claimed explicitly. Auto-acquired under CDP_REQUIRE_LEASE (then pass target, not lease). See server instructions."
+          description: "Lease token; omit for a tab this process already holds. See server instructions."
         },
         target: {
           type: "string",
-          description: "Page selector: 'active' (default), 'index:N', 'url:<substr>', 'title:<substr>', 'label:<name>', or a 32-hex '<targetId>'. Grammar: see server instructions."
+          description: "Page selector (index:/url:/title:/label:/targetId, default active); grammar in server instructions."
         },
         uid: {
           type: "number",
-          description: "CDP backendDOMNodeId of the element to click, from take_snapshot. Exactly one of uid or selector."
+          description: "Element backendDOMNodeId."
         },
         selector: {
           type: "string",
-          description: "CSS selector for the element to click (document.querySelector). Exactly one of uid or selector."
+          description: "CSS selector."
         },
         button: {
           type: "string",
@@ -7612,11 +7970,11 @@ var MANIFEST = [
             "right",
             "middle"
           ],
-          description: "Mouse button: 'left' (default), 'right', or 'middle'."
+          description: "Mouse button."
         },
         clickCount: {
           type: "number",
-          description: "Number of clicks: 1 (default), 2 = double-click, 3 = triple-click."
+          description: "Click count."
         },
         modifiers: {
           type: "array",
@@ -7629,7 +7987,7 @@ var MANIFEST = [
               "Shift"
             ]
           },
-          description: "Modifier keys held for the click's press and release, e.g. ['Shift']. Non-empty on the Firefox backend throws — not supported over BiDi."
+          description: "Modifier keys: Control|Ctrl|Shift|Alt|Meta|Cmd."
         }
       },
       required: [],
@@ -7638,25 +7996,25 @@ var MANIFEST = [
   },
   {
     name: "hover",
-    description: "Hovers the mouse over an element by dispatching a mouseMoved event at its scrolled-into-view center, firing framework hover handlers. Give exactly one of uid or selector.",
+    description: "Hover an element by UID or CSS selector; provide exactly one.",
     inputSchema: {
       type: "object",
       properties: {
         lease: {
           type: "string",
-          description: "Lease token from claim_page. Omit for a tab this process holds; required for a tab held by another process or one claimed explicitly. Auto-acquired under CDP_REQUIRE_LEASE (then pass target, not lease). See server instructions."
+          description: "Lease token; omit for a tab this process already holds. See server instructions."
         },
         target: {
           type: "string",
-          description: "Page selector: 'active' (default), 'index:N', 'url:<substr>', 'title:<substr>', 'label:<name>', or a 32-hex '<targetId>'. Grammar: see server instructions."
+          description: "Page selector (index:/url:/title:/label:/targetId, default active); grammar in server instructions."
         },
         uid: {
           type: "number",
-          description: "CDP backendDOMNodeId of the element to hover, from take_snapshot. Exactly one of uid or selector."
+          description: "Element backendDOMNodeId."
         },
         selector: {
           type: "string",
-          description: "CSS selector for the element to hover (document.querySelector). Exactly one of uid or selector."
+          description: "CSS selector."
         }
       },
       required: [],
@@ -7665,67 +8023,67 @@ var MANIFEST = [
   },
   {
     name: "drag",
-    description: "Drags from a source element to a destination or by an offset. mode:'mouse' (default) dispatches synthetic mouse press/move/release; at the default steps:2 an HTML5 drop zone (dragover preventDefault) gets ZERO dragover events and refuses the drop. mode:'html5' replays real dragstart/dragEnter/dragOver/drop with the page's own dataTransfer instead — deterministic regardless of pointer path, but CHROME-ONLY (rejected with a clear error on the Firefox backend). 'from' takes uid or selector; destination is exactly one of 'to' (uid/selector/x+y) or 'by' ({dx,dy} offset — sliders, map panning, resize handles).",
+    description: "Drag from an element to a destination or offset; html5 mode is Chrome-only.",
     inputSchema: {
       type: "object",
       properties: {
         lease: {
           type: "string",
-          description: "Lease token from claim_page. Omit for a tab this process holds; required for a tab held by another process or one claimed explicitly. Auto-acquired under CDP_REQUIRE_LEASE (then pass target, not lease). See server instructions."
+          description: "Lease token; omit for a tab this process already holds. See server instructions."
         },
         target: {
           type: "string",
-          description: "Page selector: 'active' (default), 'index:N', 'url:<substr>', 'title:<substr>', 'label:<name>', or a 32-hex '<targetId>'. Grammar: see server instructions."
+          description: "Page selector (index:/url:/title:/label:/targetId, default active); grammar in server instructions."
         },
         from: {
           type: "object",
-          description: "Source element to drag from. Exactly one of uid or selector.",
+          description: "Drag source.",
           properties: {
             uid: {
               type: "number",
-              description: "CDP backendDOMNodeId of the source element, obtained from take_snapshot."
+              description: "Element backendDOMNodeId."
             },
             selector: {
               type: "string",
-              description: "CSS selector for the source element (resolved via document.querySelector)."
+              description: "CSS selector."
             }
           },
           additionalProperties: false
         },
         to: {
           type: "object",
-          description: "Where the drag ends: exactly one of uid, selector, or x+y. Mutually exclusive with 'by'; exactly one of to/by required.",
+          description: "Drag destination.",
           properties: {
             uid: {
               type: "number",
-              description: "CDP backendDOMNodeId of the destination element, obtained from take_snapshot."
+              description: "Element backendDOMNodeId."
             },
             selector: {
               type: "string",
-              description: "CSS selector for the destination element (resolved via document.querySelector)."
+              description: "CSS selector."
             },
             x: {
               type: "number",
-              description: "Absolute viewport x-coordinate to drop at. Must be given together with 'y'. Use this when there is no droppable element to name (a canvas, a slider track)."
+              description: "Viewport x-coordinate."
             },
             y: {
               type: "number",
-              description: "Absolute viewport y-coordinate to drop at. Must be given together with 'x'."
+              description: "Viewport y-coordinate."
             }
           },
           additionalProperties: false
         },
         by: {
           type: "object",
-          description: "Offset from the source element's center: at least one of dx/dy (other defaults to 0). Mutually exclusive with 'to'; exactly one of to/by required. For sliders (by:{dx:40}), map panning, resize handles.",
+          description: "Drag offset.",
           properties: {
             dx: {
               type: "number",
-              description: "Horizontal offset in CSS pixels; positive drags RIGHT."
+              description: "Horizontal drag offset."
             },
             dy: {
               type: "number",
-              description: "Vertical offset in CSS pixels; positive drags DOWN."
+              description: "Vertical drag offset."
             }
           },
           additionalProperties: false
@@ -7736,11 +8094,11 @@ var MANIFEST = [
             "mouse",
             "html5"
           ],
-          description: "'mouse' (default): synthetic mouse press/move/release — at steps:2 an HTML5 drop zone sees zero dragover events and refuses the drop. 'html5': real HTML5 drag-and-drop, deterministic regardless of pointer path, CHROME-ONLY (rejected on Firefox)."
+          description: "Drag mode."
         },
         steps: {
           type: "number",
-          description: "Number of interpolated mouse-move events between source and destination, evenly spaced, last landing on the destination. Integer 1-500, default 2. Raise for DnD libraries with a movement threshold or per-frame sampling."
+          description: "Interpolation steps."
         }
       },
       required: [
@@ -7751,41 +8109,41 @@ var MANIFEST = [
   },
   {
     name: "scroll",
-    description: "Dispatches a wheel/scroll event at an anchor point — element (uid/selector) or x+y, scrolled into view first if an element; omit all three for viewport center. At least one of deltaX/deltaY required: positive deltaY scrolls DOWN, positive deltaX scrolls RIGHT (wheel-event convention — easy to invert). Returns the resolved anchor {x,y} plus the delta actually dispatched.",
+    description: "Dispatch a wheel event at an element or coordinate anchor; provide deltaX or deltaY.",
     inputSchema: {
       type: "object",
       properties: {
         lease: {
           type: "string",
-          description: "Lease token from claim_page. Omit for a tab this process holds; required for a tab held by another process or one claimed explicitly. Auto-acquired under CDP_REQUIRE_LEASE (then pass target, not lease). See server instructions."
+          description: "Lease token; omit for a tab this process already holds. See server instructions."
         },
         target: {
           type: "string",
-          description: "Page selector: 'active' (default), 'index:N', 'url:<substr>', 'title:<substr>', 'label:<name>', or a 32-hex '<targetId>'. Grammar: see server instructions."
+          description: "Page selector (index:/url:/title:/label:/targetId, default active); grammar in server instructions."
         },
         uid: {
           type: "number",
-          description: "CDP backendDOMNodeId of the element to scroll into view and anchor at, from take_snapshot. At most one of uid, selector, or x+y."
+          description: "Element backendDOMNodeId."
         },
         selector: {
           type: "string",
-          description: "CSS selector for the element to anchor at (document.querySelector). At most one of uid, selector, or x+y."
+          description: "CSS selector."
         },
         x: {
           type: "number",
-          description: "Absolute viewport x-coordinate to anchor at; must be given with y. At most one of uid, selector, or x+y."
+          description: "Viewport x-coordinate."
         },
         y: {
           type: "number",
-          description: "Absolute viewport y-coordinate to anchor at; must be given with x. At most one of uid, selector, or x+y."
+          description: "Viewport y-coordinate."
         },
         deltaX: {
           type: "number",
-          description: "Horizontal scroll delta; positive scrolls RIGHT. At least one of deltaX/deltaY required."
+          description: "Horizontal scroll delta."
         },
         deltaY: {
           type: "number",
-          description: "Vertical scroll delta; positive scrolls DOWN. At least one of deltaX/deltaY required."
+          description: "Vertical scroll delta."
         }
       },
       required: [],
@@ -7794,17 +8152,17 @@ var MANIFEST = [
   },
   {
     name: "dispatch_mouse",
-    description: "Dispatches one raw mouse event (move/down/up) at absolute viewport coordinates — the toolkit's lowest-level input primitive. Compose move/down/move/up calls yourself for anything click/drag's fixed sequences can't reach: canvas drag-painting, marquee/rubber-band selection, custom hit-testing widgets. Chrome-only: absent from tools/list under the Firefox backend, never present-and-throwing.",
+    description: "Dispatch one raw mouse event at viewport coordinates; Chrome-only.",
     inputSchema: {
       type: "object",
       properties: {
         lease: {
           type: "string",
-          description: "Lease token from claim_page. Omit for a tab this process holds; required for a tab held by another process or one claimed explicitly. Auto-acquired under CDP_REQUIRE_LEASE (then pass target, not lease). See server instructions."
+          description: "Lease token; omit for a tab this process already holds. See server instructions."
         },
         target: {
           type: "string",
-          description: "Page selector: 'active' (default), 'index:N', 'url:<substr>', 'title:<substr>', 'label:<name>', or a 32-hex '<targetId>'. Grammar: see server instructions."
+          description: "Page selector (index:/url:/title:/label:/targetId, default active); grammar in server instructions."
         },
         action: {
           type: "string",
@@ -7813,15 +8171,15 @@ var MANIFEST = [
             "down",
             "up"
           ],
-          description: "Which raw event to dispatch: 'move' (mouseMoved), 'down' (mousePressed), or 'up' (mouseReleased)."
+          description: "Mouse action."
         },
         x: {
           type: "number",
-          description: "Viewport x-coordinate. Required every call — CDP has no 'current pointer position' to default from."
+          description: "Viewport x-coordinate."
         },
         y: {
           type: "number",
-          description: "Viewport y-coordinate. Required every call."
+          description: "Viewport y-coordinate."
         },
         button: {
           type: "string",
@@ -7830,11 +8188,11 @@ var MANIFEST = [
             "right",
             "middle"
           ],
-          description: "Mouse button: 'left' (default), 'right', or 'middle'."
+          description: "Mouse button."
         },
         clickCount: {
           type: "number",
-          description: "Click-run length for a 'down' or 'up' event (2 = second half of a double-click, 3 = triple-click). Ignored for 'move'; defaults to 1."
+          description: "Click count."
         },
         modifiers: {
           type: "array",
@@ -7847,7 +8205,7 @@ var MANIFEST = [
               "Shift"
             ]
           },
-          description: "Modifier keys held for this one event, e.g. ['Shift']."
+          description: "Modifier keys: Control|Ctrl|Shift|Alt|Meta|Cmd."
         }
       },
       required: [
@@ -7860,25 +8218,25 @@ var MANIFEST = [
   },
   {
     name: "wait_for_download",
-    description: "Wait for a file download to finish and return it as a real file on disk: {path,suggestedFilename,bytes,url,target}, written under the artifact dir's downloads/. ORDERING RULE, not optional: capture must be ARMED BEFORE the click that starts the download — call wait_for_download{arm:true} first (returns {armed:true,downloadPath,pending}), then click, then call again to collect the file. The download-behavior override is per-connection state Chrome REVERTS the moment the arming client disconnects, and an unarmed headless Chrome denies the download outright, so one triggered before arming is lost. SIDE EFFECT, browser-global: arming redirects EVERY download in this browser (all tabs, all origins) into the toolkit's downloads dir until this server exits — they no longer land in the user's normal Downloads folder. The arm lives on a connection this server holds open (an MCP-server capability): under the one-shot CLI the connection dies with the process and nothing is captured. Chrome-only (capability 'browser.downloads'): absent from tools/list under Firefox.",
+    description: "Arm or collect a browser download; arm capture before triggering the download.",
     inputSchema: {
       type: "object",
       properties: {
         lease: {
           type: "string",
-          description: "Lease token from claim_page. Omit for a tab this process holds; required for a tab held by another process or one claimed explicitly. Auto-acquired under CDP_REQUIRE_LEASE (then pass target, not lease). See server instructions."
+          description: "Lease token; omit for a tab this process already holds. See server instructions."
         },
         target: {
           type: "string",
-          description: "Names the tab for the lease check and the echoed target — a download is browser-scoped, so this does not pick which download is returned. Grammar: server instructions."
+          description: "Page selector (index:/url:/title:/label:/targetId, default active); grammar in server instructions."
         },
         arm: {
           type: "boolean",
-          description: "Arm download capture and return immediately instead of waiting: {armed:true,downloadPath,pending}. Call this BEFORE the click that triggers the download. 'pending' counts downloads that already completed and have not been collected yet, so an arm call doubles as a peek."
+          description: "Arm download capture."
         },
         timeoutMs: {
           type: "number",
-          description: "How long to wait for a download to complete, in milliseconds. Default 30000. Ignored with arm:true. A download that already completed and was not yet collected is returned immediately, so this only bounds the wait for one still in flight."
+          description: "Timeout in milliseconds."
         }
       },
       required: [],
@@ -7887,32 +8245,32 @@ var MANIFEST = [
   },
   {
     name: "grant_permissions",
-    description: "Grant browser permissions for an origin up front, so a page asking for geolocation / notifications / clipboard gets an answer instead of a prompt no agent can click. 'permissions' takes CDP PermissionType values ('geolocation','notifications','clipboardReadWrite','camera',...); an unknown name is refused by Chrome, quoting the bad value. Returns {granted,origin,target}, or {reset:true,target} for a reset-only call. Grants are keyed by ORIGIN, not by tab: every tab on that origin is affected, including ones opened later. reset:true clears this server's previous grants first (or instead, when no permissions are given) — CDP's reset is not origin-scoped, so it clears them for every origin at once. The grant lives on a connection this server holds open and Chrome DISCARDS IT when that connection closes: an MCP-server capability, so under the one-shot CLI the grant dies with the process. Chrome-only (capability 'browser.permissions'): absent from tools/list under Firefox, never present-and-throwing.",
+    description: "Grant or reset browser permissions; permissions are origin-scoped and Chrome-only.",
     inputSchema: {
       type: "object",
       properties: {
         lease: {
           type: "string",
-          description: "Lease token from claim_page. Omit for a tab this process holds; required for a tab held by another process or one claimed explicitly. Auto-acquired under CDP_REQUIRE_LEASE (then pass target, not lease). See server instructions."
+          description: "Lease token; omit for a tab this process already holds. See server instructions."
         },
         target: {
           type: "string",
-          description: "Also the origin source when 'origin' is omitted. Grammar: server instructions."
+          description: "Page selector (index:/url:/title:/label:/targetId, default active); grammar in server instructions."
         },
         permissions: {
           type: "array",
           items: {
             type: "string"
           },
-          description: "CDP PermissionType values to grant, e.g. ['geolocation'] or ['clipboardReadWrite','clipboardSanitizedWrite']. Required unless reset:true. An empty array is refused rather than treated as a successful no-op."
+          description: "CDP PermissionType values, e.g. geolocation|notifications|clipboardReadWrite."
         },
         origin: {
           type: "string",
-          description: "Origin the grant applies to, e.g. 'https://example.com'. Defaults to the target tab's own origin. Required explicitly when that tab has no grantable origin (data:, blob:, about:blank all serialize to the opaque origin 'null'), which is refused with a message naming the tab's url."
+          description: "Permission origin."
         },
         reset: {
           type: "boolean",
-          description: "Clear this server's previous permission grants (Browser.resetPermissions). With 'permissions' it resets FIRST and then grants, so the result is exactly the listed permissions; on its own it is a reset-only call answering {reset:true}. Not scoped to 'origin': CDP resets every origin at once."
+          description: "Reset permission grants."
         }
       },
       required: [],
@@ -7921,25 +8279,25 @@ var MANIFEST = [
   },
   {
     name: "fill",
-    description: "Fills an element by focusing it, clearing existing content, then inserting value via Input.insertText (atomic paste-like commit, not per-character keystrokes — won't fire per-keypress handlers). Give exactly one of uid or selector.",
+    description: "Replace an element contents; provide exactly one of UID or selector.",
     inputSchema: {
       type: "object",
       properties: {
         lease: {
           type: "string",
-          description: "Lease token from claim_page. Omit for a tab this process holds; required for a tab held by another process or one claimed explicitly. Auto-acquired under CDP_REQUIRE_LEASE (then pass target, not lease). See server instructions."
+          description: "Lease token; omit for a tab this process already holds. See server instructions."
         },
         target: {
           type: "string",
-          description: "Page selector: 'active' (default), 'index:N', 'url:<substr>', 'title:<substr>', 'label:<name>', or a 32-hex '<targetId>'. Grammar: see server instructions."
+          description: "Page selector (index:/url:/title:/label:/targetId, default active); grammar in server instructions."
         },
         uid: {
           type: "number",
-          description: "CDP backendDOMNodeId of the field to fill, from take_snapshot. Exactly one of uid or selector."
+          description: "Element backendDOMNodeId."
         },
         selector: {
           type: "string",
-          description: "CSS selector for the field to fill (document.querySelector). Exactly one of uid or selector."
+          description: "CSS selector."
         },
         value: {
           type: "string",
@@ -7954,35 +8312,35 @@ var MANIFEST = [
   },
   {
     name: "fill_form",
-    description: "Fills multiple form fields in one call; each is focused, cleared, then set via Input.insertText (overwrites existing content, same as fill). Each entry in the non-empty 'fields' array takes exactly one of uid or selector plus a string value.",
+    description: "Fill multiple elements atomically; each field needs a UID or selector.",
     inputSchema: {
       type: "object",
       properties: {
         lease: {
           type: "string",
-          description: "Lease token from claim_page. Omit for a tab this process holds; required for a tab held by another process or one claimed explicitly. Auto-acquired under CDP_REQUIRE_LEASE (then pass target, not lease). See server instructions."
+          description: "Lease token; omit for a tab this process already holds. See server instructions."
         },
         target: {
           type: "string",
-          description: "Page selector: 'active' (default), 'index:N', 'url:<substr>', 'title:<substr>', 'label:<name>', or a 32-hex '<targetId>'. Grammar: see server instructions."
+          description: "Page selector (index:/url:/title:/label:/targetId, default active); grammar in server instructions."
         },
         fields: {
           type: "array",
-          description: "Non-empty array of fields to fill, each with exactly one of uid or selector plus a string value.",
+          description: "Form fields to fill.",
           items: {
             type: "object",
             properties: {
               uid: {
                 type: "number",
-                description: "CDP backendDOMNodeId of the field, obtained from take_snapshot. Provide exactly one of uid or selector."
+                description: "Element backendDOMNodeId."
               },
               selector: {
                 type: "string",
-                description: "CSS selector for the field (resolved via document.querySelector). Provide exactly one of uid or selector."
+                description: "CSS selector."
               },
               value: {
                 type: "string",
-                description: "The text value to set; the field is cleared first so this overwrites existing content."
+                description: "Text value to set; the field is cleared first, overwriting existing content."
               }
             },
             required: [
@@ -8000,29 +8358,29 @@ var MANIFEST = [
   },
   {
     name: "type_text",
-    description: "Focuses an element and appends text via Input.insertText without clearing first — closest primitive to typing, but still atomic (not per-character keystrokes). Give exactly one of uid or selector.",
+    description: "Append text to an element; input is atomic and does not clear existing content.",
     inputSchema: {
       type: "object",
       properties: {
         lease: {
           type: "string",
-          description: "Lease token from claim_page. Omit for a tab this process holds; required for a tab held by another process or one claimed explicitly. Auto-acquired under CDP_REQUIRE_LEASE (then pass target, not lease). See server instructions."
+          description: "Lease token; omit for a tab this process already holds. See server instructions."
         },
         target: {
           type: "string",
-          description: "Page selector: 'active' (default), 'index:N', 'url:<substr>', 'title:<substr>', 'label:<name>', or a 32-hex '<targetId>'. Grammar: see server instructions."
+          description: "Page selector (index:/url:/title:/label:/targetId, default active); grammar in server instructions."
         },
         uid: {
           type: "number",
-          description: "CDP backendDOMNodeId of the element to type into, from take_snapshot. Exactly one of uid or selector."
+          description: "Element backendDOMNodeId."
         },
         selector: {
           type: "string",
-          description: "CSS selector for the element to type into (document.querySelector). Exactly one of uid or selector."
+          description: "CSS selector."
         },
         text: {
           type: "string",
-          description: "Text to insert; appended to existing content rather than overwriting it."
+          description: "Text substring."
         }
       },
       required: [
@@ -8033,25 +8391,25 @@ var MANIFEST = [
   },
   {
     name: "press_key",
-    description: "Dispatches a keyDown/keyUp pair for one key with optional modifiers. 'key' is a named key (Enter, Tab, Escape, ArrowDown, Backspace, etc.) or a single printable character — the named-key table is curated, with no F-keys, numpad, or IME support.",
+    description: "Press one named key or printable character with modifiers; no F-keys or IME.",
     inputSchema: {
       type: "object",
       properties: {
         lease: {
           type: "string",
-          description: "Lease token from claim_page. Omit for a tab this process holds; required for a tab held by another process or one claimed explicitly. Auto-acquired under CDP_REQUIRE_LEASE (then pass target, not lease). See server instructions."
+          description: "Lease token; omit for a tab this process already holds. See server instructions."
         },
         target: {
           type: "string",
-          description: "Page selector: 'active' (default), 'index:N', 'url:<substr>', 'title:<substr>', 'label:<name>', or a 32-hex '<targetId>'. Grammar: see server instructions."
+          description: "Page selector (index:/url:/title:/label:/targetId, default active); grammar in server instructions."
         },
         key: {
           type: "string",
-          description: "Key to press: a named key (Enter, Tab, Escape, ArrowDown, Backspace, ...) or a single printable character."
+          description: "Named key or printable character; e.g. Enter|Tab|Escape|ArrowDown|Backspace."
         },
         modifiers: {
           type: "array",
-          description: "Modifier names held during the press: 'Control'/'Ctrl', 'Shift', 'Alt', 'Meta'/'Cmd'.",
+          description: "Modifier keys: Control|Ctrl|Shift|Alt|Meta|Cmd.",
           items: {
             type: "string"
           }
@@ -8065,32 +8423,32 @@ var MANIFEST = [
   },
   {
     name: "upload_file",
-    description: "Attaches one or more files to an <input type=file> element via DOM.setFileInputFiles. Give exactly one of uid or selector for the input; 'files' is an array of absolute path(s) — wrap a single path in an array too.",
+    description: "Attach absolute file paths to a file input; provide an array.",
     inputSchema: {
       type: "object",
       properties: {
         lease: {
           type: "string",
-          description: "Lease token from claim_page. Omit for a tab this process holds; required for a tab held by another process or one claimed explicitly. Auto-acquired under CDP_REQUIRE_LEASE (then pass target, not lease). See server instructions."
+          description: "Lease token; omit for a tab this process already holds. See server instructions."
         },
         target: {
           type: "string",
-          description: "Page selector: 'active' (default), 'index:N', 'url:<substr>', 'title:<substr>', 'label:<name>', or a 32-hex '<targetId>'. Grammar: see server instructions."
+          description: "Page selector (index:/url:/title:/label:/targetId, default active); grammar in server instructions."
         },
         uid: {
           type: "number",
-          description: "CDP backendDOMNodeId of the file input element, from take_snapshot. Exactly one of uid or selector."
+          description: "Element backendDOMNodeId."
         },
         selector: {
           type: "string",
-          description: "CSS selector for the file input element (document.querySelector). Exactly one of uid or selector."
+          description: "CSS selector."
         },
         files: {
           type: "array",
           items: {
             type: "string"
           },
-          description: 'Absolute path(s) to attach to the <input type=file>, as an array — wrap a single path too, e.g. ["/tmp/a.pdf"]. Array-only because some model APIs (Google Gemini function calling) reject union-typed parameters.'
+          description: "Absolute file paths."
         }
       },
       required: [
@@ -8101,17 +8459,17 @@ var MANIFEST = [
   },
   {
     name: "take_screenshot",
-    description: "Captures the viewport (default), the full scrollable page (fullPage), or one element (uid or selector, mutually exclusive) via CDP Page.captureScreenshot. Past 16384 device px per side Chrome can hang rather than refuse, so size is checked first via Page.getLayoutMetrics; an oversized capture is auto-tiled into vertical bands stitched losslessly into one PNG (see tile) instead of wedging the tab. Writes PNG/JPEG to /tmp/cdp-toolkit (override savePath, dir auto-created); returns {path,bytes,format,target,scale} plus width/height measured from the encoded bytes (omitted if undecodable). renderSize/renderRestored(+renderRestoreError) accompany a renderWidth/renderHeight capture, tiled/bands a banded one. returnBase64 adds raw bytes to the result but is refused on a banded capture. quality applies to jpeg only.",
+    description: "Capture a viewport, full page, or element to PNG/JPEG; oversized captures may be tiled.",
     inputSchema: {
       type: "object",
       properties: {
         lease: {
           type: "string",
-          description: "Lease token from claim_page. Omit for a tab this process holds; required for a tab held by another process or one claimed explicitly. Auto-acquired under CDP_REQUIRE_LEASE (then pass target, not lease). See server instructions."
+          description: "Lease token; omit for a tab this process already holds. See server instructions."
         },
         target: {
           type: "string",
-          description: "Page selector: 'active' (default), 'index:N', 'url:<substr>', 'title:<substr>', 'label:<name>', or a 32-hex '<targetId>'. Grammar: see server instructions."
+          description: "Page selector (index:/url:/title:/label:/targetId, default active); grammar in server instructions."
         },
         format: {
           type: "string",
@@ -8119,47 +8477,47 @@ var MANIFEST = [
             "png",
             "jpeg"
           ],
-          description: "Image format, default png. quality applies only to jpeg."
+          description: "Image/frame format."
         },
         quality: {
           type: "number",
-          description: "JPEG quality 0-100, default 80; ignored for png."
+          description: "JPEG quality 0-100."
         },
         fullPage: {
           type: "boolean",
-          description: "Capture the full scrollable height (via Page.getLayoutMetrics), not just the viewport."
+          description: "Capture full scrollable page."
         },
         scale: {
           type: "number",
-          description: "Output-pixel multiplier for this capture only (0<scale<=8, default 1): output px = ceil(css px x scale x devicePixelRatio); the page is never told anything changed. Chrome only (screenshot.scale) — Firefox BiDi has no scale param, use emulate{deviceScaleFactor} then scale:1. A projection over 16384 device px/side is refused up front, naming the largest scale that fits."
+          description: "Output scale (0<scale<=8)."
         },
         renderWidth: {
           type: "number",
-          description: "Emulates this viewport width (CSS px, 1-16384) for one capture, then restores it. Required with renderHeight. Unlike scale, this changes what the page believes (media queries re-flow) — e.g. capture a responsive page at 1920x1080 from a differently-sized tab. Restore only works for an override this toolkit itself set; check result.renderRestored (false = still emulated, fix via emulate). Works on both backends (capability screenshot.renderSize)."
+          description: "Rendered viewport width."
         },
         renderHeight: {
           type: "number",
-          description: "Emulates this viewport height (CSS px, 1-16384) for one capture. Required with renderWidth — a viewport is two numbers. A narrow renderWidth often reflows pages TALLER, which is the usual way a render-size capture trips the 16384px encode limit."
+          description: "Rendered viewport height."
         },
         tile: {
           type: "boolean",
-          description: "Whether to allow vertical-band stitching: omitted=AUTO (band only if a single shot wouldn't fit), false=never band (refuse instead), true=always band (Chrome-only capability). Banded output is PNG-only, can't returnBase64, and only bands on HEIGHT (oversized WIDTH is refused, not split). Bands are a faithful crop, but lazy/virtualized content the real viewport never scrolled to renders blank."
+          description: "Vertical-band stitching."
         },
         uid: {
           type: "number",
-          description: "Element to clip to: a backendDOMNodeId from take_snapshot. Mutually exclusive with selector."
+          description: "Element backendDOMNodeId."
         },
         selector: {
           type: "string",
-          description: "CSS selector to clip the capture to. Mutually exclusive with uid."
+          description: "CSS selector."
         },
         savePath: {
           type: "string",
-          description: "Override the output path (default /tmp/cdp-toolkit/screenshot-<id>-<stamp>.<ext>, stamped at capture START). Directory is created from this path's dirname."
+          description: "Output file path."
         },
         returnBase64: {
           type: "boolean",
-          description: "Also return raw base64 bytes in the result. Refused on a banded capture (see tile) — a stitched image can run to hundreds of MB; read the file at the returned path instead."
+          description: "Return base64 bytes."
         }
       },
       required: [],
@@ -8168,49 +8526,49 @@ var MANIFEST = [
   },
   {
     name: "emulate",
-    description: "Applies any subset of Chrome emulation overrides in one call: device metrics (width+height together, +deviceScaleFactor/mobile), userAgent, cpuThrottlingRate(>=1), media type+features, networkConditions. Device-metrics overrides PERSIST on the target until cleared or the renderer navigates/reloads; every other override is session-scoped and resets when this call's connection closes. clearOverrides:true resets everything (ignoring other fields) and, as of 1.9.2, genuinely clears a device-metrics override set by a DIFFERENT process — Chrome's clearDeviceMetricsOverride is normally a no-op unless the clearing connection also set the override, so the driver re-asserts the tab's current size first, then clears, throwing rather than reporting cleared:true if it can't verify.",
+    description: "Apply browser emulation overrides; width and height must be paired.",
     inputSchema: {
       type: "object",
       properties: {
         lease: {
           type: "string",
-          description: "Lease token from claim_page. Omit for a tab this process holds; required for a tab held by another process or one claimed explicitly. Auto-acquired under CDP_REQUIRE_LEASE (then pass target, not lease). See server instructions."
+          description: "Lease token; omit for a tab this process already holds. See server instructions."
         },
         target: {
           type: "string",
-          description: "Page selector: 'active' (default), 'index:N', 'url:<substr>', 'title:<substr>', 'label:<name>', or a 32-hex '<targetId>'. Grammar: see server instructions."
+          description: "Page selector (index:/url:/title:/label:/targetId, default active); grammar in server instructions."
         },
         width: {
           type: "number",
-          description: "Device-metrics viewport width in CSS px. Must be paired with height."
+          description: "Viewport width; pair with height."
         },
         height: {
           type: "number",
-          description: "Device-metrics viewport height in CSS px. Must be paired with width."
+          description: "Viewport height; pair with width."
         },
         deviceScaleFactor: {
           type: "number",
-          description: "Device pixel ratio for the device-metrics override; 0 = platform default."
+          description: "Device pixel ratio."
         },
         mobile: {
           type: "boolean",
-          description: "Emulate a mobile device (viewport meta, scrollbars, etc.) for the device-metrics override."
+          description: "Mobile emulation."
         },
         userAgent: {
           type: "string",
-          description: "User-Agent string override (Emulation.setUserAgentOverride)."
+          description: "User-Agent override."
         },
         cpuThrottlingRate: {
           type: "number",
-          description: "CPU throttling multiplier: 1=none, 2=2x slower, etc. Must be >=1."
+          description: "CPU throttling rate (>=1)."
         },
         media: {
           type: "string",
-          description: "Emulated CSS media type: 'screen' | 'print' | '' (clear)."
+          description: "CSS media: screen|print|blank."
         },
         mediaFeatures: {
           type: "array",
-          description: "Emulated media features, e.g. [{name:'prefers-color-scheme', value:'dark'}].",
+          description: "CSS media feature overrides.",
           items: {
             type: "object",
             properties: {
@@ -8220,7 +8578,7 @@ var MANIFEST = [
               },
               value: {
                 type: "string",
-                description: "Media feature value, e.g. 'dark'."
+                description: "Feature value, e.g. 'dark'."
               }
             },
             required: [
@@ -8232,34 +8590,34 @@ var MANIFEST = [
         },
         networkConditions: {
           type: "object",
-          description: "Network overrides applied via Network.emulateNetworkConditions.",
+          description: "Network condition overrides.",
           properties: {
             offline: {
               type: "boolean",
-              description: "True to simulate offline."
+              description: "Simulate offline."
             },
             latency: {
               type: "number",
-              description: "Additional round-trip latency in milliseconds."
+              description: "Network latency in milliseconds."
             },
             downloadThroughput: {
               type: "number",
-              description: "Max download throughput in bytes/sec (-1 = no limit)."
+              description: "Download throughput; -1 unlimited."
             },
             uploadThroughput: {
               type: "number",
-              description: "Max upload throughput in bytes/sec (-1 = no limit)."
+              description: "Upload throughput; -1 unlimited."
             },
             connectionType: {
               type: "string",
-              description: "Connection type: 'none' | 'cellular2g' | 'cellular3g' | 'cellular4g' | 'bluetooth' | 'ethernet' | 'wifi' | 'wimax' | 'other'."
+              description: "Connection: none|cellular2g|cellular3g|cellular4g|bluetooth|ethernet|wifi|wimax|other."
             }
           },
           additionalProperties: false
         },
         clearOverrides: {
           type: "boolean",
-          description: "Reset every override (metrics, UA, CPU, media, network) to browser default; ignores all other fields when true."
+          description: "Clear all emulation overrides."
         }
       },
       required: [],
@@ -8268,33 +8626,33 @@ var MANIFEST = [
   },
   {
     name: "resize_page",
-    description: "Sets the page's device-metrics width/height (the narrow case of emulate), optionally deviceScaleFactor/mobile, then verifies by reading back window.innerWidth/innerHeight after applying. Requires positive width and height. The override PERSISTS on the target until cleared (emulate{clearOverrides:true}) or the renderer navigates/reloads.",
+    description: "Set and verify page viewport metrics; width and height are required.",
     inputSchema: {
       type: "object",
       properties: {
         lease: {
           type: "string",
-          description: "Lease token from claim_page. Omit for a tab this process holds; required for a tab held by another process or one claimed explicitly. Auto-acquired under CDP_REQUIRE_LEASE (then pass target, not lease). See server instructions."
+          description: "Lease token; omit for a tab this process already holds. See server instructions."
         },
         target: {
           type: "string",
-          description: "Page selector: 'active' (default), 'index:N', 'url:<substr>', 'title:<substr>', 'label:<name>', or a 32-hex '<targetId>'. Grammar: see server instructions."
+          description: "Page selector (index:/url:/title:/label:/targetId, default active); grammar in server instructions."
         },
         width: {
           type: "number",
-          description: "Viewport width in CSS px (required, must be positive)."
+          description: "Viewport width; pair with height."
         },
         height: {
           type: "number",
-          description: "Viewport height in CSS px (required, must be positive)."
+          description: "Viewport height; pair with width."
         },
         deviceScaleFactor: {
           type: "number",
-          description: "Device pixel ratio; 0 = platform default."
+          description: "Device pixel ratio."
         },
         mobile: {
           type: "boolean",
-          description: "Emulate a mobile device for the device-metrics override."
+          description: "Mobile emulation."
         }
       },
       required: [
@@ -8306,33 +8664,33 @@ var MANIFEST = [
   },
   {
     name: "handle_dialog",
-    description: "Wait for the next JavaScript dialog (alert/confirm/prompt/beforeunload) on a page and respond via Page.handleJavaScriptDialog, accepting or dismissing it. Default mode resolves with the first handled dialog or throws on timeout; set autoMs to handle every dialog opening during a fixed window and resolve with the list. Trigger the dialog out-of-band (e.g. click a button) — a blocking dialog freezes the renderer, so it cannot be triggered inline.",
+    description: "Handle the next JavaScript dialog; autoMs switches to timed multi-dialog mode.",
     inputSchema: {
       type: "object",
       properties: {
         lease: {
           type: "string",
-          description: "Lease token from claim_page. Omit for a tab this process holds; required for a tab held by another process or one claimed explicitly. Auto-acquired under CDP_REQUIRE_LEASE (then pass target, not lease). See server instructions."
+          description: "Lease token; omit for a tab this process already holds. See server instructions."
         },
         target: {
           type: "string",
-          description: "Page selector: 'active' (default), 'index:N', 'url:<substr>', 'title:<substr>', 'label:<name>', or a 32-hex '<targetId>'. Grammar: see server instructions."
+          description: "Page selector (index:/url:/title:/label:/targetId, default active); grammar in server instructions."
         },
         accept: {
           type: "boolean",
-          description: "Whether to accept (OK) or dismiss (Cancel) the dialog."
+          description: "Accept or dismiss dialog."
         },
         promptText: {
           type: "string",
-          description: "Text to enter for a prompt() dialog when accepting."
+          description: "Prompt response text."
         },
         timeoutMs: {
           type: "number",
-          description: "How long to wait for the next dialog, in milliseconds (default 15000)."
+          description: "Timeout in milliseconds."
         },
         autoMs: {
           type: "number",
-          description: "Auto-handle mode: keep handling every dialog that opens for this many milliseconds, then resolve with the list of handled dialogs (an empty list is valid; never throws on 'no dialog')."
+          description: "Multi-dialog window in milliseconds."
         }
       },
       required: [
@@ -8343,29 +8701,29 @@ var MANIFEST = [
   },
   {
     name: "list_console_messages",
-    description: "Read console output (logs, warnings, exceptions) captured for the target. Reads the existing shared buffer by default (empty if no capture ran); reload:true reloads and records a fresh capture (console+network together, so a network reload never wipes console history). WORKER capture (Chrome, Capability 'worker.targets'): a worker: target records an MV3 background service worker -- its console.log arrives as Runtime.consoleAPICalled, its outbound requests from CDP's Network domain on the worker's own session -- so the two tricks callers try first fail for plain JS reasons, not worker ones: a value bound at module top level is not visible from evaluate_script's global scope, and assigning self.fetch cannot rebind a fetch the module already captured. A worker has no reload: reload:true means 'listen for durationMs while it runs', so trigger its work (tool call, message, alarm) during the window; a worker woken by the call already ran its top-level code, so a startup message can be missed. SIDE EFFECT: the CDP session KEEPS THE WORKER ALIVE for the capture (an idle MV3 worker is evicted in seconds); Chrome resumes evicting after.",
+    description: "Read or recapture console messages for a page or worker; worker capture is Chrome-only.",
     inputSchema: {
       type: "object",
       properties: {
         lease: {
           type: "string",
-          description: "Lease token from claim_page. Omit for a tab this process holds; required for a tab held by another process or one claimed explicitly. Auto-acquired under CDP_REQUIRE_LEASE (then pass target, not lease). See server instructions."
+          description: "Lease token; omit for a tab this process already holds. See server instructions."
         },
         target: {
           type: "string",
-          description: "Page selector: 'active' (default), 'index:N', 'url:<substr>', 'title:<substr>', 'label:<name>', '<targetId>'; plus 'worker:<substring>' to reach a service/shared worker (e.g. an MV3 extension background worker). The worker: arm is CHROME-ONLY (Capability 'worker.targets'). Grammar: see server instructions."
+          description: "Page selector (index:/url:/title:/label:/targetId, default active); grammar in server instructions."
         },
         reload: {
           type: "boolean",
-          description: "Record fresh by reloading the page and capturing a window. Default false (read existing buffer). With a worker: target nothing reloads -- records for durationMs while the worker runs and keeps it alive until the capture stops."
+          description: "Reload before capture."
         },
         durationMs: {
           type: "number",
-          description: "Capture window for reload mode, in ms. Default 2500."
+          description: "Capture duration in milliseconds."
         },
         wake: {
           type: "boolean",
-          description: "Worker targets only, when starting a capture. Default true: an idle-evicted MV3 service worker exists in no target listing, so it is started first (ServiceWorker.startWorker) and re-confirmed; false fails fast. Rejected on a page target, a bare target id, or a read-only call. See server instructions."
+          description: "Wake worker before capture."
         }
       },
       required: [],
@@ -8374,21 +8732,21 @@ var MANIFEST = [
   },
   {
     name: "get_console_message",
-    description: "Return one console entry by zero-based index from the target's existing console buffer. Throws if the index is out of range; run list_console_messages (optionally reload:true) first to populate the buffer.",
+    description: "Return one console entry by zero-based index from the existing buffer.",
     inputSchema: {
       type: "object",
       properties: {
         lease: {
           type: "string",
-          description: "Lease token from claim_page. Omit for a tab this process holds; required for a tab held by another process or one claimed explicitly. Auto-acquired under CDP_REQUIRE_LEASE (then pass target, not lease). See server instructions."
+          description: "Lease token; omit for a tab this process already holds. See server instructions."
         },
         target: {
           type: "string",
-          description: "Page selector: 'active' (default), 'index:N', 'url:<substr>', 'title:<substr>', 'label:<name>', or a 32-hex '<targetId>'. Grammar: see server instructions."
+          description: "Page selector (index:/url:/title:/label:/targetId, default active); grammar in server instructions."
         },
         index: {
           type: "number",
-          description: "Zero-based index into the parsed console entries. Default 0."
+          description: "Zero-based entry index."
         }
       },
       required: [],
@@ -8397,33 +8755,33 @@ var MANIFEST = [
   },
   {
     name: "list_network_requests",
-    description: "Return correlated network rows (one per requestId; status/headers/state) for the target. Reads the existing buffer by default; reload:true records a fresh both-domains capture window. filterUrl keeps only URLs containing a substring. WORKER capture (Chrome, Capability 'worker.targets'): a worker: target records an MV3 background service worker's outbound requests from CDP's Network domain on the worker's own session -- what the code ACTUALLY SENT -- so the two tricks callers try first fail for plain JS reasons, not worker ones: a value bound at module top level is not visible from evaluate_script's global scope, and assigning self.fetch cannot rebind a fetch the module already captured. A worker has no reload: reload:true means 'listen for durationMs while it runs', so trigger its work (tool call, message, alarm) during the window; a worker woken by the call already ran its top-level code, so a startup request can be missed. SIDE EFFECT: the CDP session KEEPS THE WORKER ALIVE for the capture (an idle MV3 worker is evicted in seconds); Chrome resumes evicting after.",
+    description: "Read or recapture correlated network requests; worker capture is Chrome-only.",
     inputSchema: {
       type: "object",
       properties: {
         lease: {
           type: "string",
-          description: "Lease token from claim_page. Omit for a tab this process holds; required for a tab held by another process or one claimed explicitly. Auto-acquired under CDP_REQUIRE_LEASE (then pass target, not lease). See server instructions."
+          description: "Lease token; omit for a tab this process already holds. See server instructions."
         },
         target: {
           type: "string",
-          description: "Page selector: 'active' (default), 'index:N', 'url:<substr>', 'title:<substr>', 'label:<name>', '<targetId>'; plus 'worker:<substring>' to reach a service/shared worker (e.g. an MV3 extension background worker). The worker: arm is CHROME-ONLY (Capability 'worker.targets'). Grammar: see server instructions."
+          description: "Page selector (index:/url:/title:/label:/targetId, default active); grammar in server instructions."
         },
         reload: {
           type: "boolean",
-          description: "Record fresh by reloading the page and capturing a window. Default false (read existing buffer). With a worker: target nothing reloads -- records for durationMs while the worker runs and keeps it alive until the capture stops."
+          description: "Reload before capture."
         },
         durationMs: {
           type: "number",
-          description: "Capture window for reload mode, in ms. Default 2500."
+          description: "Capture duration in milliseconds."
         },
         filterUrl: {
           type: "string",
-          description: "Return only requests whose URL contains this substring."
+          description: "URL substring filter."
         },
         wake: {
           type: "boolean",
-          description: "Worker targets only, when starting a capture. Default true: an idle-evicted MV3 service worker exists in no target listing, so it is started first (ServiceWorker.startWorker) and re-confirmed; false fails fast. Rejected on a page target, a bare target id, or a read-only call. See server instructions."
+          description: "Wake worker before capture."
         }
       },
       required: [],
@@ -8432,37 +8790,37 @@ var MANIFEST = [
   },
   {
     name: "get_network_request",
-    description: "Return one network request (matched by exact requestId, else url substring) with status/headers. Requires requestId or url (throws otherwise). includeBody:true drives a fresh capture (page reload, or worker listen window) matched by url ONLY -- a fresh capture re-mints requestIds, so a carried-over requestId returns metadata plus bodyUnavailableReason. WORKER capture (Chrome, Capability 'worker.targets'): a worker: target records an MV3 background service worker's outbound requests from CDP's Network domain on the worker's own session -- what the code ACTUALLY SENT -- so the two tricks callers try first fail for plain JS reasons, not worker ones: a value bound at module top level is not visible from evaluate_script's global scope, and assigning self.fetch cannot rebind a fetch the module already captured. A worker has no reload: reload means 'listen for durationMs while it runs', so trigger its work (tool call, message, alarm) during the window; a worker woken by the call already ran its top-level code, so a startup request can be missed. SIDE EFFECT: the CDP session KEEPS THE WORKER ALIVE for the capture (an idle MV3 worker is evicted in seconds); Chrome resumes evicting after.",
+    description: "Return a network request by ID or URL; body capture requires URL.",
     inputSchema: {
       type: "object",
       properties: {
         lease: {
           type: "string",
-          description: "Lease token from claim_page. Omit for a tab this process holds; required for a tab held by another process or one claimed explicitly. Auto-acquired under CDP_REQUIRE_LEASE (then pass target, not lease). See server instructions."
+          description: "Lease token; omit for a tab this process already holds. See server instructions."
         },
         target: {
           type: "string",
-          description: "Page selector: 'active' (default), 'index:N', 'url:<substr>', 'title:<substr>', 'label:<name>', '<targetId>'; plus 'worker:<substring>' to reach a service/shared worker (e.g. an MV3 extension background worker). The worker: arm is CHROME-ONLY (Capability 'worker.targets'). Grammar: see server instructions."
+          description: "Page selector (index:/url:/title:/label:/targetId, default active); grammar in server instructions."
         },
         requestId: {
           type: "string",
-          description: "Match by exact requestId (metadata only; cannot fetch a body, since a reload re-mints requestIds)."
+          description: "Exact request ID."
         },
         url: {
           type: "string",
-          description: "Match by URL substring (first match). Required for body fetch (includeBody), since url is stable across reload."
+          description: "URL value."
         },
         includeBody: {
           type: "boolean",
-          description: "Also fetch the response body; drives a fresh capture and requires the url selector."
+          description: "Include response body."
         },
         durationMs: {
           type: "number",
-          description: "Capture window for the body-fetch reload, in ms. Default 2500."
+          description: "Capture duration in milliseconds."
         },
         wake: {
           type: "boolean",
-          description: "Worker targets only, when starting a capture. Default true: an idle-evicted MV3 service worker exists in no target listing, so it is started first (ServiceWorker.startWorker) and re-confirmed; false fails fast. Rejected on a page target, a bare target id, or a read-only call. See server instructions."
+          description: "Wake worker before capture."
         }
       },
       required: [],
@@ -8471,24 +8829,24 @@ var MANIFEST = [
   },
   {
     name: "performance_start_trace",
-    description: "Starts a CDP trace recording on the target and holds the recording connection in-process; you MUST call performance_stop_trace from the SAME PROCESS to end it, or use performance_trace instead for a robust cross-call trace. Throws if a trace is already in progress for this target.",
+    description: "Start an in-process trace; stop it from the same process.",
     inputSchema: {
       type: "object",
       properties: {
         lease: {
           type: "string",
-          description: "Lease token from claim_page. Omit for a tab this process holds; required for a tab held by another process or one claimed explicitly. Auto-acquired under CDP_REQUIRE_LEASE (then pass target, not lease). See server instructions."
+          description: "Lease token; omit for a tab this process already holds. See server instructions."
         },
         target: {
           type: "string",
-          description: "Page selector: 'active' (default), 'index:N', 'url:<substr>', 'title:<substr>', 'label:<name>', or a 32-hex '<targetId>'. Grammar: see server instructions."
+          description: "Page selector (index:/url:/title:/label:/targetId, default active); grammar in server instructions."
         },
         categories: {
           type: "array",
           items: {
             type: "string"
           },
-          description: "Trace categories to record. Defaults to timeline + user-timing + loading + disabled-by-default timeline tracks carrying LCP/LayoutShift/RunTask."
+          description: "Trace categories."
         }
       },
       required: [],
@@ -8497,17 +8855,17 @@ var MANIFEST = [
   },
   {
     name: "performance_stop_trace",
-    description: "Stops the in-process trace started by performance_start_trace and writes it as JSON under /tmp/cdp-toolkit, returning {path,bytes,events,metrics}. Throws if no live trace exists in THIS process (e.g. start ran in a different process) — use performance_trace instead. The target arg is accepted only for API symmetry; at most one trace is ever live per process.",
+    description: "Stop the in-process trace and write JSON; a live trace is required.",
     inputSchema: {
       type: "object",
       properties: {
         lease: {
           type: "string",
-          description: "Lease token from claim_page. Omit for a tab this process holds; required for a tab held by another process or one claimed explicitly. Auto-acquired under CDP_REQUIRE_LEASE (then pass target, not lease). See server instructions."
+          description: "Lease token; omit for a tab this process already holds. See server instructions."
         },
         target: {
           type: "string",
-          description: "Page selector: 'active' (default), 'index:N', 'url:<substr>', 'title:<substr>', 'label:<name>', or a 32-hex '<targetId>'. Grammar: see server instructions."
+          description: "Page selector (index:/url:/title:/label:/targetId, default active); grammar in server instructions."
         }
       },
       required: [],
@@ -8516,17 +8874,17 @@ var MANIFEST = [
   },
   {
     name: "performance_analyze_insight",
-    description: "Reads a trace JSON file (from performance_trace/performance_stop_trace) at tracePath and returns headline metrics: FCP/LCP/CLS/TBT, long tasks, layout shifts. Requires an EXPLICIT tracePath — there is no implicit 'latest trace'. Numbers approximate DevTools's insight analyzer (no main-thread attribution or frame-scoped LCP).",
+    description: "Analyze a trace JSON file for key performance metrics; tracePath is required.",
     inputSchema: {
       type: "object",
       properties: {
         lease: {
           type: "string",
-          description: "Lease token from claim_page. Omit for a tab this process holds; required for a tab held by another process or one claimed explicitly. Auto-acquired under CDP_REQUIRE_LEASE (then pass target, not lease). See server instructions."
+          description: "Lease token; omit for a tab this process already holds. See server instructions."
         },
         tracePath: {
           type: "string",
-          description: "Path to a trace JSON file (bare array or {traceEvents:[...]}) written by performance_trace or performance_stop_trace. Required."
+          description: "Trace JSON file path."
         }
       },
       required: [],
@@ -8535,36 +8893,36 @@ var MANIFEST = [
   },
   {
     name: "performance_trace",
-    description: "RECOMMENDED entry point: one-shot trace that starts tracing, optionally reloads or navigates the page, waits durationMs (default 3000ms), stops, and writes JSON under /tmp/cdp-toolkit — returns {path,bytes,events,metrics,target}. Holds one connection open for the whole window, so unlike start/stop it is NOT limited to a single process.",
+    description: "Run a one-shot trace with optional navigation and write JSON; durationMs controls capture time.",
     inputSchema: {
       type: "object",
       properties: {
         lease: {
           type: "string",
-          description: "Lease token from claim_page. Omit for a tab this process holds; required for a tab held by another process or one claimed explicitly. Auto-acquired under CDP_REQUIRE_LEASE (then pass target, not lease). See server instructions."
+          description: "Lease token; omit for a tab this process already holds. See server instructions."
         },
         target: {
           type: "string",
-          description: "Page selector: 'active' (default), 'index:N', 'url:<substr>', 'title:<substr>', 'label:<name>', or a 32-hex '<targetId>'. Grammar: see server instructions."
+          description: "Page selector (index:/url:/title:/label:/targetId, default active); grammar in server instructions."
         },
         durationMs: {
           type: "number",
-          description: "How long to record after the optional reload/navigate, in ms. Default 3000."
+          description: "Capture duration in milliseconds."
         },
         reload: {
           type: "boolean",
-          description: "Reload the page after starting the trace, to capture full navigation timing."
+          description: "Reload before capture."
         },
         navigateTo: {
           type: "string",
-          description: "Navigate to this URL after starting the trace (alternative to reload)."
+          description: "Navigation URL."
         },
         categories: {
           type: "array",
           items: {
             type: "string"
           },
-          description: "Trace categories to record. Defaults to timeline + user-timing + loading + disabled-by-default timeline tracks carrying LCP/LayoutShift/RunTask."
+          description: "Trace categories."
         }
       },
       required: [],
@@ -8573,17 +8931,17 @@ var MANIFEST = [
   },
   {
     name: "start_screen_recording",
-    description: "Starts recording the target tab to video via CDP Page.startScreencast, holding one persistent connection and spooling every frame to disk — MUST be paired with stop_screen_recording WITHIN THE SAME PROCESS (frames are connection-scoped and cannot be reattached from another process, so this only works under the MCP server, not the one-process-per-call CLI). Chrome only: WebDriver BiDi has no screencast primitive, so both tools are absent under --browser firefox. Frames arrive ON REPAINT not on a clock (variable rate); each is timestamped into a ledger that stop_screen_recording turns into per-frame display durations, so a still page holds one long frame instead of racing. ffmpeg is probed here (not at stop) so a missing encoder fails before frames are captured and thrown away. Throws if the target already has a recording in progress; different targets record concurrently.",
+    description: "Start a tab screen recording; stop it from the same process.",
     inputSchema: {
       type: "object",
       properties: {
         lease: {
           type: "string",
-          description: "Lease token from claim_page. Omit for a tab this process holds; required for a tab held by another process or one claimed explicitly. Auto-acquired under CDP_REQUIRE_LEASE (then pass target, not lease). See server instructions."
+          description: "Lease token; omit for a tab this process already holds. See server instructions."
         },
         target: {
           type: "string",
-          description: "Page selector: 'active' (default), 'index:N', 'url:<substr>', 'title:<substr>', 'label:<name>', or a 32-hex '<targetId>'. Grammar: see server instructions."
+          description: "Page selector (index:/url:/title:/label:/targetId, default active); grammar in server instructions."
         },
         format: {
           type: "string",
@@ -8591,27 +8949,27 @@ var MANIFEST = [
             "jpeg",
             "png"
           ],
-          description: "Frame format, default jpeg (much smaller per repaint); png is lossless. quality applies to jpeg only."
+          description: "Image/frame format."
         },
         quality: {
           type: "number",
-          description: "JPEG frame quality 0-100. Ignored for png; omitted leaves Chrome's own default."
+          description: "JPEG quality 0-100."
         },
         maxWidth: {
           type: "number",
-          description: "Caps the streamed frame width in px; also pins frame size if the viewport may change mid-recording."
+          description: "Maximum frame width."
         },
         maxHeight: {
           type: "number",
-          description: "Caps the streamed frame height in px."
+          description: "Maximum frame height."
         },
         everyNthFrame: {
           type: "number",
-          description: "Capture only every Nth repaint (1=every frame), to shrink spool size on a busy page; per-frame durations keep playback at wallclock speed either way."
+          description: "Capture every Nth frame."
         },
         bringToFront: {
           type: "boolean",
-          description: "Activate the tab (Page.bringToFront) before recording, default false. A backgrounded/occluded tab may never repaint, yielding a 0-frame recording."
+          description: "Activate tab before recording."
         }
       },
       required: [],
@@ -8620,21 +8978,21 @@ var MANIFEST = [
   },
   {
     name: "stop_screen_recording",
-    description: "Stops the recording started by start_screen_recording, assembling spooled frames into an MP4 via ffmpeg with PER-FRAME durations (frame N held until N+1 painted; last frame held until this call) — capped at 25fps by ffmpeg's concat demuxer, so frames under 40ms apart are deliberately coalesced (frameCount=captured, encodedFrames=what reached the video, never silently dropped). Returns {path,bytes,durationMs,frameCount,encodedFrames,codec,encoder,width,height,droppedFrames,target}; durationMs sums encoded durations, the file runs one 40ms step longer (final frame repeated). Encoder ladder (probed at start): hevc_videotoolbox>h264_videotoolbox>libx265>libx264 (+hvc1 tag, faststart, yuv420p, even dims). target: omit with one recording in flight, required with several (avoids guessing which to stop). Throws if nothing is recording in this process, or if 0 frames arrived (no silent empty video). On ffmpeg failure the spooled frames are KEPT — spool path + exact command are in the error.",
+    description: "Stop a screen recording and encode MP4; target is required when multiple recordings exist.",
     inputSchema: {
       type: "object",
       properties: {
         lease: {
           type: "string",
-          description: "Lease token from claim_page. Omit for a tab this process holds; required for a tab held by another process or one claimed explicitly. Auto-acquired under CDP_REQUIRE_LEASE (then pass target, not lease). See server instructions."
+          description: "Lease token; omit for a tab this process already holds. See server instructions."
         },
         target: {
           type: "string",
-          description: "Which recording to stop — 'active' valid only when exactly one recording is in flight. Grammar: server instructions."
+          description: "Page selector (index:/url:/title:/label:/targetId, default active); grammar in server instructions."
         },
         savePath: {
           type: "string",
-          description: "Override the output path (default /tmp/cdp-toolkit/screen-recording-<targetIdShort>-<stamp>.mp4)."
+          description: "Output file path."
         }
       },
       required: [],
@@ -8643,21 +9001,21 @@ var MANIFEST = [
   },
   {
     name: "take_heapsnapshot",
-    description: "Captures a V8 heap snapshot of the target page over CDP and writes it as a .heapsnapshot JSON file (loadable in the DevTools Memory panel) under /tmp/cdp-toolkit unless savePath is given. Returns {path,bytes,chunks,target} only — does NOT parse or summarize the snapshot.",
+    description: "Capture a V8 heap snapshot to JSON; the snapshot is not parsed.",
     inputSchema: {
       type: "object",
       properties: {
         lease: {
           type: "string",
-          description: "Lease token from claim_page. Omit for a tab this process holds; required for a tab held by another process or one claimed explicitly. Auto-acquired under CDP_REQUIRE_LEASE (then pass target, not lease). See server instructions."
+          description: "Lease token; omit for a tab this process already holds. See server instructions."
         },
         target: {
           type: "string",
-          description: "Page selector: 'active' (default), 'index:N', 'url:<substr>', 'title:<substr>', 'label:<name>', or a 32-hex '<targetId>'. Grammar: see server instructions."
+          description: "Page selector (index:/url:/title:/label:/targetId, default active); grammar in server instructions."
         },
         savePath: {
           type: "string",
-          description: "Override the output path. Absolute paths (starting with /) are used as-is; relative paths resolve under the artifact dir (/tmp/cdp-toolkit). Defaults to an auto-named take_heapsnapshot-<targetId>-<timestamp>.heapsnapshot file."
+          description: "Output file path."
         }
       },
       required: [],
@@ -8666,28 +9024,28 @@ var MANIFEST = [
   },
   {
     name: "lighthouse_audit",
-    description: "Runs a Lighthouse audit against a URL by shelling out to `npx --yes lighthouse` (the toolkit's only non-CDP tool) — it attaches to the already-running Chrome and audits its OWN about:blank tab, NOT any live user tab you've navigated. Writes a JSON report under /tmp/cdp-toolkit; returns {path,bytes} plus per-category scores (0..1 or null).",
+    description: "Run Lighthouse against a URL in its own tab; it does not audit a user tab.",
     inputSchema: {
       type: "object",
       properties: {
         lease: {
           type: "string",
-          description: "Lease token from claim_page. Omit for a tab this process holds; required for a tab held by another process or one claimed explicitly. Auto-acquired under CDP_REQUIRE_LEASE (then pass target, not lease). See server instructions."
+          description: "Lease token; omit for a tab this process already holds. See server instructions."
         },
         url: {
           type: "string",
-          description: "The URL to audit. Required — never points at a user tab implicitly."
+          description: "URL value."
         },
         categories: {
           type: "array",
           items: {
             type: "string"
           },
-          description: 'Lighthouse categories to run (--only-categories). Defaults to the full set, e.g. ["performance"] or ["performance","accessibility","seo"].'
+          description: "Lighthouse categories to run (--only-categories)."
         },
         savePath: {
           type: "string",
-          description: "Override the report output path; defaults to a timestamped file under /tmp/cdp-toolkit."
+          description: "Output file path."
         },
         formFactor: {
           type: "string",
@@ -8695,11 +9053,11 @@ var MANIFEST = [
             "desktop",
             "mobile"
           ],
-          description: '"desktop" (default, uses --preset=desktop to avoid heavy mobile throttling) or "mobile".'
+          description: "Lighthouse form factor."
         },
         timeoutMs: {
           type: "number",
-          description: "Overall budget for the lighthouse process, in ms. Default 120000."
+          description: "Timeout in milliseconds."
         }
       },
       required: [
@@ -8710,21 +9068,21 @@ var MANIFEST = [
   },
   {
     name: "mock_request",
-    description: "Register a mock rule on a target's persistent fake-backend session (CDP Fetch domain): match requests by urlPattern and fulfill with a canned response, fail (abort), or continue -- optionally with fault injection (delayMs/failRate). The session survives reloads/navigations and lives until clear_mocks; call repeatedly to mock several endpoints on one target. reload:true applies it immediately. Persistent across calls only via the MCP server, not the one-shot CLI.",
+    description: "Register a persistent request mock; urlPattern is required.",
     inputSchema: {
       type: "object",
       properties: {
         lease: {
           type: "string",
-          description: "Lease token from claim_page. Omit for a tab this process holds; required for a tab held by another process or one claimed explicitly. Auto-acquired under CDP_REQUIRE_LEASE (then pass target, not lease). See server instructions."
+          description: "Lease token; omit for a tab this process already holds. See server instructions."
         },
         target: {
           type: "string",
-          description: "Which page's mock session. Defaults to the active page. Grammar: server instructions."
+          description: "Page selector (index:/url:/title:/label:/targetId, default active); grammar in server instructions."
         },
         urlPattern: {
           type: "string",
-          description: `CDP Fetch urlPattern glob: '*' any run of chars, '?' exactly one, '\\' escapes. Only matching URLs are paused. e.g. "*/api/users*".`
+          description: "URL glob (*, ?; \\ escapes)."
         },
         action: {
           type: "string",
@@ -8737,39 +9095,39 @@ var MANIFEST = [
         },
         status: {
           type: "number",
-          description: "fulfill: HTTP status for the canned response. Default 200."
+          description: "Mock HTTP status."
         },
         body: {
           type: "string",
-          description: "fulfill: response body string (base64-encoded for CDP internally)."
+          description: "Mock response body."
         },
         contentType: {
           type: "string",
-          description: 'fulfill: Content-Type header. Default "application/json".'
+          description: "Response Content-Type."
         },
         headers: {
           type: "object",
-          description: 'fulfill: extra response headers (name->value); override Content-Type case-insensitively. Add "Access-Control-Allow-Origin" for cross-origin fetches.'
+          description: "Extra response headers."
         },
         errorReason: {
           type: "string",
-          description: 'fail: CDP Network.ErrorReason, e.g. "Failed" (default), "BlockedByClient", "ConnectionRefused", "TimedOut".'
+          description: "CDP Network.ErrorReason, e.g. Failed|BlockedByClient|ConnectionRefused|TimedOut."
         },
         method: {
           type: "string",
-          description: 'Only mock this HTTP method (e.g. "POST"); others pass through.'
+          description: "HTTP method."
         },
         delayMs: {
           type: "number",
-          description: "Fault injection: artificial latency in ms before responding."
+          description: "Artificial delay in milliseconds."
         },
         failRate: {
           type: "number",
-          description: "Fault injection: probability 0..1 of failing a matched request regardless of action."
+          description: "Failure probability 0..1."
         },
         reload: {
           type: "boolean",
-          description: "Reload the target after arming so the mock catches traffic immediately."
+          description: "Reload before capture."
         }
       },
       required: [
@@ -8780,13 +9138,13 @@ var MANIFEST = [
   },
   {
     name: "list_mocks",
-    description: "List active fake-backend sessions (one per target) with their rules and hit counts. Prunes sessions whose tab has closed.",
+    description: "List active request-mocking sessions and hit counts.",
     inputSchema: {
       type: "object",
       properties: {
         lease: {
           type: "string",
-          description: "Lease token from claim_page. Omit for a tab this process holds; required for a tab held by another process or one claimed explicitly. Auto-acquired under CDP_REQUIRE_LEASE (then pass target, not lease). See server instructions."
+          description: "Lease token; omit for a tab this process already holds. See server instructions."
         },
         target: {
           type: "string",
@@ -8799,17 +9157,17 @@ var MANIFEST = [
   },
   {
     name: "clear_mocks",
-    description: "Tear down fake-backend sessions (Fetch.disable + close the connection). Clears the resolved target's session by default, or every active session with all:true.",
+    description: "Clear the selected or all request-mocking sessions.",
     inputSchema: {
       type: "object",
       properties: {
         lease: {
           type: "string",
-          description: "Lease token from claim_page. Omit for a tab this process holds; required for a tab held by another process or one claimed explicitly. Auto-acquired under CDP_REQUIRE_LEASE (then pass target, not lease). See server instructions."
+          description: "Lease token; omit for a tab this process already holds. See server instructions."
         },
         target: {
           type: "string",
-          description: "Which page's mock session to clear. Defaults to the active page; ignored when all:true. Grammar: server instructions."
+          description: "Page selector (index:/url:/title:/label:/targetId, default active); grammar in server instructions."
         },
         all: {
           type: "boolean",
@@ -8822,29 +9180,29 @@ var MANIFEST = [
   },
   {
     name: "claim_page",
-    description: "Take exclusive ownership of a browser tab, returning an opaque lease token (needed once under CDP_REQUIRE_LEASE for any tab you drive). Two modes: FRESH TAB (no target - opens one, optionally at url, and claims it: 'give me my own tab' in one call) and TAKEOVER (target - claims an already-open tab, e.g. the human's, resolving the selector against the live page list, creating nothing). The opened flag is true only when this call created the tab, and release_page consults that record, so a taken-over tab is left open on release. Refused from the CLI (its per-call process would make the lease instantly reclaimable). The answer carries humanActiveMs, ms since input this server did not dispatch; null is NO DATA (no activity beacon, or every input was this server's own) and never means 'no human'; absent on a backend that cannot answer. On takeover of a tab a human used within 30s it adds contention, a warning - but THE CLAIM IS NEVER REFUSED FOR THIS: takeover is its purpose, you already hold the lease; it only warns you're fighting a live person, so open your own tab or ask first. Limits: input inside a cross-origin iframe is invisible, and a second MCP server's clicks read as human.",
+    description: "Claim an existing tab or open a fresh one; CLI use is refused.",
     inputSchema: {
       type: "object",
       properties: {
         target: {
           type: "string",
-          description: "Take over an already-open tab (e.g. one the human has open). Resolved against the LIVE page list only, so it never opens a tab — a selector matching nothing is an error. Left open on release. Refused if another live process holds it (including a lease auto-acquired under CDP_REQUIRE_LEASE): takes over unleased human tabs, never steals from a live agent. Mutually exclusive with targetId. Selector grammar: server instructions."
+          description: "Page selector (index:/url:/title:/label:/targetId, default active); grammar in server instructions."
         },
         targetId: {
           type: "string",
-          description: "Exact target id (not a selector) of an already-open page to claim instead of opening one. Back-compat only; prefer target, which also accepts an exact id. Mutually exclusive with target."
+          description: "Exact target ID."
         },
         url: {
           type: "string",
-          description: "When opening a fresh tab, navigate it here. Ignored when target or targetId is given."
+          description: "URL value."
         },
         label: {
           type: "string",
-          description: "Agent label recorded on the lease; surfaced in conflict errors and list_leases. Defaults to pid-<pid>."
+          description: "Agent lease label."
         },
         ttlMs: {
           type: "number",
-          description: "How long the lease survives without use before it is reclaimable. Defaults to CDP_LEASE_TTL_MS, else 900000 (15min); every checked call refreshes it."
+          description: "Lease TTL in milliseconds."
         }
       },
       required: [],
@@ -8853,21 +9211,21 @@ var MANIFEST = [
   },
   {
     name: "release_page",
-    description: "Give a lease back, closing the tab only if this toolkit opened it. Take exactly one of lease (the token) or target (a selector for a tab this process holds - use this to release a lease the gate acquired for you automatically, since that path never handed you a token). A tab with a creation record from this toolkit is closed; a tab that was already open and merely claimed is released and left alone - override either way with close. Idempotent: an already-released, reclaimed, or expired lease reports released:false and closes nothing (by then the tab may belong to another agent). Answers {released, closed, targetId}.",
+    description: "Release a page lease and optionally close its tab; provide lease or target.",
     inputSchema: {
       type: "object",
       properties: {
         lease: {
           type: "string",
-          description: "Token from claim_page / new_page{claim:true}. Mutually exclusive with 'target'. Under CDP_REQUIRE_LEASE an auto-acquired lease never produced a token — give 'target' instead."
+          description: "Lease token; omit for a tab this process already holds. See server instructions."
         },
         target: {
           type: "string",
-          description: "A tab THIS process holds (grammar: server instructions). Mutually exclusive with 'lease'. Refused if another process holds the tab."
+          description: "Page selector (index:/url:/title:/label:/targetId, default active); grammar in server instructions."
         },
         close: {
           type: "boolean",
-          description: "Force the close decision instead of letting the creation record decide: true closes even a tab this toolkit did not open; false keeps an agent-created tab open. Omit to close only tabs this toolkit created."
+          description: "Override close behavior."
         }
       },
       required: [],
@@ -8876,7 +9234,7 @@ var MANIFEST = [
   },
   {
     name: "list_leases",
-    description: "Enumerate every active lease for diagnosis - backend, target id, label, pid, createdAt, lastUsedAt, ttlMs, whether the owning process is alive, and whether the lease is reclaimable and why. No token required; it never returns the lease nonce, so it cannot be used to forge one. An unreadable or unparseable lease row instead carries unreadable, with label, pid and timestamps zeroed and stale forced false (an unreadable lease must never read as free to take). Under CDP_REQUIRE_LEASE it reaps abandoned agent tabs exactly as list_pages does, into an additive reaped array, omitting their rows. Where the tab can answer, a row also carries humanActiveMs, ms since input this server did not dispatch - note lastUsedAt tracks TOOLKIT calls only, so a tab a person has typed in for ten minutes looks idle, which is what this exposes; the field is absent, never null, when the tab cannot answer, and that absence means 'no answer', never 'nobody is there'. idleMs (now - lastUsedAt) and expiresAt (lastUsedAt + ttlMs) are computed fresh each call and omitted on an unreadable row.",
+    description: "List active leases for diagnosis without exposing lease tokens.",
     inputSchema: {
       type: "object",
       properties: {},
@@ -8886,6 +9244,566 @@ var MANIFEST = [
   }
 ];
 
+// src/install/wizard.ts
+import { createInterface } from "node:readline";
+import { homedir as homedir3 } from "node:os";
+import { join as join14 } from "node:path";
+
+// src/install/browser.ts
+import { existsSync as existsSync2 } from "node:fs";
+import { mkdir as mkdir13, readFile as readFile9, writeFile as writeFile10 } from "node:fs/promises";
+import { homedir } from "node:os";
+import { delimiter, dirname as dirname3, join as join12 } from "node:path";
+var CANDIDATE_BUILDERS = {
+  chrome: () => [
+    process.env.CHROME_BIN,
+    "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+    "google-chrome",
+    "google-chrome-stable",
+    "chromium"
+  ],
+  arc: () => [process.env.ARC_BIN, "/Applications/Arc.app/Contents/MacOS/Arc", "arc"],
+  firefox: () => [
+    process.env.FIREFOX_BIN,
+    "/Applications/Firefox.app/Contents/MacOS/firefox",
+    "firefox",
+    "/usr/bin/firefox"
+  ]
+};
+function existsOnPath(cmd) {
+  const pathEnv = process.env.PATH;
+  if (!pathEnv)
+    return false;
+  for (const dir of pathEnv.split(delimiter)) {
+    if (!dir)
+      continue;
+    if (existsSync2(join12(dir, cmd)))
+      return true;
+  }
+  return false;
+}
+function resolveCandidate(candidates) {
+  let lastDefined = "";
+  for (const c of candidates) {
+    if (!c)
+      continue;
+    lastDefined = c;
+    if (c.startsWith("/")) {
+      if (existsSync2(c))
+        return { binary: c, found: true };
+      continue;
+    }
+    if (existsOnPath(c))
+      return { binary: c, found: true };
+  }
+  return { binary: lastDefined, found: false };
+}
+function detectBrowser(choice) {
+  const { binary, found } = resolveCandidate(CANDIDATE_BUILDERS[choice]());
+  return { choice, binary, found };
+}
+function defaultProfileDir(choice) {
+  return `$HOME/.cdp-toolkit/${choice}-profile`;
+}
+function defaultAliasName(choice) {
+  return `cdp-${choice}`;
+}
+function browserLaunchArgs(o) {
+  const profileDir = o.profileDir ?? defaultProfileDir(o.choice);
+  if (o.choice === "firefox") {
+    return ["--remote-debugging-port", String(o.port), "--marionette", "--no-remote", "--profile", profileDir];
+  }
+  return [`--remote-debugging-port=${o.port}`, `--user-data-dir=${profileDir}`];
+}
+function shellQuoteIfSpaced(token) {
+  return /\s/.test(token) ? `"${token}"` : token;
+}
+function aliasLine(o) {
+  const name = o.aliasName ?? defaultAliasName(o.choice);
+  const { binary } = detectBrowser(o.choice);
+  const parts = [shellQuoteIfSpaced(binary), ...browserLaunchArgs(o)];
+  return `alias ${name}='${parts.join(" ")}'`;
+}
+function detectShellRc() {
+  const shell = process.env.SHELL ?? "";
+  if (shell.endsWith("zsh"))
+    return join12(homedir(), ".zshrc");
+  if (shell.endsWith("bash"))
+    return join12(homedir(), ".bashrc");
+  return join12(homedir(), process.platform === "darwin" ? ".zshrc" : ".bashrc");
+}
+var MARKER_START = "# >>> cdp-toolkit alias >>>";
+var MARKER_END = "# <<< cdp-toolkit alias <<<";
+function ensureTrailingNewline(s) {
+  return s.endsWith(`
+`) ? s : `${s}
+`;
+}
+async function appendAliasToRc(rcPath, aliasBlockBody) {
+  let existing = "";
+  try {
+    existing = await readFile9(rcPath, "utf8");
+  } catch (err) {
+    if (err.code !== "ENOENT")
+      throw err;
+  }
+  const block = `${MARKER_START}
+${aliasBlockBody}
+${MARKER_END}`;
+  const startIdx = existing.indexOf(MARKER_START);
+  const endIdx = existing.indexOf(MARKER_END);
+  if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
+    const endOfEndLine = existing.indexOf(`
+`, endIdx);
+    const before = existing.slice(0, startIdx);
+    const after = endOfEndLine === -1 ? "" : existing.slice(endOfEndLine + 1);
+    const existingBlock = existing.slice(startIdx, endOfEndLine === -1 ? existing.length : endOfEndLine);
+    if (existingBlock === block) {
+      return { rcPath, action: "unchanged" };
+    }
+    const next2 = ensureTrailingNewline(`${before}${block}
+${after}`);
+    await writeFile10(rcPath, next2, "utf8");
+    return { rcPath, action: "replaced-block" };
+  }
+  await mkdir13(dirname3(rcPath), { recursive: true });
+  const sep = existing.length === 0 || existing.endsWith(`
+`) ? "" : `
+`;
+  const next = `${existing}${sep}${block}
+`;
+  await writeFile10(rcPath, next, "utf8");
+  return { rcPath, action: "created-block" };
+}
+
+// src/install/harness.ts
+import { spawnSync } from "node:child_process";
+import { mkdir as mkdir14, readFile as readFile10, writeFile as writeFile11 } from "node:fs/promises";
+import { homedir as homedir2 } from "node:os";
+import { dirname as dirname4, join as join13 } from "node:path";
+async function installMcpServer(harness, name, cfg, opts = {}) {
+  switch (harness) {
+    case "claude":
+      return installClaude(name, cfg, opts);
+    case "codex":
+      return installCodex(name, cfg);
+    case "opencode":
+      return installOpencode(name, cfg);
+    default: {
+      const exhaustive = harness;
+      throw new Error(`unknown harness: ${String(exhaustive)}`);
+    }
+  }
+}
+async function installClaude(name, cfg, opts) {
+  const path = opts.configPath ?? join13(opts.homeDir ?? homedir2(), ".claude.json");
+  let root;
+  let fileExisted;
+  try {
+    const text = await readFile10(path, "utf8");
+    const parsed = JSON.parse(text);
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+      throw new Error(`${path} does not contain a JSON object at its top level`);
+    }
+    root = parsed;
+    fileExisted = true;
+  } catch (err) {
+    if (err.code === "ENOENT") {
+      root = {};
+      fileExisted = false;
+    } else {
+      throw err;
+    }
+  }
+  const rawServers = root.mcpServers;
+  const mcpServers = typeof rawServers === "object" && rawServers !== null && !Array.isArray(rawServers) ? rawServers : {};
+  root.mcpServers = mcpServers;
+  const entry = { command: cfg.command, args: cfg.args };
+  if (Object.keys(cfg.env).length > 0)
+    entry.env = cfg.env;
+  const prior = mcpServers[name];
+  const action = prior === undefined ? "added" : canonicalJson(prior) === canonicalJson(entry) ? "unchanged" : "updated";
+  mcpServers[name] = entry;
+  if (action === "unchanged") {
+    return { harness: "claude", method: "file", path, action, detail: "no change needed" };
+  }
+  await mkdir14(dirname4(path), { recursive: true });
+  await writeFile11(path, JSON.stringify(root, null, 2) + `
+`, "utf8");
+  return {
+    harness: "claude",
+    method: "file",
+    path,
+    action,
+    detail: fileExisted ? undefined : "created new config file"
+  };
+}
+function canonicalJson(value) {
+  return JSON.stringify(canonicalize(value));
+}
+function canonicalize(value) {
+  if (Array.isArray(value))
+    return value.map(canonicalize);
+  if (value !== null && typeof value === "object") {
+    const out = {};
+    for (const key of Object.keys(value).sort()) {
+      out[key] = canonicalize(value[key]);
+    }
+    return out;
+  }
+  return value;
+}
+function codexAddArgs(name, cfg) {
+  const envArgs = Object.entries(cfg.env).flatMap(([k, v]) => ["--env", `${k}=${v}`]);
+  return ["mcp", "add", name, ...envArgs, "--", cfg.command, ...cfg.args];
+}
+async function installCodex(name, cfg) {
+  if (!isOnPath("codex")) {
+    throw new Error("codex CLI not found on PATH — install Codex or pick a different harness");
+  }
+  const probe = spawnSync("codex", ["mcp", "get", name], { encoding: "utf8" });
+  const exists = probe.status === 0;
+  if (exists) {
+    const removed = spawnSync("codex", ["mcp", "remove", name], { encoding: "utf8" });
+    if (removed.status !== 0) {
+      throw new Error(`codex mcp remove ${name} failed: ${(removed.stderr || removed.stdout || "").trim()}`);
+    }
+  }
+  const addArgs = codexAddArgs(name, cfg);
+  const added = spawnSync("codex", addArgs, { encoding: "utf8" });
+  if (added.status !== 0) {
+    throw new Error(`codex ${addArgs.join(" ")} failed: ${(added.stderr || added.stdout || "").trim()}`);
+  }
+  return {
+    harness: "codex",
+    method: "cli",
+    action: exists ? "updated" : "added",
+    detail: added.stdout?.trim() || undefined
+  };
+}
+function opencodeAddArgs(name, cfg) {
+  const envArgs = Object.entries(cfg.env).flatMap(([k, v]) => ["--env", `${k}=${v}`]);
+  return ["mcp", "add", name, ...envArgs, "--", cfg.command, ...cfg.args];
+}
+async function installOpencode(name, cfg) {
+  if (!isOnPath("opencode")) {
+    throw new Error("opencode CLI not found on PATH — install OpenCode or pick a different harness");
+  }
+  const addArgs = opencodeAddArgs(name, cfg);
+  const added = spawnSync("opencode", addArgs, { encoding: "utf8" });
+  if (added.status !== 0) {
+    throw new Error(`opencode ${addArgs.join(" ")} failed: ${(added.stderr || added.stdout || "").trim()}`);
+  }
+  return {
+    harness: "opencode",
+    method: "cli",
+    action: "added",
+    detail: added.stdout?.trim() || undefined
+  };
+}
+function isOnPath(bin) {
+  const finder = process.platform === "win32" ? "where" : "which";
+  const result = spawnSync(finder, [bin], { encoding: "utf8" });
+  return result.status === 0;
+}
+
+// src/install/wizard.ts
+var DEFAULT_NAME = "cdp-toolkit";
+var HARNESSES = ["claude", "codex", "opencode"];
+var BROWSERS = ["arc", "chrome", "firefox"];
+function defaultPortFor(browser) {
+  return browser === "firefox" ? 9223 : 9222;
+}
+function parseHarness(v) {
+  if (v === undefined)
+    throw new Error("--harness requires a value: claude, codex, or opencode");
+  if (HARNESSES.includes(v))
+    return v;
+  throw new Error(`--harness must be one of claude|codex|opencode (got '${v}')`);
+}
+function parseBrowserChoice(v) {
+  if (v === undefined)
+    throw new Error("--browser requires a value: arc, chrome, or firefox");
+  if (BROWSERS.includes(v))
+    return v;
+  throw new Error(`--browser must be one of arc|chrome|firefox (got '${v}')`);
+}
+function parsePort(v) {
+  if (v === undefined)
+    throw new Error("--port requires a value (an integer 1-65535)");
+  const n = Number(v);
+  if (!Number.isInteger(n) || n < 1 || n > 65535) {
+    throw new Error(`--port must be an integer 1-65535 (got '${v}')`);
+  }
+  return n;
+}
+function normalizeArgv(argv) {
+  const out = [];
+  for (const t of argv) {
+    if (t.startsWith("--") && t.includes("=")) {
+      const eq = t.indexOf("=");
+      out.push(t.slice(0, eq), t.slice(eq + 1));
+    } else {
+      out.push(t);
+    }
+  }
+  return out;
+}
+function parseInstallArgs(argv) {
+  const tokens = normalizeArgv(argv);
+  const out = { name: DEFAULT_NAME, alias: true };
+  for (let i = 0;i < tokens.length; i++) {
+    const t = tokens[i];
+    switch (t) {
+      case "--help":
+      case "-h":
+        out.help = true;
+        break;
+      case "--yes":
+      case "-y":
+        out.yes = true;
+        break;
+      case "--no-alias":
+        out.alias = false;
+        break;
+      case "--alias":
+        out.alias = true;
+        break;
+      case "--harness":
+        out.harness = parseHarness(tokens[++i]);
+        break;
+      case "--browser":
+        out.browser = parseBrowserChoice(tokens[++i]);
+        break;
+      case "--port":
+        out.port = parsePort(tokens[++i]);
+        break;
+      case "--name": {
+        const v = tokens[++i];
+        if (v === undefined)
+          throw new Error("--name requires a value");
+        out.name = v;
+        break;
+      }
+      case "--alias-name": {
+        const v = tokens[++i];
+        if (v === undefined)
+          throw new Error("--alias-name requires a value");
+        out.aliasName = v;
+        break;
+      }
+      default:
+        throw new Error(`cdp install: unknown option '${t}' (run \`cdp install --help\`)`);
+    }
+  }
+  return out;
+}
+function composeServerConfig(browser, port) {
+  const env = browser === "firefox" ? { CDP_BROWSER: "firefox", CDP_FIREFOX_ENDPOINT: String(port) } : { CDP_BASE: `http://127.0.0.1:${port}` };
+  return { command: "npx", args: ["-y", "cdp-toolkit"], env };
+}
+function installHelpText() {
+  return `cdp install — register the cdp-toolkit MCP server with your coding harness and add a
+browser-launch alias (with the remote-debugging port open) to your shell rc.
+
+Usage:
+  cdp install [--harness <claude|codex|opencode>] [--browser <arc|chrome|firefox>]
+              [--port <n>] [--name <server-name>] [--alias-name <name>]
+              [--no-alias] [--yes|-y] [--help|-h]
+
+Options:
+  --harness <h>     Coding harness to register the MCP server with: claude, codex, opencode.
+  --browser <b>     Browser the alias launches: arc, chrome, firefox.
+  --port <n>        Remote-debugging port (1-65535). Default: 9222 (chrome/arc), 9223 (firefox).
+  --name <name>     MCP server name to register. Default: ${DEFAULT_NAME}.
+  --alias-name <n>  Shell alias name. Default: cdp-<browser> (e.g. cdp-firefox).
+  --no-alias        Register the MCP server only; skip writing the shell alias.
+  --yes, -y         Skip the confirmation prompt (proceed immediately).
+  --help, -h        Show this help.
+
+Interactive: run \`cdp install\` in a terminal with no flags and it prompts for harness, browser,
+and port, then asks before writing anything.
+
+Non-interactive (piped/CI): pass at least --harness and --browser (port defaults per browser); a
+missing required value fails fast with usage instead of hanging on stdin.`;
+}
+async function ask(question) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    return await new Promise((resolve) => rl.question(question, resolve));
+  } finally {
+    rl.close();
+  }
+}
+async function promptMenu(label, options) {
+  const lines = [label];
+  options.forEach((o, i) => lines.push(`  ${i + 1}) ${o}`));
+  process.stdout.write(`${lines.join(`
+`)}
+`);
+  for (;; ) {
+    const ans = (await ask(`Enter 1-${options.length}: `)).trim();
+    const n = Number(ans);
+    if (Number.isInteger(n) && n >= 1 && n <= options.length)
+      return options[n - 1];
+    process.stdout.write(`Please enter a number between 1 and ${options.length}.
+`);
+  }
+}
+async function promptPort(def) {
+  for (;; ) {
+    const ans = (await ask(`Remote-debugging port [${def}]: `)).trim();
+    if (ans === "")
+      return def;
+    const n = Number(ans);
+    if (Number.isInteger(n) && n >= 1 && n <= 65535)
+      return n;
+    process.stdout.write(`Please enter an integer between 1 and 65535.
+`);
+  }
+}
+function harnessTargetDesc(harness, io) {
+  if (harness === "claude") {
+    return io.configPath ?? join14(io.homeDir ?? homedir3(), ".claude.json");
+  }
+  return `via \`${harness} mcp add\``;
+}
+function binEnvVar(browser) {
+  return `${browser.toUpperCase()}_BIN`;
+}
+async function runInstaller(argv, io = {}) {
+  const write = io.stdout ?? ((s) => void process.stdout.write(s));
+  const writeErr = io.stderr ?? ((s) => void process.stderr.write(s));
+  const isTTY = io.isTTY ?? Boolean(process.stdin.isTTY);
+  let args;
+  try {
+    args = parseInstallArgs(argv);
+  } catch (err) {
+    writeErr(`${err.message}
+
+`);
+    writeErr(`${installHelpText()}
+`);
+    return 1;
+  }
+  if (args.help) {
+    write(`${installHelpText()}
+`);
+    return 0;
+  }
+  let harness = args.harness;
+  let browser = args.browser;
+  let port = args.port;
+  if (isTTY) {
+    if (harness === undefined)
+      harness = await promptMenu("Which coding harness?", HARNESSES);
+    if (browser === undefined)
+      browser = await promptMenu("Which browser?", BROWSERS);
+    if (port === undefined)
+      port = await promptPort(defaultPortFor(browser));
+  } else {
+    const missing = [];
+    if (harness === undefined)
+      missing.push("--harness");
+    if (browser === undefined)
+      missing.push("--browser");
+    if (missing.length > 0) {
+      writeErr(`cdp install: missing required option(s) ${missing.join(", ")} in non-interactive mode.
+`);
+      writeErr("Run `cdp install` in a terminal to be prompted, or pass the option(s) explicitly.\n\n");
+      writeErr(`${installHelpText()}
+`);
+      return 1;
+    }
+    if (port === undefined)
+      port = defaultPortFor(browser);
+  }
+  if (harness === undefined || browser === undefined || port === undefined) {
+    writeErr(`cdp install: internal error resolving options
+`);
+    return 1;
+  }
+  const name = args.name ?? DEFAULT_NAME;
+  const writeAlias = args.alias !== false;
+  const rcPath = io.rcPath ?? detectShellRc();
+  const resolvedAliasName = args.aliasName ?? defaultAliasName(browser);
+  const line = aliasLine({ choice: browser, port, aliasName: args.aliasName });
+  if (!args.yes && isTTY) {
+    const plan = [
+      "",
+      "About to:",
+      `  - Register MCP server "${name}" with ${harness}  (${harnessTargetDesc(harness, io)})`,
+      writeAlias ? `  - Append a shell alias to ${rcPath}:
+      ${line}` : "  - (skipping shell alias: --no-alias)",
+      ""
+    ].join(`
+`);
+    write(`${plan}
+`);
+    const ans = (await ask("Proceed? [y/N] ")).trim();
+    if (!/^y(es)?$/i.test(ans)) {
+      write(`Aborted. Nothing was written.
+`);
+      return 0;
+    }
+  }
+  let harnessResult;
+  try {
+    harnessResult = await installMcpServer(harness, name, composeServerConfig(browser, port), {
+      configPath: io.configPath,
+      homeDir: io.homeDir
+    });
+  } catch (err) {
+    writeErr(`cdp install: could not register the MCP server with ${harness}: ${err.message}
+`);
+    return 1;
+  }
+  let rcResult;
+  let browserFound = true;
+  if (writeAlias) {
+    rcResult = await appendAliasToRc(rcPath, line);
+    browserFound = detectBrowser(browser).found;
+    if (!browserFound) {
+      writeErr(`
+Warning: could not find the ${browser} binary at its expected location. The alias was ` + `written anyway, but \`${resolvedAliasName}\` will not launch until the binary is found.
+` + `  Fix: set ${binEnvVar(browser)}=/path/to/${browser} and re-run \`cdp install\`, or edit the
+` + `  alias line in ${rcPath} to point at the real binary.
+`);
+    }
+  }
+  const summary = [
+    "",
+    "cdp-toolkit install complete.",
+    "",
+    `Harness: ${harness}`,
+    `  server name: ${name}`,
+    harnessResult.path ? `  config:      ${harnessResult.path}` : `  registered:  ${harnessTargetDesc(harness, io)}`,
+    `  method:      ${harnessResult.method}`,
+    `  action:      ${harnessResult.action}${harnessResult.detail ? `  (${harnessResult.detail})` : ""}`
+  ];
+  if (writeAlias && rcResult) {
+    summary.push("", `Browser alias: ${resolvedAliasName} -> ${rcResult.rcPath}`, `  action:  ${rcResult.action}`, `  line:    ${line}`);
+    if (!browserFound)
+      summary.push(`  note:    ${browser} binary not found yet (see warning above)`);
+  } else {
+    summary.push("", "Browser alias: skipped (--no-alias).");
+  }
+  summary.push("", "Next steps:");
+  if (writeAlias && rcResult) {
+    summary.push(`  1. Load the alias into your shell:  source ${rcResult.rcPath}   (or open a new terminal)`, `  2. Launch the browser with the debug port open:  ${resolvedAliasName}`, `  3. Restart / reconnect ${harness} so it picks up the "${name}" MCP server.`);
+    if (browser === "firefox") {
+      summary.push("", "Firefox note: the alias includes --marionette, which cdp-toolkit needs for its orphan", "auto-recovery path — don't remove it.");
+    }
+  } else {
+    summary.push(`  1. Restart / reconnect ${harness} so it picks up the "${name}" MCP server.`);
+  }
+  summary.push("");
+  write(`${summary.join(`
+`)}
+`);
+  return 0;
+}
+
 // src/cli.ts
 var USAGE = `cdp-toolkit: raw single-target CDP, 29-tool chrome-devtools-mcp parity, plus a Firefox backend over WebDriver BiDi.
 
@@ -9034,6 +9952,9 @@ function printToolHelp(name) {
 }
 async function main() {
   const rawArgv = process.argv.slice(2);
+  if (rawArgv[0] === "install") {
+    return await runInstaller(rawArgv.slice(1));
+  }
   const { kind: browser, endpoint } = resolveBackend(rawArgv);
   const parsed = parseArgv(stripConnectFlag(stripBrowserFlag(rawArgv)));
   if (parsed.help) {