@buoy-gg/agent-core 7.0.34 → 7.0.36

package/lib/module/catalog/catalog.source.json

@@ -132,7 +132,7 @@
     "actions": [
       {
         "action": "listAtoms",
-        "summary": "List every watched Jotai atom with label, change count, and whether it can be written.",
+        "summary": "Compact reader for a remote driver: the registered atoms with light metadata. Each atom's value stays on the device unless `includeValues` is set, and `limit` caps how many are returned. `writable` says which can be set via setAtom. Each atom also carries `shape` — the item type of any list it holds — which is the cheap way to learn what an addition must look like.",
         "params": {
           "type": "object",
           "properties": {
@@ -149,7 +149,7 @@
         },
         "effect": "read",
         "release": "works",
-        "description": "Start here. Returns { atoms: [{ label, changes, writable, currentValue? }], total, returned, includedValues }. Compact by default — values are omitted, so it is token-cheap. `writable:true` means the atom has a write function and the store exposes set(), i.e. setAtom will work on it; derived/read-only atoms report writable:false. Labels are the object keys the app passed to watchAtoms(store, { countAtom, authAtom }), so they are the app's own variable names. includeValues:true inlines the full current value of every atom with NO size cap — prefer getAtomValue for a single big atom.",
+        "description": "Compact reader for a remote driver: the registered atoms with light metadata. Each atom's value stays on the device unless `includeValues` is set, and `limit` caps how many are returned. `writable` says which can be set via setAtom. Each atom also carries `shape` — the item type of any list it holds — which is the cheap way to learn what an addition must look like.",
         "requires": [
           "@buoy-gg/jotai installed in the app",
           "watchAtoms(store, atoms) or watchDefaultStoreAtoms(atoms) called at app startup"
@@ -157,13 +157,17 @@
       },
       {
         "action": "getAtomValue",
-        "summary": "Fetch one atom's current value on demand, by label.",
+        "summary": "Fetch one atom's current value on demand, by label. Send `path` to get back ONE value instead of the whole atom (path:\"lines[id=seed-1].qty\") — do that whenever the value is big, because results are cut off at 24,000 characters. Also returns `shape`: a one-line sketch of the value's type plus, for each list in it, what its items look like. Read it before writing and match it exactly.",
         "params": {
           "type": "object",
           "properties": {
             "label": {
               "type": "string",
               "description": "Atom label exactly as registered — the object key in watchAtoms(store, { countAtom }), e.g. \"countAtom\". Get exact labels from listAtoms."
+            },
+            "path": {
+              "type": "string",
+              "description": "Return only the value at this path instead of the whole atom value."
             }
           },
           "required": [
@@ -173,7 +177,7 @@
         },
         "effect": "read",
         "release": "works",
-        "description": "Returns { found:true, label, currentValue } or { found:false, reason:'missing label' | 'unknown label' }. Use this after listAtoms when the snapshot showed the placeholder {__buoyValueOnDevice:true} — the sync snapshot swaps in that marker for any atom value over 16KB or that fails JSON.stringify. Values over 8MB come back as {__buoyTruncated:true}; unserializable values (cycles, functions) come back as the on-device marker. Reading never throws: a getter that throws yields currentValue undefined.",
+        "description": "Fetch one atom's current value on demand, by label. Send `path` to get back ONE value instead of the whole atom (path:\"lines[id=seed-1].qty\") — do that whenever the value is big, because results are cut off at 24,000 characters. Also returns `shape`: a one-line sketch of the value's type plus, for each list in it, what its items look like. Read it before writing and match it exactly.",
         "requires": [
           "The label must already be registered via watchAtoms — call listAtoms first for exact labels"
         ]
@@ -203,7 +207,7 @@
       },
       {
         "action": "setAtom",
-        "summary": "Write a new value to a writable Jotai atom — this mutates the running app's state.",
+        "summary": "Write to a writable Jotai atom, named by its `label` — this mutates the running app's state. Three forms: `value` alone REPLACES; `value` with `merge:true` merges a patch under the typed-edit rule (change existing fields to the same type; a list may grow or shrink but every item must have the fields the others have); `path`+`value` sets ONE value with no nesting to get wrong (path:\"lines[id=seed-1].qty\"). To change one item of a list, address it by its own id — {\"lines\":{\"seed-1\":{\"qty\":5}}} changes one, {\"lines\":{\"seed-2\":null}} removes one, a new id adds one; items you don't name are untouched. A plain array replaces the whole list. A refused merge names the field and, when the problem was depth, hands back the corrected patch — fix it that way rather than reaching for `force`, which writes raw and can crash the screen.",
         "params": {
           "type": "object",
           "properties": {
@@ -213,6 +217,18 @@
             },
             "value": {
               "description": "The new value — any JSON (number, string, boolean, object, array, null). Passed straight to store.set(atom, value); it REPLACES the value, no merging."
+            },
+            "merge": {
+              "type": "boolean",
+              "description": "Merge `value` into the atom's current value instead of replacing it, under the typed-edit rule. Default false."
+            },
+            "path": {
+              "type": "string",
+              "description": "Set ONE value inside the atom, named by its path in the CURRENT value — read it first and copy the path from `shape`. Always a merge. A list step is written [field=value] or [0] and resolves to that item's own id."
+            },
+            "force": {
+              "type": "boolean",
+              "description": "Bypass the typed-edit safety and write raw. This is what crashes screens; use ONLY to deliberately replace the whole shape."
             }
           },
           "required": [
@@ -223,7 +239,7 @@
         },
         "effect": "write",
         "release": "works",
-        "description": "Calls store.set(atom, value) — the app re-renders exactly as if user code had written the atom. Replaces the whole value; there is no merge, so pass a complete object for object atoms. THROWS (no silent failure) with 'setAtom requires a `label`' when label is missing, 'Atom \"X\" is not registered' for an unknown label, and 'Atom \"X\" is read-only (derived) — cannot set' for a derived atom — check writable:true in listAtoms first. Returns no payload; confirm the write with getAtomValue. Note the param is `label` on the wire even though the MCP wrapper names it `atom`.",
+        "description": "Write to a writable Jotai atom, named by its `label` — this mutates the running app's state. Three forms: `value` alone REPLACES; `value` with `merge:true` merges a patch under the typed-edit rule (change existing fields to the same type; a list may grow or shrink but every item must have the fields the others have); `path`+`value` sets ONE value with no nesting to get wrong (path:\"lines[id=seed-1].qty\"). To change one item of a list, address it by its own id — {\"lines\":{\"seed-1\":{\"qty\":5}}} changes one, {\"lines\":{\"seed-2\":null}} removes one, a new id adds one; items you don't name are untouched. A plain array replaces the whole list. A refused merge names the field and, when the problem was depth, hands back the corrected patch — fix it that way rather than reaching for `force`, which writes raw and can crash the screen.",
         "requires": [
           "listAtoms reports writable:true for this label (atom has a write fn AND the store exposes set())"
         ]
@@ -280,7 +296,7 @@
       },
       {
         "action": "navigate",
-        "summary": "Navigate the device to a concrete path (pushes by default; replace:true swaps the current screen).",
+        "summary": "Navigate the device to a concrete path (pushes by default; replace:true swaps the current screen). ALSO HOW YOU LOAD DATA THE APP HAS NOT FETCHED YET: go to the screen that fetches it, waitFor something on it, then read. Moving the user's screen to go and look is not a change to the app — you do not need to ask, and you do not have to navigate back.",
         "params": {
           "type": "object",
           "properties": {
@@ -300,7 +316,7 @@
         },
         "effect": "write",
         "release": "works",
-        "description": "Calls expo-router's router.navigate(path), or router.replace(path) when replace:true. On bare React Navigation (no expo-router) it falls back to navigating by SCREEN NAME through the captured container ref — pass the screen's name ('Settings' or '/Settings'; replace is ignored there), and nested navigators are resolved automatically. The fallback needs <RouteTracker/> mounted inside the NavigationContainer. Pass a CONCRETE path — sitemap entries are templates ('/pokemon/[id]'), so resolve dynamic segments to real values ('/pokemon/25') first; a query string is allowed ('/pokemon/25?tab=stats'). Push is the default so navigate-then-back flows keep working; pass replace:true when you mean 'leave this screen' (e.g. resetting to '/'), otherwise repeated 'go to home' stacks another '/' on top. Throws 'navigate requires a path param' when path is missing/empty, and 'expo-router is not available on this device' on React-Navigation-only apps. Returns { navigated: path, replaced: boolean }. The return only proves the router call was made, not that the screen rendered — re-read the snapshot's stack to confirm.",
+        "description": "Calls expo-router's router.navigate(path), or router.replace(path) when replace:true. On bare React Navigation (no expo-router) it falls back to navigating by SCREEN NAME through the captured container ref — pass the screen's name ('Settings' or '/Settings'; replace is ignored there), and nested navigators are resolved automatically. The fallback needs <RouteTracker/> mounted inside the NavigationContainer. Pass a CONCRETE path — sitemap entries are templates ('/pokemon/[id]'), so resolve dynamic segments to real values ('/pokemon/25') first; a query string is allowed ('/pokemon/25?tab=stats'). Push is the default so navigate-then-back flows keep working; pass replace:true when you mean 'leave this screen' (e.g. resetting to '/'), otherwise repeated 'go to home' stacks another '/' on top. Throws 'navigate requires a path param' when path is missing/empty, and 'expo-router is not available on this device' on React-Navigation-only apps. Returns { navigated: path, replaced: boolean }. The return only proves the router call was made, not that the screen rendered — re-read the snapshot's stack to confirm, and use highlight-updates.waitFor before reading anything the new screen has to FETCH. This is the main tool for filling a gap in what you can read: the query cache, the request list and the events timeline only ever hold what the app has ALREADY done, so when the data you were asked about was never loaded, the answer is to go to the screen that loads it rather than to report the gap.",
         "requires": [
           "expo-router installed and initialized in the app",
           "<FloatingDevTools> mounted (adapter registered)"
@@ -482,7 +498,7 @@
         },
         "effect": "read",
         "release": "works",
-        "description": "The entry point — call this first to learn valid storeName values for getStoreState/setState. Returns {stores:[{name, changes, isPersisted, persistName?, keys?|currentState?}], total, returned, includedValues}. Compact by default: `keys` is Object.keys() of the state (undefined when the state isn't a plain object). includeValues:true swaps `keys` for the full `currentState` object and can be very large — the state objects here are NOT wire-budget-capped the way the streaming snapshot is. `changes` is that store's recorded state-change count, reset to 0 by clearEvents. Names come from the app: the object keys passed to watchStores({counterStore: useCounterStore}) or the `name` option of buoyDevTools(). An empty stores array means the app never instrumented its stores, not that it has none.",
+        "description": "The entry point — call this first to learn valid storeName values for getStoreState/setState. Returns {stores:[{name, changes, isPersisted, persistName?, keys?|currentState?}], total, returned, includedValues}. Compact by default: `keys` is Object.keys() of the state (undefined when the state isn't a plain object). includeValues:true swaps `keys` for the full `currentState` object and can be very large — the state objects here are NOT wire-budget-capped the way the streaming snapshot is. `changes` is that store's recorded state-change count, reset to 0 by clearEvents. Names come from the app: the object keys passed to watchStores({counterStore: useCounterStore}) or the `name` option of buoyDevTools(). An empty stores array means the app never instrumented its stores, not that it has none. Every read here also returns `shape`: a one-line sketch of the value's type plus, for each list in it, what its items look like. It is tiny and does not grow with the data, so it survives the 24,000-character cut when the data itself does not — read it before writing, and match it exactly. A list whose `item` is missing is EMPTY, which means nothing in the running app knows what belongs in it; anything you add there cannot be checked and will be accepted as-is, so say so rather than inventing fields.",
         "requires": [
           "@buoy-gg/zustand installed and the zustand tool registered with FloatingDevTools",
           "the app calls watchStores({...}) or wraps stores with buoyDevTools() — otherwise the registry is empty"
@@ -490,13 +506,17 @@
       },
       {
         "action": "getStoreState",
-        "summary": "Fetch one store's full current state object on demand, by store name.",
+        "summary": "Fetch one store's full current state object on demand, by store name. Send `path` to get back ONE value instead of the whole store (path:\"lines[lineId=seed-1].qty\") — do that whenever the store is big, because results are cut off at 24,000 characters.",
         "params": {
           "type": "object",
           "properties": {
             "storeName": {
               "type": "string",
               "description": "Registered store name exactly as listStores reports it (e.g. \"counterStore\", \"authStore\", \"cartStore\"). Case-sensitive; no fuzzy matching."
+            },
+            "path": {
+              "type": "string",
+              "description": "Return only the value at this path instead of the whole payload. Use it when you only need one field, and ALWAYS when the payload is big: results are cut off at 24,000 characters, and a field you never saw is a field you will guess the shape of. The path must match the CURRENT data — read `shape` first rather than assuming a wrapper. On a bad path it answers with the field names that do exist, and with the path that would have worked if that field lives somewhere else."
             }
           },
           "required": [
@@ -506,7 +526,7 @@
         },
         "effect": "read",
         "release": "works",
-        "description": "Use when listStores' compact `keys` view isn't enough, or when the streaming snapshot showed the {__buoyStateOnDevice:true} marker (states over 16KB are withheld from the per-snapshot wire). Returns {found:true, storeName, currentState} — or {found:false, reason:\"missing storeName\"} / {found:false, reason:\"unknown storeName\"}, which is a plain answer, not an error. currentState is read live via store.api.getState(); if that throws it comes back undefined. Over the 8MB detail cap it returns {__buoyTruncated:true, note} instead, or the STATE_ON_DEVICE marker when the state isn't JSON-serializable. Note that action functions living in state (increment, reset, …) do not survive the JSON wire — what you read back is the data half of the store only.",
+        "description": "Use when listStores' compact `keys` view isn't enough, or when the streaming snapshot showed the {__buoyStateOnDevice:true} marker (states over 16KB are withheld from the per-snapshot wire). Returns {found:true, storeName, currentState} — or {found:false, reason:\"missing storeName\"} / {found:false, reason:\"unknown storeName\"}, which is a plain answer, not an error. currentState is read live via store.api.getState(); if that throws it comes back undefined. Over the 8MB detail cap it returns {__buoyTruncated:true, note} instead, or the STATE_ON_DEVICE marker when the state isn't JSON-serializable. Note that action functions living in state (increment, reset, …) do not survive the JSON wire — what you read back is the data half of the store only. Every read here also returns `shape`: a one-line sketch of the value's type plus, for each list in it, what its items look like. It is tiny and does not grow with the data, so it survives the 24,000-character cut when the data itself does not — read it before writing, and match it exactly. A list whose `item` is missing is EMPTY, which means nothing in the running app knows what belongs in it; anything you add there cannot be checked and will be accepted as-is, so say so rather than inventing fields. Send `path` to get back ONE value instead of the whole store (path:\"lines[lineId=seed-1].qty\") — do that whenever the store is big, because results are cut off at 24,000 characters.",
         "requires": [
           "the store must already be registered — get the exact name from listStores"
         ]
@@ -536,7 +556,7 @@
       },
       {
         "action": "setState",
-        "summary": "Write new state into a live Zustand store. Buoy defaults this to a partial MERGE (replace:false) so a write cannot silently wipe the store's other fields and action functions.",
+        "summary": "Change a live zustand store. Ask Buoy MERGES by default (replace:false): it shallow-merges the fields you send and KEEPS the store's action functions (setQty, removeLine, …) and untouched keys. Never send replace:true unless you mean to reset the whole store — replacing drops the functions (they can't cross the wire), and the app's buttons that call them then crash. To change a list in the store, ADDRESS ITEMS BY THEIR OWN id instead of resending the list: {\"lines\":{\"seed-1\":{\"qty\":5}}} changes one field of one item, {\"lines\":{\"seed-2\":null}} removes that item, and a key that isn't in the list yet appends a new item (send all its fields). Items you don't name are untouched, so this is the only safe form when you haven't seen the whole list — a capped read means you CANNOT resend it without deleting what you weren't shown. Sending a plain ARRAY still works and still replaces the whole list, which is how you deliberately empty it. On a merge it's a TYPED EDIT: you can only change a field that already exists, to the same type, and any list item you add must match the shape of the ones already there — a wrong type, an unknown field, or a malformed new item is refused with the exact path. force:true bypasses. To change a single value, `path` + `value` is the safest form (path:\"lines[lineId=seed-1].qty\", value:5): it is always a merge and there is no nesting to get wrong.",
         "params": {
           "type": "object",
           "properties": {
@@ -553,17 +573,27 @@
               "type": "boolean",
               "description": "true replaces the whole state — including the store's action functions, which breaks every button wired to them until the app reloads. Buoy sends false for you unless you explicitly pass true, so a partial merge is the safe path: pass only the fields you intend to change (e.g. {\"count\": 5}). The ADAPTER's own default is true; this is a deliberately safer default for agent calls.",
               "default": false
+            },
+            "force": {
+              "type": "boolean",
+              "description": "Bypass the typed-edit safety on a merge and write raw. Default false — a violating merge is refused."
+            },
+            "path": {
+              "type": "string",
+              "description": "Set ONE value, named by its full path in the CURRENT data: path:\"<the real path>\", value:<new value>. READ THE DATA FIRST AND COPY THE PATH FROM IT — `shape` on getStoreState/listStores prints it. A path is only safer than a hand-nested `data` if it matches the payload you are actually looking at; if the field is at the top level the path is just \"name\", and inventing a wrapper that is not there is refused. A list step is written [field=value] or [0] and resolves to that item's own id, so it still means the same row if the list changed. Always a merge, and always through the same typed-edit guard as `data`. Requires `value`; send `data` OR `path`+`value`, not both."
+            },
+            "value": {
+              "description": "The value `path` is set to. Required whenever `path` is sent. null is a real value (only allowed if the field is already nullable), not a delete."
             }
           },
           "required": [
-            "storeName",
-            "state"
+            "storeName"
           ],
           "additionalProperties": false
         },
         "effect": "destructive",
         "release": "works",
-        "description": "Powers time-travel / reset / 'put the app in this state' from a dashboard. Calls the store's real setState(state, replace ?? true). THE DEFAULT IS DESTRUCTIVE: `replace` defaults to TRUE, so any key missing from `state` is deleted — and Zustand stores conventionally keep their action functions in state (increment, login, addToCart). Functions cannot cross the sync wire, so a JSON `state` object can never carry them back; a default-replace leaves every `useStore(s => s.increment)` call site reading undefined and the app broken until reload. Buoy's own Time Machine restore avoids this by re-grafting the live store's functions onto the snapshot before replacing (packages/zustand/src/zustand/utils/snapshotProvider.ts:8-12) — this raw action does NOT do that. For a QA-facing tweak always pass replace:false to merge just the fields you're changing. Returns {ok:true}, or {ok:false, error:\"Missing storeName.\"} / {ok:false, error:'No store named \"X\".'}. The write also lands in the change log as a normal recorded change.",
+        "description": "Powers time-travel / reset / 'put the app in this state' from a dashboard. Calls the store's real setState(state, replace ?? true). THE DEFAULT IS DESTRUCTIVE: `replace` defaults to TRUE, so any key missing from `state` is deleted — and Zustand stores conventionally keep their action functions in state (increment, login, addToCart). Functions cannot cross the sync wire, so a JSON `state` object can never carry them back; a default-replace leaves every `useStore(s => s.increment)` call site reading undefined and the app broken until reload. Buoy's own Time Machine restore avoids this by re-grafting the live store's functions onto the snapshot before replacing (packages/zustand/src/zustand/utils/snapshotProvider.ts:8-12) — this raw action does NOT do that. For a QA-facing tweak always pass replace:false to merge just the fields you're changing. Returns {ok:true}, or {ok:false, error:\"Missing storeName.\"} / {ok:false, error:'No store named \"X\".'}. The write also lands in the change log as a normal recorded change. A write that adds the first item to an EMPTY list comes back ok with `unchecked`: the list had no items, so nothing knew its item shape and yours was not verified. Treat that as a warning to check the screen, not as a pass. To change a single value, `path` + `value` is the safest form (path:\"lines[lineId=seed-1].qty\", value:5): it is always a merge and there is no nesting to get wrong.",
         "requires": [
           "the store must be registered — get the exact name from listStores",
           "the store's registered setState handle: watchStores registers the raw setState, buoyDevTools registers its instrumented set (both apply the write)"
@@ -912,11 +942,11 @@
   {
     "toolId": "query",
     "title": "React Query",
-    "summary": "Reads and mutates the app's live TanStack Query (React Query) cache on the device: list every query with status/staleness/observers/error, pull one query's real cached data, and then refetch / invalidate / reset / remove / overwrite it, simulate a query error or a perpetual loading state, clear the whole query or mutation cache, and flip TanStack's onlineManager to fake offline. Reach for it when data on screen is stale, wrong, or missing and you need to know whether the CACHE or the API is at fault (get_network_requests answers the API half). Everything here is the current cache — for the history of query updates over time use the events tool with sources:['react-query'].",
+    "summary": "THE way to change what a server-backed screen shows. Most screens that render API data render this cache, so \"edit what I'm looking at\" on such a screen means setQueryData on the query that is mounted (observers > 0), not a store and not the API. Also reads and mutates the rest of the app's live TanStack Query (React Query) cache on the device: list every query with status/staleness/observers/error, pull one query's real cached data, and then refetch / invalidate / reset / remove / overwrite it, simulate a query error or a perpetual loading state, clear the whole query or mutation cache, and flip TanStack's onlineManager to fake offline. Reach for it when data on screen is stale, wrong, or missing and you need to know whether the CACHE or the API is at fault (network.getSnapshot answers the API half), and for the QA moves — force the error view (triggerError), the loading view (triggerLoading), a specific payload (setQueryData). A cache edit lasts until the next successful refetch; when the change must survive a refetch or a reload, put a network override on the request instead and invalidate. Everything here is the current cache — for the history of query updates over time use the events tool with sources:['react-query'].",
     "actions": [
       {
         "action": "listQueries",
-        "summary": "List every query in the cache — hash, key, status, staleness, observer count, last-updated, error message. The token-cheap cache reader; start here.",
+        "summary": "List every query in the cache — hash, key, status, staleness, observer count, last-updated, error message. The token-cheap cache reader; start here. Send `staleOnly:true` to see only stale queries. THIS IS A CACHE, NOT AN INVENTORY: it holds only what this app has already fetched in this session, so a short list means the user has not visited those screens yet, never that the data does not exist.",
         "params": {
           "type": "object",
           "properties": {
@@ -937,7 +967,7 @@
         },
         "effect": "read",
         "release": "works",
-        "description": "Projects each live query to light fields: queryHash, queryKey, status (one of fresh/stale/fetching/error/inactive/paused/disabled, from getQueryStatusLabel), fetchStatus, isStale, observers, updatedAt (state.dataUpdatedAt), and error.message when present. Returns {queries, total, returned, includedData}. Sorted most-recently-updated first. Safe to call repeatedly — unlike the full dehydrated snapshot, the heavy cached data stays on the device by default. TWO TRAPS: (1) the adapter has NO default limit — omit it and you get every query in the cache; (2) includeData:true returns q.state.data RAW and UNCAPPED (no 16KB wire marker, no 8MB cap like getQueryData), so it can blow the wire/token budget on a big cache — prefer getQueryData for one query's payload. The queryHash of each row is the handle every other action takes.",
+        "description": "Projects each live query to light fields: queryHash, queryKey, status (one of fresh/stale/fetching/error/inactive/paused/disabled, from getQueryStatusLabel), fetchStatus, isStale, observers, updatedAt (state.dataUpdatedAt), and error.message when present. Returns {queries, total, returned, includedData}. Sorted most-recently-updated first. Safe to call repeatedly — unlike the full dehydrated snapshot, the heavy cached data stays on the device by default. TWO TRAPS: (1) the adapter has NO default limit — omit it and you get every query in the cache; (2) includeData:true returns q.state.data RAW and UNCAPPED (no 16KB wire marker, no 8MB cap like getQueryData), so it can blow the wire/token budget on a big cache — prefer getQueryData for one query's payload. The queryHash of each row is the handle every other action takes. What is NOT here has not been fetched yet — the cache fills as the user visits screens — so treat a missing key as a screen to go to (route-events.navigate, then highlight-updates.waitFor, then read again), not as an absence to report. Every read here also returns `shape`: a one-line sketch of the value's type plus, for each list in it, what its items look like. It is tiny and does not grow with the data, so it survives the 24,000-character cut when the data itself does not — read it before writing, and match it exactly. A list whose `item` is missing is EMPTY, which means nothing in the running app knows what belongs in it; anything you add there cannot be checked and will be accepted as-is, so say so rather than inventing fields. Send `staleOnly:true` to see only stale queries.",
         "requires": [
           "QueryClientProvider above <FloatingDevTools/>",
           "@tanstack/react-query v5"
@@ -945,13 +975,17 @@
       },
       {
         "action": "getQueryData",
-        "summary": "Get ONE query's real cached data by queryHash — the size-guarded channel for a payload the snapshot replaced with a marker.",
+        "summary": "Get ONE query's real cached data by queryHash — the size-guarded channel for a payload the snapshot replaced with a marker. Send `path` to get back ONE value instead of the whole payload (path:\"item.name\", path:\"results[name=pikachu].url\") — do that whenever the payload is big, because results are cut off at 24,000 characters.",
         "params": {
           "type": "object",
           "properties": {
             "queryHash": {
               "type": "string",
               "description": "The target query's hash from listQueries — TanStack's default hash is the JSON-stringified key, e.g. '[\"todos\",{\"page\":1}]'. Tolerated if omitted (returns found:false) but then the call does nothing useful."
+            },
+            "path": {
+              "type": "string",
+              "description": "Return only the value at this path instead of the whole payload. Use it when you only need one field, and ALWAYS when the payload is big: results are cut off at 24,000 characters, and a field you never saw is a field you will guess the shape of. The path must match the CURRENT data — read `shape` first rather than assuming a wrapper. On a bad path it answers with the field names that do exist, and with the path that would have worked if that field lives somewhere else."
             }
           },
           "required": [
@@ -961,7 +995,7 @@
         },
         "effect": "read",
         "release": "works",
-        "description": "Returns {found:true, queryHash, data} where data is query.state.data capped at 8MB (over that you get {__buoyTruncated:true}; non-JSON-serializable values such as circular refs or bigint come back as {__buoyUnserializable:true}). Use this when a snapshot or detail pane shows the {__buoyDataOnDevice:true} marker — streamed snapshots strip anything over 16KB. Never throws: an unknown or missing hash returns {found:false, reason:'unknown queryHash'|'missing queryHash'}.",
+        "description": "Returns {found:true, queryHash, data} where data is query.state.data capped at 8MB (over that you get {__buoyTruncated:true}; non-JSON-serializable values such as circular refs or bigint come back as {__buoyUnserializable:true}). Use this when a snapshot or detail pane shows the {__buoyDataOnDevice:true} marker — streamed snapshots strip anything over 16KB. Never throws: an unknown or missing hash returns {found:false, reason:'unknown queryHash'|'missing queryHash'}. Every read here also returns `shape`: a one-line sketch of the value's type plus, for each list in it, what its items look like. It is tiny and does not grow with the data, so it survives the 24,000-character cut when the data itself does not — read it before writing, and match it exactly. A list whose `item` is missing is EMPTY, which means nothing in the running app knows what belongs in it; anything you add there cannot be checked and will be accepted as-is, so say so rather than inventing fields. Send `path` to get back ONE value instead of the whole payload (path:\"item.name\", path:\"results[name=pikachu].url\") — do that whenever the payload is big, because results are cut off at 24,000 characters.",
         "requires": [
           "QueryClientProvider above <FloatingDevTools/>"
         ]
@@ -992,7 +1026,7 @@
       },
       {
         "action": "invalidate",
-        "summary": "Mark a query stale and refetch it if it has active observers — the normal 'this data is out of date' fix.",
+        "summary": "Mark a query stale and refetch it if it has active observers — the normal 'this data is out of date' fix. Takes the query's `queryHash`.",
         "params": {
           "type": "object",
           "properties": {
@@ -1008,14 +1042,14 @@
         },
         "effect": "write",
         "release": "works",
-        "description": "Looks the query up by hash, then passes the Query itself to queryClient.invalidateQueries() as the filter. Because the filter carries only queryKey with no exact:true, matching is a NON-EXACT prefix match: invalidating '[\\\"todos\\\"]' also invalidates '[\\\"todos\\\",{\\\"page\\\":1}]' and any other key that extends it. Mounted (observed) queries refetch immediately, so this can fire real API calls; inactive ones just go stale. Prefer this over refetch when you want the app's own screens to re-render with fresh data. THROWS for an unknown hash.",
+        "description": "Looks the query up by hash, then passes the Query itself to queryClient.invalidateQueries() as the filter. Because the filter carries only queryKey with no exact:true, matching is a NON-EXACT prefix match: invalidating '[\\\"todos\\\"]' also invalidates '[\\\"todos\\\",{\\\"page\\\":1}]' and any other key that extends it. Mounted (observed) queries refetch immediately, so this can fire real API calls; inactive ones just go stale. Prefer this over refetch when you want the app's own screens to re-render with fresh data. THROWS for an unknown hash. Takes the query's `queryHash`.",
         "requires": [
           "QueryClientProvider above <FloatingDevTools/>"
         ]
       },
       {
         "action": "reset",
-        "summary": "Reset a query to its initial state — DISCARDS its cached data, then refetches if it is active.",
+        "summary": "Reset a query to its initial state — DISCARDS its cached data, then refetches if it is active. Takes the query's `queryHash`.",
         "params": {
           "type": "object",
           "properties": {
@@ -1031,14 +1065,14 @@
         },
         "effect": "destructive",
         "release": "works",
-        "description": "queryClient.resetQueries() with the Query as filter, so the same NON-EXACT prefix match as invalidate applies (resetting '[\\\"todos\\\"]' also resets deeper todos keys). Unlike invalidate this throws the cached value away and reverts to initialData/pending — screens bound to it will flash their loading state. There is no undo: the data only comes back if the query has a queryFn and an active observer to refetch it. THROWS for an unknown hash.",
+        "description": "queryClient.resetQueries() with the Query as filter, so the same NON-EXACT prefix match as invalidate applies (resetting '[\\\"todos\\\"]' also resets deeper todos keys). Unlike invalidate this throws the cached value away and reverts to initialData/pending — screens bound to it will flash their loading state. There is no undo: the data only comes back if the query has a queryFn and an active observer to refetch it. THROWS for an unknown hash. Takes the query's `queryHash`.",
         "requires": [
           "QueryClientProvider above <FloatingDevTools/>"
         ]
       },
       {
         "action": "remove",
-        "summary": "Delete a query from the cache entirely — the entry, its data, and its state are gone.",
+        "summary": "Delete a query from the cache entirely — the entry, its data, and its state are gone. Takes the query's `queryHash`.",
         "params": {
           "type": "object",
           "properties": {
@@ -1054,14 +1088,14 @@
         },
         "effect": "destructive",
         "release": "works",
-        "description": "queryClient.removeQueries() with the Query as filter — again a NON-EXACT prefix match, so removing '[\\\"todos\\\"]' removes every key that extends it. Harsher than reset: the cache entry itself disappears rather than reverting to pending. Irreversible; a mounted component will create a brand-new entry and fetch from scratch on its next render. THROWS for an unknown hash. Returns nothing.",
+        "description": "queryClient.removeQueries() with the Query as filter — again a NON-EXACT prefix match, so removing '[\\\"todos\\\"]' removes every key that extends it. Harsher than reset: the cache entry itself disappears rather than reverting to pending. Irreversible; a mounted component will create a brand-new entry and fetch from scratch on its next render. THROWS for an unknown hash. Returns nothing. Takes the query's `queryHash`.",
         "requires": [
           "QueryClientProvider above <FloatingDevTools/>"
         ]
       },
       {
         "action": "setQueryData",
-        "summary": "Overwrite a query's cached data with a value you supply — takes the queryKey ARRAY, not the hash.",
+        "summary": "Change a query's cached data — takes the queryKey ARRAY, not the hash. The instant, on-screen edit for anything a mounted query renders. To change some fields send merge:true and ONLY those fields (deep-merged into the cached value); never paste a whole payload back — large getQueryData results are truncated, and a replace that drops fields the screen renders is refused. Reverts on the next successful refetch — say so; use a network override when it must not. To change a single field, `path` + `value` is the safest form (path:\"item.name\", value:\"test123\") — always a merge, and no nesting to get wrong. Read the data first either way: the path has to match the shape that is actually there.",
         "params": {
           "type": "object",
           "properties": {
@@ -1070,29 +1104,43 @@
               "description": "The query's key ARRAY exactly as listQueries returns it, e.g. [\"todos\",{\"page\":1}] — NOT the queryHash string. An unknown key creates a new cache entry."
             },
             "data": {
-              "description": "The value to write as the query's cached data. Any JSON value; shape must match what the app's components expect or they will crash on render."
+              "description": "With merge:true: only the fields to change, nested to match the current shape. Without: the complete new value. If you are changing a single field, use `path`+`value` instead — it cannot be nested wrongly."
             },
             "queryHash": {
               "type": "string",
               "description": "Declared by the adapter's param type but never read by the handler — passing it has no effect."
+            },
+            "merge": {
+              "type": "boolean",
+              "description": "Deep-merge `data` into the cached value as a TYPED LEAF EDIT — like the React Query devtools editor. Change the value of a field that already exists, to the SAME type: no new object fields, no type changes, no null-ing a rendered list/object. A LIST may gain or lose items, but every item you send must have the same fields as the items already in it — to change one item, resend the WHOLE list with just that item changed. Refused with the exact field on a violation. Default false."
+            },
+            "force": {
+              "type": "boolean",
+              "description": "Bypass the typed-edit safety and write raw — can add/remove fields, change types, resize lists. This is what crashes screens; use ONLY when you deliberately mean to replace the whole shape. Default false."
+            },
+            "path": {
+              "type": "string",
+              "description": "Set ONE value, named by its full path in the CURRENT data: path:\"<the real path>\", value:<new value>. READ THE DATA FIRST AND COPY THE PATH FROM IT — `shape` on getQueryData/listQueries prints it. A path is only safer than a hand-nested `data` if it matches the payload you are actually looking at; if the field is at the top level the path is just \"name\", and inventing a wrapper that is not there is refused. A list step is written [field=value] or [0] and resolves to that item's own id, so it still means the same row if the list changed. Always a merge, and always through the same typed-edit guard as `data`. Requires `value`; send `data` OR `path`+`value`, not both."
+            },
+            "value": {
+              "description": "The value `path` is set to. Required whenever `path` is sent. null is a real value (only allowed if the field is already nullable), not a delete."
             }
           },
           "required": [
-            "queryKey",
-            "data"
+            "queryKey"
           ],
           "additionalProperties": false
         },
         "effect": "write",
         "release": "works",
-        "description": "queryClient.setQueryData(queryKey, data, {updatedAt: Date.now()}). Use it to force the UI into a specific state (empty list, error-ish payload, a boundary value) without touching the API. Two gotchas: (1) it keys off queryKey, the actual array from a listQueries row (e.g. ['todos',{page:1}]) — the declared param type also mentions queryHash but the handler IGNORES it; (2) if that key is not in the cache, setQueryData CREATES a new entry with no queryFn, which then errors if anything refetches it. No validation — a bad queryKey silently writes to the wrong place. The injected value is overwritten by the next successful refetch.",
+        "description": "queryClient.setQueryData(queryKey, value, {updatedAt: Date.now()}). With merge:true the value written is the CURRENT cached data deep-merged with `data` (plain objects merge key by key, arrays and primitives are replaced), so `{name:'test123'}` changes one field of a 30KB payload. TO CHANGE ONE ITEM IN A LIST, address it by its own id rather than resending the array: if rows carry an id, `{results:{pikachu:{name:'test123'}}}` edits that row and leaves every other row untouched. This is the ONLY correct form when the read was capped and you did not see every row — a plain array REPLACES the list, so a one-item array deletes the rest. Without merge it REPLACES — and if the cached value is an object whose top-level keys `data` lacks, the call is refused with {ok:false, error, missingKeys} unless force:true, because a screen that renders the dropped fields crashes. Returns {ok:true, mode:'merge'|'replace'}. Gotchas: (1) it keys off queryKey, the actual array from a listQueries row (e.g. ['todos',{page:1}]) — the declared param type also mentions queryHash but the handler IGNORES it; (2) if that key is not in the cache, setQueryData CREATES a new entry with no queryFn, which then errors if anything refetches it. The injected value is overwritten by the next successful refetch. When a merge is refused for writing at the wrong depth, the refusal carries `suggestedData`: the SAME edit rebuilt at the right depth. Send that back as `data` rather than re-deriving it. To change a single field, `path` + `value` is the safest form (path:\"item.name\", value:\"test123\") — always a merge, and no nesting to get wrong. Read the data first either way: the path has to match the shape that is actually there.",
         "requires": [
           "QueryClientProvider above <FloatingDevTools/>"
         ]
       },
       {
         "action": "triggerError",
-        "summary": "Force a query into error status with a fake Error, to exercise the app's error UI.",
+        "summary": "Force a query into error status with a fake Error, to exercise the app's error UI. The QA move for 'show me this screen's error state'; undo with restoreError.",
         "params": {
           "type": "object",
           "properties": {
@@ -1138,7 +1186,7 @@
       },
       {
         "action": "triggerLoading",
-        "summary": "Pin a query in a permanent loading/suspense state to exercise skeletons and spinners. MUST be undone.",
+        "summary": "Pin a query in a permanent loading/suspense state to exercise skeletons and spinners. MUST be undone. The QA move for 'show me this screen's loading state'; undo with restoreLoading.",
         "params": {
           "type": "object",
           "properties": {
@@ -1690,7 +1738,7 @@
       },
       {
         "action": "upsertOverrideRule",
-        "summary": "Create (or replace by id) a rule that forces matching requests to return a chosen status/body, fail outright, or arrive late.",
+        "summary": "Create (or replace by id) a rule that forces matching requests to return a chosen status/body, fail outright, or arrive late. Pick this over query.setQueryData when the change must survive a refetch or reload, or when the ask is about what the API returns; follow it with query.invalidate so the mounted screen refetches through the rule. To change ONE value of the real response send fromRequestId plus `bodyPath` and `bodyValue` (bodyPath:\"sprites.front_default\", or \"stats[stat.name=hp].base_stat\" for one row of a list) — there is no nesting to get wrong, which matters most here because you read that body through a wire that truncates at 24,000 characters. For several fields use `bodyPatch` with ONLY those fields; never paste a whole captured body back. For \"just the NEXT call\" / \"once, then let it work again\", send rule.times:1 — the rule auto-disables after one match. Without times it overrides EVERY matching request until deleted. Never fake one-shot by triggering the request yourself and deleting the rule: that spends the failure the user wanted to see.",
         "params": {
           "type": "object",
           "properties": {
@@ -1732,7 +1780,7 @@
                     "fail",
                     "delay"
                   ],
-                  "description": "respond = return your status/body, never hitting the network (default). fail = transport failure, as if offline. delay = run the real request, just late. Anything else falls back to respond."
+                  "description": "respond = return your status/body, never hitting the network (default). fail = transport failure, as if offline (`fail:true` is accepted for this). delay = run the real request, just late. Anything else falls back to respond."
                 },
                 "status": {
                   "type": "number",
@@ -1747,7 +1795,7 @@
                   "description": "kind 'respond': response headers, string values."
                 },
                 "body": {
-                  "description": "kind 'respond': the response body. A string is used as-is; an object or array is JSON.stringify'd for you — do not pre-stringify."
+                  "description": "kind 'respond': the COMPLETE response body. A string is used as-is; an object or array is JSON.stringify'd for you — do not pre-stringify. To change a few fields of the real response use bodyPatch instead — bodies you read over the wire are truncated past 24K chars, and pasting a torn body back gives the app a response missing half its fields."
                 },
                 "failKind": {
                   "type": "string",
@@ -1762,7 +1810,7 @@
                 },
                 "times": {
                   "type": "number",
-                  "description": "Auto-disable after N matches. Use 1 for 'make the next call fail' so it cannot linger. Omitted = unlimited."
+                  "description": "Auto-disable after N matches. **Set times:1 whenever the ask is about the NEXT call** — \"make the next request fail\", \"just once\", \"then let it work again\". Omitted = the rule overrides EVERY matching request until something deletes it, and the result will tell you so. `once:true`, `failOnce:true` and `maxHits:N` are accepted as ways of saying this."
                 },
                 "alternate": {
                   "type": "boolean",
@@ -1771,6 +1819,21 @@
                 "bodyOmitted": {
                   "type": "boolean",
                   "description": "Wire flag: send true WITH an `id` when re-saving a rule whose body the snapshot withheld, so the stored body is preserved instead of erased."
+                },
+                "bodyPatch": {
+                  "type": "object",
+                  "description": "Fields to change in the real captured response (needs fromRequestId, or the id of an existing rule) as a TYPED LEAF EDIT — like the devtools editor: same-type changes to existing fields, no new fields, no type changes, no null-ing a rendered list/object. A list may gain/lose items but each item must match the existing item shape (to change one item resend the whole list). Refused with the exact field on a violation. Ignored when `body` is sent. To change ONE ROW of a list in the response, address it by its own id instead of resending the array: {results:{pikachu:{name:'test123'}}} edits that row and leaves every other row exactly as the server sent it. That is the only correct form when you read the response through a view that truncated it."
+                },
+                "force": {
+                  "type": "boolean",
+                  "description": "Bypass the typed-edit safety on bodyPatch and write the patch raw. Default false — a violating patch is refused."
+                },
+                "bodyPath": {
+                  "type": "string",
+                  "description": "Set ONE value inside the real response, named by its path (\"sprites.front_default\", \"stats[stat.name=hp].base_stat\"). Needs fromRequestId or an existing rule id to address. Always goes through the same typed-edit guard as bodyPatch."
+                },
+                "bodyValue": {
+                  "description": "The value `bodyPath` is set to. Required whenever bodyPath is sent."
                 }
               },
               "additionalProperties": false
@@ -1780,7 +1843,7 @@
         },
         "effect": "write",
         "release": "noop",
-        "description": "The way to drive an app into a state it cannot reach on its own: force a 500 and check the error UI, return [] and check the empty state, simulate offline or a slow connection. Rules run INSIDE the app, are persisted, and re-apply on every launch — so they cover the boot path too. Send the fields under `rule` (the adapter also accepts them flat, reading `params.rule ?? params`). `urlPattern` is the one field with no default: without it, and without a `fromRequestId` that resolves, the call is rejected with {ok:false,error}. Prefer `fromRequestId` over pasting a URL — it rewrites the query string to `*`, which is the difference between a rule that fires and one that sits at 0 hits against a cache-busting client. Returns a RECEIPT, not the rule: {ok:true, rule:{id, urlPattern, enabled, kind, status, bodySize}}, or {ok:false,error} on a bad pattern, an unresolvable fromRequestId, or the 50-rule ceiling. Side effect: if the new rule is enabled, the MASTER SWITCH is forced ON, arming every other enabled rule too. ALWAYS delete your rules when done — a forgotten rule is indistinguishable from a real bug, and a body the app cannot render can wedge it across restarts (the 3-launch auto-pause guard exists because that once required deleting the app's data).",
+        "description": "Create (or replace by id) a rule that forces matching requests to return a chosen status/body, fail outright, or arrive late. Pick this over query.setQueryData when the change must survive a refetch or reload, or when the ask is about what the API returns; follow it with query.invalidate so the mounted screen refetches through the rule. To change ONE value of the real response send fromRequestId plus `bodyPath` and `bodyValue` (bodyPath:\"sprites.front_default\", or \"stats[stat.name=hp].base_stat\" for one row of a list) — there is no nesting to get wrong, which matters most here because you read that body through a wire that truncates at 24,000 characters. For several fields use `bodyPatch` with ONLY those fields; never paste a whole captured body back. For \"just the NEXT call\" / \"once, then let it work again\", send rule.times:1 — the rule auto-disables after one match. Without times it overrides EVERY matching request until deleted. Never fake one-shot by triggering the request yourself and deleting the rule: that spends the failure the user wanted to see.",
         "releaseNote": "packages/network/src/network/overrides/engine.ts:74 — overrideForRequest returns null when __DEV__ === false. The rule is still created, persisted and listed, and this action still returns ok:true, but it is NEVER applied to real traffic in a release build. Confirm with debugOverrides → engine.devFlag before telling anyone the override took effect.",
         "requires": [
           "a __DEV__ build for the rule to actually apply",
@@ -2932,15 +2995,20 @@
     "actions": [
       {
         "action": "describeScreen",
-        "summary": "List every meaningful/interactive element currently on screen, with normalized tap points — the read half of driving the app.",
+        "summary": "List every meaningful/interactive element currently on screen, with normalized tap points — the read half of driving the app. The ONLY way to read what is on screen but in no store: text, values and names held in component state, which no other Buoy tool can see.",
         "params": {
           "type": "object",
-          "properties": {},
+          "properties": {
+            "includeBuoy": {
+              "type": "boolean",
+              "description": "Also list Buoy's own overlay (the dial, tool sheets, Ask Buoy's own chat). Default false — those are the tool, not the app."
+            }
+          },
           "additionalProperties": false
         },
         "effect": "read",
         "release": "empty",
-        "description": "Walks the live React fiber tree across ALL renderers and measures each candidate. Returns {screen:{width,height}, count, elements[]} where each element has: nativeTag, name (owning component, not the host View), role, testID, label, text, interactive, control ('toggle'|'slider'|'text', omitted for a plain press), value (current value for toggle/slider/text), longPressable, tap:{x,y} and frame:{x,y,width,height} both normalized to 0-1. Sorted top-to-bottom then left-to-right. Prunes offscreen/inactive react-native-screens and hidden Offscreen subtrees, so it reflects the CURRENT screen only — re-run after every navigation, positions and tags move. No screenshot and no tracking needed; it does not require the highlight overlay to be enabled. Call this before tapElement to get an exact testID/nativeTag instead of guessing a fuzzy query.",
+        "description": "Walks the live React fiber tree across ALL renderers and measures each candidate. Returns {screen:{width,height}, count, elements[]} where each element has: nativeTag, name (owning component, not the host View), role, testID, label, text, interactive, control ('toggle'|'slider'|'text', omitted for a plain press), value (current value for toggle/slider/text), longPressable, tap:{x,y} and frame:{x,y,width,height} both normalized to 0-1. Sorted top-to-bottom then left-to-right. Prunes offscreen/inactive react-native-screens and hidden Offscreen subtrees, so it reflects the CURRENT screen only — re-run after every navigation, positions and tags move. No screenshot and no tracking needed; it does not require the highlight overlay to be enabled. Call this before tapElement to get an exact testID/nativeTag instead of guessing a fuzzy query. Buoy's OWN overlay is left out — the dial, tool sheets and your own chat sheet are the tool, not the app under test — and `hiddenBuoy` counts what was omitted; pass includeBuoy:true only when the task is about Buoy itself.",
         "releaseNote": "packages/highlight-updates/src/highlight-updates/utils/screenElements.ts:57 — getReactDevToolsHook() reads __REACT_DEVTOOLS_GLOBAL_HOOK__, which RN installs only under __DEV__; getAllFiberRoots() then returns [] and collectCandidates() short-circuits at line 539, so the result is a valid-looking {count:0, elements:[]} rather than an error.",
         "requires": [
           "@buoy-gg/highlight-updates installed and registered with <FloatingDevTools>",
@@ -2949,7 +3017,7 @@
       },
       {
         "action": "tapElement",
-        "summary": "Interact with one on-screen element by invoking its real handler in JS: press, long-press, toggle/slider, or type into a text input.",
+        "summary": "Interact with one on-screen element by invoking its real handler in JS: press, long-press, toggle/slider, or type into a text input. This is how you make the app FETCH MORE — press its own \"next\", \"load more\" or a list row, waitFor, then read: the app fetches through its own code, so the data arrives in the shape its own screens render.",
         "params": {
           "type": "object",
           "properties": {
@@ -2983,13 +3051,17 @@
             "scrollIntoView": {
               "type": "boolean",
               "description": "Scroll an ancestor ScrollView so the target is visible before acting. Default true — set false to avoid moving the user's screen."
+            },
+            "includeBuoy": {
+              "type": "boolean",
+              "description": "Let a fuzzy `query` match Buoy's own overlay. Default false. An exact nativeTag/testID always may."
             }
           },
           "additionalProperties": false
         },
         "effect": "write",
         "release": "empty",
-        "description": "WARNING: this fires the app's ACTUAL handler, so it can trigger irreversible flows (delete, purchase, logout, submit). Matching by fuzzy `query` can select the wrong element — prefer an exact nativeTag or testID from describeScreen, and confirm the target before firing anything consequential. Resolution order: the element's OWN onValueChange (toggle/slider) or onChangeText (text input) wins; otherwise the nearest onPress walking up the fiber chain (up to 25 levels). Returns {tapped, reason?, scrolled?, matched:{nativeTag,name,testID,label,text,via,value}, candidates?} — `via` is onPress|onLongPress|onValueChange|onChangeText. Trap: passing `text` to something that is not a text input silently runs its onPress instead, so check `matched.via` in the result. Elements driven only by react-native-gesture-handler GestureDetector have no JS handler and return tapped:false with a clear reason. If the target is off-screen it is scrolled into view first (this moves the user's screen). Provide exactly one of nativeTag / testID / query.",
+        "description": "WARNING: this fires the app's ACTUAL handler, so it can trigger irreversible flows (delete, purchase, logout, submit). Matching by fuzzy `query` can select the wrong element — prefer an exact nativeTag or testID from describeScreen, and confirm the target before firing anything consequential. Resolution order: the element's OWN onValueChange (toggle/slider) or onChangeText (text input) wins; otherwise the nearest onPress walking up the fiber chain (up to 25 levels). Returns {tapped, reason?, scrolled?, matched:{nativeTag,name,testID,label,text,via,value}, candidates?} — `via` is onPress|onLongPress|onValueChange|onChangeText. Trap: passing `text` to something that is not a text input silently runs its onPress instead, so check `matched.via` in the result. Elements driven only by react-native-gesture-handler GestureDetector have no JS handler and return tapped:false with a clear reason. If the target is off-screen it is scrolled into view first (this moves the user's screen). Provide exactly one of nativeTag / testID / query. A fuzzy query never matches Buoy's own overlay unless includeBuoy:true (your chat sheet echoes the words you search for; that echo used to be the best match). READ THE RESULT BEFORE TRUSTING THE TAP: `effect.commits` is how many React commits followed inside the settle window, and 0 means the handler ran but NOTHING re-rendered — the match was probably a screen still mounted underneath the current one (a stack keeps them), or an inert control — so treat it as not done and pick another target from describeScreen. `alsoMatched` lists elements that matched equally well; non-empty means the choice was a coin toss, so re-tap by nativeTag.",
         "releaseNote": "packages/highlight-updates/src/highlight-updates/utils/screenElements.ts:793 — collectCandidates() returns [] with no DevTools hook, so it returns {tapped:false, reason:\"No React fiber roots / elements found on screen.\"}; it reports the failure honestly rather than claiming a tap.",
         "requires": [
           "@buoy-gg/highlight-updates installed and registered with <FloatingDevTools>",
@@ -2999,7 +3071,7 @@
       {
         "action": "waitFor",
         "summary": "Block until an element is on screen (or gone), then report how long it took. Use it between navigating and tapping.",
-        "description": "Returns {ok, waitedMs, polls, matched?, reason?}. USE THIS AFTER ANY ACTION THAT STARTS A LOAD — `route-events.navigate` returns the moment the route is pushed, not when the screen has data, so tapping straight after it hits a loading skeleton and fails for a reason that looks like a bad selector. Matching is `tapElement`'s exactly (same fields, same ranking), so a wait can never resolve on an element the tap then cannot find. Presence means ON SCREEN: a candidate matching by name is measured before it counts, so a previous screen still mounted behind this one does not satisfy the wait. `gone:true` waits for absence instead — and returns immediately when nothing matched in the first place, which is a real answer, not a failure. Defaults: timeoutMs 5000 (capped at 30000), pollMs 150 (floored at 50, because this polls on the JS thread the app renders on). Provide exactly one of nativeTag / testID / query.",
+        "description": "Returns {ok, waitedMs, polls, matched?, reason?}. USE THIS AFTER ANY ACTION THAT STARTS A LOAD — `route-events.navigate` returns the moment the route is pushed, not when the screen has data, so tapping straight after it hits a loading skeleton and fails for a reason that looks like a bad selector. Matching is `tapElement`'s exactly (same fields, same ranking), so a wait can never resolve on an element the tap then cannot find. Presence means ON SCREEN: a candidate matching by name is measured before it counts, so a previous screen still mounted behind this one does not satisfy the wait. `gone:true` waits for absence instead — and returns immediately when nothing matched in the first place, which is a real answer, not a failure. Like tapElement, a fuzzy query ignores Buoy's own overlay unless includeBuoy:true; an exact nativeTag/testID always counts. Defaults: timeoutMs 5000 (capped at 30000), pollMs 150 (floored at 50, because this polls on the JS thread the app renders on). Provide exactly one of nativeTag / testID / query.",
         "params": {
           "type": "object",
           "properties": {
@@ -3026,6 +3098,10 @@
             "pollMs": {
               "type": "number",
               "description": "Gap between scans. Default 150, floored at 50."
+            },
+            "includeBuoy": {
+              "type": "boolean",
+              "description": "Let a fuzzy `query` match Buoy's own overlay. Default false. An exact nativeTag/testID always may."
             }
           },
           "additionalProperties": false
@@ -4922,7 +4998,7 @@
   {
     "toolId": "ask-buoy",
     "title": "Ask Buoy",
-    "summary": "Ask Buoy's OWN session — the changes it has made in this conversation, and the undo for them. Call listChanges when the user asks \"what did you change?\"; call undoAll when they say \"undo that\" / \"put it back\" / \"clean up\". Undo restores exactly what the ledger captured at write time: override rules Ask Buoy created are deleted, impersonation is stopped, storage keys are restored to their pre-write values. Changes listed with reversible:false (state writes, wipes, one-shot actions) cannot be automatically reversed — say so honestly. NEVER improvise a reverse-write with a guessed shape instead of calling undoAll; a hand-rolled \"undo\" that writes invented data is worse than telling the user a change is permanent.",
+    "summary": "Ask Buoy's OWN session — the changes it has made in this conversation, and the undo for them. Call listChanges when the user asks \"what did you change?\"; call undoAll when they say \"undo that\" / \"put it back\" / \"clean up\". Undo restores exactly what the ledger captured at write time: override rules Ask Buoy created are deleted, impersonation is stopped, storage keys are restored to their pre-write values, and a query cache edit (setQueryData) is put back to the data read just before the write — unless the app has refetched it since, in which case the server's data is already back and undo says so. Changes listed with reversible:false (state writes, wipes, one-shot actions) cannot be automatically reversed — say so honestly. NEVER improvise a reverse-write with a guessed shape instead of calling undoAll; a hand-rolled \"undo\" that writes invented data is worse than telling the user a change is permanent.",
     "actions": [
       {
         "action": "listChanges",