@buoy-gg/agent-core 7.0.39 → 7.0.41

package/lib/module/catalog/catalog.g.js

@@ -4,7 +4,7 @@
  * GENERATED by scripts/gen-agent-catalog.mjs — do not edit.
  * Source: packages/agent-core/src/catalog/catalog.source.json
  *
- * 24 Buoy tools, 196 actions.
+ * 26 Buoy tools, 218 actions.
  */
 
 export const CATALOG = [{
@@ -456,7 +456,7 @@ export const CATALOG = [{
     "requires": ["a change id from the zustand change log (the tool snapshot, or get_events sources:['zustand'])"]
   }, {
     "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": {
@@ -1067,7 +1067,7 @@ export const CATALOG = [{
 }, {
   "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",
     "summary": "Read the recorded cross-tool timeline as a formatted string (markdown/json/plaintext/mermaid), optionally filtered by source and status.",
@@ -1179,7 +1179,7 @@ export const CATALOG = [{
     },
     "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", "the source packages you want in the timeline (@buoy-gg/network, /redux, /storage, /react-query, /route-events, /zustand, /jotai); the /highlight-updates 'render' source produces NOTHING in a release build"],
     "armsCapture": true
   }, {
@@ -1777,7 +1777,7 @@ export const CATALOG = [{
 }, {
   "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",
     "summary": "List all restore points plus which state sources can currently be captured/restored and whether the device can navigate routes.",
@@ -1788,7 +1788,7 @@ export const CATALOG = [{
     },
     "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"]
   }, {
     "action": "capture",
@@ -1870,7 +1870,7 @@ export const CATALOG = [{
     },
     "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", "expo-updates for the reload leg in a release build"]
   }, {
     "action": "preview",
@@ -2061,6 +2061,17 @@ export const CATALOG = [{
   "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).",
     "params": {
@@ -2468,7 +2479,7 @@ export const CATALOG = [{
 }, {
   "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",
     "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.",
@@ -2753,8 +2764,57 @@ export const CATALOG = [{
     "description": "Clears the nativeTag->count map and empties RenderTracker's entire renders store. There is no undo and no snapshot: any render history a human was watching accumulate, or that a colleague armed tracking to collect, is gone. Only call this when the user explicitly asks to reset counts, typically to get a clean baseline before measuring an interaction. Prefer beginMeasurement/endMeasurement for measuring — that opens its own window and never touches the user's overlay data. Takes no params. Returns undefined.",
     "releaseNote": "packages/highlight-updates/src/highlight-updates/utils/HighlightUpdatesController.ts:1744 (initialize), :1819 (enable), :1905 (enableBackgroundTracking) all return early when __DEV__===false, and the only writers of nodeRenderCounts/RenderTracker are the DevTools-hook interceptors (ProfilerInterceptor.ts:107, CommitProfiler.ts:74). In a release build those stores are permanently empty, so clearRen",
     "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",
   "title": "Scenarios",
@@ -3138,7 +3198,7 @@ export const CATALOG = [{
   "unavailableWhen": "The app does not install the Scenarios tool (no `createScenariosTool` / scenarios preset passed to `<FloatingDevTools />`), so \"scenarios\" is absent from the device's capability list. Driven through MCP or the desktop dashboard, the device must also be on a Pro license (`requireProDevice`)."
 }, {
   "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": [{
     "action": "setEnabled",
@@ -3552,7 +3612,7 @@ export const CATALOG = [{
 }, {
   "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",
     "summary": "The whole asset inventory, largest-first, plus stats, scan status, audit insights and the baseline diff in one call.",
@@ -3578,7 +3638,7 @@ export const CATALOG = [{
     },
     "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)"]
   }, {
     "action": "getDetail",
@@ -3676,7 +3736,7 @@ export const CATALOG = [{
     },
     "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."
 }, {
@@ -4199,7 +4259,296 @@ export const CATALOG = [{
     "description": "Returns `{id, title, version?, requires?, body, note}`; `{ok:false, error}` naming the available ids when the id is unknown or the app has none. A procedure grants nothing: each step still runs through the same catalog, policy, approval card and undo as any other call."
   }],
   "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": {
+          "description": "A test-run label of 1 to 128 characters, or null to stop capture.",
+          "anyOf": [{
+            "type": "string"
+          }, {
+            "type": "null"
+          }]
+        },
+        "durationMs": {
+          "type": "number",
+          "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",
+          "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."
 }];
-export const CATALOG_TOOL_COUNT = 24;
-export const CATALOG_ACTION_COUNT = 196;
+export const CATALOG_TOOL_COUNT = 26;
+export const CATALOG_ACTION_COUNT = 218;
 //# sourceMappingURL=catalog.g.js.map