@buoy-gg/agent-core 7.0.40 → 7.0.42

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

@@ -556,7 +556,7 @@
       },
       {
         "action": "setState",
-        "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.",
+        "summary": "Change a live zustand store. Ask Buoy MERGES by default (replace:false): it merges the fields you send, including inside nested objects (so {\"member\":{\"crowns\":5}} changes crowns and keeps member's other fields), 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": {
@@ -1289,7 +1289,7 @@
   {
     "toolId": "events",
     "title": "Events",
-    "summary": "The cross-tool activity timeline: one chronological ring buffer (max 200, newest-first) that aggregates events from every other installed Buoy tool — network requests, redux/zustand/jotai state changes, react-query query/mutation updates, AsyncStorage/MMKV writes, route navigations, and component renders. Reach for it first for any \"what just happened in the app?\" question, before drilling into a single-tool reader. It exposes 3 actions: exportEvents (formatted read), setEnabledSources (choose what the device records), clearEvents (wipe the timeline). CRITICAL: it only records while something is watching — a cold exportEvents on a freshly connected session usually returns 0 events because nothing has ever armed capture, which is NOT the same as \"the app did nothing\".",
+    "summary": "The cross-tool activity timeline: one chronological ring buffer (max 200, newest-first) that aggregates events from every other installed Buoy tool — network requests, redux/zustand/jotai state changes, react-query query/mutation updates, AsyncStorage/MMKV writes, route navigations, and component renders. Reach for it first for any \"what just happened in the app?\" question, before drilling into a single-tool reader. It exposes 3 actions: exportEvents (formatted read), setEnabledSources (choose what the device records), clearEvents (wipe the timeline). CRITICAL: it only records while something is watching — a cold exportEvents on a freshly connected session usually returns 0 events because nothing has ever armed capture, which is NOT the same as \"the app did nothing\". Swift captures network, storage-async, storage-mmkv, and route. React state and render sources are unavailable. Native export accepts format, includeEventData, includeSource, includeStatus, includeTitle, includeSubtitle, includeSummaryHeader, filterMode, filterSources, dataSizeThreshold, and timestampFormat; other settings are rejected. Native detail inherits source snapshot payload limits.",
     "actions": [
       {
         "action": "exportEvents",
@@ -1441,7 +1441,7 @@
         },
         "effect": "read",
         "release": "works",
-        "description": "Runs the device's own \"Copy Settings\" formatter over the unified store and returns {output: string, returned: number, totalAvailable: number, includedData: boolean, format: string}. The store is a 200-event ring, newest-first. Defaults are compact: includeEventData=false, so heavy raw payloads (network bodies, redux state trees, query data) stay on the device — pass settings.includeEventData=true only when you actually need them.\n\nTHREE traps a caller must know:\n(1) COLD READS ARE EMPTY. Sources are only subscribed while a consumer holds a watch on toolId \"events\" (the adapter's subscribe() calls ensureRemoteSourcesDefault) or the on-device Events modal is open. A bare call_action does NOT arm capture — the MCP SyncClient only watches on getSnapshot, never on callAction (packages/mcp/src/tools/packs/events.ts:80). If totalAvailable is 0, say \"nothing was being recorded\", not \"nothing happened\": arm it first (read the events snapshot, or call setEnabledSources), reproduce, then export.\n(2) limit IS APPLIED BEFORE FILTERING. The adapter does all.slice(0, limit) and only then does generateExport filter by settings.filterSources / filterMode (packages/events/src/sync/eventsSyncAdapter.ts:378-381 + eventExportFormatter.ts:616). Filtering to one source with limit:25 can produce an EMPTY output while `returned` still reports 25 — `returned` counts events handed to the formatter, not events in the output. When filtering by source, pass a large limit (or omit it, which uses the whole buffer).\n(3) filterSources takes GRANULAR EventSource values, not friendly names. \"storage\" matches nothing — use [\"storage-async\",\"storage-mmkv\"]; react-query is three values ([\"react-query\",\"react-query-query\",\"react-query-mutation\"]). The MCP get_events wrapper expands those aliases for you; a direct call_action does not.\n\nAn unrecognized preset name silently falls back to DEFAULT_COPY_SETTINGS instead of erroring. settings is shallow-merged OVER the preset.",
+        "description": "Runs the device's own \"Copy Settings\" formatter over the unified store and returns {output: string, returned: number, totalAvailable: number, includedData: boolean, format: string}. The store is a 200-event ring, newest-first. Defaults are compact: includeEventData=false, so heavy raw payloads (network bodies, redux state trees, query data) stay on the device — pass settings.includeEventData=true only when you actually need them.\n\nTHREE traps a caller must know:\n(1) COLD READS ARE EMPTY. Sources are only subscribed while a consumer holds a watch on toolId \"events\" (the adapter's subscribe() calls ensureRemoteSourcesDefault) or the on-device Events modal is open. A bare call_action does NOT arm capture — the MCP SyncClient only watches on getSnapshot, never on callAction (packages/mcp/src/tools/packs/events.ts:80). If totalAvailable is 0, say \"nothing was being recorded\", not \"nothing happened\": arm it first (read the events snapshot, or call setEnabledSources), reproduce, then export.\n(2) limit IS APPLIED BEFORE FILTERING. The adapter does all.slice(0, limit) and only then does generateExport filter by settings.filterSources / filterMode (packages/events/src/sync/eventsSyncAdapter.ts:378-381 + eventExportFormatter.ts:616). Filtering to one source with limit:25 can produce an EMPTY output while `returned` still reports 25 — `returned` counts events handed to the formatter, not events in the output. When filtering by source, pass a large limit (or omit it, which uses the whole buffer).\n(3) filterSources takes GRANULAR EventSource values, not friendly names. \"storage\" matches nothing — use [\"storage-async\",\"storage-mmkv\"]; react-query is three values ([\"react-query\",\"react-query-query\",\"react-query-mutation\"]). The MCP get_events wrapper expands those aliases for you; a direct call_action does not.\n\nAn unrecognized preset name silently falls back to DEFAULT_COPY_SETTINGS instead of erroring. settings is shallow-merged OVER the preset. Swift captures network, storage-async, storage-mmkv, and route. React state and render sources are unavailable. Native export accepts format, includeEventData, includeSource, includeStatus, includeTitle, includeSubtitle, includeSummaryHeader, filterMode, filterSources, dataSizeThreshold, and timestampFormat; other settings are rejected. Native detail inherits source snapshot payload limits.",
         "requires": [
           "@buoy-gg/events installed and auto-discovered by FloatingDevTools",
           "a live watch on toolId \"events\" (an events snapshot read, a desktop Events panel, or a prior setEnabledSources call) before the window you want recorded — otherwise the buffer is empty",
@@ -2171,7 +2171,7 @@
   {
     "toolId": "time-machine",
     "title": "Time Machine",
-    "summary": "Save and restore the app's entire client-side state (device storage, redux, zustand, jotai, react-query) as named snapshots (\"restore points\"), plus the route it was captured on. Reach for it to put the app back into a known state before re-running a flow, to preview exactly what a restore would change before committing, or to wipe the app to fresh-install state. Snapshot payloads stay on-device — `list` returns metadata only; use `inspect` for one source's actual captured data and `preview` for item-level diffs.",
+    "summary": "Save and restore the app's entire client-side state (device storage, redux, zustand, jotai, react-query) as named snapshots (\"restore points\"), plus the route it was captured on. Reach for it to put the app back into a known state before re-running a flow, to preview exactly what a restore would change before committing, or to wipe the app to fresh-install state. Snapshot payloads stay on-device — `list` returns metadata only; use `inspect` for one source's actual captured data and `preview` for item-level diffs. Swift supports live restore of registered providers, with UserDefaults and MMKV supplied by default. Keychain is excluded. Read provider detail and restoreModes. Native capabilities omit captureBaseline and wipeAll, and mode reload is rejected before writes. Snapshots include a safety copy before restoration; this is not a full process reset.",
     "actions": [
       {
         "action": "list",
@@ -2183,7 +2183,7 @@
         },
         "effect": "read",
         "release": "works",
-        "description": "Same payload as the tool's synced snapshot. Returns { snapshots, busy, lastOutcome, providers, route }. `snapshots[]` = { id (e.g. \"snap_m1x2y3_4\"), name, createdAt, sizeBytes, baseline?, route?:{pathname,href}, restoreRoute?, scope?, excludedKeys?, sources:{ [sourceId]: { warnings:string[] } } } — METADATA ONLY, no captured values. `providers[]` = { id, label, canCapture, canRestore, detail } for the registered sources: \"storage\", \"redux\", \"zustand\", \"jotai\", \"query\" (plus any custom ones the app registered). Read `detail` before reporting a source as broken — e.g. redux says \"Auto-instrumented store cannot be restored\" when the app didn't wrap its root reducer. `route.available` is false on apps without expo-router (those snapshots record no route). `lastOutcome` is the previous restore's per-source result. Call this first — every other action needs an `id` from here.",
+        "description": "Same payload as the tool's synced snapshot. Returns { snapshots, busy, lastOutcome, providers, route }. `snapshots[]` = { id (e.g. \"snap_m1x2y3_4\"), name, createdAt, sizeBytes, baseline?, route?:{pathname,href}, restoreRoute?, scope?, excludedKeys?, sources:{ [sourceId]: { warnings:string[] } } } — METADATA ONLY, no captured values. `providers[]` = { id, label, canCapture, canRestore, detail } for the registered sources: \"storage\", \"redux\", \"zustand\", \"jotai\", \"query\" (plus any custom ones the app registered). Read `detail` before reporting a source as broken — e.g. redux says \"Auto-instrumented store cannot be restored\" when the app didn't wrap its root reducer. `route.available` is false on apps without expo-router (those snapshots record no route). `lastOutcome` is the previous restore's per-source result. Call this first — every other action needs an `id` from here. Swift supports live restore of registered providers, with UserDefaults and MMKV supplied by default. Keychain is excluded. Read provider detail and restoreModes. Native capabilities omit captureBaseline and wipeAll, and mode reload is rejected before writes. Snapshots include a safety copy before restoration; this is not a full process reset.",
         "requires": [
           "@buoy-gg/time-machine registered in FloatingDevTools"
         ]
@@ -2283,7 +2283,7 @@
         },
         "effect": "destructive",
         "release": "works",
-        "description": "Requires `id` (throws \"restore requires a snapshot `id`\" without it). mode \"live\" (default) replaces state in place source by source in a fixed order (storage → redux → zustand → jotai → query); mode \"reload\" restores ONLY persisted storage and then reloads the JS bundle so in-memory stores rebuild themselves. A baseline snapshot ALWAYS takes the clear+reload path regardless of mode. Storage restore is a diff — app keys missing from the snapshot are DELETED. Returns a RestoreOutcome: read `results[sourceId].applied` / `.skipped[].reason` / `.warnings` rather than assuming success (a source with canRestore:false comes back skipped with a reason, not an error), and read `willReload` and `route.status` (\"navigated\" | \"deferred\" | \"failed\" | \"unavailable\"). TWO GOTCHAS: (1) omitting `excludeKeys` makes the snapshot's own SAVED excludedKeys apply, and a saved `scope` narrows the restore to only the scoped items — passing an explicit `excludeKeys` array disables that saved scope. (2) omitting `restoreRoute` does NOT mean false: it falls back to the snapshot's own setting, which is ON whenever the snapshot captured a route. Pass restoreRoute:false to keep the app on the current screen.",
+        "description": "Requires `id` (throws \"restore requires a snapshot `id`\" without it). mode \"live\" (default) replaces state in place source by source in a fixed order (storage → redux → zustand → jotai → query); mode \"reload\" restores ONLY persisted storage and then reloads the JS bundle so in-memory stores rebuild themselves. A baseline snapshot ALWAYS takes the clear+reload path regardless of mode. Storage restore is a diff — app keys missing from the snapshot are DELETED. Returns a RestoreOutcome: read `results[sourceId].applied` / `.skipped[].reason` / `.warnings` rather than assuming success (a source with canRestore:false comes back skipped with a reason, not an error), and read `willReload` and `route.status` (\"navigated\" | \"deferred\" | \"failed\" | \"unavailable\"). TWO GOTCHAS: (1) omitting `excludeKeys` makes the snapshot's own SAVED excludedKeys apply, and a saved `scope` narrows the restore to only the scoped items — passing an explicit `excludeKeys` array disables that saved scope. (2) omitting `restoreRoute` does NOT mean false: it falls back to the snapshot's own setting, which is ON whenever the snapshot captured a route. Pass restoreRoute:false to keep the app on the current screen. Swift supports live restore of registered providers, with UserDefaults and MMKV supplied by default. Keychain is excluded. Read provider detail and restoreModes. Native capabilities omit captureBaseline and wipeAll, and mode reload is rejected before writes. Snapshots include a safety copy before restoration; this is not a full process reset.",
         "requires": [
           "a source's provider must report canRestore:true or that source is skipped with a reason",
           "expo-router for the route leg",
@@ -2515,11 +2515,272 @@
     ],
     "unavailableWhen": "The `@buoy-gg/time-machine` tool is not in the app's FloatingDevTools tool list, or the app is a release build that has not opted into `externalSync.enableInRelease` with a real Pro license (packages/devtools-floating-menu/src/floatingMenu/autoExternalSync.tsx:190 — no socket, so no action reaches the device at all). Individual state sources are also absent unless their tool package is installed and instrumented: check `providers[].canCapture`/`canRestore` from `list` before assuming a source is covered."
   },
+  {
+    "toolId": "clock",
+    "title": "Clock",
+    "summary": "Override the app's own clock without touching the device: move it to any date (setTime), jump it forward or back (shift), stop it (freeze/resume), run it faster (setRate), or go back to real time (reset). Reach for it to test anything time-based on the client: expired offers and coupons, countdowns, trial and renewal dates, day or month rollovers, 'last seen' labels, token expiry the app checks itself. What moves: Date.now(), new Date(), Date() and Intl.DateTimeFormat format() with no date; a forward shift also runs the app's setTimeout/setInterval callbacks that come due inside the jump, once each. What stays real: performance.now(), animations, native timers and scheduled notifications, the time zone, and the backend's clock, so a server that checks expiry itself still uses real time. Values the app computed before the change keep their old time until the screen re-reads the clock or the app reloads (the override survives reloads). It also reads the app's sign-in tokens from Network's captured requests (JWTs, PASETO, opaque tokens whose login response gave an expiry, session cookies) and tests the app's token refresh: jumpToTokenExpiry for apps that refresh before expiry, failNextRequest for apps that refresh after a 401. Raw tokens are never returned. Every action returns the same state object as getState: { mode:'real'|'running'|'frozen', active, rate, virtualNow, virtualIso, realNow, offsetMs, timeZone, timers:{total,timeouts,intervals,nextTimeoutInMs}, lastJump:{byMs,firedTimers,at}|null, settings:{persist,showChip,fireTimersOnJump}, tokens:{available, tokens:[{id,label,host,formatLabel,hint,claims,expiresAt,serverExpiresAt,expirySource,lifetimeMs,issuedBy,refresh,uses,refreshes,looping,expiredSends,rejected}], check:{kind:'expiry'|'401',tokenId,status:'waiting'|'refreshed'|'loop',forcedAt,refreshedAt,newLifetimeMs,newIssuedBy,newTokens,staleAfterFailure}|null}, patched:{date,intl,timers,animatedOnRealClock} }. expiresAt is on the app's clock; serverExpiresAt on real time.",
+    "unavailableWhen": "Needs @buoy-gg/clock installed (FloatingDevTools auto-discovers it). In release builds the saved override and timer tracking load when the Clock tool is first opened rather than at app start.",
+    "actions": [
+      {
+        "action": "getState",
+        "summary": "Read what the app's clock says right now, how far it is from real time, and the pending timers.",
+        "description": "Returns the state object described in the tool summary. Read virtualIso (the app's time) against realNow before reporting what 'now' is for the app; offsetMs is app minus real. mode 'real' means no override is on. timers counts the app's pending setTimeout/setInterval callbacks, which is how many a forward shift could run.",
+        "effect": "read",
+        "release": "works",
+        "params": {
+          "type": "object",
+          "properties": {},
+          "additionalProperties": false
+        }
+      },
+      {
+        "action": "setTime",
+        "summary": "Move the app's clock to `time` (ISO 8601, epoch ms, or relative like \"+3d\"); pass `freeze` true to stop it there.",
+        "description": "`time` accepts \"2026-12-31T23:59:50\" (device-local when no zone is given), \"2026-12-31 23:59\", \"2026-12-31T23:59:50Z\", epoch milliseconds, or a signed duration from the app's current time (\"+30d\", \"-2h\"). The clock keeps running from there at the current speed unless `freeze` is true. Unlike shift, setTime never runs timers. Throws a message naming the accepted formats when `time` cannot be read. Returns the new state.",
+        "effect": "write",
+        "release": "works",
+        "undo": {
+          "action": "reset",
+          "note": "reset returns to the device's real clock. If an override was already on before this call, reset does not bring that one back: read getState first and set it again with setTime/setRate."
+        },
+        "params": {
+          "type": "object",
+          "properties": {
+            "time": {
+              "type": [
+                "string",
+                "number"
+              ],
+              "description": "Target time: ISO 8601 (\"2026-12-31T23:59:50\"), \"YYYY-MM-DD HH:MM\", epoch ms, or relative (\"+1d\", \"-2h\")."
+            },
+            "freeze": {
+              "type": "boolean",
+              "description": "Stop the clock at `time` instead of letting it run. Default false."
+            }
+          },
+          "required": [
+            "time"
+          ],
+          "additionalProperties": false
+        }
+      },
+      {
+        "action": "shift",
+        "summary": "Jump the app's clock `by` a duration (\"+1d\", \"-2h30m\", \"90s\" or ms); forward jumps also run app timers that come due unless `fireTimers` is false.",
+        "description": "Moves the clock relative to what it reads now; a frozen clock stays frozen. Units: ms, s, m, h, d, w, mo (30 days), y (365 days). A forward jump runs, once each and soonest first, every app setTimeout/setInterval callback due within the jump (Playwright fastForward rules) and shortens what is left of the others; lastJump.firedTimers reports how many ran. Buoy's own timers are never run. Backward jumps never run timers. Returns the new state.",
+        "effect": "write",
+        "release": "works",
+        "undo": {
+          "action": "reset",
+          "note": "reset returns to the device's real clock. If an override was already on before this call, reset does not bring that one back: read getState first and set it again with setTime/setRate."
+        },
+        "params": {
+          "type": "object",
+          "properties": {
+            "by": {
+              "type": [
+                "string",
+                "number"
+              ],
+              "description": "Signed duration: \"+1d\", \"-2h30m\", \"90s\", \"1.5 hours\", or a number of ms."
+            },
+            "fireTimers": {
+              "type": "boolean",
+              "description": "Run app timers that come due inside a forward jump. Default: the fireTimersOnJump setting (on)."
+            }
+          },
+          "required": [
+            "by"
+          ],
+          "additionalProperties": false
+        }
+      },
+      {
+        "action": "freeze",
+        "summary": "Stop the app's clock where it is, or at `time` if given.",
+        "description": "The app reads the same instant until resume, shift, setTime or reset. Timers keep running in real time and animations keep moving; only reads of the time stop. `time` takes the same formats as setTime. Returns the new state.",
+        "effect": "write",
+        "release": "works",
+        "undo": {
+          "action": "resume",
+          "note": "resume starts the clock again from the frozen instant; it does not return to the time before the freeze. Use reset for real time."
+        },
+        "params": {
+          "type": "object",
+          "properties": {
+            "time": {
+              "type": [
+                "string",
+                "number"
+              ],
+              "description": "Optional instant to freeze at (same formats as setTime). Omit to freeze at the current app time."
+            }
+          },
+          "additionalProperties": false
+        }
+      },
+      {
+        "action": "resume",
+        "summary": "Start a frozen app clock again from the instant it was frozen at.",
+        "description": "No-op when the clock is not frozen. The clock continues at its current speed. Returns the new state.",
+        "effect": "write",
+        "release": "works",
+        "undo": {
+          "action": "freeze",
+          "note": "freeze stops it again, at the current app time."
+        },
+        "params": {
+          "type": "object",
+          "properties": {},
+          "additionalProperties": false
+        }
+      },
+      {
+        "action": "setRate",
+        "summary": "Run the app's clock `rate` times as fast as real time (1 = normal, 60 = a minute per second, 3600 = an hour per second).",
+        "description": "Starts from what the app's clock reads now, so nothing jumps. Only reads of the time speed up: timer delays stay real, so taps, animations and polling behave; code that recomputes from Date.now() on each tick (most countdowns) shows the faster time. Range 0.1 to 86400. Returns the new state.",
+        "effect": "write",
+        "release": "works",
+        "undo": {
+          "action": "setRate",
+          "note": "Call again with rate 1. That keeps the time already gained; use reset for real time."
+        },
+        "params": {
+          "type": "object",
+          "properties": {
+            "rate": {
+              "type": "number",
+              "description": "Speed multiplier, 0.1-86400. 1 is normal speed."
+            }
+          },
+          "required": [
+            "rate"
+          ],
+          "additionalProperties": false
+        }
+      },
+      {
+        "action": "reset",
+        "summary": "Put the app back on the device's real clock.",
+        "description": "Removes the Date and Intl patches entirely, clears the saved override and closes the clock chip. Screens that already computed a time keep it until they re-read the clock or the app reloads. Returns the new state (mode 'real').",
+        "effect": "write",
+        "release": "works",
+        "params": {
+          "type": "object",
+          "properties": {},
+          "additionalProperties": false
+        }
+      },
+      {
+        "action": "updateSettings",
+        "summary": "Change the Clock tool's settings: `persist` (keep the override across reloads), `showChip` (floating reminder), `fireTimersOnJump`.",
+        "description": "Only the booleans given are changed. persist=false still applies the override now but forgets it on the next reload. Returns the new state with settings.",
+        "effect": "write",
+        "release": "works",
+        "params": {
+          "type": "object",
+          "properties": {
+            "persist": {
+              "type": "boolean",
+              "description": "Keep the override across reloads and restarts."
+            },
+            "showChip": {
+              "type": "boolean",
+              "description": "Show the floating clock chip while an override is on."
+            },
+            "fireTimersOnJump": {
+              "type": "boolean",
+              "description": "Whether forward shifts run app timers that come due."
+            }
+          },
+          "additionalProperties": false
+        }
+      },
+      {
+        "action": "jumpToTokenExpiry",
+        "summary": "Move the app's clock to just before a sign-in token expires (default 10 s before), then watch for the app to fetch a new token.",
+        "description": "Tests apps that refresh their token before it expires by comparing its expiry with Date.now(). Shifts the app's clock forward (running timers that come due, like a scheduled refresh) to `leadMs` before the token's expiry, and starts a refresh check. The server keeps real time, so it still accepts the old token: only the app's own refresh logic is exercised. The app has to send a request (or run its refresh timer) before a new token shows up; read getState's tokens.check for the result: 'refreshed' with the new token's lifetime and issuing endpoint, or 'loop' when new tokens keep arriving because they already look expired to the moved clock. Throws when no token has been seen, when the token's expiry is unreadable (then use failNextRequest), or when it has already expired on the app's clock.",
+        "effect": "write",
+        "release": "works",
+        "undo": {
+          "action": "reset",
+          "note": "reset puts the app back on real time. The app keeps any token it fetched meanwhile, which is harmless."
+        },
+        "params": {
+          "type": "object",
+          "properties": {
+            "token": {
+              "type": "string",
+              "description": "Token id from getState's tokens[].id. Default: the most recently used token that has a readable expiry."
+            },
+            "leadMs": {
+              "type": "number",
+              "description": "Land this many ms before expiry. Default 10000."
+            }
+          },
+          "additionalProperties": false
+        }
+      },
+      {
+        "action": "failNextRequest",
+        "summary": "Answer the app's next request that carries a sign-in token with a 401 (or `status` 403), once or `times` times, then watch for the app to fetch a new token.",
+        "description": "Tests apps that refresh their token after the server rejects it. Adds a one-shot Network override on the token's origin, limited to requests that send the token's header, so the 401 never lands on the app's own token request. It answers with `WWW-Authenticate: Bearer error=\"invalid_token\"` and an invalid_token JSON body, and starts a refresh check. Needs @buoy-gg/network. The app has to send a request for the 401 to reach it; getState's tokens.check then shows forcedAt, whether a new token arrived, staleAfterFailure (requests that re-sent the old token after the 401) and failedRefreshes (token requests that failed). Replaces an earlier 401 that has not fired yet.",
+        "effect": "write",
+        "release": "works",
+        "undo": {
+          "action": "stopTokenCheck",
+          "note": "stopTokenCheck withdraws the 401 if it has not reached the app yet. A 401 the app already received cannot be taken back."
+        },
+        "params": {
+          "type": "object",
+          "properties": {
+            "token": {
+              "type": "string",
+              "description": "Token id from getState's tokens[].id. Default: the most recently used token that has a readable expiry."
+            },
+            "status": {
+              "type": "number",
+              "description": "401 (default) or 403."
+            },
+            "times": {
+              "type": "number",
+              "description": "How many requests to fail, 1-10. Default 1."
+            }
+          },
+          "additionalProperties": false
+        }
+      },
+      {
+        "action": "stopTokenCheck",
+        "summary": "End the refresh check, withdrawing a forced 401 that has not reached the app yet.",
+        "description": "Clears tokens.check. When the check was started by failNextRequest and the 401 has not fired, removes that Network override so it cannot fail a later request. Returns the new state.",
+        "effect": "write",
+        "release": "works",
+        "params": {
+          "type": "object",
+          "properties": {},
+          "additionalProperties": false
+        }
+      }
+    ]
+  },
   {
     "toolId": "storage",
     "title": "Storage",
     "summary": "Read and write the app's persisted state across all three backends — AsyncStorage, every registered MMKV instance, and registered Expo SecureStore keys — plus a recorded timeline of storage writes with per-event undo/jump. Reach for this first when a value is wrong, stale, missing, or only broken after a restart/upgrade: the bad value is usually sitting in storage. Buoy's own devtool keys (@react_buoy*, @buoy*, buoy-*) are stripped from every read path, so results are app data only. Nothing here is __DEV__-gated — every action really runs in a release build.",
     "actions": [
+      {
+        "action": "getRequiredKeys",
+        "summary": "List the storage keys the app declares as required, with their expected types and backends.",
+        "params": {
+          "type": "object",
+          "properties": {},
+          "additionalProperties": false
+        },
+        "effect": "read",
+        "release": "works",
+        "description": "Returns the requiredStorageKeys array given to createStorageTool (or the FloatingDevTools requiredStorageKeys prop): each entry is a key, or an object with key, expectedType or expectedValue, description and storageType (async, mmkv or secure). Returns [] when the app declared none. It reports the configuration only; read the keys themselves to see whether they are present and valid. Swift returns the requirements configured through BuoyStorageModule.configure(requiredKeys:)."
+      },
       {
         "action": "async.getAllKeys",
         "summary": "List every AsyncStorage key in the app (Buoy's own devtool keys stripped).",
@@ -3028,7 +3289,7 @@
   {
     "toolId": "highlight-updates",
     "title": "Highlight Updates",
-    "summary": "Two different jobs share one tool: (1) DRIVING and READING the live screen — describeScreen lists every on-screen element with tap points, tapElement invokes its real handler in JS (works on physical devices, no screenshots), and locateComponent resolves a component to an on-screen rect; (2) MEASURING re-renders — beginMeasurement/endMeasurement wrap an interaction and return per-component render cost + cause, while toggle/setEnabled draw the user-visible colored highlight boxes on the device. Reach for describeScreen+tapElement to see or operate the app, and beginMeasurement/endMeasurement to answer \"why is this screen slow\". CRITICAL: every action here depends on React's DevTools global hook, which React Native installs ONLY in dev builds — in a release/production build five of these actions return ok:true and silently do nothing, so never report a highlight toggle as applied without confirming it's a dev build.",
+    "summary": "Read and drive the live screen with describeScreen, tapElement, and waitFor. RN also exposes React render tracking; native Swift does not. Inspect the connected device’s actions before calling a platform-specific operation. The touch-capture actions support Scenarios recording. Native capture is restricted to development builds and excludes Buoy controls and secure text inputs.",
     "actions": [
       {
         "action": "describeScreen",
@@ -3371,9 +3632,62 @@
         "requires": [
           "@buoy-gg/highlight-updates installed and registered with <FloatingDevTools>"
         ]
+      },
+      {
+        "action": "startTouchCapture",
+        "summary": "Start recording supported host interactions.",
+        "description": "Returns capture status and a reason if unavailable. RN uses its touch stream; Swift uses UIKit events and native-driver interactions in development builds. Read the status before driving the app. This does not save a scenario.",
+        "params": {
+          "type": "object",
+          "properties": {},
+          "additionalProperties": false
+        },
+        "effect": "write",
+        "release": "empty"
+      },
+      {
+        "action": "stopTouchCapture",
+        "summary": "Stop capturing new interactions and retain recorded data.",
+        "description": "Read retained records with readTouchCapture. Stopping does not save a scenario.",
+        "params": {
+          "type": "object",
+          "properties": {},
+          "additionalProperties": false
+        },
+        "effect": "write",
+        "release": "works"
+      },
+      {
+        "action": "clearTouchCapture",
+        "summary": "Clear retained interactions and reset the sequence number.",
+        "description": "Existing recording data is removed. Start subsequent reads with sinceSeq:0.",
+        "params": {
+          "type": "object",
+          "properties": {},
+          "additionalProperties": false
+        },
+        "effect": "destructive",
+        "release": "works"
+      },
+      {
+        "action": "readTouchCapture",
+        "summary": "Read captured interactions after a sequence number.",
+        "description": "Returns {status, reason, records, seq}. Pass the last returned seq as sinceSeq on the next read. Coverage depends on platform; records do not prove every gesture was captured or replayable.",
+        "params": {
+          "type": "object",
+          "properties": {
+            "sinceSeq": {
+              "type": "number",
+              "description": "Return records with a sequence number greater than this value. Default 0."
+            }
+          },
+          "additionalProperties": false
+        },
+        "effect": "read",
+        "release": "works"
       }
     ],
-    "unavailableWhen": "The app doesn't mount <FloatingDevTools> with @buoy-gg/highlight-updates registered. Also effectively inert in any release/production build: React Native installs __REACT_DEVTOOLS_GLOBAL_HOOK__ only under __DEV__, so the fiber walk finds zero roots and the controller's initialize() bails at HighlightUpdatesController.ts:1744 — read each action's release field before claiming it worked."
+    "unavailableWhen": "RN requires @buoy-gg/highlight-updates registered with FloatingDevTools; React inspection and render tracking depend on a development build. Swift exposes native interaction and touch-capture actions under this ID, without React render tracking. Inspect the connected device’s available actions. Swift touch capture refuses production builds."
   },
   {
     "toolId": "scenarios",
@@ -3845,7 +4159,7 @@
   },
   {
     "toolId": "perf-monitor",
-    "title": "Perf Monitor",
+    "title": "Bench",
     "summary": "Measures runtime performance on the device: live JS/UI FPS, CPU and memory sampled every 250ms, plus recorded \"benchmark runs\" saved to disk and an automation mode that navigates a screen with different query params and ranks the variants. Reach for it to answer \"is this screen slow / which variant is faster / did my fix land\", not to inspect data — it reads no app state. Two traps: live metrics are all zeros until `setEnabled {enabled:true}` arms sampling, and `startAutomation` swallows every validation error, so a bad config returns ok and simply never runs.",
     "actions": [
       {
@@ -4315,7 +4629,7 @@
   {
     "toolId": "assets",
     "title": "Assets",
-    "summary": "Inventory of what the app SHIPS — every bundled asset (images, fonts, video, audio, data) with dimensions, @1x/@2x/@3x scale coverage, content hash, byte size, loaded-vs-never-loaded state, audit findings (duplicates, unused, WebP candidates, over-decode, heavy GIFs/fonts, scale gaps), and a diff vs a saved baseline. Reach for it for bundle-size questions (\"what's making the app big\", \"did this branch add megabytes\", \"which images ship but are never used\"); use the images tool instead for what the app actually RENDERS. Nothing here is __DEV__-gated (zero `__DEV__` in packages/assets/src), but the Metro dev server is what supplies the full-bundle graph and real byte sizes — in an embedded/release bundle the inventory shrinks to registry-only records with estimated sizes.",
+    "summary": "Inventory of what the app SHIPS — every bundled asset (images, fonts, video, audio, data) with dimensions, @1x/@2x/@3x scale coverage, content hash, byte size, loaded-vs-never-loaded state, audit findings (duplicates, unused, WebP candidates, over-decode, heavy GIFs/fonts, scale gaps), and a diff vs a saved baseline. Reach for it for bundle-size questions (\"what's making the app big\", \"did this branch add megabytes\", \"which images ship but are never used\"); use the images tool instead for what the app actually RENDERS. Nothing here is __DEV__-gated (zero `__DEV__` in packages/assets/src), but the Metro dev server is what supplies the full-bundle graph and real byte sizes — in an embedded/release bundle the inventory shrinks to registry-only records with estimated sizes. Swift inventories loose resources in the main bundle and explicitly registered app resource bundles. Buoy resource bundles are excluded. Compiled Assets.car files are aggregate records, not per-image inventory. Native loaded status requires host calls to BuoyAssets.markLoaded; unobserved does not mean unused. Native scale and decoded-memory insight arrays are currently empty. Check scanStatus.coverage and warnings.",
     "actions": [
       {
         "action": "list",
@@ -4349,7 +4663,7 @@
         },
         "effect": "read",
         "release": "works",
-        "description": "Returns { stats, scanStatus, insights, diff, total, records }. `records` is sorted by size descending and sliced to `limit`; `total` is the count AFTER kind/loadedOnly filtering but BEFORE the slice. Each record: { id, key, registryId, name, type, kind, hash, location, width, height, scales, uri, loaded, sizeBytes, sizeSource }. `sizeSource` is \"measured\" (real bytes from the Metro dev server) or \"estimate\" (decoded RGBA memory, width*scale*height*scale*4) — never present them as the same number. `insights` carries id lists: duplicates (grouped by content hash, with wastedBytes), neverLoaded, webpCandidates (png/jpg >= 50KB), overDecode (decodes to >2 screenfuls), heavyGifs (>= 100KB), heavyFonts (>= 150KB), scaleGaps, scaleAnomalies. If `scanStatus.lastScanAt` is null or `graphCount` is null, run `rescan` first — the inventory is registry-only until the Metro graph is merged. If `scanStatus.measuring` is true, byte totals are partial; re-run shortly.",
+        "description": "Returns { stats, scanStatus, insights, diff, total, records }. `records` is sorted by size descending and sliced to `limit`; `total` is the count AFTER kind/loadedOnly filtering but BEFORE the slice. Each record: { id, key, registryId, name, type, kind, hash, location, width, height, scales, uri, loaded, sizeBytes, sizeSource }. `sizeSource` is \"measured\" (real bytes from the Metro dev server) or \"estimate\" (decoded RGBA memory, width*scale*height*scale*4) — never present them as the same number. `insights` carries id lists: duplicates (grouped by content hash, with wastedBytes), neverLoaded, webpCandidates (png/jpg >= 50KB), overDecode (decodes to >2 screenfuls), heavyGifs (>= 100KB), heavyFonts (>= 150KB), scaleGaps, scaleAnomalies. If `scanStatus.lastScanAt` is null or `graphCount` is null, run `rescan` first — the inventory is registry-only until the Metro graph is merged. If `scanStatus.measuring` is true, byte totals are partial; re-run shortly. Swift inventories loose resources in the main bundle and explicitly registered app resource bundles. Buoy resource bundles are excluded. Compiled Assets.car files are aggregate records, not per-image inventory. Native loaded status requires host calls to BuoyAssets.markLoaded; unobserved does not mean unused. Native scale and decoded-memory insight arrays are currently empty. Check scanStatus.coverage and warnings.",
         "requires": [
           "@buoy-gg/assets imported in the app",
           "Metro dev server (for full-bundle coverage, never-loaded detection and measured bytes)"
@@ -4465,7 +4779,7 @@
         },
         "effect": "read",
         "release": "works",
-        "description": "Returns { registryAvailable, patched, registryCount, graphSupported, graphCount, graphError, lastScanAt, measuring, measuredCount, fontFamilies: string[], localAssetCount }. Use it to explain a thin or surprising inventory before drawing conclusions: registryAvailable:false means the RN asset registry could not be required at all; graphCount:null with a graphError means only runtime-registered assets are known (so 'never loaded' is unanswerable); measuring:true means byte totals are still landing. lastScanAt:null means nothing has scanned yet — call rescan."
+        "description": "Returns { registryAvailable, patched, registryCount, graphSupported, graphCount, graphError, lastScanAt, measuring, measuredCount, fontFamilies: string[], localAssetCount }. Use it to explain a thin or surprising inventory before drawing conclusions: registryAvailable:false means the RN asset registry could not be required at all; graphCount:null with a graphError means only runtime-registered assets are known (so 'never loaded' is unanswerable); measuring:true means byte totals are still landing. lastScanAt:null means nothing has scanned yet — call rescan. Swift inventories loose resources in the main bundle and explicitly registered app resource bundles. Buoy resource bundles are excluded. Compiled Assets.car files are aggregate records, not per-image inventory. Native loaded status requires host calls to BuoyAssets.markLoaded; unobserved does not mean unused. Native scale and decoded-memory insight arrays are currently empty. Check scanStatus.coverage and warnings."
       }
     ],
     "unavailableWhen": "The app doesn't import @buoy-gg/assets (autoExternalSync only registers the adapter when the module resolves — packages/devtools-floating-menu/src/floatingMenu/autoExternalSync.tsx:391), or the app is a release/production JS bundle that didn't opt in with `externalSync.enableInRelease` plus a real Pro license, in which case the device never connects to the broker at all."
@@ -5130,5 +5444,335 @@
       }
     ],
     "unavailableWhen": "Only present while an Ask Buoy session is running — which is exactly when this catalog is in use, so in practice always available to you."
+  },
+  {
+    "toolId": "push-notifications",
+    "title": "Push Notifications",
+    "summary": "Inspect notification receipt, responses, presentation decisions, background-task results and tokens from an explicitly configured Expo capture adapter. Use test IDs to correlate stages. Simulator sending lives in the desktop host and is not a device action. Real-provider sending is not implemented.",
+    "unavailableWhen": "Capture requires @buoy-gg/notifications and early installExpoNotificationCapture setup with the app SDK. Release capture needs an explicit enableInRelease option; release desktop sync separately requires its own opt-in and Pro. Background evidence requires the app task wrapper. Native delivery validation covers Expo 56 on iOS.",
+    "actions": [
+      {
+        "action": "getSnapshot",
+        "summary": "Read captured notification evidence and tokens.",
+        "description": "Returns the bounded journal, session, provider capabilities, permissions and token observations. A missing callback does not prove that no OS alert appeared.",
+        "effect": "read",
+        "release": "works",
+        "params": {
+          "type": "object",
+          "properties": {},
+          "additionalProperties": false
+        }
+      },
+      {
+        "action": "getCapabilities",
+        "summary": "Check notification capture setup.",
+        "description": "Returns provider/version, app ID, platform, supported operations and durable-storage state. No device tokens are registered by this action.",
+        "effect": "read",
+        "release": "works",
+        "params": {
+          "type": "object",
+          "properties": {},
+          "additionalProperties": false
+        }
+      },
+      {
+        "action": "getEvent",
+        "summary": "Read one captured event by id.",
+        "description": "Returns an event by its Buoy record ID, or null after eviction. Native notification ID and test ID are separate fields.",
+        "effect": "read",
+        "release": "works",
+        "params": {
+          "type": "object",
+          "properties": {
+            "id": {
+              "type": "string",
+              "description": "Buoy event record id from getSnapshot.events."
+            }
+          },
+          "additionalProperties": false,
+          "required": [
+            "id"
+          ]
+        }
+      },
+      {
+        "action": "getPermissions",
+        "summary": "Refresh notification permission settings.",
+        "description": "Reads the existing OS settings through Expo. Does not display a permission prompt.",
+        "effect": "read",
+        "release": "works",
+        "params": {
+          "type": "object",
+          "properties": {},
+          "additionalProperties": false
+        }
+      },
+      {
+        "action": "listPresented",
+        "summary": "Inspect notifications currently in the system tray.",
+        "description": "Reads a current snapshot through Expo. This is not a historical record and does not dismiss notifications.",
+        "effect": "read",
+        "release": "works",
+        "params": {
+          "type": "object",
+          "properties": {},
+          "additionalProperties": false
+        }
+      },
+      {
+        "action": "refreshToken",
+        "summary": "Register a token with type \"device\" or \"expo\". Expo registration requires a configured projectId.",
+        "description": "May register with APNs/FCM or contact Expo Push Service. Expo tokens require projectId in app setup. Never invoke merely to open the inspector.",
+        "effect": "write",
+        "release": "works",
+        "params": {
+          "type": "object",
+          "properties": {
+            "type": {
+              "type": "string",
+              "enum": [
+                "device",
+                "expo"
+              ],
+              "description": "device returns APNs on iOS or FCM on Android; expo requests an Expo token."
+            }
+          },
+          "additionalProperties": false,
+          "required": [
+            "type"
+          ]
+        }
+      },
+      {
+        "action": "setCaptureSession",
+        "summary": "Set runId and optional durationMs to arm capture, or runId:null to stop.",
+        "description": "Arm while the app is connected, before backgrounding or stopping it. Await durable:true before relying on cold-launch recovery. Sessions last at most one hour.",
+        "effect": "write",
+        "release": "works",
+        "params": {
+          "type": "object",
+          "properties": {
+            "runId": {
+              "type": [
+                "string",
+                "null"
+              ],
+              "description": "A test-run label of 1 to 128 characters, or null to stop capture."
+            },
+            "durationMs": {
+              "type": "number",
+              "minimum": 1000,
+              "maximum": 3600000,
+              "description": "Capture duration in milliseconds. Default 1800000."
+            }
+          },
+          "additionalProperties": false,
+          "required": [
+            "runId"
+          ]
+        }
+      },
+      {
+        "action": "clearCapturedEvents",
+        "summary": "Clear Buoy notification history.",
+        "description": "Deletes retained captured events. Leaves device tokens, OS notifications and the capture session unchanged.",
+        "effect": "destructive",
+        "release": "works",
+        "params": {
+          "type": "object",
+          "properties": {},
+          "additionalProperties": false
+        }
+      },
+      {
+        "action": "scheduleLocal",
+        "summary": "Schedule a local notification with title, body, optional data and a delay in seconds.",
+        "description": "This tests local notification behavior, not APNs or FCM delivery. The app must be connected before scheduling. Uses the app SDK and notification settings.",
+        "effect": "write",
+        "release": "works",
+        "params": {
+          "type": "object",
+          "properties": {
+            "title": {
+              "type": "string",
+              "description": "Displayed title."
+            },
+            "body": {
+              "type": "string",
+              "description": "Displayed message."
+            },
+            "data": {
+              "type": "object",
+              "description": "Custom notification data. Include __buoyTestId to correlate with a test run."
+            },
+            "seconds": {
+              "type": "number",
+              "minimum": 1,
+              "maximum": 3600,
+              "description": "Delay before local delivery."
+            }
+          },
+          "additionalProperties": false,
+          "required": [
+            "title",
+            "body",
+            "seconds"
+          ]
+        }
+      }
+    ]
+  },
+  {
+    "toolId": "image-overlay",
+    "title": "Image Overlay",
+    "summary": "Control the Swift design-image overlay. Uses the same state as the on-device controls. Read getSnapshot after loadImage to check loading and error. Available on Swift iOS only; check device capabilities.",
+    "actions": [
+      {
+        "action": "getSnapshot",
+        "summary": "Read overlay loading, image presence, placement, selected target and settings.",
+        "params": {
+          "type": "object",
+          "properties": {},
+          "additionalProperties": false
+        },
+        "effect": "read",
+        "release": "works"
+      },
+      {
+        "action": "listTargets",
+        "summary": "Scan visible app image-overlay targets and return their ids, labels and frames.",
+        "params": {
+          "type": "object",
+          "properties": {},
+          "additionalProperties": false
+        },
+        "effect": "read",
+        "release": "works"
+      },
+      {
+        "action": "selectTarget",
+        "summary": "Attach the overlay to a visible target.",
+        "params": {
+          "type": "object",
+          "properties": {
+            "id": {
+              "type": "string",
+              "description": "Target id returned by listTargets."
+            }
+          },
+          "additionalProperties": false,
+          "required": [
+            "id"
+          ]
+        },
+        "effect": "write",
+        "release": "works"
+      },
+      {
+        "action": "loadImage",
+        "summary": "Start loading a design image; returns {scheduled:true}. Check getSnapshot for completion or error.",
+        "params": {
+          "type": "object",
+          "properties": {
+            "url": {
+              "type": "string",
+              "description": "HTTP(S) image URL."
+            }
+          },
+          "additionalProperties": false,
+          "required": [
+            "url"
+          ]
+        },
+        "effect": "write",
+        "release": "works"
+      },
+      {
+        "action": "setSettings",
+        "summary": "Update overlay settings. Invalid batches fail before any settings change.",
+        "params": {
+          "type": "object",
+          "properties": {
+            "visible": {
+              "type": "boolean",
+              "description": "Show the overlay."
+            },
+            "locked": {
+              "type": "boolean",
+              "description": "Lock direct manipulation."
+            },
+            "flipped": {
+              "type": "boolean",
+              "description": "Flip horizontally."
+            },
+            "flippedY": {
+              "type": "boolean",
+              "description": "Flip vertically."
+            },
+            "showOutline": {
+              "type": "boolean",
+              "description": "Show the target outline."
+            },
+            "autoTrack": {
+              "type": "boolean",
+              "description": "Follow the selected target."
+            },
+            "opacity": {
+              "type": "number",
+              "description": "Opacity from 0 to 1."
+            },
+            "scale": {
+              "type": "number",
+              "description": "Positive scale factor."
+            },
+            "offsetX": {
+              "type": "number",
+              "description": "Horizontal offset in points."
+            },
+            "offsetY": {
+              "type": "number",
+              "description": "Vertical offset in points."
+            }
+          },
+          "additionalProperties": false
+        },
+        "effect": "write",
+        "release": "works"
+      },
+      {
+        "action": "fitToScreen",
+        "summary": "Fit the image to the screen width while preserving its aspect ratio.",
+        "params": {
+          "type": "object",
+          "properties": {},
+          "additionalProperties": false
+        },
+        "effect": "write",
+        "release": "works"
+      },
+      {
+        "action": "resetSettings",
+        "summary": "Reset opacity, flips, scale and offsets.",
+        "params": {
+          "type": "object",
+          "properties": {},
+          "additionalProperties": false
+        },
+        "effect": "write",
+        "release": "works"
+      },
+      {
+        "action": "remove",
+        "summary": "Remove the image and target; cancel pending image loading.",
+        "params": {
+          "type": "object",
+          "properties": {},
+          "additionalProperties": false
+        },
+        "effect": "write",
+        "release": "works"
+      }
+    ],
+    "unavailableWhen": "The native Swift image-overlay adapter is not registered. React Native does not expose these actions."
   }
 ]