docs(site): dedicated React Native DevTools coexistence guide (#269)

New guides/devtools-coexistence page written for the reported symptoms
("second DevTools window" eviction + __RN_NET__ console spam), linked
from a new Guides sidebar group and a troubleshooting tip; the
maestro-interop section becomes a pointer. Tool docs regenerated
(catches up cdp_status/cdp_wait_for_network/cdp_network_body from
PR #267 plus stale device_fill/maestro_run descriptions).

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: Lykhoyda

docs-site/astro.config.mjs

@@ -132,6 +132,13 @@ export default defineConfig({
             },
           ],
         },
+        {
+          label: 'Guides',
+          items: [
+            { label: 'React Native DevTools coexistence', slug: 'guides/devtools-coexistence' },
+            { label: 'maestro-mcp interop', slug: 'guides/maestro-interop' },
+          ],
+        },
         { label: 'Benchmarks', slug: 'benchmarks' },
         { label: 'Troubleshooting', slug: 'troubleshooting' },
         { label: 'Changelog', slug: 'changelog' },

docs-site/src/content/docs/guides/devtools-coexistence.mdx

@@ -0,0 +1,61 @@
+---
+title: Using rn-dev-agent with React Native DevTools
+description: Stop the CDP bridge from kicking React Native DevTools off the debugger seat, and what happened to the __RN_NET__ console spam.
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+You open React Native DevTools and it immediately disconnects with **"Disconnected due to opening a second DevTools window"**. Or your Metro logs are full of `__RN_NET__:request:{...}` lines. Both come from the rn-dev-agent CDP bridge — and both are fixed. This page explains what's happening and how to configure it.
+
+## Why DevTools gets kicked
+
+React Native allows **exactly one debugger frontend** per app (on RN versions before dev-middleware learned to multiplex frontends). The rn-dev-agent bridge and the visual React Native DevTools window connect to the *same* `/inspector/debug` slot, so they evict each other — whoever connects last wins.
+
+By default the bridge is **agent-first**: after any disconnect it auto-reconnects in the background (instant first retry, then a 5-second poll). So the moment you open DevTools, the bridge re-grabs the seat and your DevTools window gets kicked. You never had a chance.
+
+## The fix: turn off background auto-reconnect
+
+Two equivalent opt-out surfaces — the environment variable wins if both are set:
+
+**Environment variable** (set where the MCP server starts, e.g. in your shell profile or the Claude Code MCP env):
+
+```bash
+RN_CDP_AUTOCONNECT=0   # also accepts 'false'; '1'/'true' force the default back on
+```
+
+**Project config file** — `.rn-agent/config.json` in your React Native project root:
+
+```json
+{ "cdp": { "autoConnect": false } }
+```
+
+With either set, the bridge runs in **passive mode**: after a disconnect it stays down instead of re-grabbing the seat. Open React Native DevTools and it keeps the connection — Console, Network, Components, Profiler all work.
+
+## What passive mode does and doesn't change
+
+- **Disabled:** all *background* reconnection — the close-triggered reconnect loop and the 5-second background poll. The bridge never takes the seat behind your back.
+- **Unchanged:** on-demand connection. When the agent actually runs a CDP tool (`cdp_status`, `cdp_component_tree`, …), the bridge connects for that work — which **does** evict your DevTools window at that moment. That's deliberate: a tool call is a visible, foreground action. Once you reopen DevTools afterwards, the bridge yields again.
+- **Unchanged:** `device_*` tools (taps, screenshots, fills). They don't touch the debugger connection at all — use them freely while DevTools is open.
+
+<Aside type="tip" title="Rule of thumb">
+Passive mode means: *the bridge holds the debugger seat only while the agent is actively working.* If you want uninterrupted DevTools time, just don't run `cdp_*` tools meanwhile.
+</Aside>
+
+You can always see the resolved mode in `cdp_status` → top-level `autoConnect` field (`{ enabled, source: 'env' | 'config' | 'default' }`), and `/rn-dev-agent:doctor` reports it as the **CDP auto-reconnect** row (YELLOW when off — informational, not an error).
+
+**Known limitation:** a DevTools-sharing proxy started with `cdp_open_devtools` is not auto-resumed after a disconnect in passive mode — re-run `cdp_open_devtools` if you use that flow.
+
+## The `__RN_NET__` console spam is gone
+
+Unrelated knob, same release: on React Native < 0.83 the bridge falls back to in-app `fetch`/XHR wrappers for network capture, and these used to transport every request/response as a `console.log('__RN_NET__:…')` line — invisible to the bridge (it filters them) but spamming Metro logs and your DevTools console.
+
+That transport is replaced: entries now go to an in-app ring buffer (`globalThis.__RN_AGENT_NET_BUF__`, capped at 100) that the network tools drain on demand. **No configuration needed** — update the plugin and the console noise disappears while `cdp_network_log` keeps working.
+
+## Quick reference
+
+| I want… | Do this |
+|---|---|
+| DevTools to stay connected while the agent is idle | `RN_CDP_AUTOCONNECT=0` or `.rn-agent/config.json` → `{ "cdp": { "autoConnect": false } }` |
+| The agent-first default back | Remove the override, or `RN_CDP_AUTOCONNECT=1` |
+| To check which mode is active | `cdp_status` → `autoConnect`, or `/rn-dev-agent:doctor` |
+| No `__RN_NET__` lines in my console | Nothing — fixed automatically as of this release |

docs-site/src/content/docs/guides/maestro-interop.mdx

@@ -32,25 +32,4 @@ A natural question: since maestro drives the device fine via WebDriverAgent, can
 
 ## Using rn-dev-agent with React Native DevTools
 
-React Native (Hermes) allows **exactly one debugger frontend** per app at a time. By default, rn-dev-agent is agent-first: its CDP bridge auto-reconnects in the background after each disconnect, which means opening the visual React Native DevTools window will kick the bridge out — and the bridge will immediately reclaim the seat.
-
-**To let React Native DevTools hold the debugger seat**, disable background auto-reconnect with one of two opt-out surfaces:
-
-- **Environment variable** (takes precedence over everything):
-  ```bash
-  RN_CDP_AUTOCONNECT=0 # also accepts 'false'; '1'/'true' force it back on
-  ```
-- **Project config file** (`.rn-agent/config.json` in your project root, env wins):
-  ```json
-  { "cdp": { "autoConnect": false } }
-  ```
-
-In passive mode the bridge **yields the seat** and reconnects only when a CDP tool actually runs (e.g. `cdp_status`, `cdp_component_tree`). Once you reopen React Native DevTools after a tool call, the bridge yields again automatically.
-
-**Known limitation:** in passive mode, a previously-opened DevTools-sharing proxy (`cdp_open_devtools`) is not auto-resumed after a disconnect — re-run `cdp_open_devtools` if you use it.
-
-**Important caveat:** *any* CDP tool call — including `cdp_status` — reclaims the seat while it runs. Passive mode stops only *background* re-grabs (the close-triggered reconnect loop and the background poll). If you need uninterrupted DevTools access, avoid running CDP tools while the window is open.
-
-The resolved auto-connect mode is always visible in `cdp_status` → top-level `autoConnect` field: `{ enabled: true|false, source: 'default'|'env'|'config' }`. The `/rn-dev-agent:doctor` command also reports it as the **CDP auto-reconnect** row (YELLOW when OFF — informational, not an error).
-
-**Hook-mode network capture note:** on React Native < 0.83 (or when `RN_FORCE_NETWORK_HOOK=1` is set), network entries are captured by in-app `fetch`/XHR wrappers. As of this release that capture **no longer writes `__RN_NET__:…` lines to the console** — entries go directly to an in-app ring buffer (`globalThis.__RN_AGENT_NET_BUF__`, capped at 100) that the network tools drain on demand. Metro logs and your React Native DevTools console will no longer contain hook-mode network noise. No user action is required; the change is transparent.
+The same coexistence question exists for the **visual React Native DevTools window**, which competes with the bridge for the single debugger seat. That has its own opt-out (`RN_CDP_AUTOCONNECT=0` / `.rn-agent/config.json`) and is covered in a dedicated guide: [Using rn-dev-agent with React Native DevTools](/rn-dev-agent/guides/devtools-coexistence/).

docs-site/src/content/docs/tools/cdp/cdp_network_body.mdx

@@ -3,7 +3,7 @@ title: "cdp_network_body"
 description: "Get the actual response body for a network request by its requestId"
 ---
 
-Get the actual response body for a network request by its requestId. Use cdp_network_log first to find request IDs. Only works in CDP network mode (RN 0.83+). Bodies are fetched on-demand, not cached. Pass `device` to look up requestId in a specific device buffer; defaults to the active device.
+Get the actual response body for a network request by its requestId. Use cdp_network_log first to find request IDs. In CDP mode (RN 0.83+) bodies are fetched on-demand; on RN < 0.83 hook mode a small recent-response cache is used. Pass `device` to look up requestId in a specific device buffer; defaults to the active device.
 
 ## Parameters
 

docs-site/src/content/docs/tools/cdp/cdp_status.mdx

@@ -13,6 +13,7 @@ Get full environment status. Auto-connects if not connected. Returns Metro statu
 |------|------|----------|---------|-------------|-------------|
 | `metroPort` | `number` | No |  |  | Override Metro port (default: auto-detect 8081/8082/19000/19006) |
 | `platform` | `string` | No |  |  | Filter target by platform (e.g. "ios", "android") to avoid connecting to the wrong device in multi-simulator setups |
+| `resetArbiter` | `boolean` | No |  |  | Clear a wedged in-memory device arbiter (a leaked plane lease refusing all flows). Escape hatch — cdp_status is unarbitrated so it always runs. |
 
 ## Usage
 

docs-site/src/content/docs/tools/cdp/cdp_wait_for_network.mdx

@@ -3,7 +3,7 @@ title: "cdp_wait_for_network"
 description: "Block until a network request matching url_pattern (URL substring) and optional method completes (response received), or timeout_ms elapses"
 ---
 
-Block until a network request matching url_pattern (URL substring) and optional method completes (response received), or timeout_ms elapses. Two-phase: scans the existing buffer first (retroactive match), then polls every poll_interval_ms until deadline. Returns \{matched:true, mutation, network_log_since\} on success or \{matched:false, timeout_ms, candidates_seen\} (capped at 10) on timeout — never errors on timeout; agents should check `data.matched`. Use after triggering an action that fires a request to deterministically confirm it landed without buffer-churn races. Pin `since` to a timestamp captured BEFORE the trigger (Date.now() ISO) to also catch mutations that land in the MCP transport window.
+Block until a network request matching url_pattern (URL substring) and optional method completes (response received), or timeout_ms elapses. Two-phase: scans the existing buffer first (retroactive match), then polls every poll_interval_ms until deadline. Returns \{matched:true, mutation, network_log_since\} on success or \{matched:false, timeout_ms, candidates_seen\} (capped at 10) on timeout — never errors on timeout; agents should check `data.matched`. Use after triggering an action that fires a request to deterministically confirm it landed without buffer-churn races. Pin `since` to a timestamp captured BEFORE the trigger (Date.now() ISO) to also catch mutations that land in the MCP transport window. On RN < 0.83 (hook network mode) new-entry detection granularity is ~500ms — sub-500ms poll_interval_ms buys nothing there.
 
 ## Parameters
 

docs-site/src/content/docs/tools/device/device_fill.mdx

@@ -14,6 +14,7 @@ Type text into an input field by its @ref from device_snapshot. Always re-taps t
 | `ref` | `string` | Yes |  |  | Input field ref from device_snapshot (e.g. "e5" or "@e5") |
 | `text` | `string` | Yes |  |  | Text to type into the field |
 | `waitForKeyboardMs` | `number` | No |  | min: 0, max: 5000, integer | Wait between pre-tap and fill probe in ms (default 150). Bump to 500-1000ms when filling Pressable-wrapped TextInputs on slow keyboard animations to give RN native focus dispatch time to land. |
+| `testID` | `string` | No |  |  | Explicit testID for the JS-first fill path; resolved from the ref\\'s cached snapshot identifier when omitted. Pass this when the ref is not a snapshot token. |
 
 ## Usage
 

docs-site/src/content/docs/tools/testing/maestro_run.mdx

@@ -15,6 +15,7 @@ Execute a Maestro flow via maestro-runner. Pass flowPath for an existing .yaml f
 | `inlineYaml` | `string` | No |  |  | Inline YAML flow content (written to /tmp and executed) |
 | `platform` | `enum: ios | android` | No |  |  | Target platform (auto-detected from session) |
 | `appId` | `string` | No |  |  | App bundle ID (auto-detected from app.json) |
+| `appFile` | `string` | No |  |  | iOS only — path to a built .app/.ipa for maestro-runner to reinstall on clearState. Auto-resolved from the flow appId when omitted (GH#201). |
 | `timeoutMs` | `number` | No | `120000` | min: 5000, max: 300000, integer | Execution timeout in ms |
 
 ## Usage

docs-site/src/content/docs/troubleshooting.mdx

@@ -19,6 +19,10 @@ Open the app on the simulator and ensure Hermes is enabled. Check your `app.json
 Close React Native DevTools, Flipper, or Chrome DevTools — only one debugger can connect at a time. The 1006 close code means session conflict.
 </Aside>
 
+<Aside type="tip" title='DevTools shows "Disconnected due to opening a second DevTools window"'>
+The bridge auto-reconnects by default and evicts the visual React Native DevTools from the single debugger seat. Set `RN_CDP_AUTOCONNECT=0` (or `.rn-agent/config.json` → `{ "cdp": { "autoConnect": false } }`) to let DevTools hold the seat — the bridge then connects only when a CDP tool runs. Full guide: [React Native DevTools coexistence](/rn-dev-agent/guides/devtools-coexistence/).
+</Aside>
+
 <Aside type="tip" title="CDP connection lost after reload">
 This is normal. `cdp_reload` automatically reconnects within 15 seconds. If it fails, call `cdp_status` to re-establish the connection.
 </Aside>