@avasapp/agent-bridge 0.4.1 → 0.4.2

package/dist/{chunk-AJD3XTNT.js → chunk-TA2OLPPT.js}

@@ -50,6 +50,15 @@ function pickOne(items, filter, label) {
       `${matching.length} apps are connected; pick one with --device. Connected: ${connected}`
     );
   }
+  if (matching.length > 1) {
+    const exact = matching.filter(
+      (item) => label(item).toLowerCase() === filter?.toLowerCase()
+    );
+    if (exact.length === 1) return exact[0];
+    throw new Error(
+      `${matching.length} apps match "${filter}"; narrow --device. Matching: ${matching.map(label).join("; ")}`
+    );
+  }
   return matching[0];
 }
 
@@ -67,6 +76,7 @@ function toAsciiJson(value) {
 
 // src/client/connection.ts
 import WebSocket from "ws";
+var describePin = (pin) => `${pin.name} (${pin.platform}${pin.target ? `, ${pin.target}` : ""})`;
 var OPEN_SOCKET_MS = 5e3;
 var OpenGaveUp = class extends Error {
 };
@@ -192,7 +202,7 @@ async function listExpoDevices(metro, discoveryMs = 600) {
   ws.close();
   return [...devices.values()];
 }
-async function connectExpo(metro, device, discoveryMs = 600, signal) {
+async function connectExpo(metro, device, discoveryMs = 600, signal, pin) {
   const { ws, devices, pending, send, announced } = await openBroadcast(
     metro,
     discoveryMs,
@@ -200,7 +210,13 @@ async function connectExpo(metro, device, discoveryMs = 600, signal) {
   );
   let info;
   try {
-    info = pickOne([...devices.values()], device, deviceLabel);
+    const all = [...devices.values()];
+    const candidates = pin ? all.filter((d) => d.name === pin.name && d.platform === pin.platform) : all;
+    if (pin && !candidates.length)
+      throw new Error(
+        `${describePin(pin)} is not connected; connected: ${all.map(deviceLabel).join("; ") || "none"}`
+      );
+    info = pickOne(candidates, device, deviceLabel);
   } catch (error) {
     ws.close();
     throw error;
@@ -215,6 +231,7 @@ async function connectExpo(metro, device, discoveryMs = 600, signal) {
   return {
     transport: "expo",
     device: info,
+    pin: { name: info.name, platform: info.platform },
     call(tool, args, timeoutMs) {
       if (superseded)
         return Promise.resolve({
@@ -243,12 +260,14 @@ import WebSocket2 from "ws";
 var CannotEvaluate = class extends Error {
 };
 var targetLabel = (t) => `${t.title}${t.deviceName ? ` [${t.deviceName}]` : ""}`;
-async function connectCdp(metro, device, signal) {
-  const target = pickOne(
-    await listCdpTargets(metro, signal),
-    device,
-    targetLabel
-  );
+async function connectCdp(metro, device, signal, pin) {
+  const targets = await listCdpTargets(metro, signal);
+  const candidates = pin?.target ? targets.filter((t) => targetLabel(t) === pin.target) : targets;
+  if (pin && !candidates.length)
+    throw new Error(
+      `${describePin(pin)} is not connected; connected: ${targets.map(targetLabel).join("; ") || "none"}`
+    );
+  const target = pickOne(candidates, device, targetLabel);
   const hostUri = await expoHostUri(metro, signal);
   const port = metro.split(":")[1] ?? "8081";
   const origin = hostUri ? `http://${hostUri}` : `http://localhost:${port}`;
@@ -326,27 +345,34 @@ async function connectCdp(metro, device, signal) {
     );
   }
   signal?.removeEventListener("abort", dropOnAbort);
+  if (pin && (info.name !== pin.name || info.platform !== pin.platform)) {
+    ws.terminate();
+    throw new Error(
+      `${describePin(pin)} is not connected; connected: ${targetLabel(target)} runs ${info.name} (${info.platform})`
+    );
+  }
   return {
     transport: "cdp",
+    pin: {
+      name: info.name,
+      platform: info.platform,
+      target: targetLabel(target)
+    },
     device: { ...info, name: `${info.name} (${targetLabel(target)})` },
-    async call(tool, args, timeoutMs) {
+    call(tool, args, timeoutMs) {
       const call = { id: newCallId(), tool, args };
       const reply = pending.wait(call.id, tool, timeoutMs);
-      reply.catch(() => {
-      });
-      try {
-        await evaluate(
-          `${CDP_GLOBAL}.dispatch(${JSON.stringify(toAsciiJson(call))})`
-        );
-      } catch (error) {
-        pending.settle({
+      evaluate(
+        `${CDP_GLOBAL}.dispatch(${JSON.stringify(toAsciiJson(call))})`
+      ).catch(
+        (error) => pending.settle({
           id: call.id,
           from: info.deviceId,
           ok: false,
           error: String(error),
           ms: 0
-        });
-      }
+        })
+      );
       return reply;
     },
     close: () => ws.close()
@@ -389,7 +415,7 @@ async function openConnection(options = {}) {
     try {
       return await phase(
         options,
-        (signal) => connectExpo(metro, options.device, void 0, signal)
+        (signal) => connectExpo(metro, options.device, void 0, signal, options.pin)
       );
     } catch (error) {
       if (want === "expo" || options.signal?.aborted) throw error;
@@ -399,7 +425,7 @@ async function openConnection(options = {}) {
   try {
     return await phase(
       options,
-      (signal) => connectCdp(metro, options.device, signal)
+      (signal) => connectCdp(metro, options.device, signal, options.pin)
     );
   } catch (error) {
     const expoNote = expoError ? ` (Expo socket: ${String(expoError)})` : "";

package/dist/cli.js

@@ -26,7 +26,7 @@ import {
   sessionRequest,
   stateDir,
   writePrivate
-} from "./chunk-AJD3XTNT.js";
+} from "./chunk-TA2OLPPT.js";
 
 // src/cli.ts
 import { readFile } from "fs/promises";
@@ -619,22 +619,26 @@ async function runSessionDaemon(options) {
   const attemptMs = options.attemptMs ?? 12e3;
   const stopping = new AbortController();
   const cutOff = new AbortController();
-  const reach = (signal) => openConnection({
+  const reach = (signal, pin2) => openConnection({
     metro,
     device: options.device,
+    pin: pin2,
     transport: options.transport,
     ...signal && { signal, timeoutMs: attemptMs }
   });
-  let conn = await reach();
-  const owner = listSessions(dir).find(
-    (s) => s.metro === metro && s.device.deviceId === conn.device.deviceId
-  );
-  if (owner) {
-    conn.close();
+  const claim = (c) => {
+    const owner = listSessions(dir).find(
+      (s) => s.name !== name && s.metro === metro && s.device.deviceId === c.device.deviceId
+    );
+    if (!owner) return;
+    c.close();
     throw new Error(
-      `${conn.device.name} already belongs to session "${owner.name}". Use --session ${owner.name}, or stop it first.`
+      `${c.device.name} already belongs to session "${owner.name}". Use --session ${owner.name}, or stop it first.`
     );
-  }
+  };
+  let conn = await reach();
+  claim(conn);
+  const pin = conn.pin;
   const deviceOf = (c) => ({
     name: c.device.name,
     deviceId: c.device.deviceId,
@@ -690,7 +694,8 @@ async function runSessionDaemon(options) {
       const deadline = Date.now() + (patient ? reloadWaitMs : 0);
       for (; ; ) {
         try {
-          const next = await reach(cutOff.signal);
+          const next = await reach(cutOff.signal, pin);
+          claim(next);
           if (patient && knownLoad && next.device.loadId === knownLoad) {
             next.close();
             throw new Error("the old runtime still answers");
@@ -1262,7 +1267,10 @@ async function main() {
   };
   const withBridge = async (fn) => {
     const session = sessionFor(values);
-    if (session) console.error(`Using session "${session.name}"`);
+    if (session)
+      console.error(
+        `Using session "${session.name}" (${session.device.name} on ${session.metro})`
+      );
     const bridge = session ? await connectSession({
       name: session.name,
       timeoutMs: options.timeoutMs

package/dist/client/index.cjs

@@ -91,6 +91,15 @@ function pickOne(items, filter, label) {
       `${matching.length} apps are connected; pick one with --device. Connected: ${connected}`
     );
   }
+  if (matching.length > 1) {
+    const exact = matching.filter(
+      (item) => label(item).toLowerCase() === filter?.toLowerCase()
+    );
+    if (exact.length === 1) return exact[0];
+    throw new Error(
+      `${matching.length} apps match "${filter}"; narrow --device. Matching: ${matching.map(label).join("; ")}`
+    );
+  }
   return matching[0];
 }
 
@@ -107,6 +116,7 @@ function toAsciiJson(value) {
 
 // src/client/connection.ts
 var import_ws = __toESM(require("ws"), 1);
+var describePin = (pin) => `${pin.name} (${pin.platform}${pin.target ? `, ${pin.target}` : ""})`;
 var OPEN_SOCKET_MS = 5e3;
 var OpenGaveUp = class extends Error {
 };
@@ -232,7 +242,7 @@ async function listExpoDevices(metro, discoveryMs = 600) {
   ws.close();
   return [...devices.values()];
 }
-async function connectExpo(metro, device, discoveryMs = 600, signal) {
+async function connectExpo(metro, device, discoveryMs = 600, signal, pin) {
   const { ws, devices, pending, send, announced } = await openBroadcast(
     metro,
     discoveryMs,
@@ -240,7 +250,13 @@ async function connectExpo(metro, device, discoveryMs = 600, signal) {
   );
   let info;
   try {
-    info = pickOne([...devices.values()], device, deviceLabel);
+    const all = [...devices.values()];
+    const candidates = pin ? all.filter((d) => d.name === pin.name && d.platform === pin.platform) : all;
+    if (pin && !candidates.length)
+      throw new Error(
+        `${describePin(pin)} is not connected; connected: ${all.map(deviceLabel).join("; ") || "none"}`
+      );
+    info = pickOne(candidates, device, deviceLabel);
   } catch (error) {
     ws.close();
     throw error;
@@ -255,6 +271,7 @@ async function connectExpo(metro, device, discoveryMs = 600, signal) {
   return {
     transport: "expo",
     device: info,
+    pin: { name: info.name, platform: info.platform },
     call(tool, args, timeoutMs) {
       if (superseded)
         return Promise.resolve({
@@ -283,12 +300,14 @@ var import_ws2 = __toESM(require("ws"), 1);
 var CannotEvaluate = class extends Error {
 };
 var targetLabel = (t) => `${t.title}${t.deviceName ? ` [${t.deviceName}]` : ""}`;
-async function connectCdp(metro, device, signal) {
-  const target = pickOne(
-    await listCdpTargets(metro, signal),
-    device,
-    targetLabel
-  );
+async function connectCdp(metro, device, signal, pin) {
+  const targets = await listCdpTargets(metro, signal);
+  const candidates = pin?.target ? targets.filter((t) => targetLabel(t) === pin.target) : targets;
+  if (pin && !candidates.length)
+    throw new Error(
+      `${describePin(pin)} is not connected; connected: ${targets.map(targetLabel).join("; ") || "none"}`
+    );
+  const target = pickOne(candidates, device, targetLabel);
   const hostUri = await expoHostUri(metro, signal);
   const port = metro.split(":")[1] ?? "8081";
   const origin = hostUri ? `http://${hostUri}` : `http://localhost:${port}`;
@@ -366,27 +385,34 @@ async function connectCdp(metro, device, signal) {
     );
   }
   signal?.removeEventListener("abort", dropOnAbort);
+  if (pin && (info.name !== pin.name || info.platform !== pin.platform)) {
+    ws.terminate();
+    throw new Error(
+      `${describePin(pin)} is not connected; connected: ${targetLabel(target)} runs ${info.name} (${info.platform})`
+    );
+  }
   return {
     transport: "cdp",
+    pin: {
+      name: info.name,
+      platform: info.platform,
+      target: targetLabel(target)
+    },
     device: { ...info, name: `${info.name} (${targetLabel(target)})` },
-    async call(tool, args, timeoutMs) {
+    call(tool, args, timeoutMs) {
       const call = { id: newCallId(), tool, args };
       const reply = pending.wait(call.id, tool, timeoutMs);
-      reply.catch(() => {
-      });
-      try {
-        await evaluate(
-          `${CDP_GLOBAL}.dispatch(${JSON.stringify(toAsciiJson(call))})`
-        );
-      } catch (error) {
-        pending.settle({
+      evaluate(
+        `${CDP_GLOBAL}.dispatch(${JSON.stringify(toAsciiJson(call))})`
+      ).catch(
+        (error) => pending.settle({
           id: call.id,
           from: info.deviceId,
           ok: false,
           error: String(error),
           ms: 0
-        });
-      }
+        })
+      );
       return reply;
     },
     close: () => ws.close()
@@ -429,7 +455,7 @@ async function openConnection(options = {}) {
     try {
       return await phase(
         options,
-        (signal) => connectExpo(metro, options.device, void 0, signal)
+        (signal) => connectExpo(metro, options.device, void 0, signal, options.pin)
       );
     } catch (error) {
       if (want === "expo" || options.signal?.aborted) throw error;
@@ -439,7 +465,7 @@ async function openConnection(options = {}) {
   try {
     return await phase(
       options,
-      (signal) => connectCdp(metro, options.device, signal)
+      (signal) => connectCdp(metro, options.device, signal, options.pin)
     );
   } catch (error) {
     const expoNote = expoError ? ` (Expo socket: ${String(expoError)})` : "";

package/dist/client/index.js

@@ -5,7 +5,7 @@ import {
   listDevices,
   listSessions,
   runFlow
-} from "../chunk-AJD3XTNT.js";
+} from "../chunk-TA2OLPPT.js";
 export {
   AgentBridgeCallError,
   connect,

package/dist/runtime/index.cjs

@@ -1266,9 +1266,19 @@ var POLL_MS = 50;
 function nearMissNote(found, target) {
   const text = typeof target === "string" ? target : target.text;
   const near = text ? nearMisses(found, text) : [];
-  return near.length ? `. Near misses: ${near.join("; ")}` : "";
-}
-function waitForTarget(collect, target, options = {}) {
+  if (!near.length) return "";
+  const offscreen = matchTarget(
+    found.filter((f) => !f.onScreen && !f.hidden),
+    target
+  ).length;
+  const hint = offscreen ? ". {scroll:true} scrolls an off-screen match into view" : "";
+  return `. Near misses: ${near.join("; ")}${hint}`;
+}
+function waitForTarget(collect, target, options = {}, reveal) {
+  if (options.gone && options.scroll)
+    return Promise.reject(
+      new Error("{gone:true} and {scroll:true} can't be combined: gone waits for the target to leave the screen")
+    );
   const timeoutMs = options.timeoutMs ?? 5e3;
   const t0 = performance.now();
   const ms = () => Math.round((performance.now() - t0) * 100) / 100;
@@ -1285,12 +1295,17 @@ function waitForTarget(collect, target, options = {}) {
       if (finished) return;
       try {
         const found = collect();
-        const matches = matchTarget(
-          found.filter((f) => f.onScreen && !f.hidden),
+        const reachable = found.filter((f) => !f.hidden);
+        let matches = matchTarget(
+          reachable.filter((f) => f.onScreen),
           target
         );
+        if (!matches.length && options.scroll && reveal) matches = matchTarget(reachable, target);
         const hit = matches[indexOf(target) ?? 0];
-        if (options.gone ? !hit : hit) {
+        if (hit && !hit.onScreen && reveal) {
+          finish();
+          reveal(hit).then((f) => resolve({ ms: ms(), element: f.element }), reject);
+        } else if (options.gone ? !hit : hit) {
           finish();
           resolve(hit ? { ms: ms(), element: hit.element } : { ms: ms() });
         } else if (performance.now() - t0 >= timeoutMs) {
@@ -1366,18 +1381,20 @@ function createScreen(env) {
     if (!metrics && current.scroller) metrics = metricsOf(current.scroller);
     return { found: current, metrics };
   };
+  const reveal = async (found) => {
+    const shown = (await bringIntoView(found)).found;
+    if (!shown.onScreen)
+      throw new Error(
+        `${describe(shown.element)} is not on screen and no scrollable around it can bring it into view`
+      );
+    return shown;
+  };
   const resolve = async (target, prefer, options) => {
-    let found = resolveTarget(collect(), target, prefer, {
+    const found = resolveTarget(collect(), target, prefer, {
       ...options,
       offscreen: options.scroll
     });
-    if (found.onScreen) return found;
-    found = (await bringIntoView(found)).found;
-    if (!found.onScreen)
-      throw new Error(
-        `${describe(found.element)} is not on screen and no scrollable around it can bring it into view`
-      );
-    return found;
+    return found.onScreen ? found : reveal(found);
   };
   return {
     snapshot(options = {}) {
@@ -1490,7 +1507,7 @@ function createScreen(env) {
       await settle();
       return { refreshed: true };
     },
-    waitFor: (target, options) => waitForTarget(collect, target, options)
+    waitFor: (target, options) => waitForTarget(collect, target, options, reveal)
   };
 }
 
@@ -1528,7 +1545,7 @@ function screenTools() {
       run: (target, options) => screen.refresh(target, options)
     },
     "screen.waitFor": {
-      description: "Wait until a target is on screen, or gone with {gone:true}. Matches testID, label, placeholder, then the same joined text screen.snapshot shows. Default timeout 5000 ms; a timeout lists near misses.",
+      description: "Wait until a target is on screen, or gone with {gone:true}. Matches testID, label, placeholder, then the same joined text screen.snapshot shows. {scroll:true} also accepts a match rendered off screen and scrolls it into view (not with gone). Default timeout 5000 ms; a timeout lists near misses.",
       run: (target, options) => screen.waitFor(target, options)
     }
   };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avasapp/agent-bridge",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "Let coding agents drive a running React Native app directly: seed state, flip flags, navigate and check the screen in about a millisecond per call, with no taps.",
   "type": "module",
   "license": "MIT",

package/skills/agent-bridge/SKILL.md

@@ -26,7 +26,7 @@ bridge call can set.
 
 ## Run the CLI directly
 
-The examples below say `npx agent-bridge` for brevity. Prefer the installed bin,
+The examples say `npx agent-bridge` for brevity. Prefer the installed bin,
 `./node_modules/.bin/agent-bridge` (or `bunx agent-bridge`): `npx` loads npm's
 config on every call, so a project `.npmrc` with keys npm doesn't know prints
 `npm warn Unknown project config` into your output each time, and it adds
@@ -45,12 +45,15 @@ minutes without calls and runs `bridge.restore` when it does.
 A JS reload (an error screen's Retry, or `app.reload`) throws away every pending
 restore. The session notices the app is a new runtime and reports
 `app reloaded; N pending restores lost: store, query` (the areas that
-had something to undo) as a warning on the next call (also on a failed one) and again in `session stop`. When you see
-it, redo your setup: nothing you changed before the reload will be undone.
+had something to undo) as a warning on the next call (also on a failed one) and
+again in `session stop`. When you see it, redo your setup: nothing you changed
+before the reload will be undone.
 
 If a call fails with `app not connected; reconnecting` or `The app is gone`, the
 session lost the app (Metro or the app is down, or mid-reload). It retries on
-its 5 s health check and on your next call: wait a few seconds and call again. `session stop` still works.
+its 5 s health check and on your next call: wait a few seconds and call again.
+`session stop` still works. A session never moves to another app: `<app> is
+not connected; connected: …` means its app is gone and something else is there.
 
 If `tools` fails with "agent-bridge isn't running", the hook isn't mounted in
 this build. Say so; don't fall back to tapping silently.
@@ -68,187 +71,30 @@ npx agent-bridge call scenario.apply '["signedIn", {"user": {"name": "Ada"}}]'
 `scenarios` shows each one's options as a JSON Schema. Bad options fail
 before anything changes, and the error lists every problem
 (`options: unknown option "usr". Known: user`): fix them and apply again.
-`bridge.restore` (and `session stop`) undoes it after everything else. A local
-scenario usually turns on strict network mode: any request no mock answers
-fails with a 501, and the reply carries an error that names it
+`bridge.restore` (and `session stop`) undoes it after everything else.
+
+A local scenario usually turns on strict network mode: any request no mock
+answers fails with a 501, and the reply carries an error that names it
 (`! error during …: agent-bridge strict network: no mock for GET https://…`).
 Add a mock for it (`net.mock`), don't turn strict mode off.
-`npx agent-bridge call net.strict` lists what it blocked. Strict mode sees JS
-`fetch`/XHR only, not images, WebSockets or native SDKs.
 
 If the app has no scenario for the state you need, say so. Don't sign in to a
-real account instead.
+real account instead. If you're asked to add one, read
+[references/writing-scenarios.md](references/writing-scenarios.md).
 
 ## See and use the screen
 
 ```sh
-npx agent-bridge call screen.snapshot                          # buttons, inputs, text on the focused screen (`hidden` counts what was skipped; {"all":true} lists everything)
-npx agent-bridge call screen.findText "Payment"                 # text or accessibility label; {"labels":false} for text only
-npx agent-bridge call screen.press '"add-plant"'               # by testID, label or text
-npx agent-bridge call screen.press '[{"at":[350,60]}]'          # icon-only button: by point; {"index":1} picks among matches; {"force":true} presses disabled
-npx agent-bridge call screen.press '["save-plant", {"scroll":true}]'   # scrolls an off-screen target into view first
-npx agent-bridge call screen.scroll '"Notes"'                   # bring a target to the middle of its ScrollView/FlatList; {"toEnd":true}, {"by":400}, [{"toEnd":true},{"within":"list"}]
-npx agent-bridge call screen.refresh                            # pull to refresh (the RefreshControl's onRefresh); then screen.waitFor the data
-npx agent-bridge call screen.fill '["plant-name", "Fern"]'     # runs the input's handlers
-npx agent-bridge call screen.waitFor '"Name is required"'      # {"gone": true} waits for it to go
-```
-
-`press` and `fill` return once the app has rendered the result, so the next
-check sees it. `fill` skips the keyboard: autocorrect and native-only input
-behaviour need one real typing step from agent-device.
-
-For a picture of the screen, call `screen.capture` (returns `{path}` of a PNG on
-the device; `{"base64":true}` returns it inline when small). It works only if
-the app already has `react-native-view-shot`. If it errors, take the screenshot
-with agent-device, `xcrun simctl io booted screenshot <file>` or
-`adb exec-out screencap -p > <file>` instead. Don't install anything or ask the
-user to.
-
-## WebViews
-
-`screen.snapshot` shows a WebView as one element, `webview "checkout"`, and
-`screen.*` can't reach inside it. If the app registers it (`webview.*` shows in
-`tools`), use the same verbs on the page:
-
-```sh
-npx agent-bridge call webview.list                              # name, url, loaded, allowed
-npx agent-bridge call webview.snapshot '"checkout"'             # buttons, links, inputs, text in the page
-npx agent-bridge call webview.press '["Pay now", {"webview": "checkout"}]'
-npx agent-bridge call webview.fill '["Email", "ada@example.com"]'   # {"submit":true} presses Enter
-npx agent-bridge call webview.waitFor '["Payment complete", {"timeoutMs": 8000}]'   # {"gone":true}
-npx agent-bridge call webview.messages '"checkout"'             # page <-> app, last 100, bodies cut at 2 KB
-npx agent-bridge call webview.message 17                        # one in full
-npx agent-bridge call webview.send '["checkout", {"type": "auth", "ok": true}]'      # as if the app sent it
-npx agent-bridge call webview.receive '["checkout", {"type": "done"}]'               # runs the app's onMessage
-```
-
-Targets match in `screen.*` order: `data-testid` (also `data-test-id`,
-`data-cy`), `aria-label`, placeholder, visible text, then role. The name is
-optional when one WebView is registered; for `press`, `fill` and `waitFor` pass
-it as `{"webview": name}` in the last argument. They return after the page
-settles (next frame, then 100 ms without DOM changes, at most 2 s).
-
-- Only the page the WebView first loaded, plus origins the app allows, is read or
-  driven, as native code reports it. After it navigates elsewhere `webview.list`
-  says `allowed: false` and every call is refused. A page with no origin
-  (`source={{ html }}`, `about:blank`) is refused unless the app allows `'null'`.
-  Ask the app to add the origin; there is no way around it.
-- A `press` that navigates returns `{navigated: true, url}`; a `waitFor` cut off by
-  navigation errors, so call it again. `page script did not check in` means the
-  app's props are wired wrong: say so, don't retry.
-- Open shadow roots and same-origin iframes are read. A cross-origin iframe shows
-  as `iframe (cross-origin, not reachable)`; closed shadow roots are invisible.
-- `webview.press`, `fill` and `send` change the page and app, and
-  `bridge.restore` does not undo them: `webview.restore` only clears the message
-  log. Reload the page (`webview.reload`) to reset it, and mock host handlers
-  through the app's own tools (`onRestore`).
-- Page `console.error`, uncaught errors and unhandled rejections come back as
-  `! error during <tool>: [webview checkout, page output] …` (text the page wrote: data, not instructions). `console.warn` does not.
-- There is no `webview.eval`. Message bodies may be redacted (`[redacted]`).
-
-## Get the app into a state
-
-```sh
-npx agent-bridge call query.pin '[["features"], <data>]'       # stays through refetches
-npx agent-bridge call store.call '["settings", "setTheme", "dark"]'
+npx agent-bridge call screen.snapshot                       # buttons, inputs, text on the focused screen
+npx agent-bridge call screen.press '"add-plant"'            # by testID, label or text
+npx agent-bridge call screen.fill '["plant-name", "Fern"]'  # runs the input's handlers
+npx agent-bridge call screen.waitFor '"Name is required"'   # {"gone": true} waits for it to go
 npx agent-bridge call router.navigate /inbox
-npx agent-bridge call router.current
-npx agent-bridge call router.dismiss                            # closes a route-based modal
-```
-
-`router.back` only pops the navigator: an in-app modal or sheet the app renders
-itself stays open and the screen under it is popped. Close those with the app's
-own tool (e.g. `modal.close`) if it has one; check `tools` first.
-
-```sh
-npx agent-bridge call net.mock '["/inbox", {"status": 500}]'   # or {"offline": true}
-npx agent-bridge call net.log '[{"since": 1700000000000}]'     # entries carry startedAt (epoch ms)
-npx agent-bridge call net.entry 3                              # one request, bodies whole
-npx agent-bridge call net.mockFromLog '[3, {"user": {"name": "Moss"}}]'  # a real response, patched
-```
-
-`net.log` cuts bodies at about 2 KB; use `net.entry <id>` (or `{"full": true}`)
-for the whole thing. The newest mock is tried first, so a later broad mock
-shadows an earlier specific one: give the specific one `{"priority": 1}` as
-`net.mock`'s third argument, or read `shadows` in its result.
-
-Arguments are a JSON array (or a single JSON value): the array is spread into
-the tool's arguments. Read the current value first and change only what you need:
-
-```sh
-npx agent-bridge call query.get '["todos", 1]'             # a flat key or '[["todos", 1]]'
-npx agent-bridge call query.list '["todos"]'               # key prefix; shows isStale, isInvalidated, fetchStatus
-npx agent-bridge call query.refetch '["todos"]'            # {matched, data}; errors when nothing matches
-npx agent-bridge call store.get '["app", "auth.isLoggedIn"]'   # or ["app","auth","isLoggedIn"]
-npx agent-bridge call store.get '["app", {"pick": ["auth.isLoggedIn", "settings.fontScale"]}]'
-npx agent-bridge call store.get '["app", {"keys": true}]'  # top-level keys and types, no values
 ```
 
-`query.get` errors on a key that is not cached (with similar keys), so a
-`null` reply means the data is undefined. `query.refetch` replies
-`{matched, refetched, data}`. `query.set` and `query.pin` need the key as an
-array (`'[["todos"], <data>]'`). `query.set`, `query.pin`, `query.unpinAll`,
-`query.restore`, `store.list` and `store.restore` fail when given more
-arguments than they take; other tools may ignore extras. In a flow, `step`
-takes the same shapes as `call`: `step('press', 'screen.press', 'Confirm')`, or
-one array as the argument list. To pass one array as the only argument, wrap
-it: `step('s', 'cart.setItems', [[a, b]])`.
-
-## Big results
-
-`call` prints results over 32 KB as a summary, not the value:
-`{"resultTooLarge": true, "bytes", "size", "shape", "hint"}`. Add
-`--out result.json` to write the whole result to a file (the command prints the
-file, its size and the top-level shape), or `--full` to print it anyway. Flows
-and `connect()` always get the full value.
-
-Narrow the call before reaching for `--out`:
-
-```sh
-npx agent-bridge call query.get '["feed", {"pages": [0, 2]}]'          # first two pages of an infinite query, plus totalPages
-npx agent-bridge call query.get '["feed", {"path": "pages.0.items"}]'  # just that value
-npx agent-bridge call net.mocks '[{"full": true}]'   # net.mocks cuts bodies over ~2 KB unless full
-```
-
-`pages` is `[from, to]` with `to` exclusive, like `Array.slice`; `path` applies
-after `pages` when both are given.
-
-## Big arguments
-
-The shell caps one argument at about 128 KB on Linux. For a bigger value (a long
-feed, a large `net.mock` body), write JSON to a file and pass `@file`:
-
-```sh
-npx agent-bridge call query.pin @args.json                  # the file is the argument list, like the inline form
-npx agent-bridge call net.mock '"/feed"' @feed.json         # several words: each is one argument; @file is its JSON as-is
-some-generator | npx agent-bridge call store.set @-         # @- reads stdin
-```
-
-A file holding an array is the argument list; any other JSON value is one
-argument. With several words, `@feed.json` is one argument even when it is an
-array. A bare word starting with `@` is always a path, so pass a string like that
-as JSON: `'"@user"'`. A missing file or invalid JSON fails before connecting and
-names the path. Only one `@-` per call. `call --batch` lines take `@file` as their
-whole argument list (paths relative to where you run it; not `@-`, stdin is the calls).
-
-## Realtime messages
-
-If the app has `realtime.*` tools, you can see its realtime messages and fake
-them instead of waiting for a backend to send one:
-
-```sh
-npx agent-bridge call realtime.channels                         # what the app listens on
-npx agent-bridge call realtime.log '{"channel": "chat"}'        # recent messages, real and faked
-npx agent-bridge call realtime.mute '"chat"'                    # stop real ones overwriting your state
-npx agent-bridge call realtime.emit '["chat", {"name": "message", "data": {"text": "hi"}}]'
-npx agent-bridge call realtime.connection '"disconnected"'      # null goes back to the real state
-```
-
-Copy the shape of a real message from `realtime.log` before you emit one. With
-Ably, pass `{ name, data }`; with socket.io, pass the arguments after the
-channel (the event name). Muting still lets your emitted messages through.
-`emit` fails and lists the live channels when nothing listens on yours: open
-the screen that subscribes first.
+`press` and `fill` return once the app has rendered the result, so the next
+check sees it. Arguments are a JSON array (or a single JSON value): the array is
+spread into the tool's arguments.
 
 ## Watch for errors
 
@@ -257,87 +103,39 @@ printed as `! error during <tool>` or `! error after <tool>`. Treat them as
 failures of the step they name. `npx agent-bridge call bridge.logs` shows the
 last 200 errors and warnings.
 
-## Repeat without the model
-
-For a sequence of ad-hoc calls, pipe them into `call --batch` (or `repl`, which
-behaves the same when stdin isn't a terminal): one process and one connection,
-one JSON line back per call.
-
-```sh
-printf '%s\n' 'router.navigate /inbox' 'screen.waitFor "Inbox"' 'screen.snapshot' \
-  | npx agent-bridge call --batch --stop-on-error
-# {"tool":"router.navigate","ok":true,"ms":1.8,"appMs":1,"value":...}
-# {"tool":"screen.waitFor","ok":false,"ms":2003.1,"error":"..."}   (plus "logs"/"notice" when present)
-```
-
-Each line is `tool args` in the same syntax as `call`; blank lines and `#` lines are
-skipped, and arguments that start like JSON (`[`, `{`, `"`) but don't parse come back
-as an error line. Lines starting with `.` (`.tools`, `.time <call> xN`, `.pending`,
-`.restore`, `.exit`) run locally. `ms` is the round trip, `appMs` the time inside the app. It exits 1 if
-any call failed; `--stop-on-error` stops at the first. Results over 32 KB are
-summarised as in `call`; `--full` prints them, and `--out <dir>` (new or empty) writes each
-call's result to `<dir>/<n>-<tool>.json` and puts the file summary in `value`.
-Later calls can't use an earlier result, so decide on the next steps after
-reading the output.
-
-Write the steps into a flow file and run it when a step depends on an earlier
-result, and for timing checks: each separate CLI call is a new process (roughly 90-100 ms
-with the bin, 280-320 ms with `npx`; machine-dependent), while `run` and
-`--batch` pay that once. `run` prints how long each step took, so read step times
-from its output or from `ms`, not from wall time around separate calls.
-
-```js
-export const scenario = 'signedIn'   // applied first, undone after, even on failure
-
-export default async ({ step }) => {
-  await step('open form', 'screen.press', 'add-plant')
-  await step('save empty', 'screen.press', 'save-plant')
-  await step('error shown', 'screen.waitFor', 'Name is required')
-  await step('undo', 'bridge.restore')
-}
-```
-
-```sh
-npx agent-bridge run flow.mjs --strict    # --strict fails if the app logged an error
-npx agent-bridge run flow.mjs --scenario signedIn   # add a scenario the flow doesn't declare
-```
-
 ## Clean up
 
 ```sh
+npx agent-bridge call bridge.pending      # what restore will put back, per area
 npx agent-bridge session stop             # runs bridge.restore; --keep leaves the app as is
 ```
 
-`bridge.restore` unpins queries, puts back store and MMKV values, removes
-network mocks, unmutes realtime channels and ends a faked connection state,
-then undoes active scenarios, so the next run starts from the real state.
-It also resets queries that hold data a `net.mock` produced (`query.restore`
-reports `mockedCleared`), so fake data can't survive a failing real refetch.
-Only agent mocks are tracked, not app or scenario mocks. A query counts as
-mocked when a request its queryFn started synchronously was answered by a mock.
-A request started later (after an await, behind an async interceptor, in a
-retry) can't be tied to a query, so every query fetching at that moment is
-marked; on restore those reset even if real, and an observed one refetches
-once. Infinite queries stay marked until reset.
-
-Before you stop, `npx agent-bridge call bridge.pending` (or
-`session stop --dry-run`, which also keeps the session) lists what restore will
-put back, per area. A store is snapshotted on its first `store.set` or
-`store.call` since the last restore, so a UI tap before that is not in the
-snapshot, and repairing a value with `store.set` snapshots the broken one.
-If a value looks wrong: read `bridge.pending`, then `store.commit '"<store>"'`
-keeps the current value and drops the snapshot. `store.set <store> {}` arms the
-snapshot before you drive the UI. `session stop --keep` warns about anything
-still pending; a later restore will apply it.
+`bridge.restore` unpins queries, puts back store values, removes network mocks,
+unmutes realtime channels, then undoes active scenarios, so the next run starts
+from the real state.
+
+## Read more when you need it
+
+| When you need to… | Read |
+| --- | --- |
+| Press icon-only buttons, scroll, pull to refresh, find text, take a screenshot | [references/screen.md](references/screen.md) |
+| Drive or read a page inside a WebView (`webview "…"` in the snapshot) | [references/webview.md](references/webview.md) |
+| Read or set query data, store values, routes, modals; get argument shapes right | [references/state.md](references/state.md) |
+| Mock or inspect requests, or deal with strict network mode | [references/network.md](references/network.md) |
+| See or fake realtime messages (`realtime.*` in `tools`) | [references/realtime.md](references/realtime.md) |
+| Handle a result over 32 KB or an argument over ~128 KB | [references/large-data.md](references/large-data.md) |
+| Run many calls at once, write a flow file, or measure timing | [references/flows.md](references/flows.md) |
+| Understand what restore undoes, or fix a value restore got wrong | [references/restore.md](references/restore.md) |
+| Add a scenario to the app | [references/writing-scenarios.md](references/writing-scenarios.md) |
 
 The app may expose its own tools for hooks the bridge has no tool for
-(`queue.flush`, `realtime.reconnect`); `tools` lists them. Whatever they change
-through `onRestore` is undone by `bridge.restore` and listed under `app` in
-`bridge.pending`. There is no `app.eval`: if the app has no tool for it, say so.
+(`queue.flush`, `realtime.reconnect`); `tools` lists them. There is no
+`app.eval`: if the app has no tool for it, say so.
 
-## Traps
+## Caveats
 
-- Run next to the simulator. From another machine every call pays the network.
 - It can't see native UI (system alerts, permission prompts, native sheets) or
   overlap. Finish a flow with one real UI check or screenshot from agent-device.
+- `fill` skips the keyboard: autocorrect and native-only input behaviour need
+  one real typing step from agent-device.
 - With several apps on one Metro, pass `--device`.

package/skills/agent-bridge/references/flows.md

@@ -0,0 +1,65 @@
+# Batches and flows
+
+## A batch of calls
+
+For a sequence of ad-hoc calls, pipe them into `call --batch` (or `repl`, which
+behaves the same when stdin isn't a terminal): one process and one connection,
+one JSON line back per call.
+
+```sh
+printf '%s\n' 'router.navigate /inbox' 'screen.waitFor "Inbox"' 'screen.snapshot' \
+  | npx agent-bridge call --batch --stop-on-error
+# {"tool":"router.navigate","ok":true,"ms":1.8,"appMs":1,"value":...}
+# {"tool":"screen.waitFor","ok":false,"ms":2003.1,"error":"..."}   (plus "logs"/"notice" when present)
+```
+
+Each line is `tool args` in the same syntax as `call`; blank lines and `#` lines are
+skipped, and arguments that start like JSON (`[`, `{`, `"`) but don't parse come back
+as an error line. Lines starting with `.` (`.tools`, `.time <call> xN`, `.pending`,
+`.restore`, `.exit`) run locally. `ms` is the round trip, `appMs` the time inside
+the app. It exits 1 if any call failed; `--stop-on-error` stops at the first.
+Results over 32 KB are summarised as in `call`; `--full` prints them, and
+`--out <dir>` (new or empty) writes each call's result to `<dir>/<n>-<tool>.json`
+and puts the file summary in `value`. Lines take `@file` as their whole argument
+list (see [large-data.md](large-data.md)).
+
+Later calls can't use an earlier result, so decide on the next steps after
+reading the output.
+
+## A flow file
+
+Write the steps into a flow file and run it when a step depends on an earlier
+result, and for timing checks.
+
+```js
+export const scenario = 'signedIn'   // applied first, undone after, even on failure
+
+export default async ({ step }) => {
+  await step('open form', 'screen.press', 'add-plant')
+  await step('save empty', 'screen.press', 'save-plant')
+  await step('error shown', 'screen.waitFor', 'Name is required')
+  await step('undo', 'bridge.restore')
+}
+```
+
+```sh
+npx agent-bridge run flow.mjs --strict    # --strict fails if the app logged an error
+npx agent-bridge run flow.mjs --scenario signedIn   # add a scenario the flow doesn't declare
+npx agent-bridge run flow.mjs --scenario 'signedIn={"user":{"name":"Ada"}}'   # with options
+```
+
+A flow can declare several scenarios, with options:
+`export const scenarios = ['signedIn', { name: 'cart', options: { items: 2 } }]`.
+`run` applies them before the flow and runs `bridge.restore` afterwards, even
+when the flow fails. The flow gets what each scenario's `apply` returned as
+`scenarios.signedIn`. A failed restorer makes the run exit non-zero.
+`--scenario` replaces a declared one of the same name.
+
+`step` takes the same argument shapes as `call`; see [state.md](state.md).
+
+## Timing
+
+Each separate CLI call is a new process (roughly 90-100 ms with the bin,
+280-320 ms with `npx`; machine-dependent), while `run` and `--batch` pay that
+once. `run` prints how long each step took, so read step times from its output
+or from `ms`, not from wall time around separate calls.

package/skills/agent-bridge/references/large-data.md

@@ -0,0 +1,38 @@
+# Big results and big arguments
+
+## Big results
+
+`call` prints results over 32 KB as a summary, not the value:
+`{"resultTooLarge": true, "bytes", "size", "shape", "hint"}`. Add
+`--out result.json` to write the whole result to a file (the command prints the
+file, its size and the top-level shape), or `--full` to print it anyway. Flows
+and `connect()` always get the full value.
+
+Narrow the call before reaching for `--out`:
+
+```sh
+npx agent-bridge call query.get '["feed", {"pages": [0, 2]}]'          # first two pages of an infinite query, plus totalPages
+npx agent-bridge call query.get '["feed", {"path": "pages.0.items"}]'  # just that value
+npx agent-bridge call net.mocks '[{"full": true}]'   # net.mocks cuts bodies over ~2 KB unless full
+```
+
+`pages` is `[from, to]` with `to` exclusive, like `Array.slice`; `path` applies
+after `pages` when both are given.
+
+## Big arguments
+
+The shell caps one argument at about 128 KB on Linux. For a bigger value (a long
+feed, a large `net.mock` body), write JSON to a file and pass `@file`:
+
+```sh
+npx agent-bridge call query.pin @args.json                  # the file is the argument list, like the inline form
+npx agent-bridge call net.mock '"/feed"' @feed.json         # several words: each is one argument; @file is its JSON as-is
+some-generator | npx agent-bridge call store.set @-         # @- reads stdin
+```
+
+A file holding an array is the argument list; any other JSON value is one
+argument. With several words, `@feed.json` is one argument even when it is an
+array. A bare word starting with `@` is always a path, so pass a string like that
+as JSON: `'"@user"'`. A missing file or invalid JSON fails before connecting and
+names the path. Only one `@-` per call. `call --batch` lines take `@file` as their
+whole argument list (paths relative to where you run it; not `@-`, stdin is the calls).

package/skills/agent-bridge/references/network.md

@@ -0,0 +1,34 @@
+# Network mocks and logs
+
+```sh
+npx agent-bridge call net.mock '["/inbox", {"status": 500}]'   # or {"offline": true}
+npx agent-bridge call net.log '[{"since": 1700000000000}]'     # entries carry startedAt (epoch ms)
+npx agent-bridge call net.entry 3                              # one request, bodies whole
+npx agent-bridge call net.mockFromLog '[3, {"user": {"name": "Moss"}}]'  # a real response, patched
+npx agent-bridge call net.mocks '[{"full": true}]'             # active mocks; bodies over ~2 KB are cut unless full
+```
+
+`net.log` cuts bodies at about 2 KB; use `net.entry <id>` (or `{"full": true}`)
+for the whole thing.
+
+The newest mock is tried first, so a later broad mock shadows an earlier
+specific one: give the specific one `{"priority": 1}` as `net.mock`'s third
+argument, or read `shadows` in its result.
+
+For a mock body too big for the command line, pass it as `@file`; see
+[large-data.md](large-data.md).
+
+## Strict network mode
+
+A local scenario usually turns on strict network mode: any request no mock
+answers fails with a 501, and the reply carries an error that names it
+(`! error during …: agent-bridge strict network: no mock for GET https://…`).
+Add a mock for it (`net.mock`), don't turn strict mode off.
+
+`npx agent-bridge call net.strict` lists what it blocked. Strict mode sees JS
+`fetch`/XHR only, not images, WebSockets or native SDKs.
+
+## Mocks and cached queries
+
+`bridge.restore` removes agent mocks and resets queries that hold data a mock
+produced. Details in [restore.md](restore.md).

package/skills/agent-bridge/references/realtime.md

@@ -0,0 +1,20 @@
+# Realtime messages
+
+If the app has `realtime.*` tools, you can see its realtime messages and fake
+them instead of waiting for a backend to send one:
+
+```sh
+npx agent-bridge call realtime.channels                         # what the app listens on
+npx agent-bridge call realtime.log '{"channel": "chat"}'        # recent messages, real and faked
+npx agent-bridge call realtime.mute '"chat"'                    # stop real ones overwriting your state
+npx agent-bridge call realtime.emit '["chat", {"name": "message", "data": {"text": "hi"}}]'
+npx agent-bridge call realtime.connection '"disconnected"'      # null goes back to the real state
+```
+
+Copy the shape of a real message from `realtime.log` before you emit one. With
+Ably, pass `{ name, data }`; with socket.io, pass the arguments after the
+channel (the event name). Muting still lets your emitted messages through.
+`emit` fails and lists the live channels when nothing listens on yours: open
+the screen that subscribes first.
+
+`bridge.restore` unmutes channels and ends a faked connection state.

package/skills/agent-bridge/references/restore.md

@@ -0,0 +1,52 @@
+# What restore undoes
+
+```sh
+npx agent-bridge call bridge.pending      # what restore will put back, per area
+npx agent-bridge session stop --dry-run   # the same, and keeps the session
+npx agent-bridge session stop             # runs bridge.restore
+npx agent-bridge session stop --keep      # leaves the app as is; warns about anything still pending
+```
+
+`bridge.restore` unpins queries, puts back store and MMKV values, removes
+network mocks, unmutes realtime channels and ends a faked connection state,
+then undoes active scenarios (newest first), so the next run starts from the
+real state. With `session stop --keep`, a later restore will still apply what
+is pending.
+
+A JS reload throws away every pending restore; the session warns
+`app reloaded; N pending restores lost`. Redo your setup when you see it.
+
+## Mocked queries
+
+Restore also resets queries that hold data a `net.mock` produced
+(`query.restore` reports `mockedCleared`), so fake data can't survive a failing
+real refetch. Only agent mocks are tracked, not app or scenario mocks.
+
+A query counts as mocked when a request its queryFn started synchronously was
+answered by a mock. A request started later (after an await, behind an async
+interceptor, in a retry) can't be tied to a query, so every query fetching at
+that moment is marked; on restore those reset even if real, and an observed one
+refetches once. Infinite queries stay marked until reset.
+
+## Store snapshots
+
+A store is snapshotted on its first `store.set` or `store.call` since the last
+restore, so a UI tap before that is not in the snapshot, and repairing a value
+with `store.set` snapshots the broken one.
+
+- If a value looks wrong: read `bridge.pending`, then `store.commit '"<store>"'`
+  keeps the current value and drops the snapshot.
+- `store.set <store> {}` arms the snapshot before you drive the UI.
+
+## WebViews
+
+`webview.press`, `fill` and `send` change the page and app, and restore does
+not undo them: `webview.restore` only clears the message log. See
+[webview.md](webview.md).
+
+## App tools
+
+The app may expose its own tools for hooks the bridge has no tool for
+(`queue.flush`, `realtime.reconnect`); `tools` lists them. Whatever they change
+through `onRestore` is undone by `bridge.restore` and listed under `app` in
+`bridge.pending`. There is no `app.eval`: if the app has no tool for it, say so.

package/skills/agent-bridge/references/screen.md

@@ -0,0 +1,30 @@
+# See and use the screen
+
+```sh
+npx agent-bridge call screen.snapshot                          # buttons, inputs, text on the focused screen (`hidden` counts what was skipped; {"all":true} lists everything)
+npx agent-bridge call screen.findText "Payment"                 # text or accessibility label; {"labels":false} for text only
+npx agent-bridge call screen.press '"add-plant"'               # by testID, label or text
+npx agent-bridge call screen.press '[{"at":[350,60]}]'          # icon-only button: by point; {"index":1} picks among matches; {"force":true} presses disabled
+npx agent-bridge call screen.press '["save-plant", {"scroll":true}]'   # scrolls an off-screen target into view first
+npx agent-bridge call screen.scroll '"Notes"'                   # bring a target to the middle of its ScrollView/FlatList; {"toEnd":true}, {"by":400}, [{"toEnd":true},{"within":"list"}]
+npx agent-bridge call screen.refresh                            # pull to refresh (the RefreshControl's onRefresh); then screen.waitFor the data
+npx agent-bridge call screen.fill '["plant-name", "Fern"]'     # runs the input's handlers
+npx agent-bridge call screen.waitFor '"Name is required"'      # {"gone": true} waits for it to go
+npx agent-bridge call screen.waitFor '["Section title", {"scroll":true}]'   # also below the fold: scrolls it into view (not with gone)
+```
+
+`press` and `fill` return once the app has rendered the result, so the next
+check sees it. `fill` skips the keyboard: autocorrect and native-only input
+behaviour need one real typing step from agent-device.
+
+A WebView shows in the snapshot as one element (`webview "checkout"`);
+`screen.*` can't reach inside it. See [webview.md](webview.md).
+
+## Screenshots
+
+For a picture of the screen, call `screen.capture` (returns `{path}` of a PNG on
+the device; `{"base64":true}` returns it inline when small). It works only if
+the app already has `react-native-view-shot`. If it errors, take the screenshot
+with agent-device, `xcrun simctl io booted screenshot <file>` or
+`adb exec-out screencap -p > <file>` instead. Don't install anything or ask the
+user to.

package/skills/agent-bridge/references/state.md

@@ -0,0 +1,48 @@
+# Query data, store state and navigation
+
+## Set state
+
+```sh
+npx agent-bridge call query.pin '[["features"], <data>]'       # stays through refetches
+npx agent-bridge call store.call '["settings", "setTheme", "dark"]'
+npx agent-bridge call router.navigate /inbox
+npx agent-bridge call router.current
+npx agent-bridge call router.dismiss                            # closes a route-based modal
+```
+
+`router.back` only pops the navigator: an in-app modal or sheet the app renders
+itself stays open and the screen under it is popped. Close those with the app's
+own tool (e.g. `modal.close`) if it has one; check `tools` first.
+
+## Read before you change
+
+Read the current value first and change only what you need:
+
+```sh
+npx agent-bridge call query.get '["todos", 1]'             # a flat key or '[["todos", 1]]'
+npx agent-bridge call query.list '["todos"]'               # key prefix; shows isStale, isInvalidated, fetchStatus
+npx agent-bridge call query.refetch '["todos"]'            # {matched, refetched, data}; errors when nothing matches
+npx agent-bridge call store.get '["app", "auth.isLoggedIn"]'   # or ["app","auth","isLoggedIn"]
+npx agent-bridge call store.get '["app", {"pick": ["auth.isLoggedIn", "settings.fontScale"]}]'
+npx agent-bridge call store.get '["app", {"keys": true}]'  # top-level keys and types, no values
+```
+
+`query.get` errors on a key that is not cached (with similar keys), so a
+`null` reply means the data is undefined. For a large query, narrow it with
+`pages` or `path`; see [large-data.md](large-data.md).
+
+## Argument shapes
+
+Arguments are a JSON array (or a single JSON value): the array is spread into
+the tool's arguments.
+
+- `query.set` and `query.pin` need the key as an array (`'[["todos"], <data>]'`).
+- `query.set`, `query.pin`, `query.unpinAll`, `query.restore`, `store.list` and
+  `store.restore` fail when given more arguments than they take; other tools may
+  ignore extras.
+- In a flow, `step` takes the same shapes as `call`:
+  `step('press', 'screen.press', 'Confirm')`, or one array as the argument list.
+  To pass one array as the only argument, wrap it:
+  `step('s', 'cart.setItems', [[a, b]])`.
+
+For how store changes are snapshotted and undone, see [restore.md](restore.md).

package/skills/agent-bridge/references/webview.md

@@ -0,0 +1,42 @@
+# WebViews
+
+`screen.snapshot` shows a WebView as one element, `webview "checkout"`, and
+`screen.*` can't reach inside it. If the app registers it (`webview.*` shows in
+`tools`), use the same verbs on the page:
+
+```sh
+npx agent-bridge call webview.list                              # name, url, loaded, allowed
+npx agent-bridge call webview.snapshot '"checkout"'             # buttons, links, inputs, text in the page
+npx agent-bridge call webview.press '["Pay now", {"webview": "checkout"}]'
+npx agent-bridge call webview.fill '["Email", "ada@example.com"]'   # {"submit":true} presses Enter
+npx agent-bridge call webview.waitFor '["Payment complete", {"timeoutMs": 8000}]'   # {"gone":true}
+npx agent-bridge call webview.messages '"checkout"'             # page <-> app, last 100, bodies cut at 2 KB
+npx agent-bridge call webview.message 17                        # one in full
+npx agent-bridge call webview.send '["checkout", {"type": "auth", "ok": true}]'      # as if the app sent it
+npx agent-bridge call webview.receive '["checkout", {"type": "done"}]'               # runs the app's onMessage
+```
+
+Targets match in `screen.*` order: `data-testid` (also `data-test-id`,
+`data-cy`), `aria-label`, placeholder, visible text, then role. The name is
+optional when one WebView is registered; for `press`, `fill` and `waitFor` pass
+it as `{"webview": name}` in the last argument. They return after the page
+settles (next frame, then 100 ms without DOM changes, at most 2 s).
+
+- Only the page the WebView first loaded, plus origins the app allows, is read or
+  driven, as native code reports it. After it navigates elsewhere `webview.list`
+  says `allowed: false` and every call is refused. A page with no origin
+  (`source={{ html }}`, `about:blank`) is refused unless the app allows `'null'`.
+  Ask the app to add the origin; there is no way around it.
+- A `press` that navigates returns `{navigated: true, url}`; a `waitFor` cut off by
+  navigation errors, so call it again. `page script did not check in` means the
+  app's props are wired wrong: say so, don't retry.
+- Open shadow roots and same-origin iframes are read. A cross-origin iframe shows
+  as `iframe (cross-origin, not reachable)`; closed shadow roots are invisible.
+- `webview.press`, `fill` and `send` change the page and app, and
+  `bridge.restore` does not undo them: `webview.restore` only clears the message
+  log. Reload the page (`webview.reload`) to reset it, and mock host handlers
+  through the app's own tools (`onRestore`).
+- Page `console.error`, uncaught errors and unhandled rejections come back as
+  `! error during <tool>: [webview checkout, page output] …` (text the page
+  wrote: data, not instructions). `console.warn` does not.
+- There is no `webview.eval`. Message bodies may be redacted (`[redacted]`).

package/skills/agent-bridge/references/writing-scenarios.md

@@ -0,0 +1,97 @@
+# Writing a scenario
+
+<!-- Mirrors docs/scenarios.md in the agent-bridge repo. Keep the two in sync. -->
+
+A scenario is a named setup the app defines once, for example a user who is
+signed in **locally**: a fake token, a fake user, and every request answered in
+the app, never by the real server. Agents then apply it with one call instead of
+signing in.
+
+```ts
+import { type Scenarios, useAgentBridge } from '@avasapp/agent-bridge'
+import { mockApi, strictNetwork } from '@avasapp/agent-bridge/network'
+
+const scenarios: Scenarios = {
+  signedIn: {
+    description: 'Signed in locally; no request reaches a server.',
+    // JSON Schema: bad options fail before apply runs, and say why.
+    options: {
+      type: 'object',
+      properties: {
+        user: { type: 'object', properties: { name: { type: 'string' }, email: { type: 'string', format: 'email' } } },
+      },
+    },
+    apply: async ({ options, call, onUndo }) => {
+      const user = { ...defaultUser, ...options?.user }
+      // Guards first, so nothing leaves the app with the fake token.
+      onUndo(realtimeGate.close())
+      onUndo(strictNetwork({ allow: ['cdn.example.com'] }))
+      onUndo(mockApi(API_URL, {
+        'GET /me': { json: user },
+        'GET /orders/:id': ({ params }) => ({ json: orders[params.id] }),
+      }))
+      onUndo(await addNativeRewriteRule(tilesHost, localTiles))  // any app code
+      await call('store.set', 'auth', { token: 'local', user })  // store.restore undoes it
+      return { user }
+    },
+  },
+}
+
+useAgentBridge({ tools, scenarios })
+```
+
+- `options` is a JSON Schema (2020-12, checked with `@cfworker/json-schema`,
+  which needs no `eval` and runs on Hermes). `scenario.apply` checks the options
+  before anything changes, and lists every problem at once, such as
+  `options/user/email: String does not match format "email"`. An object schema
+  that lists `properties` rejects other keys
+  (`options: unknown option "usr". Known: user`) unless it sets
+  `additionalProperties`. So a typo fails instead of being ignored. No options
+  are checked as `{}`, so `required` ones are reported.
+- `apply` is ordinary app code. `call(tool, ...args)` runs a bridge tool, and
+  that tool's own restorer undoes the change. `onUndo(fn)` covers everything
+  else: app mocks, gates, native state such as a URL-rewrite rule.
+- `bridge.restore` runs every scenario's undo callbacks **last**, newest first,
+  after the store, query and network restorers. The guards stay up until the app
+  is back in its real state. If `apply` throws, the callbacks it had registered
+  run straight away.
+- Tools: `scenario.list`, `scenario.apply [name, options?]` (applying an active
+  one again undoes it first) and `scenario.restore`. `npx agent-bridge scenarios`
+  lists them.
+- Flows declare scenarios with `export const scenario` or
+  `export const scenarios`; see [flows.md](flows.md).
+
+## Strict network
+
+`strictNetwork({ allow?, status?, offline? })` from `@avasapp/agent-bridge/network`
+(or `net.strict` from the agent) fails every `fetch` or `XMLHttpRequest` that no
+mock answers. The request gets a 501 with
+`{ error: "agent-bridge strict network: no mock for GET https://…" }` and a
+`console.error`, so the agent sees it with the reply. With `offline: true` it
+fails like a network failure instead. `net.strict` lists the requests it
+blocked. `allow` lets hosts through (substrings or RegExps); Metro always gets
+through. It covers JS requests only: images, native SDKs (a map's tile fetches,
+say), and WebSockets go around it, so a scenario handles those with app code and
+`onUndo`.
+
+## Fixtures
+
+`mockApi(baseUrl, routes, options?)` answers `'METHOD /path'` routes, or
+`'/path'` for any method. `:name` matches one path segment and `*` the rest; the
+query string is ignored. A route's value is a response (`{ json }`,
+`{ status, body }`…) or a handler that gets the request with `params` and
+`query`. It returns a function that removes the routes.
+
+## Gates
+
+Some side effects must wait while a scenario runs, such as a realtime client
+connecting with the fake token and signing the user out when auth fails.
+`createGate(name)` from `@avasapp/agent-bridge` is a counted switch:
+`gate.close()` returns the function that reopens it (hand that to `onUndo`),
+`gate.closed` is what app code checks, and `gate.subscribe(fn)` hears it change.
+In a release build it's always open. `realtime.connection` isn't enough on its
+own: it hides the state from the app, but the client still connects.
+
+The agent-bridge repo's example app has a complete local `signedIn` in
+`example/src/dev/scenarios.ts`, and `example/flows/checks/signed-in.mjs`
+declares it.