@buoy-gg/mcp 7.0.36 → 7.0.39

package/dist/{chunk-QIINQPNK.mjs → chunk-UXLRYEUQ.mjs}

@@ -12,6 +12,189 @@ var DEVICE_RETENTION_MS = 15 * 6e4;
 var DASHBOARD_NAME = "Dashboard";
 var ALL_DEVICES = "All";
 
+// src/sync/NodeAccount.ts
+import { readFileSync, writeFileSync, mkdirSync, renameSync, unlinkSync } from "fs";
+import { dirname, join, resolve } from "path";
+import { homedir } from "os";
+import { createHash } from "crypto";
+import {
+  validateLicense,
+  isAcceptedValidation,
+  isTransientLicenseError,
+  resolveTier,
+  isRecognizedAccount,
+  isBuoyToken,
+  verifyFreeToken,
+  resolveAccountAccess,
+  signCache,
+  verifyCacheSignature,
+  LICENSE_LAUNCH_VALIDATION_TTL,
+  LICENSE_REVALIDATION_INTERVAL,
+  LICENSE_TRANSIENT_RETRY_DELAYS,
+  KEYGEN_CONFIG
+} from "@buoy-gg/license/headless";
+var KEY_NAMES = ["BUOY_LICENSE_KEY", "BUOY_KEY", "EXPO_PUBLIC_BUOY_KEY", "VITE_BUOY_KEY", "REACT_APP_BUOY_KEY"];
+function readProjectKey(projectDir, env = process.env) {
+  for (const name of KEY_NAMES) if (env[name] !== void 0) return env[name].trim().toUpperCase() || null;
+  for (const file of [".env.development.local", ".env.local", ".env"]) {
+    let contents;
+    try {
+      contents = readFileSync(join(projectDir, file), "utf8");
+    } catch {
+      continue;
+    }
+    const values = /* @__PURE__ */ new Map();
+    for (const line of contents.split(/\r?\n/)) {
+      const match = line.match(/^\s*(?:export\s+)?([A-Z_][A-Z_0-9]*)\s*=\s*(.*)$/);
+      if (!match) continue;
+      const raw = match[2].trim();
+      const quoted = raw.match(/^(['"])(.*?)\1\s*(?:#.*)?$/);
+      values.set(match[1], quoted ? quoted[2] : raw.split("#")[0].trim());
+    }
+    for (const name of KEY_NAMES) if (values.has(name)) return values.get(name).trim().toUpperCase() || null;
+  }
+  return null;
+}
+var NodeAccount = class {
+  constructor(changed, opts = {}) {
+    this.changed = changed;
+    this.key = null;
+    this.cache = null;
+    this.timer = null;
+    this.generation = 0;
+    this.busy = false;
+    this.nextCheck = 0;
+    this.retry = 0;
+    this.lastAdmission = false;
+    this.hasAccess = () => resolveAccountAccess({
+      initialized: true,
+      validating: false,
+      key: this.key,
+      tierSource: this.cache?.tier ? "key" : "none",
+      verifiedAt: this.cache?.cachedAt ?? null
+    }).status === "admitted";
+    this.projectDir = resolve(opts.projectDir ?? process.env.BUOY_PROJECT_DIR ?? process.cwd());
+    const project = createHash("sha256").update(this.projectDir).digest("hex").slice(0, 20);
+    this.cacheFile = opts.cacheFile ?? join(homedir(), ".buoy", `account-${project}.json`);
+  }
+  start() {
+    if (this.timer) return;
+    try {
+      const cached = JSON.parse(readFileSync(this.cacheFile, "utf8"));
+      if (cached.valid && verifyCacheSignature(cached)) this.cache = cached;
+    } catch {
+    }
+    void this.tick();
+    this.timer = setInterval(() => {
+      void this.tick();
+    }, 1e3);
+    this.timer.unref();
+  }
+  stop() {
+    ++this.generation;
+    if (this.timer) clearInterval(this.timer);
+    this.timer = null;
+    this.key = null;
+    this.cache = null;
+    this.notify();
+  }
+  notify() {
+    const admitted = this.hasAccess();
+    if (admitted === this.lastAdmission) return;
+    this.lastAdmission = admitted;
+    this.changed();
+  }
+  async tick() {
+    const selected = readProjectKey(this.projectDir);
+    if (selected !== this.key) {
+      ++this.generation;
+      this.key = selected;
+      if (this.cache?.licenseKey !== selected) this.cache = null;
+      this.nextCheck = 0;
+      this.retry = 0;
+      if (!selected) this.removeCache();
+    }
+    this.notify();
+    if (!selected || this.busy || Date.now() < this.nextCheck) return;
+    if (this.cache && this.hasAccess() && Date.now() - this.cache.lastValidatedAt < LICENSE_LAUNCH_VALIDATION_TTL && this.nextCheck === 0) {
+      this.nextCheck = this.cache.lastValidatedAt + LICENSE_LAUNCH_VALIDATION_TTL;
+      return;
+    }
+    this.busy = true;
+    const startedAt = this.generation;
+    try {
+      if (isBuoyToken(selected)) {
+        const claims = verifyFreeToken(selected);
+        if (!claims) {
+          this.cache = null;
+          this.removeCache();
+        } else {
+          const now2 = Date.now();
+          this.cache = signCache({
+            licenseKey: selected,
+            licenseId: `token:${claims.accountHash}`,
+            valid: true,
+            tier: "free",
+            isPro: false,
+            expiresAt: null,
+            cachedAt: now2,
+            lastValidatedAt: now2
+          });
+          this.persistCache();
+        }
+        this.nextCheck = Date.now() + LICENSE_REVALIDATION_INTERVAL;
+        return;
+      }
+      const response = await validateLicense(selected);
+      if (startedAt !== this.generation || readProjectKey(this.projectDir) !== selected) return;
+      const product = response.data?.relationships?.product?.data?.id;
+      const expired = response.meta.code === "EXPIRED" && (isRecognizedAccount(response.data) || this.cache?.licenseKey === selected);
+      if (product && product !== KEYGEN_CONFIG.productId || !expired && !isAcceptedValidation(response)) {
+        this.cache = null;
+        this.removeCache();
+        this.nextCheck = Date.now() + LICENSE_REVALIDATION_INTERVAL;
+        return;
+      }
+      const tier = expired ? "free" : resolveTier(response.data);
+      const now = Date.now();
+      this.cache = signCache({
+        licenseKey: selected,
+        licenseId: response.data?.id ?? "",
+        valid: true,
+        tier,
+        isPro: tier === "pro",
+        expiresAt: expired ? null : response.data.attributes.expiry,
+        cachedAt: now,
+        lastValidatedAt: now
+      });
+      this.persistCache();
+      this.retry = 0;
+      this.nextCheck = now + LICENSE_REVALIDATION_INTERVAL;
+    } catch (error) {
+      if (startedAt !== this.generation) return;
+      const delay6 = isTransientLicenseError(error) ? LICENSE_TRANSIENT_RETRY_DELAYS[this.retry++] : void 0;
+      this.nextCheck = Date.now() + (delay6 ?? LICENSE_REVALIDATION_INTERVAL);
+    } finally {
+      this.busy = false;
+      this.notify();
+    }
+  }
+  persistCache() {
+    try {
+      mkdirSync(dirname(this.cacheFile), { recursive: true, mode: 448 });
+      writeFileSync(`${this.cacheFile}.tmp`, JSON.stringify(this.cache), { mode: 384 });
+      renameSync(`${this.cacheFile}.tmp`, this.cacheFile);
+    } catch {
+    }
+  }
+  removeCache() {
+    try {
+      unlinkSync(this.cacheFile);
+    } catch {
+    }
+  }
+};
+
 // src/sync/SyncClient.ts
 import http from "http";
 import { randomUUID } from "crypto";
@@ -51,6 +234,9 @@ function diagnoseCrashed(opts) {
 var SyncClient = class {
   constructor(opts = {}) {
     this.socket = null;
+    this.admitted = false;
+    this.lockedDevices = /* @__PURE__ */ new Set();
+    this.hostAccount = null;
     this.broker = null;
     /** Latest capabilities announce per deviceId. */
     this.capabilities = /* @__PURE__ */ new Map();
@@ -99,7 +285,10 @@ var SyncClient = class {
         );
       }
       this.log(`no broker at ${this.url} \u2014 spawning one in-process on :${this.port}`);
+      this.hostAccount = new NodeAccount(() => this.broker?.refreshAccess());
+      this.hostAccount.start();
       this.broker = createBroker({
+        canUseDesktop: this.hostAccount.hasAccess,
         port: this.port,
         onError: (e) => this.log(`broker error: ${e.code ?? e.message}`)
       });
@@ -112,7 +301,7 @@ var SyncClient = class {
     return mode;
   }
   connectSocket() {
-    return new Promise((resolve, reject) => {
+    return new Promise((resolve2, reject) => {
       const socket = ioClient(this.url, {
         transports: ["websocket"],
         query: { deviceName: DASHBOARD_NAME },
@@ -122,31 +311,59 @@ var SyncClient = class {
       });
       this.socket = socket;
       let settled = false;
-      const onConnect = () => {
+      const onReady = () => {
         if (settled) return;
         settled = true;
         this.log("connected to broker");
-        resolve();
+        resolve2();
       };
-      socket.on("connect", onConnect);
-      socket.on("connect", () => this.rearmWatches());
+      const readinessTimeout = setTimeout(() => {
+        if (settled) return;
+        settled = true;
+        reject(new Error("Broker account is locked or the broker needs an update. Sign in to Buoy Desktop or run npx buoy login for standalone MCP."));
+      }, 5e3);
+      socket.on("buoy:access", (message) => {
+        const ready = !!message && typeof message === "object" && message.protocol === 1 && message.ready === true;
+        this.setAdmission(ready);
+        if (ready) {
+          clearTimeout(readinessTimeout);
+          this.rearmWatches();
+          onReady();
+        }
+      });
+      socket.on("connect", () => {
+        socket.emit("buoy:access:request");
+      });
+      socket.on("disconnect", () => this.setAdmission(false, true));
       socket.once("connect_error", (err) => {
         if (settled) return;
         settled = true;
+        clearTimeout(readinessTimeout);
         reject(new Error(`failed to connect to broker at ${this.url}: ${err.message}`));
       });
       socket.on("devtool-capabilities", (msg) => {
+        if (!this.admitted || this.lockedDevices.has(msg.persistentDeviceId)) return;
         this.capabilities.set(msg.persistentDeviceId, msg);
         void this.learnDevServerOrigin(msg.persistentDeviceId);
       });
       socket.on("all-devices-update", (list) => {
+        if (!this.admitted) return;
         if (!Array.isArray(list)) return;
+        let deviceReadmitted = false;
+        for (const device of list) {
+          if (device.deviceId && device.tier === "locked") this.lockDevice(String(device.deviceId));
+          else if (device.deviceId && (device.tier === "free" || device.tier === "pro")) {
+            deviceReadmitted = this.lockedDevices.delete(String(device.deviceId)) || deviceReadmitted;
+          }
+        }
         this.devices = list;
         const now = Date.now();
         for (const d of list) if (d.deviceId) this.lastSeen.set(d.deviceId, now);
         this.pruneStaleDevices();
+        if (deviceReadmitted) this.rearmWatches();
       });
       socket.on("devtool-sync", (msg) => {
+        if (!this.admitted || this.lockedDevices.has(msg.persistentDeviceId)) return;
         const key = snapKey(msg.persistentDeviceId, msg.toolId);
         this.snapshots.set(key, msg.payload);
         this.snapshotAt.set(key, Date.now());
@@ -157,6 +374,7 @@ var SyncClient = class {
         }
       });
       socket.on("devtool-action-result", (msg) => {
+        if (!this.admitted) return;
         const pending = this.pendingActions.get(msg.requestId);
         if (!pending) return;
         this.pendingActions.delete(msg.requestId);
@@ -174,6 +392,55 @@ var SyncClient = class {
    * with every simulator erase and fresh dev client, and each one can hold
    * multi-MB snapshots, so a long-lived server has to forget eventually.
    */
+  requireAdmission() {
+    if (!this.admitted) throw new Error("A verified Buoy account and an updated broker are required. Sign in to Buoy Desktop, or run npx buoy login for standalone MCP.");
+  }
+  setAdmission(ready, preserveWatchIntent = false) {
+    this.admitted = ready;
+    if (ready) return;
+    this.devices = [];
+    this.lockedDevices.clear();
+    this.capabilities.clear();
+    this.snapshots.clear();
+    this.snapshotAt.clear();
+    this.devServerOrigins.clear();
+    this.originProbed.clear();
+    this.health.clear();
+    this.lastSeen.clear();
+    if (!preserveWatchIntent) this.watching.clear();
+    for (const pending of this.pendingActions.values()) {
+      clearTimeout(pending.timer);
+      pending.reject(new Error("Buoy account access ended while the action was pending."));
+    }
+    this.pendingActions.clear();
+    for (const waiters of this.snapshotWaiters.values()) for (const waiter of waiters) waiter(void 0);
+    this.snapshotWaiters.clear();
+    if (this.socket) this.socket.sendBuffer = [];
+  }
+  requireDeviceAccount(deviceId) {
+    if (this.lockedDevices.has(deviceId)) throw new Error("The device's Buoy account access ended. Sign in and verify its key.");
+  }
+  lockDevice(deviceId) {
+    this.lockedDevices.add(deviceId);
+    this.capabilities.delete(deviceId);
+    this.health.delete(deviceId);
+    this.devServerOrigins.delete(deviceId);
+    this.originProbed.delete(deviceId);
+    const prefix = `${deviceId}::`;
+    for (const key of this.snapshots.keys()) if (key.startsWith(prefix)) {
+      this.snapshots.delete(key);
+      this.snapshotAt.delete(key);
+    }
+    for (const [key, waiters] of this.snapshotWaiters) if (key.startsWith(prefix)) {
+      this.snapshotWaiters.delete(key);
+      for (const waiter of waiters) waiter(void 0);
+    }
+    for (const [id, pending] of this.pendingActions) if (pending.target === deviceId || pending.target === ALL_DEVICES) {
+      clearTimeout(pending.timer);
+      this.pendingActions.delete(id);
+      pending.reject(new Error("Device account access ended while the action was pending."));
+    }
+  }
   pruneStaleDevices() {
     const cutoff = Date.now() - DEVICE_RETENTION_MS;
     for (const [deviceId, seen] of this.lastSeen) {
@@ -198,6 +465,9 @@ var SyncClient = class {
   }
   /** Disconnect and tear down a spawned broker, if any. */
   async stop() {
+    this.setAdmission(false);
+    this.hostAccount?.stop();
+    this.hostAccount = null;
     for (const [, p] of this.pendingActions) {
       clearTimeout(p.timer);
       p.reject(new Error("SyncClient stopped"));
@@ -217,6 +487,7 @@ var SyncClient = class {
   // ----------------------------------------------------------------
   /** All devices the broker knows about, merged with their advertised tools. */
   listDevices() {
+    if (!this.admitted) return [];
     return this.devices.filter((d) => d.deviceName !== DASHBOARD_NAME && d.deviceId).map((d) => {
       const caps = this.capabilities.get(d.deviceId);
       return {
@@ -225,7 +496,7 @@ var SyncClient = class {
         platform: d.platform,
         isConnected: d.isConnected !== false,
         isPro: d.isPro === true,
-        tier: d.tier ?? (d.isPro === true ? "pro" : "anonymous"),
+        tier: d.tier === "free" || d.tier === "pro" ? d.tier : d.tier === void 0 && d.isPro === true ? "pro" : "locked",
         collision: d.collision === true,
         tools: caps?.tools ?? []
       };
@@ -248,9 +519,19 @@ var SyncClient = class {
    * or many, an informative error is thrown (callers can pass "All" explicitly).
    */
   resolveDevice(deviceId) {
-    if (deviceId) return deviceId;
-    const connected = this.connectedDevices();
+    this.requireAdmission();
+    if (deviceId) {
+      this.requireDeviceAccount(deviceId);
+      return deviceId;
+    }
+    const allConnected = this.connectedDevices();
+    const connected = allConnected.filter((d) => !this.lockedDevices.has(d.deviceId));
     if (connected.length === 0) {
+      if (allConnected.length > 0) {
+        throw new Error(
+          `Devices are connected (${allConnected.map((d) => d.deviceName).join(", ")}), but the broker has not admitted their accounts. Check app account validation and the account announcement after reconnect; this does not prove the user is signed out.`
+        );
+      }
       throw new Error("No devices are connected to the broker. Open the app with Buoy devtools running.");
     }
     if (connected.length === 1) return connected[0].deviceId;
@@ -276,9 +557,10 @@ var SyncClient = class {
    * is blocked.
    */
   requireProDevice(deviceId) {
+    this.requireAdmission();
     const tierNote = (dev2) => {
       if (!dev2) return "";
-      return dev2.tier === "anonymous" ? ` The connected app "${dev2.deviceName}" has no license key at all.` : ` The connected app "${dev2.deviceName}" is on the ${dev2.tier} tier.`;
+      return dev2.tier === "locked" ? ` The broker has not confirmed account access for "${dev2.deviceName}"; a locked status does not establish whether a key is configured.` : ` The connected app "${dev2.deviceName}" is on the ${dev2.tier} tier.`;
     };
     const proMsg = (dev2) => `Buoy Pro is required to use the MCP.${tierNote(
       dev2
@@ -393,6 +675,7 @@ var SyncClient = class {
   }
   /** Age of the cached snapshot for a tool, in ms (null = never received). */
   snapshotAgeMs(toolId, deviceId) {
+    this.requireAdmission();
     const at = this.snapshotAt.get(snapKey(deviceId, toolId));
     return at ? Date.now() - at : null;
   }
@@ -428,6 +711,7 @@ var SyncClient = class {
   }
   /** The dev-server origin last reported by this device, if any. */
   devServerOrigin(deviceId) {
+    this.requireAdmission();
     const known = this.devServerOrigins.get(deviceId);
     if (known) return known;
     const snap = this.snapshots.get(snapKey(deviceId, "app"));
@@ -461,6 +745,7 @@ var SyncClient = class {
     this.sendWatch(toolId, targetDeviceId);
   }
   sendWatch(toolId, targetDeviceId) {
+    if (!this.admitted || !this.socket?.connected || this.lockedDevices.has(targetDeviceId)) return;
     this.socket?.emit("devtool-watch", {
       toolId,
       targetDeviceId,
@@ -486,10 +771,12 @@ var SyncClient = class {
   unwatch(toolId, targetDeviceId) {
     const key = snapKey(targetDeviceId, toolId);
     if (!this.watching.delete(key)) return;
-    this.socket?.emit("devtool-watch", { toolId, targetDeviceId, watching: false });
+    if (this.admitted && this.socket?.connected) this.socket.emit("devtool-watch", { toolId, targetDeviceId, watching: false });
   }
   /** Last snapshot received for a tool/device, if any. */
   cachedSnapshot(toolId, deviceId) {
+    this.requireAdmission();
+    this.requireDeviceAccount(deviceId);
     return this.snapshots.get(snapKey(deviceId, toolId));
   }
   /**
@@ -517,6 +804,8 @@ var SyncClient = class {
     const next = this.waitForSnapshot(key, budget);
     this.socket?.emit("request-devtool-state", { toolId, targetDeviceId: target });
     const payload = await next;
+    this.requireAdmission();
+    this.requireDeviceAccount(target);
     if (payload !== void 0) {
       if (!opts.silent) this.noteOk(target);
       return { deviceId: target, payload };
@@ -537,16 +826,16 @@ var SyncClient = class {
     return `\u26A0\uFE0F Served from the last sync (${ageText}) \u2014 ${this.unresponsiveNote(deviceId)}`;
   }
   waitForSnapshot(key, timeoutMs) {
-    return new Promise((resolve) => {
+    return new Promise((resolve2) => {
       const waiters = this.snapshotWaiters.get(key) ?? [];
       const timer = setTimeout(() => {
         const remaining = (this.snapshotWaiters.get(key) ?? []).filter((w) => w !== onSnap);
         this.snapshotWaiters.set(key, remaining);
-        resolve(void 0);
+        resolve2(void 0);
       }, timeoutMs);
       const onSnap = (payload) => {
         clearTimeout(timer);
-        resolve(payload);
+        resolve2(payload);
       };
       waiters.push(onSnap);
       this.snapshotWaiters.set(key, waiters);
@@ -560,11 +849,12 @@ var SyncClient = class {
    * target one device, or "All" to broadcast (resolves with the first responder).
    */
   async callAction(toolId, action, params, deviceId, opts = {}) {
+    this.requireAdmission();
     const target = deviceId === ALL_DEVICES ? ALL_DEVICES : this.resolveDevice(deviceId);
     if (!this.socket) throw new Error("SyncClient is not connected");
     const requestId = randomUUID();
     const timeoutMs = opts.timeoutMs ?? this.timeoutFor(target, toolId, action);
-    const result = await new Promise((resolve, reject) => {
+    const result = await new Promise((resolve2, reject) => {
       const timer = setTimeout(() => {
         this.pendingActions.delete(requestId);
         if (target !== ALL_DEVICES && !opts.silent) this.noteTimeout(target);
@@ -574,7 +864,7 @@ var SyncClient = class {
           )
         );
       }, timeoutMs);
-      this.pendingActions.set(requestId, { resolve, reject, timer });
+      this.pendingActions.set(requestId, { resolve: resolve2, reject, timer, target });
       this.socket.emit("devtool-action", {
         requestId,
         toolId,
@@ -592,16 +882,16 @@ var SyncClient = class {
 };
 var snapKey = (deviceId, toolId) => `${deviceId}::${toolId}`;
 function probeBroker(url, timeoutMs = 800) {
-  return new Promise((resolve) => {
+  return new Promise((resolve2) => {
     const req = http.get(url, (res) => {
       res.resume();
-      resolve((res.statusCode ?? 0) > 0);
+      resolve2((res.statusCode ?? 0) > 0);
     });
     req.setTimeout(timeoutMs, () => {
       req.destroy();
-      resolve(false);
+      resolve2(false);
     });
-    req.on("error", () => resolve(false));
+    req.on("error", () => resolve2(false));
   });
 }
 async function waitForBroker(url, attempts = 20) {
@@ -614,7 +904,7 @@ async function waitForBroker(url, attempts = 20) {
 var delay = (ms) => new Promise((r) => setTimeout(r, ms));
 
 // src/version.ts
-var VERSION = "7.0.36" ? "7.0.36" : "0.0.0-dev";
+var VERSION = "7.0.39" ? "7.0.39" : "0.0.0-dev";
 var PACKAGE_NAME = "@buoy-gg/mcp";
 
 // src/update/checkForUpdate.ts
@@ -711,7 +1001,7 @@ function registerGenericTools(server, sync) {
       }
       const connected = devices.filter((d) => d.isConnected);
       const anyPro = connected.some((d) => d.isPro);
-      const anySignedIn = connected.some((d) => d.tier !== "anonymous");
+      const anySignedIn = connected.some((d) => d.tier !== "locked");
       const collided = connected.filter((d) => d.collision);
       return json({
         devices,
@@ -721,7 +1011,7 @@ function registerGenericTools(server, sync) {
         ...anyPro ? {} : {
           // A headless build has no on-device UI, so "upgrade in the app"
           // cannot be followed there — name the `licenseKey` prop too.
-          hint: anySignedIn ? "The Buoy MCP is a Pro feature \u2014 the connected device is signed in on the free tier, so data/action tools are blocked. Upgrade to Buoy Pro in the app, or pass `licenseKey` to `<FloatingDevTools />` if it runs headless." : "The Buoy MCP is a Pro feature \u2014 no connected device has an active Buoy Pro license, so data/action tools are blocked. Enter a license in the app, or pass `licenseKey` to `<FloatingDevTools />` if it runs headless (no on-device UI)."
+          hint: anySignedIn ? "The Buoy MCP is a Pro feature \u2014 the connected device is signed in on the free tier, so data/action tools are blocked. Upgrade to Buoy Pro in the app, or pass `licenseKey` to `<FloatingDevTools />` if it runs headless." : "The broker has not confirmed account access for the connected devices, so data/action tools are blocked. A locked status can mean missing configuration, pending/failed validation, or a missing account announcement after reconnect; it does not prove the user is signed out. Check app account status and broker compatibility."
         },
         ...updateNotice ? { updateAvailable: updateNotice } : {}
       });
@@ -1037,7 +1327,7 @@ function formatRankingMarkdown(ranking) {
   ].filter(Boolean).join(" \xB7 ");
   if (leaderLine) lines.push(`**Per-metric best:** ${leaderLine}`);
   lines.push(
-    ranking.balanced.length ? `**Balanced (caps nothing):** ${ranking.balanced.join(", ")}` : `**Balanced (caps nothing):** none \u2014 every case stressed at least one axis; pick by which trade-off you can accept.`
+    ranking.balanced.length ? `**No configured risk flags:** ${ranking.balanced.join(", ")}. Check missing metrics and workload requirements before choosing.` : `**No configured risk flags:** no candidates listed. Review failures, available metrics and flags before choosing.`
   );
   if (ranking.flagged.length) {
     lines.push(
@@ -1263,7 +1553,7 @@ function registerPerfMonitorTools(server, sync) {
   server.registerTool(
     "run_benchmark_batch",
     {
-      description: "Run a perf-monitor benchmark batch and return a RANKED comparison of all cases (winner by UI FPS). Give it a target route and a matrix of cases (each a name + query params that select a variant on that route); it navigates, records, and benchmarks each case on the device, then ranks them. This blocks until the batch completes (can be minutes for large batches). The app must have the target route render its variants from the params.",
+      description: "Run a perf-monitor benchmark batch and return per-metric leaders, risk flags and a comparison of available case results. Give it a target route and a matrix of cases (each a name + query params that select a variant on that route); it navigates, records, and benchmarks each case on the device, then ranks them. This blocks until the batch completes (can be minutes for large batches). The app must have the target route render its variants from the params.",
       inputSchema: {
         targetRoute: z3.string().describe('The screen to benchmark, e.g. "/perf-test". Reads case params to pick a variant.'),
         cases: z3.array(caseSchema).min(1).describe("The variants to compare. Case #0 is the baseline for deltas."),
@@ -1274,10 +1564,10 @@ function registerPerfMonitorTools(server, sync) {
         coolDownMs: z3.number().optional().describe("Idle between runs/cases for thermal recovery. Default 2000."),
         navTimeoutMs: z3.number().optional().describe("Max wait for navigation per run. Default 5000."),
         discardWarmupRuns: z3.number().optional().describe("Discard first N runs of each case before taking the median. Default 0."),
-        shuffleCases: z3.boolean().optional().describe("Interleave + shuffle case order to cancel thermal bias. Default on for >3 cases."),
+        shuffleCases: z3.boolean().optional().describe("Interleave and shuffle case order to reduce order-related bias. Default on for >3 cases."),
         reloadBetweenCases: z3.boolean().optional().describe("Fully reload JS between cases (needs <AutomationResumer/> mounted). Default false."),
         captureRenders: z3.boolean().optional().describe(
-          "Capture per-component render counts/durations during each run (needs @buoy-gg/highlight-updates installed; dev builds only). Adds slight JS-thread overhead applied equally to every case. Default true."
+          "Capture per-component render counts/durations during each run (needs @buoy-gg/highlight-updates installed; dev builds only). Adds instrumentation overhead that can vary with the workload. Default true."
         ),
         deviceId: z3.string().optional().describe("Target device id. Omit to auto-select when one device is connected."),
         maxWaitMs: z3.number().optional().describe("Safety cap for how long to wait for completion. Defaults to ~3\xD7 the estimate + 60s.")
@@ -1471,7 +1761,7 @@ ${JSON.stringify(ranking, null, 2)}
   server.registerTool(
     "compare_reports",
     {
-      description: "Compare two saved benchmark runs head-to-head: avg + p95 for FPS/CPU/memory, jank, AND render counts \u2014 total, commits, and wasted (parent cascades + identity-only prop churn) \u2014 each with deltas. Use this to prove a memoization or re-render fix actually landed: the wasted-render delta is the number that says so.",
+      description: "Compare two saved benchmark runs head-to-head: avg + p95 for FPS/CPU/memory, jank, AND render counts \u2014 total, commits, and wasted (parent cascades + identity-only prop churn) \u2014 each with deltas. Use comparable workloads and inspect available metrics together. A wasted-render delta alone does not prove a fix.",
       inputSchema: {
         reportIdA: z3.string().describe("First (baseline) report id."),
         reportIdB: z3.string().describe("Second report id to compare against the baseline."),
@@ -1540,7 +1830,7 @@ ${JSON.stringify(settings, null, 2)}
         navTimeoutMs: z3.number().optional().describe("Max wait for navigation per run (ms)."),
         runsPerCase: z3.number().optional().describe("Runs per page; median is the canonical result (1\u201310)."),
         discardWarmupRuns: z3.number().optional().describe("Discard first N runs of each page before the median."),
-        shuffleCases: z3.boolean().optional().describe("Interleave + shuffle case order to cancel thermal bias."),
+        shuffleCases: z3.boolean().optional().describe("Interleave and shuffle case order to reduce order-related bias."),
         reloadBetweenCases: z3.boolean().optional().describe("Fully reload JS between pages (needs <AutomationResumer/> mounted)."),
         captureRenders: z3.boolean().optional().describe("Capture per-component render counts/durations during each run."),
         deviceId: deviceIdInput
@@ -1605,7 +1895,7 @@ function registerEventsTools(server, sync) {
   server.registerTool(
     "get_events",
     {
-      description: "The UNIVERSAL, token-bounded activity reader for what's happening in the app across ALL Buoy tools. Check this timeline BEFORE driving the UI to reproduce a bug \u2014 the failure is usually already recorded here. The events tool aggregates every source \u2014 network requests, redux/zustand/jotai actions, react-query query/mutation updates, storage writes, route changes, renders \u2014 so filter to one with `sources`: ['network'] lists HTTP requests, ['redux'] dispatched actions, ['react-query'] query updates, ['storage'] writes, ['route'] navigation. Returns a compact one-line summary per event (source \xB7 status \xB7 title \xB7 timing) by DEFAULT \u2014 not the heavy raw payloads \u2014 so it's cheap. Re-call with includeData:true, a bigger limit, or specific sources only when you need detail. PREFER this over get_snapshot (and over reading source code) for any 'what happened' / 'show me the requests/actions' question; get_snapshot is the raw heavy current-state escape hatch.",
+      description: "Read retained events from connected Buoy sources. Filter with sources, such as ['network'], ['redux'], ['react-query'], ['storage'] or ['route']. Returns compact summaries by default; use includeData:true for available payload details. Coverage depends on integrations and retention. An empty timeline does not prove an event never happened. Use get_network_requests for request IDs and get_snapshot for available current tool state.",
       inputSchema: {
         limit: z4.number().optional().describe("Most-recent N events to include. Default 25."),
         sources: z4.array(z4.string()).optional().describe('Only these sources. Coarse names accepted: "network", "redux", "react-query", "storage", "route", "render", "zustand", "jotai". Omit for all.'),
@@ -1682,7 +1972,7 @@ function registerReactQueryTools(server, sync) {
   server.registerTool(
     "get_react_query",
     {
-      description: "Read the app's CURRENT React Query cache \u2014 every query with its status (fresh/stale/fetching/error), staleness, observer count, last-updated time, and any error. Compact by DEFAULT (no cached payloads) so it's token-cheap; pass includeData:true for the actual cached data, or staleOnly:true to see just stale queries. Use this for 'what's in the cache / why is this stale / which queries errored'. (For the history of query updates over time, use get_events with sources:['react-query'].) Each row's hash is what you pass to react_query_action.",
+      description: "Read queries reported by the connected React Query integration, including available status, observer counts, timestamps and errors. includeData:true requests cached payloads; staleOnly:true filters stale queries. Use each returned hash with react_query_action. History depends on retained events.",
       inputSchema: {
         includeData: z5.boolean().optional().describe("Include each query's full cached data payload (HEAVY). Default false."),
         staleOnly: z5.boolean().optional().describe("Only stale queries. Default false."),
@@ -1741,13 +2031,13 @@ ${lines.join("\n")}${note}`);
         const target = sync.requireProDevice(args.deviceId);
         if (args.action === "clear") {
           await callQueryAction(sync, "clearQueryCache", {}, target);
-          return text("Cleared the entire React Query cache.");
+          return text("Requested clearing of the connected React Query cache. Read it again to confirm.");
         }
         if (!args.queryHash) {
           return fail2(`'${args.action}' needs a queryHash. Call get_react_query first and use a row's hash (in backticks).`);
         }
         await callQueryAction(sync, args.action, { queryHash: args.queryHash }, target);
-        return text(`Ran ${args.action} on query \`${args.queryHash}\`.`);
+        return text(`Requested ${args.action} on query \`${args.queryHash}\`.`);
       } catch (e) {
         return fail2(errMsg2(e));
       }
@@ -1762,7 +2052,7 @@ function registerZustandTools(server, sync) {
   server.registerTool(
     "get_zustand_state",
     {
-      description: "Read the app's CURRENT Zustand store state \u2014 each registered store with its name, change count, persistence, and (by default) just its top-level keys so it's token-cheap. Pass includeValues:true for the full state objects. Use this for 'what's in my zustand stores / what's the current count'. (For the history of state changes over time, use get_events with sources:['zustand'].)",
+      description: 'Read registered Zustand stores, available state keys, change counts and persistence metadata. includeValues:true requests values. Use get_events with sources:["zustand"] for retained changes.',
       inputSchema: {
         includeValues: z6.boolean().optional().describe("Include each store's full current state object (HEAVY). Default false (keys only)."),
         limit: z6.number().optional().describe("First N stores. Default all."),
@@ -1814,7 +2104,7 @@ ${lines.join("\n")}${note}`);
         { storeName: args.store, state: args.state, replace: args.replace ?? true },
         target
       );
-      return text(`Set state on Zustand store "${args.store}" (${args.replace === false ? "merged" : "replaced"}).`);
+      return text(`Requested state update on Zustand store "${args.store}" (${args.replace === false ? "merged" : "replaced"}).`);
     })
   );
 }
@@ -1826,7 +2116,7 @@ function registerJotaiTools(server, sync) {
   server.registerTool(
     "get_jotai_state",
     {
-      description: "Read the app's CURRENT Jotai atom values \u2014 each watched atom with its label, change count, and whether it's writable. Compact by DEFAULT (no values) so it's token-cheap; pass includeValues:true for the actual current values. Use this for 'what are my jotai atoms / what's the current value'. (For the history of atom changes over time, use get_events with sources:['jotai'].)",
+      description: 'Read watched Jotai atoms and their available labels, change counts and writable status. includeValues:true requests values. Use get_events with sources:["jotai"] for retained changes.',
       inputSchema: {
         includeValues: z7.boolean().optional().describe("Include each atom's current value (HEAVY). Default false."),
         limit: z7.number().optional().describe("First N atoms. Default all."),
@@ -1872,7 +2162,7 @@ ${lines.join("\n")}${note}`);
     },
     withDevice(sync, async (args, target) => {
       await sync.callAction(JOTAI_TOOL_ID, "setAtom", { label: args.atom, value: args.value }, target);
-      return text(`Set Jotai atom "${args.atom}" to ${JSON.stringify(args.value)}.`);
+      return text(`Requested update of Jotai atom "${args.atom}" to ${JSON.stringify(args.value)}.`);
     })
   );
 }
@@ -1896,7 +2186,7 @@ function registerReduxTools(server, sync) {
   server.registerTool(
     "get_redux_state",
     {
-      description: "Read the app's CURRENT Redux state. Compact by DEFAULT \u2014 just the top-level slice names \u2014 so it's token-cheap; pass includeValues:true for the full state tree. Use this for 'what's in my redux store / current auth state'. (For the history of dispatched actions over time, use get_events with sources:['redux'].)",
+      description: 'Read available state from the connected Redux integration. Lists top-level slices by default; includeValues:true requests state values. Use get_events with sources:["redux"] for retained action history.',
       inputSchema: {
         includeValues: z8.boolean().optional().describe("Include the full current state tree (HEAVY). Default false (slice names only)."),
         deviceId: deviceIdInput
@@ -2045,9 +2335,9 @@ ${lines.join("\n")}`);
   server.registerTool(
     "storage_action",
     {
-      description: "Modify the app's AsyncStorage: set a key, remove a key, or clear all app storage (Buoy's own devtool keys are preserved). Values are stored as strings \u2014 JSON-encode objects yourself.",
+      description: "Modify the app's AsyncStorage: set a key, remove a key, or clear supported app AsyncStorage keys (Buoy's own devtool keys are preserved). Values are stored as strings \u2014 JSON-encode objects yourself.",
       inputSchema: {
-        action: z9.enum(["set", "remove", "clear"]).describe("set/remove a key, or clear all app storage."),
+        action: z9.enum(["set", "remove", "clear"]).describe("set/remove a key, or clear supported app AsyncStorage keys."),
         key: z9.string().optional().describe("The key (required for set and remove)."),
         value: z9.string().optional().describe("The string value to store (required for set; JSON-encode objects)."),
         deviceId: deviceIdInput
@@ -2058,20 +2348,20 @@ ${lines.join("\n")}`);
         const target = sync.requireProDevice(args.deviceId);
         if (args.action === "clear") {
           await sync.callAction(STORAGE_TOOL_ID, "clearAppStorage", {}, target);
-          return text("Cleared all app storage (Buoy's own devtool keys preserved).");
+          return text("Requested clearing of supported app AsyncStorage keys. Read storage again to confirm.");
         }
         if (!args.key) {
           return fail2(`'${args.action}' needs a key.`);
         }
         if (args.action === "remove") {
           await sync.callAction(STORAGE_TOOL_ID, "async.removeItem", { key: args.key }, target);
-          return text(`Removed storage key "${args.key}".`);
+          return text(`Requested removal of storage key "${args.key}".`);
         }
         if (args.value === void 0) {
           return fail2("'set' needs a value (a string).");
         }
         await sync.callAction(STORAGE_TOOL_ID, "async.setItem", { key: args.key, value: args.value }, target);
-        return text(`Set storage key "${args.key}".`);
+        return text(`Requested update of storage key "${args.key}".`);
       } catch (e) {
         return fail2(errMsg2(e));
       }
@@ -2093,9 +2383,9 @@ function registerRoutesTools(server, sync) {
   server.registerTool(
     "get_routes",
     {
-      description: "Read the app's CURRENT route + navigation stack (where the user is and how they got there). Compact by DEFAULT; pass includeSitemap:true to also list every route path the app defines (useful before navigate). Use for 'what screen am I on / what's the nav stack / what routes exist'. (For navigation history over time, use get_events with sources:['route'].)",
+      description: 'Read reported current navigation state and stack. includeSitemap:true includes available configured route paths; it does not establish complete application route coverage. Use get_events with sources:["route"] for retained navigation history.',
       inputSchema: {
-        includeSitemap: z10.boolean().optional().describe("Also list all defined route paths (can be long). Default false."),
+        includeSitemap: z10.boolean().optional().describe("Also list available configured route paths (can be long). Default false."),
         deviceId: deviceIdInput
       }
     },
@@ -2176,7 +2466,7 @@ function registerConsoleTools(server, sync) {
   server.registerTool(
     "get_console",
     {
-      description: "Read the app's captured console logs (console.log/warn/error/\u2026) as a compact tail \u2014 time \xB7 level \xB7 message. App crashing or erroring \u2192 read this FIRST: it captures crashes and errors including FATAL uncaught JS errors (tagged [FATAL], hooked from RN's global error handler), so a dead app's last words are here, not in the code. Token-cheap (uses each entry's pre-rendered message, not raw args). Filter by minimum level (e.g. level:'warning' for warnings+errors) or a message substring. For full args/stack of an entry, fall back to get_snapshot('console').",
+      description: "Read retained captured console output as a compact tail of timestamps, levels and messages. Filter by minimum level or a case-insensitive message substring. Fatal JavaScript errors may be included when supported hooks captured them; post-crash availability is not guaranteed. Missing entries do not establish that no error occurred. Use get_snapshot for available full entry details. Requires configured console capture and Buoy Pro.",
       inputSchema: {
         level: z11.enum(["verbose", "info", "warning", "error"]).optional().describe("Minimum level to include (severity threshold). e.g. 'warning' = warnings + errors. Default all."),
         limit: z11.number().optional().describe("Most-recent N entries. Default 50."),
@@ -2209,7 +2499,7 @@ function registerConsoleTools(server, sync) {
 ${lines.join("\n")}
 \`\`\`
 
-_Tail of recent logs. Use get_snapshot('console') for full args/stacks._`);
+_Tail of recent logs. Use get_snapshot for available console entry details._`);
     })
   );
 }
@@ -2358,11 +2648,11 @@ function registerScreenshotTools(server, sync) {
   server.registerTool(
     "screenshot_component",
     {
-      description: "Take a tight, cropped screenshot of a single React Native component running in the iOS Simulator \u2014 no manual coordinates needed. Give a testID, nativeID, accessibilityLabel, or component name in `query` (or an exact `nativeTag` from a previous call's candidates) and it locates the live component on-device (scrolling it into view), then captures + crops the Simulator framebuffer to just that component. If highlight tracking hasn't seen a render yet, it falls back to a live fiber walk (same as describe_screen). iOS Simulator only, and the MCP server must run on the same Mac as the booted Simulator. Requires Buoy Pro.",
+      description: "Locate a supported React Native component and attempt a cropped iOS Simulator screenshot. Select by query or an exact nativeTag. Uses measured bounds or an available fiber-walk fallback and can attempt scrolling. Inspect the match and crop before treating it as visual evidence. Requires Buoy Pro, a compatible highlight-updates integration, and the MCP server on the same Mac as the booted iOS Simulator.",
       inputSchema: {
         query: z12.string().optional().describe('Fuzzy match against testID, nativeID, accessibilityLabel, component name, or view type \u2014 e.g. "submit-button".'),
         nativeTag: z12.number().optional().describe("An exact nativeTag (from a previous call's candidates) to skip fuzzy matching."),
-        scrollIntoView: z12.boolean().optional().describe("Scroll the component into view before capturing, if it's off-screen. Default true."),
+        scrollIntoView: z12.boolean().optional().describe("Attempt to scroll an off-screen component into view before capture. Default true; inspect the result."),
         deviceId: deviceIdInput
       }
     },
@@ -2534,12 +2824,12 @@ async function captureDiagnosis(sync, target) {
       target
     );
   } catch {
-    return "The network tool has captured nothing yet.";
+    return "Capture status is unavailable. An empty result does not establish whether requests occurred.";
   }
   if (!status || status.capturing !== false) {
-    return "The device IS capturing, so nothing has been requested since it started.";
+    return "No requests are available in this result. Check capture setup, supported transports and hook timing before concluding that no request occurred.";
   }
-  return "The device is NOT capturing. Reading from here arms capture, so the very next read should see traffic \u2014 trigger it and call again. This is not an app or interception problem. (If it stays off, the device is on a Buoy older than the capture-mode watch: open the Network panel on the device or in Buoy Desktop to record.)";
+  return "Capture is disabled. Open the Network panel on the device or in Buoy Desktop, trigger a supported request and read again. An empty result does not establish whether requests occurred. Capture depends on installed hooks, supported transports and recording timing.";
 }
 function skippedNote(skipped) {
   return skipped > 0 ? `
@@ -2571,15 +2861,33 @@ function formatRow(index, e, markers) {
    \u2514\u2500 ${bits.join(" \xB7 ")}`;
 }
 function registerNetworkTools(server, sync) {
+  server.registerTool("network_conditions", {
+    description: "Read or set the device's network conditions. Offline blocks new intercepted HTTP requests; slow adds 500 ms and verySlow adds 2000 ms before dispatch. Normal clears conditions. State resets on JS reload. Check app and server observations to verify the effect.",
+    inputSchema: {
+      action: z13.enum(["get", "set"]).describe("Read the effective profile or select one."),
+      profile: z13.enum(["normal", "offline", "slow", "verySlow"]).optional().describe("Required for set."),
+      deviceId: deviceIdInput
+    }
+  }, async (args) => {
+    try {
+      if (args.action === "set" && !args.profile) return fail2("Set requires a profile.");
+      const target = sync.resolveDevice(args.deviceId);
+      const result = await sync.callAction(NETWORK_TOOL_ID, args.action === "get" ? "getNetworkConditions" : "setNetworkConditions", args.action === "set" ? { profile: args.profile } : void 0, target);
+      if (!result || typeof result !== "object" || !("profile" in result)) return fail2("The device did not report its effective network conditions.");
+      return text(JSON.stringify(result));
+    } catch (error) {
+      return fail2(errMsg2(error));
+    }
+  });
   server.registerTool(
     "get_network_requests",
     {
-      description: "List captured HTTP requests WITH their request ids, plus which ones are pinned/saved. API data wrong or calls failing \u2192 read the actual request+response bodies here instead of guessing from code; capture starts at app launch, so boot-time requests (session bootstrap, first queries) are included. Use this (not get_events) when you need to ACT on a request \u2014 every network action is keyed by the id, and get_events does not emit ids. Compact by default: one line per request (id \xB7 status \xB7 method \xB7 path \xB7 timing \xB7 size). Set flagged:'pinned'|'saved'|'any' to read the developer's KEPT requests \u2014 those are snapshots that outlive Clear, the 500-request cap and app restarts, so treat a pinned request as 'a human flagged this as the problem'. Filter with status:'errors' to go straight to failures, or `pattern` to match a URL substring. includeBodies:true adds truncated request/response payloads (heavier).",
+      description: "List captured HTTP requests with IDs, available status/timing/size fields and pinned or saved markers. Capture depends on supported transports, installed hooks and recording timing; requests made before capture starts may be absent. Use IDs for network actions and flagged to inspect retained records. A flag does not establish who created it or the cause of a problem. Filter by status or URL pattern. includeBodies:true requests available truncated bodies, which can be missing or withheld. Requires the network integration and Buoy Pro.",
       inputSchema: {
         limit: z13.number().optional().describe("Most-recent N requests. Default 25."),
         pattern: z13.string().optional().describe("Only requests whose URL contains this substring (case-insensitive)."),
         status: z13.enum(["all", "errors", "success", "pending"]).optional().describe("Filter by outcome. Default all."),
-        flagged: z13.enum(["pinned", "saved", "any"]).optional().describe("Read KEPT requests instead of the live list: 'pinned' (held at the top of the developer's list), 'saved' (their favorites), 'any' (either). These survive Clear and app restarts."),
+        flagged: z13.enum(["pinned", "saved", "any"]).optional().describe("Read KEPT requests instead of the live list: 'pinned' (held at the top of the developer's list), 'saved' (their favorites), 'any' (either). These are separate from the live list; restart retention depends on successful persistence."),
         includeBodies: z13.boolean().optional().describe("Include truncated request/response bodies. Default false (compact)."),
         deviceId: deviceIdInput
       }
@@ -2658,7 +2966,7 @@ _\u{1F4CC} pinned \xB7 \u{1F516} saved. Act on one with its id, e.g. network_act
   server.registerTool(
     "network_action",
     {
-      description: "Act on captured HTTP requests: PIN one (holds it at the top of the developer's Network list, ignoring their filters), SAVE one to their favorites, or clear the list. Pinning and saving keep a full snapshot that survives Clear, the 500-request cap and app restarts \u2014 so this is how you hand a request to a human ('I pinned the failing call') or keep one you'll need after the log rolls over. Get ids from get_network_requests (get_events does not emit them). `remove` takes the record `key` from get_network_requests({flagged:'any'}), not a request id.",
+      description: "Pin or save captured requests as retained records, or remove records and clear lists. Bodies may be truncated or omitted by storage budgets. Records are kept separately from the live list; availability after restart depends on successful device persistence. Get request IDs from get_network_requests. remove uses a retained-record key from flagged results. An action acknowledgement does not confirm a durable storage write.",
       inputSchema: {
         action: z13.enum(["pin", "unpin", "save", "unsave", "remove", "clearPinned", "clearSaved", "clearRequests"]).describe("pin/unpin/save/unsave act on one request by `id`. remove drops one kept record by `key`. clearPinned/clearSaved drop all of that kind. clearRequests wipes the live capture list (kept requests survive)."),
         id: z13.string().optional().describe("Request id for pin/unpin/save/unsave \u2014 from get_network_requests."),
@@ -2714,7 +3022,7 @@ _\u{1F4CC} pinned \xB7 \u{1F516} saved. Act on one with its id, e.g. network_act
             return text(`Cleared saved requests on ${target} (pinned ones kept).`);
           case "clearRequests":
             await sync.callAction(NETWORK_TOOL_ID, "clearEvents", {}, target);
-            return text(`Cleared the captured request list on ${target}. Pinned/saved requests are unaffected.`);
+            return text(`Clear request sent to ${target}. Re-list to confirm the live capture list; this action does not clear retained records.`);
         }
       } catch (e) {
         return fail2(errMsg2(e));
@@ -2724,7 +3032,7 @@ _\u{1F4CC} pinned \xB7 \u{1F516} saved. Act on one with its id, e.g. network_act
   server.registerTool(
     "network_override",
     {
-      description: "Force matching HTTP requests to return a chosen status/body, to fail outright, or to arrive late \u2014 without touching the backend or the app's code. This is how you drive an app into a state it won't reach on its own: force a 500 and see whether the error UI appears, return [] and check the empty state, simulate offline or a slow connection. Rules run INSIDE the app and survive an app reload, so they also cover the boot path. After adding one, trigger the request (navigate/tap_element) and read the result with get_network_requests or describe_screen. ALWAYS remove your rules when done \u2014 a forgotten rule looks exactly like a real bug. Requires Buoy Pro.",
+      description: "Configure response, failure or delay rules for supported requests intercepted by the app integration. Coverage depends on transport, hooks and rule-loading timing; early startup requests may bypass a rule. Inspect existing rules before editing, trigger the intended request and check observed results. Simulated offline behavior does not disconnect the device. Remove rules created for this task afterward or restore prior settings; preserve unrelated rules. Requires Buoy Pro and network override support.",
       inputSchema: {
         action: z13.enum(["list", "add", "remove", "clear", "enable", "disable", "debug"]).describe(
           "add creates a rule (or replaces one when `id` is given). remove drops one by `id`. clear drops all. enable/disable flip ONE rule when `id` is given, otherwise the master switch \u2014 rules are kept either way. list shows every rule with its hit counts; pass `id` to dump one rule in full, body included. debug reports why a rule is or isn't firing."
@@ -2762,7 +3070,7 @@ _\u{1F4CC} pinned \xB7 \u{1F516} saved. Act on one with its id, e.g. network_act
         ),
         name: z13.string().optional().describe("Label shown in the developer's UI."),
         enabled: z13.boolean().optional().describe(
-          "For `add`: create the rule switched off (default true). Useful for staging a rule you'll arm later with enable({id})."
+          "For `add`: whether the rule is enabled. Default true; pass false to stage it switched off. Useful for staging a rule you'll arm later with enable({id})."
         ),
         id: z13.string().optional().describe(
           "Rule id. Required for `remove`. For `add` it replaces that rule. For `enable`/`disable` it targets ONE rule instead of the master switch. For `list` it dumps that rule in full."
@@ -2833,7 +3141,7 @@ Trigger the request now (navigate / tap_element), then check it with get_network
           }
           case "clear":
             await sync.callAction(NETWORK_TOOL_ID, "clearOverrideRules", {}, target);
-            return text(`Removed all override rules on ${target}. Traffic is real again.`);
+            return text(`Removed all override rules on ${target}. Other interception or simulation settings may still apply.`);
           case "enable":
           case "disable": {
             const enabled = args.action === "enable";
@@ -2845,12 +3153,12 @@ Trigger the request now (navigate / tap_element), then check it with get_network
                 target
               );
               return text(
-                `Rule \`${args.id}\` is now ${enabled ? "ON" : "OFF"} on ${target}. The other rules and the master switch are unchanged.`
+                `Rule \`${args.id}\` was requested ${enabled ? "ON" : "OFF"} on ${target}. The other rules and the master switch are unchanged.`
               );
             }
             await sync.callAction(NETWORK_TOOL_ID, "setOverridesEnabled", { enabled }, target);
             return text(
-              enabled ? `Overrides switched ON for ${target}.` : `Overrides switched OFF for ${target}. Rules are kept \u2014 re-enable with network_override({action:"enable"}).`
+              enabled ? `Overrides enabled in settings for ${target}.` : `Overrides switched OFF for ${target}. Rules are kept \u2014 re-enable with network_override({action:"enable"}).`
             );
           }
           case "list": {
@@ -2880,7 +3188,7 @@ ${JSON.stringify(rule, null, 2)}
               return text(
                 `No override rules on ${target}.
 
-Add one with network_override({action:"add", urlPattern:"*", status:500}) to force an error state.`
+Add one with network_override({action:"add", urlPattern:"https://api.example.com/test*", status:500}) to force an error state.`
               );
             }
             const rows = rules.map((rule, i) => {
@@ -2998,7 +3306,7 @@ function registerSentryTools(server, sync) {
   server.registerTool(
     "get_sentry_envelopes",
     {
-      description: "Read what the app is actually sending to Sentry \u2014 every outgoing envelope with its item types, byte size, span count, and summary. Use this to answer 'is this error reaching Sentry', 'what does my app send at startup', or 'why is my Sentry bill high'. Debugging an error locally? These payloads are the final post-processing event, so you can read the exception, breadcrumbs and contexts here WITHOUT waiting for ingestion or spending quota. Filter by envelope item type (event / transaction / log / session / client_report / attachment / replay_event).",
+      description: "Inspect retained captured Sentry envelopes and available item types, sizes, spans and payload details. Coverage depends on supported hooks. Local capture does not prove successful delivery, ingestion or billing impact. Filter by item type to investigate the available evidence.",
       inputSchema: {
         type: z14.string().optional().describe(
           "Only envelopes containing this item type, e.g. 'event' for errors or 'transaction' for traces."
@@ -3048,7 +3356,7 @@ _Full payloads (exception, breadcrumbs, contexts) via get_snapshot('sentry'). Bi
   server.registerTool(
     "get_sentry_cost",
     {
-      description: "What this session would cost in Sentry's billing units, and what that rate implies for a month against the free plan. Sentry bills on RECEIPT \u2014 data its server-side sampling later discards is still charged \u2014 and spans are billed individually, so one transaction is many units. Use this before shipping a Sentry config, or when asked why a Sentry bill is high.",
+      description: "Inspect captured session usage and the tool's configured monthly extrapolation and quota assumptions. These estimates do not establish Sentry ingestion, current plan limits or an actual bill. Check the account's current terms and usage before making cost decisions.",
       inputSchema: {
         deviceId: z14.string().optional().describe("Target device id (auto-selected if one is connected).")
       }
@@ -3064,7 +3372,7 @@ _Full payloads (exception, breadcrumbs, contexts) via get_snapshot('sentry'). Bi
         const usage = p.usage;
         if (!usage?.session) {
           return text2(
-            `${staleHeader2}No usage recorded yet \u2014 nothing has been sent to Sentry this session.${statusNote(p.status)}`
+            `${staleHeader2}No usage is available in this capture.${statusNote(p.status)}`
           );
         }
         const session = usage.session;
@@ -3077,7 +3385,7 @@ _Full payloads (exception, breadcrumbs, contexts) via get_snapshot('sentry'). Bi
           const month = projected[key];
           const quota = FREE_QUOTA[key];
           const pct = quota > 0 ? Math.round(month / quota * 100) : null;
-          const pctNote = pct === null ? " (not on the free plan)" : ` \u2014 ${pct}% of the free plan's ${units(quota, format)}`;
+          const pctNote = pct === null ? " (no configured reference quota)" : ` \u2014 ${pct}% of the configured reference quota of ${units(quota, format)}`;
           return `- ${key}: ${now} this session \u2192 ~${units(month, format)}/mo${pctNote}`;
         });
         const windowNote = usage.windowMs ? ` over ${Math.round(usage.windowMs / 1e3)}s` : "";
@@ -3087,7 +3395,7 @@ _Full payloads (exception, breadcrumbs, contexts) via get_snapshot('sentry'). Bi
 ${usage.topContributors.map((c) => `- ${c.label} \u2014 ${c.units} ${c.category}`).join("\n")}` : "";
         const caveat = projected ? "\n\n_The monthly figure extrapolates one session on one device \u2014 it catches a config that is orders of magnitude off, it is not a forecast._" : "\n\n_Session too short to project a month from._";
         return text2(
-          `${staleHeader2}**Sentry cost \u2014 ${p.envelopes?.length ?? 0} envelopes${windowNote}:**
+          `${staleHeader2}**Sentry usage estimate \u2014 ${p.envelopes?.length ?? 0} envelopes${windowNote}:**
 
 ${rows.join("\n")}${contributors}${caveat}`
         );
@@ -3117,9 +3425,9 @@ ${rows.join("\n")}${contributors}${caveat}`
         const recent = p.drops?.recent ?? [];
         if (summary.length === 0) {
           return text2(
-            `${staleHeader2}Nothing dropped this session \u2014 every captured event reached the transport.${statusNote(p.status)}
+            `${staleHeader2}No drops are reported in the available capture.${statusNote(p.status)}
 
-_If an event is still missing from sentry.io, it left the device: check the DSN, the project, and Sentry's own inbound filters and quota._`
+_If an event is missing from sentry.io, check capture coverage, transport errors, the DSN/project, inbound filters and quota. Local capture does not confirm delivery._`
           );
         }
         const limit = typeof args.limit === "number" && args.limit > 0 ? args.limit : 30;
@@ -3198,7 +3506,7 @@ function registerTimeMachineTools(server, sync) {
   server.registerTool(
     "get_time_machine",
     {
-      description: "List the app's Time Machine state snapshots (restore points) and which state sources (storage/redux/zustand/jotai/react-query) can currently be captured/restored. Each snapshot also records the route it was captured on (shown as `route`), which a restore can navigate back to. Use time_machine_action to capture a snapshot before driving a flow, then restore it to re-run the flow from the same state.",
+      description: "List the app's Time Machine state snapshots (restore points) and which state sources (storage/redux/zustand/jotai/react-query) can currently be captured/restored. Each snapshot also records the route it was captured on (shown as `route`), which a restore can navigate back to. Use time_machine_action to capture a snapshot before driving a flow, then restore supported sources to repeat the flow. Uncaptured and backend state can still differ.",
       inputSchema: {
         deviceId: deviceIdInput
       }
@@ -3221,7 +3529,7 @@ function registerTimeMachineTools(server, sync) {
         }
         const snapLines = snapshots.map((s) => {
           const warnings = Object.values(s.sources).reduce((n, src) => n + src.warnings.length, 0);
-          const desc = s.baseline ? "baseline \u2014 restore wipes to fresh install (always reloads)" : `${kb(s.sizeBytes)} \xB7 ${Object.keys(s.sources).join(", ")}`;
+          const desc = s.baseline ? "baseline: clear supported providers and request reload" : `${kb(s.sizeBytes)} \xB7 ${Object.keys(s.sources).join(", ")}`;
           const route = s.route ? ` \xB7 route ${s.route.href}` : "";
           return `- \`${s.id}\` **${s.name}** \u2014 ${new Date(s.createdAt).toISOString()} \xB7 ${desc}${route}${warnings ? ` \xB7 \u26A0 ${warnings}` : ""}`;
         });
@@ -3242,7 +3550,7 @@ ${formatOutcome(p.lastOutcome)}`);
   server.registerTool(
     "time_machine_action",
     {
-      description: "Manage Time Machine state snapshots: capture the app's current state as a named restore point, preview what restoring one would change (per-item added/removed/changed/won't-apply verdicts \u2014 check the blast radius BEFORE restoring), restore one (mode 'live' replaces state in place; 'reload' restores persisted storage then reloads the JS bundle \u2014 baselines always reload; pass restoreRoute:true to also return to the screen the snapshot was captured on), capture_baseline (an empty wipe-to-fresh-install restore point), delete, or rename. The restore result reports per-source applied/skipped counts \u2014 check them rather than assuming success.",
+      description: "Manage snapshots of supported registered state sources: capture, preview, restore, capture_baseline, delete or rename. Preview affected items before restoring. Live mode replaces supported state in place; reload mode restores supported persisted storage and requests a JS reload. Baselines clear providers that support clearing and request a reload; they do not reset backend state or reproduce a complete reinstall. restoreRoute:true requests the captured route when available. Inspect per-source applied/skipped results and reload outcomes.",
       inputSchema: {
         action: z15.enum(["capture", "capture_baseline", "preview", "restore", "delete", "rename"]).describe("What to do."),
         id: z15.string().optional().describe("Snapshot id (required for restore/delete/rename; from get_time_machine)."),
@@ -3389,7 +3697,7 @@ function registerScenariosTools(server, sync) {
   server.registerTool(
     "get_scenarios",
     {
-      description: "List the app's saved Scenarios \u2014 named, parameterized app states that can be applied with one call (override a response, write storage, impersonate a user, navigate). Shows what each one WILL do in plain English with a durability label per step, plus which scenario is currently active and what it changed. Use scenario_action to run one as a deterministic fixture BEFORE driving a flow, so the flow starts from a known state instead of whatever the app happened to be in. If a scenario is active, whatever you observe on the device is partly simulated \u2014 check here first when the app's data looks wrong.",
+      description: "List saved scenarios, configured steps, available durability labels and the reported active scenario. Inspect these settings when app behavior may be simulated. A scenario covers its supported steps, not every source of app or backend state.",
       inputSchema: {
         deviceId: z16.string().optional().describe("Target device id (auto-selected if one is connected).")
       }
@@ -3430,7 +3738,7 @@ ${drafts.map(summarize).join("\n")}`
   server.registerTool(
     "scenario_action",
     {
-      description: `Drive Buoy Scenarios: 'preview' dry-runs one and reports exactly what it WOULD change (plus any conflict with the active scenario) without touching the app \u2014 do this before running an unfamiliar scenario; 'run' applies it and resolves only once every step has landed, which makes it a deterministic fixture to call before run_flow; 'deactivate' reverses it and reports what it could NOT restore (storage writes have no automatic inverse); 'save' writes a new scenario onto the device \u2014 it lands as a DRAFT that a human must accept on the device before it can run, so tell the user to go accept it; 'setFolder' files a saved scenario under a flow ("Checkout", "Login") or clears its folder, which is how a QA library stays navigable \u2014 check get_scenarios for the folders already in use and reuse one instead of inventing a near-duplicate; 'delete' removes a device scenario. Prefer a network override step over a query-cache poke: the override survives refetch and restart, the poke dies on the next fetch.`,
+      description: "Preview, run, deactivate, save, organize or delete a scenario. Preview unfamiliar scenarios before running; inspect applied steps, failures and unrestored effects afterward. Storage changes need suitable undo steps. Saved scenarios are drafts requiring acceptance on the device before running. Reuse existing folders when appropriate. A completed scenario does not guarantee a deterministic app or backend state; overrides and cache edits have different coverage and lifetimes.",
       inputSchema: {
         action: z16.enum(["preview", "run", "deactivate", "save", "setFolder", "delete"]).describe("What to do."),
         folder: z16.string().optional().describe(
@@ -3520,7 +3828,7 @@ ${r.willDo.map((s) => `  \xB7 ${s.label}  [${s.durability}]`).join("\n")}`
             if (r.warnings?.length) lines.push(`**Warnings:**
 ${r.warnings.map((w) => `  \xB7 ${w}`).join("\n")}`);
             lines.push(
-              r.ok ? "\u2705 Pre-flight passed \u2014 safe to run." : `\u274C **Cannot run:**
+              r.ok ? "Pre-flight checks passed. Review the intended effects before running." : `\u274C **Cannot run:**
 ${r.errors.map((e) => `  \xB7 ${e}`).join("\n")}`
             );
             return text3(lines.join("\n\n"));
@@ -3555,9 +3863,9 @@ The device is now in a partial state. Deactivate to reverse what landed, or fix
               [
                 `\u2705 **Scenario active \u2014 ${r.name ?? args.id}**`,
                 steps,
-                `**Now bent:**
+                `**Reported effects:**
 ${(r.effects ?? []).map((e) => `  \xB7 ${e.label} [${e.kind}]`).join("\n")}`,
-                "The device shows a SIMULATED banner while this is active. Deactivate when done, or anything you observe from here is partly fake."
+                "The device shows a SIMULATED banner while this is active. Deactivate when done, and account for these effects when interpreting observations."
               ].join("\n\n")
             );
           }
@@ -3622,7 +3930,7 @@ import { z as z17 } from "zod";
 // src/capture/camera.ts
 import { execFile as execFile2 } from "child_process";
 import { promisify as promisify2 } from "util";
-import { existsSync, readFileSync } from "fs";
+import { existsSync, readFileSync as readFileSync2 } from "fs";
 import os3 from "os";
 import path3 from "path";
 var execFileAsync2 = promisify2(execFile2);
@@ -3754,20 +4062,20 @@ function readEntitlement() {
   for (const p of entitlementPaths()) {
     try {
       if (!existsSync(p)) continue;
-      const parsed = JSON.parse(readFileSync(p, "utf8"));
+      const parsed = JSON.parse(readFileSync2(p, "utf8"));
       return {
-        tier: parsed.tier === "pro" || parsed.tier === "free" ? parsed.tier : "anonymous",
-        isPro: parsed.isPro === true
+        tier: parsed.tier === "pro" || parsed.tier === "free" ? parsed.tier : "locked",
+        isPro: parsed.isPro === true && parsed.hasDesktopAccess === true && typeof parsed.validUntil === "number" && Number.isFinite(parsed.validUntil) && Date.now() < parsed.validUntil && typeof parsed.proValidUntil === "number" && Number.isFinite(parsed.proValidUntil) && Date.now() < parsed.proValidUntil
       };
     } catch {
     }
   }
-  return { tier: "anonymous", isPro: false };
+  return { tier: "locked", isPro: false };
 }
 function proRequired(tool) {
   return `\`${tool}\` is a Buoy Pro feature.
 
-The simulator camera itself is free \u2014 the Mac camera, image, video, test-pattern and QR sources all work in the Buoy desktop panel without a licence. Pro adds the screen region, the non-QR symbologies (PDF417, Aztec, DataMatrix, Code 128), and driving any of it from an agent.
+The simulator camera itself is free \u2014 the Mac camera, image, video, test-pattern and QR sources all work in the Buoy desktop panel with a Free account. Pro adds the screen region, the non-QR symbologies (PDF417, Aztec, DataMatrix, Code 128), and driving any of it from an agent.
 
 _Tell the user to enter a licence in Buoy Desktop, or see https://buoy.gg/pricing. Don't try to work around it \u2014 use the desktop panel by hand instead._`;
 }
@@ -4014,7 +4322,7 @@ function registerInteractTools(server, sync) {
   server.registerTool(
     "describe_screen",
     {
-      description: "List the interactive / labeled elements currently on screen \u2014 the app's live accessibility-style tree walked from the React fiber tree. Each row shows the component name, visible text/label, role, testID, a normalized tap point (tap: x,y in 0\u20131), and its #nativeTag. Rows marked with \u2022 are tappable (have an onPress). Use this to see what's on screen and pick something to tap with tap_element \u2014 no screenshot needed. If you already know the sequence you want to drive, `run_flow` does the whole thing (taps, waits, assertions) in one call instead. Re-run after navigating or when the screen changes, since positions move. Requires Buoy Pro.",
+      description: "List elements exposed by the app React-fiber inspection integration, with available names, text, roles, testIDs, positions and native tags. This is not a complete native accessibility tree or a visual screenshot. Use the returned controls to select a target for tap_element; refresh after navigation or state changes. Empty results can reflect unavailable inspection. Requires Buoy Pro and the highlight-updates interaction integration.",
       inputSchema: {
         interactiveOnly: z18.boolean().optional().describe("Only return tappable (onPress) elements. Default false (include labels/text for context)."),
         includeBuoy: z18.boolean().optional().describe(
@@ -4052,7 +4360,7 @@ ${elements.map(formatElement).join("\n")}`);
   server.registerTool(
     "tap_element",
     {
-      description: "Interact with an on-screen element by invoking its handler directly in JS (no screenshot, no coordinate math, works on real devices). Handles buttons (onPress + onLongPress), toggles/switches and sliders (onValueChange), and text inputs (onChangeText) \u2014 see each element's `control` in describe_screen. Identify the target with an exact `nativeTag` or `testID`, or a fuzzy `query`. Pass `longPress:true` to invoke onLongPress instead of onPress (elements that support it show {long-press} in describe_screen). For a toggle, pass `value:true/false` (omit to flip); for a slider, pass a numeric `value` (omit to jump to the far end); for a text input, pass `text`. If the element is off-screen it's scrolled into view first (scrollIntoView:false to skip). Call describe_screen first to see options + current values. Driving MORE THAN ONE step (reproducing a bug, verifying a fix)? Use `run_flow` instead \u2014 it runs the whole sequence in one call. Requires Buoy Pro.",
+      description: "Invoke a supported element handler in JavaScript: onPress/onLongPress, onValueChange or onChangeText. This does not reproduce native hit testing, keyboard entry or a physical gesture. Select an exposed element by nativeTag, testID or fuzzy query; inspect the matched target and resulting behavior. value sets a supported toggle or slider, text invokes a text-input handler, and longPress selects onLongPress. Can attempt to scroll an off-screen target into view. Use describe_screen for current controls and run_flow for sequences. Requires Buoy Pro and the app interaction integration.",
       inputSchema: {
         nativeTag: z18.number().optional().describe("Exact nativeTag from describe_screen (most precise)."),
         testID: z18.string().optional().describe("Exact testID of the element."),
@@ -4060,7 +4368,7 @@ ${elements.map(formatElement).join("\n")}`);
         value: z18.union([z18.number(), z18.boolean()]).optional().describe("For a toggle: true/false (omit to flip). For a slider: the numeric value (omit to jump to the far end)."),
         text: z18.string().optional().describe("For a text input: the string to set via onChangeText."),
         longPress: z18.boolean().optional().describe("Invoke the element's onLongPress instead of onPress. Fails with a clear reason if the element has no onLongPress handler."),
-        scrollIntoView: z18.boolean().optional().describe("Scroll the target into view first if it's off-screen. Default true."),
+        scrollIntoView: z18.boolean().optional().describe("Attempt to scroll an off-screen target into view. Default true; inspect the action result."),
         includeBuoy: z18.boolean().optional().describe("Let a fuzzy `query` match Buoy's own overlay. Default false \u2014 an exact nativeTag/testID always may."),
         deviceId: deviceIdInput
       }
@@ -4184,11 +4492,11 @@ function registerJsThreadTools(server, sync) {
   server.registerTool(
     "get_js_thread_top",
     {
-      description: 'Task Manager for the React Native JS thread: sample for a few seconds and return a ranked table of which task origins (timers, Promise chains, rAF callbacks, bridge call-ins) consumed JS-thread time \u2014 plus thread busy% and freeze (50ms+ block) attribution. Use when JS FPS is low and you need to know WHAT is eating the thread. To profile one specific interaction, pass clearFirst:true, then drive the UI with tap_element while the sample runs. Drill into a row with get_js_thread_origin_detail. NOT the tool for React components re-rendering too often \u2014 this measures TASKS on the thread, not renders; for "the page re-renders constantly / typing lags / tapping one button re-renders everything" use measure_renders. Requires @buoy-gg/js-top on the device.',
+      description: "Sample instrumented JavaScript task origins and return available timing, busy percentage and freeze attribution. Coverage depends on installed hooks; unattributed work can remain. Requires @buoy-gg/js-top and Buoy Pro. The call waits for the sample: arrange the interaction during that window using an available concurrent driver or a person, rather than starting it after this call returns. clearFirst resets tracked statistics before sampling. Use get_js_thread_origin_detail for a returned row key and measure_renders for component render diagnostics.",
       inputSchema: {
         deviceId: deviceIdInput,
-        durationMs: z19.number().optional().describe("How long to sample before reading the table. Default 3000, max 30000."),
-        clearFirst: z19.boolean().optional().describe("Reset all stats before sampling, so the result attributes only what happens during this sample.")
+        durationMs: z19.number().optional().describe("How long to sample before reading the table. Default 3000; clamped to 250\u201330000."),
+        clearFirst: z19.boolean().optional().describe("Reset tracked statistics before sampling. Hook coverage and attribution limits still apply.")
       }
     },
     async ({ deviceId, durationMs, clearFirst }) => {
@@ -4372,7 +4680,7 @@ function registerImagesTools(server, sync) {
   server.registerTool(
     "get_images",
     {
-      description: "Live image registry from the app: every RN <Image> and expo-image load with cache verdict (memory/disk/network), load ms, decoded vs displayed size with an oversize/upscale verdict and wasted-KB estimate, error details, and any active simulation overrides. Image HTTP never hits the JS network stack, so this is the only visibility into image loading. Requires @buoy-gg/images on the device.",
+      description: "Inspect image loads reported through the Buoy image integration, including available cache origin, load timing, size estimates, errors and simulation overrides. Coverage depends on instrumented components and platform support. Requires @buoy-gg/images on the device.",
       inputSchema: {
         deviceId: deviceIdInput,
         limit: z20.number().optional().describe("Max records to return (newest first). Default 30, max 200."),
@@ -4429,7 +4737,7 @@ ${JSON.stringify(slim)}
   server.registerTool(
     "image_action",
     {
-      description: "Act on one image from get_images (by id): hard_reload (bypass caches + refetch), retry, evict_disk (expo disk entry), flash (red border to locate it on screen), prove_savings (re-encode at displayed size as WebP ON DEVICE and return real byte savings + a previewable file:// uri), or simulation overrides \u2014 force_error (instant offline-safe failure), force_loading (request hangs forever), force_blank, swap_url (requires url), restore (remove override). Returns the record's state after the action so the effect is visible.",
+      description: "Request an action for a registered image ID: hard_reload, retry, evict_disk, flash, prove_savings or a supported simulation override. swap_url requires url; restore removes the override. Support depends on the component and platform. prove_savings attempts a WebP conversion at displayed size and reports available byte comparisons and a device-local URI; inspect visual quality and originalBytesSource before using the result. Other actions return an acknowledgement and, when available, a later record snapshot; that snapshot may precede load completion. A device-local URI is not necessarily accessible from the editor host.",
       inputSchema: {
         deviceId: deviceIdInput,
         id: z20.number().describe("Record id from get_images."),
@@ -4499,12 +4807,12 @@ ${JSON.stringify(slim)}
   server.registerTool(
     "set_image_simulation",
     {
-      description: "App-wide image simulation modes: network 'offline' (every NETWORK image load fails immediately, both libs \u2014 bundled assets still load; reload/remount on-screen images to see it), 'cold' (every image bypasses caches \u2014 first-launch behavior, nothing cleared), 'normal' to reset. blankImages renders every image without a source. massAction applies per-image simulations to everything mounted. Also clears the registry or expo caches when asked.",
+      description: "Configure supported instrumented image loads: offline simulates network-load failures while bundled assets can still load; cold requests cache bypass; normal resets the network mode. Reload or remount existing images as needed. blankImages removes sources from integrated images; massAction targets registered mounted images. Can also clear the registry or supported Expo caches. These modes do not change device connectivity.",
       inputSchema: {
         deviceId: deviceIdInput,
         network: z20.enum(["normal", "offline", "cold"]).optional().describe("Network simulation mode."),
-        blankImages: z20.boolean().optional().describe("Render all images without a source."),
-        massAction: z20.enum(["error", "loading", "blank", "reload", "flash", "restore"]).optional().describe("Apply to EVERY mounted image at once: force error/loading/blank overrides, hard-reload all, flash all, or restore all overrides."),
+        blankImages: z20.boolean().optional().describe("Render integrated images without a source."),
+        massAction: z20.enum(["error", "loading", "blank", "reload", "flash", "restore"]).optional().describe("Apply to registered mounted images: force error/loading/blank overrides, hard-reload all, flash all, or restore all overrides."),
         clearRegistry: z20.boolean().optional().describe("Clear the captured image log."),
         clearExpoCaches: z20.boolean().optional().describe("Clear expo-image memory + disk caches.")
       }
@@ -4643,7 +4951,7 @@ function registerAssetsTools(server, sync) {
   server.registerTool(
     "get_assets",
     {
-      description: "Bundled-asset inventory from the app: every asset (images, fonts, video, audio) with dimensions, @1x/@2x/@3x scale coverage, byte sizes (measured from the Metro server in dev), loaded vs never-loaded state, and audit findings \u2014 duplicates (by content hash), shipped-but-never-loaded, WebP candidates, images decoding larger than the screen, heavy GIFs/fonts, scale gaps \u2014 plus the change vs a saved baseline. This is what the app SHIPS; use get_images for what it RENDERS. Requires @buoy-gg/assets on the device.",
+      description: "Inspect assets reported by the configured manifest, runtime registry and available Metro bundle graph. Includes available dimensions, scale coverage, byte sizes, observed load history, audit findings and saved-baseline differences. Size measurement and coverage depend on setup; not observed loading does not mean unused. Use get_images for instrumented runtime image loads. Requires @buoy-gg/assets on the device.",
       inputSchema: {
         deviceId: deviceIdInput,
         limit: z21.number().optional().describe("Max records to return (largest first). Default 40, max 500."),
@@ -4776,12 +5084,12 @@ function messageSocketUrl(origin) {
   return `${origin.replace(/^http/, "ws").replace(/\/+$/, "")}/message`;
 }
 function reloadViaDevServer(origin) {
-  return new Promise((resolve) => {
+  return new Promise((resolve2) => {
     let settled = false;
     const done = (result) => {
       if (settled) return;
       settled = true;
-      resolve(result);
+      resolve2(result);
     };
     let socket;
     try {
@@ -4866,7 +5174,7 @@ function registerReloadTools(server, sync) {
   server.registerTool(
     "reload_app",
     {
-      description: "Reload the running app's JS bundle (Expo Go, dev client, or RN CLI) \u2014 the equivalent of shaking the device and hitting Reload, but from here. Use it to pick up a change Fast Refresh didn't apply, to clear leaked in-memory state before a measurement, to re-run app startup, or to RECOVER A CRASHED APP: after a fatal error the other tools stop answering, and reloading is how you get them back (it falls through to the dev server when the app is too broken to reload itself). In dev builds it uses React Native's DevSettings.reload(); otherwise it falls back to expo-updates (if the app installs it). All in-memory state is lost \u2014 read anything you need from get_console/get_storage BEFORE reloading. By default this waits for the app to come back up and reports how long the reload took. Works on any app running @buoy-gg/core \u2014 no particular tool package needed. Requires Buoy Pro.",
+      description: "Request a JS reload for a supported app using DevSettings in development or installed expo-updates where available. For an unresponsive app, can try its known dev server when reachable. Recovery is not guaranteed. Reload can discard in-memory state and evidence; collect needed observations first when possible. By default waits for reconnection up to timeoutMs. Requires configured @buoy-gg/core support and Buoy Pro.",
       inputSchema: {
         strategy: z22.enum(["auto", "dev-settings", "expo-updates"]).optional().describe(
           "Reload mechanism. 'auto' (default) uses DevSettings in dev builds and expo-updates otherwise. Force one only when debugging the reload itself."
@@ -4990,7 +5298,7 @@ function registerTriageTools(server, sync) {
   server.registerTool(
     "get_triage",
     {
-      description: "START HERE when debugging a running app. One call = the app's current runtime state: connected device, recent console errors (including [FATAL] crashes), recent network requests with statuses, persisted storage values, and what's on screen right now. Use it as the first step for ANY 'why is the app doing X' question \u2014 it is far cheaper than calling get_console + get_network_requests + get_storage + describe_screen separately, and it tells you which of those to drill into next. If the app has crashed it says so and shows the crash. Requires Buoy Pro.",
+      description: "Summarize available runtime observations for a connected app: captured console errors, recent network requests, configured storage and screen information. Use the returned sections and errors to choose follow-up tools. Missing data or an unresponsive app does not prove a crash; crash output may be unavailable. Requires Buoy Pro.",
       inputSchema: {
         deviceId: z23.string().optional().describe("Target device id (auto-selected if one is connected).")
       }
@@ -5157,10 +5465,10 @@ function registerFlowTools(server, sync) {
   server.registerTool(
     "run_flow",
     {
-      description: "Run a scripted sequence of UI interactions in ONE call and report what happened: per-step results, the final screen, plus the network requests and console errors the flow produced. Use this instead of alternating describe_screen/tap_element \u2014 reproducing a bug ('open cart, checkout, submit') or verifying a fix after an edit is one call, not a dozen. Steps run in order and stop at the first failure, returning the screen at that point so you can see WHERE it broke. Each step can tap, type, set a toggle/slider, reload, wait for an element, and assert. Requires Buoy Pro.",
+      description: "Run supported UI actions and element checks in sequence, with per-step results. Stops on the first failed step unless continueOnFailure is true. Depending on include, attempts to return the final element tree and newly observed captured network/console entries. Background activity can appear in that output; it does not establish causation. Actions use exposed app handlers, not physical gestures. Review failures and check the expected behavior. Requires Buoy Pro and the app interaction integration.",
       inputSchema: {
         steps: z24.array(stepSchema).min(1).describe("Steps to run, in order."),
-        include: z24.enum(["all", "screen", "none"]).optional().describe("What to report after the flow: 'all' (default) = final screen + network/console produced by the flow; 'screen' = final screen only; 'none' = step results only."),
+        include: z24.enum(["all", "screen", "none"]).optional().describe("What to report after the flow: 'all' (default) = available final element tree + newly observed captured network/console entries; 'screen' = available final element tree only; 'none' = step results only."),
         continueOnFailure: z24.boolean().optional().describe("Keep going after a failed step instead of stopping. Default false."),
         deviceId: deviceIdInput
       }
@@ -5482,7 +5790,7 @@ function formatCapture(c, top) {
   }
   lines.push("");
   lines.push(
-    "`wasted` = renders that produced nothing new (parent cascades + identity-only prop changes) \u2014 the removable part. Sorted by **self ms**: fix what costs time, not what renders often. Cheap components re-rendering is usually fine, and blanket `memo()` trades real code clarity for a number that was never the problem."
+    "`wasted` classifies parent cascades and identity-only prop changes. Investigate whether these renders are needed before changing them. Rows are sorted by **self ms**. Compare timing and render counts for the measured workload, and check behavior before deciding whether memoization helps."
   );
   return lines.join("\n");
 }
@@ -5518,14 +5826,14 @@ function registerRenderTools(server, sync) {
   server.registerTool(
     "measure_renders",
     {
-      description: "Find out WHAT re-rendered on the current screen and WHY, in one call \u2014 no test route, no scaffolding. THE tool for 'this page is slow/laggy/janky', 'typing lags', 'the whole page re-renders when I tap one button'. Give it `steps` to measure a specific interaction (tap a button, type in a field) \u2014 measuring an idle window instead tells you nothing about what taps cost, which is how re-render fixes usually go wrong. Returns per-component render COST in ms (sorted by it \u2014 a component rendering 40x for 0.4ms is noise, one rendering 4x for 38ms is the answer), the CAUSE of each (parent cascade / own state / changed props), which parent dragged it along, and which props changed. `wasted` counts renders that produced nothing new \u2014 that's the removable part. AFTER YOU EDIT, call it again with the same steps and compareToPrevious:true to prove the fix landed and didn't move the cost somewhere else. (For choosing between several implementations of a screen, use run_benchmark_batch instead \u2014 that ranks variants; this explains one screen.) Requires Buoy Pro and @buoy-gg/highlight-updates.",
+      description: "Measure captured component renders during supplied interaction steps or an idle window. Returns available timings, render counts, reported reasons and changed props. The wasted count is a diagnostic classification, not proof a render can be removed. Check interaction warnings before comparing runs. Use the same steps and comparable conditions with compareToPrevious:true after editing; the comparison alone does not prove correctness or overall performance. Requires Buoy Pro and a highlight-updates integration exposing beginMeasurement. Use run_benchmark_batch to compare route-based variants.",
       inputSchema: {
         steps: z25.array(stepSchema2).max(20).optional().describe(
           "The interaction to measure, e.g. [{tap:'favorite-deal-2', repeat:5}] or [{type:'bench', into:'deals-search'}]. Omit to sample the screen idle \u2014 only useful for churn that happens with nobody touching it."
         ),
         idleMs: z25.number().min(500).max(2e4).optional().describe(`Idle sample length when no steps are given. Default ${DEFAULT_IDLE_MS}.`),
         label: z25.string().optional().describe('Name this measurement, e.g. "before fix". Shown in the next comparison.'),
-        compareToPrevious: z25.boolean().optional().describe("Diff against the previous measure_renders on this device. Use after an edit to prove the fix."),
+        compareToPrevious: z25.boolean().optional().describe("Compare with the previous measurement on this device. Use equivalent steps and conditions; review warnings and behavior separately."),
         top: z25.number().min(1).max(40).optional().describe(`Components to list. Default ${DEFAULT_TOP}.`),
         deviceId: deviceIdInput
       }
@@ -5615,7 +5923,7 @@ function registerRenderTools(server, sync) {
             "_Nothing re-rendered in this window. If you expected renders, check the app is on the screen you meant and that the steps actually hit something._"
           );
         } else if (!args.compareToPrevious) {
-          parts.push("", "_Fixed something? Call this again with the same steps and `compareToPrevious:true` to prove it landed._");
+          parts.push("", "_Compare another run using the same steps and `compareToPrevious:true`; check behavior and interaction warnings as well._");
         }
         return text8(parts.join("\n"));
       } catch (e) {
@@ -5728,129 +6036,89 @@ var EditWatcher = class {
 
 ---
 \u26A0\uFE0F **${files.length} source file${files.length === 1 ? "" : "s"} changed since anything was last checked on the device** (${shown}${more}).
-Before reporting this as fixed, observe it working: re-run the same interaction with \`measure_renders\` (\`compareToPrevious: true\`) or \`run_flow\`, and say what the numbers did. A fix nobody watched work is a guess \u2014 and re-render fixes in particular tend to move cost somewhere else rather than remove it.`;
+For a behavior change, repeat the affected interaction and check the expected result. Use \`measure_renders\` with the same steps and \`compareToPrevious: true\` for render comparisons, or \`run_flow\` for supported behavior checks. Report what was checked and any remaining limits. This reminder tracks edits and tool calls; clearing it does not prove the change is correct.`;
   }
 };
 var editWatcher = new EditWatcher();
 
 // src/server.ts
-var SERVER_INSTRUCTIONS = `Buoy MCP \u2014 drive Buoy dev tools running in a React Native app from your editor.
-
-Buoy tools live inside the app and sync to a local broker; this server connects to that
-broker as a dashboard client.
-
-DEBUGGING A RUNNING APP? Call \`get_triage\` FIRST \u2014 one call returns the connected device,
-recent console errors (including [FATAL] crashes), recent network requests with statuses,
-persisted storage keys, and what's on screen. It replaces the usual five-call opening
-sequence and tells you which tool to drill into. Read runtime facts before hypothesizing
-from source: the app's actual state beats a guess about what the code should do.
-
-Routing after triage \u2014 match the SYMPTOM to the tool:
-- Value wrong/stale/NaN, or broken only after an upgrade \u2192 \`get_storage includeValues:true\`
-  (a bad persisted value is a top root cause, and it survives reinstalls of the JS).
-- Failed request, wrong data from the API, auth/session bug \u2192 \`get_network_requests
-  includeBodies:true\` and read the response BODY.
-- Crash or redbox \u2192 \`get_console\` (fatals are captured, and still readable after the app
-  dies), then \`get_storage\` for the state that triggered it.
-- Data on screen doesn't match the API \u2192 \`get_react_query\` / \`get_zustand_state\` /
-  \`get_redux_state\` / \`get_jotai_state\` for the cache or store between them.
-
-AFTER YOU EDIT, PROVE IT on the device \u2014 the most common way a fix fails is being incomplete,
-not being wrong. Reload (\`run_flow\` step \`{reload:true}\`, or \`reload_app\`) and re-drive EVERY
-screen the symptom could appear on, asserting the corrected value: a price shown in three places
-has to be right in all three, and a migration only counts if it survives a restart. A fix you
-haven't watched work is a guess.
-
-Use \`list_devices\` when you need the full tool/action inventory or several devices are
-connected (\`get_triage\` already names the active one).
-
-To inspect what's HAPPENING at runtime \u2014 network requests, state changes (redux/zustand/jotai),
-react-query updates, storage writes, route changes, renders \u2014 use \`get_events\` with a \`sources\`
-filter (e.g. sources:["network"] to list HTTP requests). It's the universal, token-bounded
-activity reader across ALL tools and is compact by default \u2014 reach for it before reading source
-code, and prefer it over \`get_snapshot\` for any "what happened / show me the requests" question.
-
-Working on ONE HTTP request rather than skimming activity? \`get_events\` deliberately emits no
-request ids, so use \`get_network_requests\` \u2014 same compact style, but it leads with the id every
-network action is keyed by, and marks which requests are pinned/saved. \`flagged:'any'\` lists the
-requests the DEVELOPER kept: those are snapshots that outlive Clear, the 500-request cap and app
-restarts, so treat a pinned request as "a human flagged this as the problem". \`network_action\`
-pins/saves one \u2014 pin the failing call you want a human to see, or keep one before the log rolls over.
-
-Testing anything that opens a CAMERA \u2014 a QR/barcode scanner, document capture, an avatar
-picker? The iOS Simulator has no camera, so those screens normally cannot be exercised at
-all. \`camera_source\` gives it one: \`barcode\` generates the code from text you supply
-(pdf417 is what a driver's licence carries), \`image\`/\`video\` play a file, \`screen\` points
-the phone at this Mac. \`camera_devices\` lists the booted simulators and their apps when
-you need a bundle id; \`camera_inputs\` lists this Mac's cameras and windows when you need
-one of those ids. Then \`camera_launch\` to relaunch the app with it attached \u2014 a camera
-can only be attached at process start \u2014 or \`camera_zero_setup\` when something else starts
-the app. \`camera_status\` shows what is being decoded right now, which separates "the
-scanner is broken" from "it never saw the code", \`camera_diagnose\` says why when nothing
-works, and \`camera_stop\` turns it off when you are done. These need no device connection
-and no Buoy integration in the app.
-
-Need to SEE a component (verify a UI change, check styling/layout)? Use \`screenshot_component\` with
-a testID/name \u2014 it locates the live component on-device and returns a cropped screenshot inline.
-iOS Simulator only, and only works when this MCP server runs on the same Mac as the booted Simulator.
-
-Need to DRIVE the UI? Reach for \`run_flow\` FIRST: it runs a whole scripted sequence
-(tap / type / set / reload / waitFor / expect) in ONE call and reports the per-step result, the
-final screen, and the network + console output the flow produced. Reproducing a bug and verifying
-a fix are one call each instead of a dozen alternating reads and taps, and a failed step reports
-the screen at the point it broke. Drop to \`describe_screen\` (list on-screen elements with testIDs
-and tap points) + \`tap_element\` only for one-off pokes or when you don't yet know what's there.
-
-Screen slow / laggy / janky / stutters, typing lags, or "the whole page re-renders when I tap
-one thing"? Start with \`measure_renders\` \u2014 one call, no test route needed. Pass \`steps\` for the
-interaction you're actually asking about (a tap, some typing); an idle sample says nothing about
-what a tap costs. It returns per-component render counts, WHY each rendered (parent cascade / own
-state / changed props), which parent dragged it along, and \`wasted\` \u2014 the renders that produced
-nothing new. After you edit, call it again with the same steps and \`compareToPrevious:true\`:
-re-render fixes routinely move the cost somewhere else instead of removing it, and only a second
-measurement catches that.
-
-JS FPS low / app hitching and you need to know WHAT is eating the JS thread? Use
-\`get_js_thread_top\` (a live "Task Manager" of timers, Promise chains, rAF callbacks and
-freezes, ranked by thread time), then \`get_js_thread_origin_detail\` to drill into a row.
-Pass clearFirst:true and drive the UI with \`tap_element\` mid-sample to profile one interaction.
-This is about TASKS on the thread \u2014 for React components re-rendering too often, it's
-\`measure_renders\`, not this.
-
-Debugging images (not loading, slow, stale cache, memory)? \`get_images\` lists every RN <Image> /
-expo-image load with cache verdicts and oversize audits; \`image_action\` reloads, retries, or
-simulates failures per image; \`set_image_simulation\` flips app-wide offline/cold/blank modes.
-
-Auditing app size / bundled assets? \`get_assets\` inventories everything the app SHIPS \u2014 images,
-fonts, video, audio \u2014 with byte sizes, scale coverage, and findings (duplicates, never-loaded,
-WebP candidates, heavy GIFs/fonts). \`asset_action\` rescans, fetches per-asset detail, and runs
-the baseline diff workflow (save_baseline \u2192 change something \u2192 get_assets shows what it added).
-get_images = what RENDERS at runtime; get_assets = what SHIPS in the bundle.
-
-Need the app RESTARTED (a change Fast Refresh didn't pick up, leaked in-memory state before a
-measurement, re-running startup)? \`reload_app\` reloads the JS bundle \u2014 DevSettings.reload() in dev
-builds, expo-updates otherwise \u2014 and waits for the app to reconnect. It wipes in-memory state, so
-re-read anything you cached.
-
-Testing a multi-step flow repeatedly (cart \u2192 checkout, login states, a bug that needs specific
-state)? \`time_machine_action\` captures the app's COMPLETE client state (storage, redux, zustand,
-jotai, react-query cache) as a named restore point and restores it in one call \u2014 capture once,
-drive the flow with \`tap_element\`, restore, repeat. \`get_time_machine\` lists restore points and
-which sources are restorable. Restore mode 'live' swaps state in place; 'reload' restores
-persisted storage then reloads the bundle (bulletproof; baselines = wipe to fresh install).
-Check the per-source applied/skipped results it returns \u2014 a partial restore is reported, not hidden.
-
-For everything else:
-- \`list_tool_actions\` to see what a tool can do,
-- \`get_snapshot\` ONLY when you need a tool's full current state (returns raw, heavy payloads),
-- \`call_action\` to invoke any tool action generically.
-
-Higher-level tools (e.g. perf-monitor's \`run_benchmark_batch\`) wrap these for common workflows.
-If no device is connected, open the app with Buoy devtools running and try again.
-
-The Buoy MCP is a Pro feature: \`list_devices\` is always available, but data/action tools
-require the connected app to have an active Buoy Pro license. If they error with "Buoy Pro
-required", tell the user to upgrade to Buoy Pro in the app \u2014 don't try to work around it.`;
+var SERVER_INSTRUCTIONS = `Buoy MCP connects your editor to supported Buoy tools through the configured broker.
+
+Start with account and connection setup. Use \`list_devices\` to select an app and inspect
+its available tools. App data and action tools require Buoy Pro. If access fails, explain
+the reported requirement and setup steps. Camera tools use a separate local setup and
+account gate; \`camera_diagnose\` can report setup problems without an app connection.
+
+For a runtime bug, \`get_triage\` summarizes available console errors, network activity,
+storage and screen information. Follow up on the relevant section and read source when
+needed. Missing data can reflect missing integration, retention limits or a disconnected
+app. An unresponsive app is not proof of a crash, and post-crash evidence may be unavailable.
+
+Choose follow-up tools by the symptom:
+- Persisted values: \`get_storage\` with \`includeValues:true\` for configured storage sources.
+- Requests or API responses: \`get_network_requests\` with \`includeBodies:true\` for captured
+  bodies. Capture depends on supported transports, installed hooks and recording timing.
+- Errors: \`get_console\` for retained captured output. A stopped app cannot provide new data.
+- Cache or store state: \`get_react_query\`, \`get_zustand_state\`, \`get_redux_state\` or
+  \`get_jotai_state\` for the integrations registered in the app.
+
+Use \`get_events\` with \`sources\` to read retained activity from connected event sources.
+It returns compact summaries by default; request \`includeData:true\` when details are needed.
+For request IDs and network actions, use \`get_network_requests\`. Its \`flagged:'any'\` filter
+finds pinned or saved requests. A flag is a reason to inspect a request, not proof of its
+cause or who flagged it. Use \`network_action\` to retain relevant evidence within task scope.
+
+For supported UI interactions, \`run_flow\` runs steps such as tap, type, set, reload,
+waitFor and expect. Review step results, failures and available captured output. Use
+\`describe_screen\` to discover exposed elements and \`tap_element\` for individual actions.
+A completed tool call alone does not establish that the user's expected behavior occurred.
+
+For render-heavy interactions, use \`measure_renders\` with representative \`steps\`.
+Repeat the same steps after a change with \`compareToPrevious:true\`. Interpret available
+render counts, reasons and wasted-render diagnostics alongside behavior and performance;
+these diagnostics do not prove that a render was unnecessary. For instrumented JavaScript
+tasks, use \`get_js_thread_top\` and \`get_js_thread_origin_detail\`. Their coverage depends
+on the installed hooks. Keep measurement conditions comparable.
+
+\`get_images\` inspects instrumented image loads and available cache, timing, size and error
+data. Use \`image_action\` for supported per-image actions and \`set_image_simulation\` for
+integrated image behavior. Simulation does not disconnect the device's network.
+\`get_assets\` inspects the configured manifest, runtime registry and available bundle graph.
+Reported load history and size estimates do not prove complete shipped-asset coverage or
+that an unobserved asset is unused. \`asset_action\` can refresh data and manage baselines.
+
+\`reload_app\` requests a JS reload using supported app mechanisms and can wait for
+reconnection. It can try a dev-server fallback for an unresponsive app when that server
+is known and reachable. Recovery is not guaranteed. Reload can discard in-memory evidence;
+collect needed observations first when possible and read state again after reconnecting.
+
+\`get_time_machine\` lists snapshots and provider capabilities. \`time_machine_action\`
+captures or restores supported registered state sources. Preview the affected state before
+restoring. Live restore changes supported state in place; reload mode restores supported
+persisted sources and requests a reload. A baseline clears providers that support clearing
+and requests a reload. This does not reset backend state or reproduce a complete reinstall.
+Check per-source applied/skipped outcomes and any reload or route-restoration failures.
+
+For iOS Simulator camera input, inspect setup with \`camera_diagnose\`. Use \`camera_source\`
+for supported barcode, file or screen input, \`camera_devices\` for simulators/apps and
+\`camera_inputs\` for local sources. \`camera_launch\` attaches input when launching the app;
+\`camera_zero_setup\` configures attachment for another launcher. \`camera_status\` reports
+available source/decoder status, which does not establish the app's scanner result.
+Use \`camera_stop\` when finished. These tools operate locally without an in-app Buoy
+integration, but require their supported host, simulator and account setup.
+
+\`screenshot_component\` locates a supported component by testID/name and attempts a crop.
+It requires the MCP server on the same Mac as the booted iOS Simulator and the component
+inspection setup. Inspect the result before using it as visual evidence.
+
+For other supported operations, use \`list_tool_actions\`, \`get_snapshot\` or \`call_action\`.
+Snapshots describe available current state and can be large; request only needed data.
+
+After a behavior change, repeat the affected interaction and check the expected result.
+Include restart or persistence checks when relevant to the change. Use appropriate static
+checks for documentation-only work. Report actual checks, observations and remaining limits.
+BUOY_VERIFY reminders track selected edits and tool calls; clearing a reminder is not a
+test result. Stay within the user's authorized task and preserve existing project work.`;
 var VERIFYING_TOOLS = /* @__PURE__ */ new Set([
   "measure_renders",
   "scenario_action",
@@ -5946,21 +6214,21 @@ function runInit(opts = {}) {
   installSkills(skillSrcDir, cwd, done);
   appendDebuggingGuide(path5.join(cwd, "CLAUDE.md"), cwd, done);
   appendDebuggingGuide(path5.join(cwd, "AGENTS.md"), cwd, done);
-  log("Buoy MCP installed:");
+  log("Buoy MCP configuration written:");
   for (const line of done) log("  \u2022 " + line);
   log("");
   log("Next steps:");
   log("  1. Restart your editor (or reconnect the MCP server) to load `buoy`.");
-  log("  2. Open your app with Buoy devtools running on a device or simulator.");
-  log('  3. Say "buoy optimize" to start a guided performance pass.');
+  log("  2. Complete account setup, then open an app with the required Buoy tools and sync integration.");
+  log("  3. Confirm the device and tools are available. MCP data/action access requires Pro.");
   if (entry.command === "npx") {
     log("");
-    log(`This launches the server via \`npx -y ${PACKAGE_NAME}@latest\`, so it stays`);
-    log(`up to date automatically. To force-refresh, re-run \`npx -y ${PACKAGE_NAME}@latest init\`.`);
+    log(`The editor launches the server with \`npx -y ${PACKAGE_NAME}@latest\`, so it stays`);
+    log(`Registry access may be needed. Re-run \`npx -y ${PACKAGE_NAME}@latest init\` to refresh configuration.`);
   } else if (!opts.cliPath) {
     log("");
     log(`This uses a pinned local install (no network on startup). To update it later,`);
-    log(`re-run init (\`node ${entry.args[0]?.replace(/dist[/\\]cli\.js$/, "") ?? ""}...\` \u2014 or reinstall).`);
+    log(`To update the local package, run: npx -y ${entry.args[0]?.replace(/dist[/\\]cli\.js$/, "") ?? ""}@latest init --local`);
   }
 }
 function resolveEntry(opts, log) {
@@ -6095,57 +6363,37 @@ function upsertMcpConfig(file, key, entry, cwd, done) {
 var GUIDE_HEADING = "# Debugging with Buoy";
 var DEBUGGING_GUIDE = `${GUIDE_HEADING}
 
-This app's runtime is inspectable while it runs: the Buoy MCP tools read live
-state straight from the device. Route by symptom before reading source:
-
-- \`get_triage\` \u2014 START HERE. One call: device, recent console errors and
-  crashes, recent network requests, storage keys, and what's on screen. It
-  usually names the problem, and always names the tool to drill into next.
-- \`run_flow\` \u2014 reproduce a bug or verify a fix in ONE call: a scripted
-  tap/type/wait/assert sequence that returns the final screen plus the network
-  and console output it produced. Use it instead of alternating
-  \`describe_screen\` and \`tap_element\` a dozen times.
-- \`get_events\` \u2014 the universal activity timeline (network, state changes,
-  storage writes, routes, renders). Check it BEFORE driving the UI to
-  reproduce a bug \u2014 the failure is usually already recorded.
-- \`get_network_requests\` \u2014 API data wrong or calls failing \u2192 read the actual
-  request + response bodies instead of guessing from code. Boot-time requests
-  are captured too.
-- \`get_console\` \u2014 crashes and errors, including FATAL uncaught JS errors
-  (tagged \`[FATAL]\`, with the component that crashed). Readable even after the
-  app dies, so a redboxed app still tells you why.
-- \`get_storage\` \u2014 data wrong or missing after an app restart \u2192 read the
-  persisted values FIRST.
-- \`reload_app\` \u2014 recover a crashed app (the other tools stop answering until
-  you do) or pick up a change Fast Refresh missed.
-- \`get_snapshot\` \u2014 full current state of any one tool when the compact views
-  aren't enough.
-
-Runtime facts beat guesses \u2014 and after you edit, prove the fix on the device:
-reload, then re-drive EVERY screen the symptom could show up on and assert the
-corrected value. Fixes usually fail by being incomplete, not by being wrong.
-
-## Don't report a fix you haven't watched work
-
-Saying "fixed" is a claim about how the app behaves, so check it the same way
-you'd check anything else about the app \u2014 by looking at it. Re-run the exact
-interaction that was broken and report what the numbers did:
-
-- \`measure_renders\` with the same \`steps\` and \`compareToPrevious: true\` for a
-  performance change \u2014 it prints the before/after delta and flags a change that
-  made things worse.
-- \`run_flow\` re-driving the broken screen for a behaviour change.
-
-Two things this catches that reading cannot: a fix that is right but incomplete
-(the value was wrong in three places and you corrected one), and a fix that
-moved the cost instead of removing it \u2014 the usual failure mode for re-render
-work, where a page gets faster to type in and slower to tap.
-
-If the app changed since anything was last checked, Buoy will say so in a tool
-result. Whether that's worth acting on is your call \u2014 a doc edit isn't worth a
-device check, a state-management change is. Set \`BUOY_VERIFY\` in the MCP config
-to \`always\` (repeat until checked) or \`never\` (silent) to change how often it
-mentions it.
+Use Buoy to inspect a connected app when runtime evidence helps the task.
+Complete account, tool integration and connection setup first. MCP data and
+action access requires Pro. Follow the user's scope and repository instructions.
+
+- \`get_triage\`: summarize available device and tool observations, then choose
+  a relevant tool. Missing data is not proof that no problem occurred.
+- \`run_flow\`: run supported tap, type, wait and assertion steps to reproduce
+  a failure or check a change. Review the flow before running it.
+- \`get_events\`: inspect retained events from connected tools.
+- \`get_network_requests\`: inspect captured requests and responses. Capture
+  depends on installed hooks, transport and when recording began.
+- \`network_conditions\`: take the app offline or add latency to check error
+  and retry paths. Development builds only. Restore \`normal\` when finished.
+- \`get_console\`: inspect retained console and error output. A terminated or
+  disconnected app may not provide new data.
+- \`get_storage\`: inspect registered storage backends and available keys.
+- \`reload_app\`: reload where supported. Confirm the device remains connected;
+  a reload does not guarantee recovery from a crash.
+- \`get_snapshot\`: inspect the available state of a specific tool.
+
+After a behavior change, repeat the failing interaction when the environment
+allows it. Use relevant tests and report what was actually checked. For a
+performance change, compare \`measure_renders\` runs with the same steps and
+\`compareToPrevious: true\`; inspect the measurements and their limitations.
+Use \`run_flow\` for supported UI checks. Do not claim a fix was verified when
+only source review or a build was performed.
+
+\`BUOY_VERIFY\` controls verification reminders: \`auto\` uses edit-based
+reminders, \`always\` repeats until checked, and \`never\` disables them.
+A reminder is not a test result. Choose checks appropriate to the change;
+prose-only edits do not require running device actions.
 `;
 function appendDebuggingGuide(file, cwd, done) {
   let existing = "";
@@ -6157,7 +6405,7 @@ function appendDebuggingGuide(file, cwd, done) {
       return;
     }
     if (existing.includes(GUIDE_HEADING)) {
-      done.push(`${rel(file, cwd)} already has the "${GUIDE_HEADING}" block`);
+      done.push(`${rel(file, cwd)} already has the "${GUIDE_HEADING}" block; preserved existing text. Review it against the current bundled guidance before relying on older instructions.`);
       return;
     }
   }