react-native-ai-devtools 1.4.14 → 1.4.16

package/README.md

@@ -13,12 +13,10 @@ Have an idea or found something that could be better? Head over to [GitHub Discu
 ### Runtime Interaction
 
 -   **Console Log Capture** - Capture `console.log`, `warn`, `error`, `info`, `debug` with filtering and search
--   **React Component Inspection** - Inspect component tree, props, state/hooks, and layout styles at runtime
 -   **Network Request Tracking** - Monitor HTTP requests/responses with headers, timing, and body content. Install the optional [SDK](https://www.npmjs.com/package/react-native-ai-devtools-sdk) for full capture from app startup including request/response bodies
 -   **JavaScript Execution** - Run code directly in your app (REPL-style) and inspect results
 -   **Global State Debugging** - Discover and inspect Apollo Client, Redux stores, Expo Router, and custom globals
 -   **Bundle Error Detection** - Get Metro bundler errors and compilation issues with file locations
--   **Debug Web Dashboard** - Browser-based UI for real-time log and network monitoring
 
 ### Device Control
 
@@ -44,56 +42,57 @@ Have an idea or found something that could be better? Head over to [GitHub Discu
 -   **Efficient Buffering** - Circular buffers: 500 logs, 200 network requests
 -   **Platform Support** - Expo SDK 54+ (Bridgeless) and React Native 0.70+ (Hermes)
 
-## Claude Code Skills
+## Platform Setup
 
-This repository includes pre-built [Claude Code skills](https://docs.anthropic.com/en/docs/claude-code/skills) for common React Native debugging workflows. Skills let Claude handle multi-step tasks (session setup, log inspection, network debugging, etc.) with a single slash command instead of manual back-and-forth.
+### Android
 
-### Available Skills
+Android works out of the box — all device control tools use ADB, which ships with Android Studio. Verify it's available:
 
-| Skill | Description |
-| ----- | ----------- |
-| `session-setup` | Bootstrap a debugging session: discover devices, boot simulators, connect to Metro |
-| `debug-logs` | Capture, filter, and analyze console logs to find errors and warnings |
-| `network-inspect` | Monitor and inspect HTTP requests, filter by status/method, and analyze failures |
-| `app-state` | Inspect Redux/Apollo/context state, navigate the app, and execute code in the runtime |
-| `component-inspect` | Inspect React component tree, props, state, and layout |
-| `layout-check` | Verify UI layout against design specs using screenshots and component data |
-| `device-interact` | Automate device interaction: tap, swipe, text input, and element finding |
-| `bundle-check` | Detect and diagnose Metro bundler errors and compilation failures |
-| `native-rebuild` | Rebuild and verify the app after installing native Expo packages |
+```bash
+adb devices
+```
 
-See [`skills/overview.md`](./skills/overview.md) for a decision guide on which skill to use and a recommended workflow.
+### iOS Simulator — IDB Setup
 
-### Installing Skills (Claude Code)
+[IDB (iOS Development Bridge)](https://github.com/facebook/idb) is a tool built by Meta for automating iOS Simulators and devices. It provides programmatic access to gestures, text input, accessibility trees, and more — capabilities that Apple's built-in `simctl` doesn't cover.
 
-Copy the skill files into your project's `.claude/skills/` directory:
+Many iOS tools (tap, swipe, text input, accessibility queries) require IDB's `idb-companion` daemon. Without it, the tool can detect UI elements via OCR but **cannot execute taps or gestures** on iOS Simulators.
+
+**Install:**
 
 ```bash
-# Install all skills
-mkdir -p .claude/skills
-curl -s https://api.github.com/repos/igorzheludkov/react-native-ai-devtools/contents/skills \
-  | grep download_url \
-  | cut -d '"' -f 4 \
-  | xargs -I {} sh -c 'curl -sL {} -o .claude/skills/$(basename {})'
+brew install idb-companion
 ```
 
-Or pick individual skills from the [`skills/`](./skills/) folder and drop them into `.claude/skills/`.
-
-Then invoke in Claude Code:
+**Verify:**
 
+```bash
+idb_companion --list 1
 ```
-/session-setup
-/debug-logs
-/network-inspect
-```
 
-Skills can also be triggered **automatically** — each skill file contains a "When to Trigger" section that tells Claude when to proactively invoke it without a slash command. For example, Claude will run `bundle-check` on its own when it detects a red screen, or `session-setup` when starting a fresh debugging task with no connection established yet.
+You should see a list of available simulators. If the command is not found, the installation didn't succeed.
+
+**What works without IDB:**
+
+| Capability | Without IDB | With IDB |
+|------------|-------------|----------|
+| Screenshots | Yes (simctl) | Yes |
+| App install/launch/terminate | Yes (simctl) | Yes |
+| URL opening | Yes (simctl) | Yes |
+| Boot simulator | Yes (simctl) | Yes |
+| **Tap / swipe / gestures** | **No** | Yes |
+| **Text input** | **No** | Yes |
+| **Accessibility tree queries** | **No** | Yes |
+| **Element finding / waiting** | **No** | Yes |
+| **Hardware buttons (Home, Lock)** | **No** | Yes |
+
+> **Troubleshooting**: If you see errors like `"IDB is not installed"` or `"Coordinate tap failed: IDB is not installed"` in tap results, install IDB with the command above and retry.
 
 ## Requirements
 
 -   Node.js 18+
 -   React Native app running with Metro bundler
--   **Optional for iOS UI automation**: [Facebook IDB](https://fbidb.io/) - `brew install idb-companion`
+-   **iOS UI automation**: [Facebook IDB](https://fbidb.io/) — `brew install idb-companion` (required for tap, swipe, text input, accessibility on iOS Simulator)
 -   **Optional for offline OCR fallback**: Python 3.6+ (only needed when cloud OCR is unavailable, see [OCR Setup](#ocr-text-extraction))
 
 ## Claude Code Setup
@@ -169,167 +168,22 @@ Requires VS Code 1.102+ with Copilot ([docs](https://code.visualstudio.com/docs/
 }
 ```
 
-## Available Tools
-
-### Usage Guide
-
-| Tool              | Description                                                                 |
-| ----------------- | --------------------------------------------------------------------------- |
-| `get_usage_guide` | Get recommended workflows for all tools. Call without params for overview, with a topic (`setup`, `inspect`, `layout`, `interact`, `logs`, `network`, `state`, `bundle`) for the full guide |
-
-The server also sends instructions on connection, so MCP clients automatically learn about `get_usage_guide`.
-
-### Connection & Logs
-
-| Tool                    | Description                                                        |
-| ----------------------- | ------------------------------------------------------------------ |
-| `scan_metro`            | Scan for Metro servers and auto-connect. **Call this first** to start debugging |
-| `connect_metro`         | Connect to a specific Metro port (use when you know the exact port) |
-| `disconnect_metro`      | Disconnect from all Metro servers. Frees the CDP slot for the built-in RN debugger. Reconnect with `scan_metro` |
-| `get_apps`              | List connected apps. Run `scan_metro` first if none connected      |
-| `get_connection_status` | Get detailed connection health, uptime, and recent disconnects     |
-| `ensure_connection`     | Verify/establish connection with health checks                     |
-| `get_logs`              | Retrieve console logs (filtering, truncation, summary, TONL format) |
-| `search_logs`           | Search logs for specific text (truncation, TONL format)            |
-| `clear_logs`            | Clear the log buffer                                               |
-
-### Network Tracking
-
-| Tool                   | Description                                                |
-| ---------------------- | ---------------------------------------------------------- |
-| `get_network_requests` | Retrieve network requests (filtering, summary, TONL format) |
-| `search_network`       | Search requests by URL pattern (TONL format)               |
-| `get_request_details`  | Get full details of a request (headers, body with truncation) |
-| `get_network_stats`    | Get statistics: counts by method, status code, domain      |
-| `clear_network`        | Clear the network request buffer                           |
-
-### App Inspection & Execution
-
-| Tool                 | Description                                                         |
-| -------------------- | ------------------------------------------------------------------- |
-| `execute_in_app`     | Execute simple JS expressions using globals discovered via `list_debug_globals` |
-| `list_debug_globals` | Discover available debug objects (Apollo, Redux, Expo Router, etc.) |
-| `inspect_global`     | Inspect a global object to see its properties and callable methods  |
-| `reload_app`         | Reload the app (auto-connects if needed). Use sparingly - Fast Refresh handles most changes |
-| `get_debug_server`   | Get the debug HTTP server URL for browser-based viewing             |
-| `restart_http_server` | Restart the debug HTTP server                                      |
-
-### Bundle Tools
-
-| Tool                 | Description                                                         |
-| -------------------- | ------------------------------------------------------------------- |
-| `get_bundle_status`  | Get Metro bundler status and build state                            |
-| `get_bundle_errors`  | Get compilation errors with file locations                          |
-| `clear_bundle_errors` | Clear the bundle error buffer                                      |
-
-### React Component Inspection
-
-**Recommended Workflow**: Use `get_component_tree(focusedOnly=true, structureOnly=true)` for a token-efficient overview of just the active screen (~1-3KB), then drill down with `inspect_component` or `find_components`.
-
-| Tool                 | Description                                                         |
-| -------------------- | ------------------------------------------------------------------- |
-| `get_component_tree` | **Start here** with `focusedOnly=true, structureOnly=true` for active screen overview |
-| `inspect_component`  | **Drill-down tool**: Inspect specific component's props, state/hooks, children |
-| `find_components`    | **Targeted search**: Find components by pattern with optional layout info |
-| `get_screen_layout`  | Full layout data - use sparingly, can be large for complex screens  |
-
-### Element Inspector (Coordinate-Based)
-
-Inspect React components at specific screen coordinates - like React Native's built-in Element Inspector, but programmatically.
-
-| Tool                       | Description                                                                    |
-| -------------------------- | ------------------------------------------------------------------------------ |
-| `get_inspector_selection`  | **Main tool**: Get React component at coordinates. Auto-enables inspector and taps if x/y provided |
-| `toggle_element_inspector` | Manually toggle the Element Inspector overlay on/off                           |
-| `inspect_at_point`         | Inspect React component at (x,y) coordinates                                   |
-
-**Quick Inspection (Recommended)**:
-```
-# Single call - auto-enables inspector, taps, returns component info
-get_inspector_selection(x=210, y=400)
-```
-
-Returns:
-```
-Element: FastImageView
-Path: App > RootNavigation > ... > PlayerModal > FastImage > FastImageView
-Frame: (62.3, 130.0) 295.67x295.67
-Style: { borderRadius: 15, overflow: "hidden" }
-```
-
-**Manual Flow** (for more control):
-```
-# 1. Enable the inspector overlay
-toggle_element_inspector()
-
-# 2. Tap to select element
-tap with x=630 y=1200    # pixel coordinates from screenshot
-
-# 3. Read the selection
-get_inspector_selection()
-
-# 4. Disable overlay when done
-toggle_element_inspector()
-```
-
-**Token Efficiency**: Returns ~0.2-0.5KB vs 15-25KB for full component tree. Works on all React Native versions including Fabric/New Architecture.
+## Claude Code Skills
 
-### UI Interaction (Cross-Platform)
+Pre-built skills for common debugging workflows — session setup, log inspection, network debugging, and more. See the [skills guide](docs/skills.md) for the full list and installation instructions.
 
-| Tool             | Description                                                              |
-| ---------------- | ------------------------------------------------------------------------ |
-| `tap`            | **Unified tap** — auto-detects platform, tries fiber tree → accessibility → OCR → coordinates. Accepts text, testID, component name, or pixel coordinates from screenshots. Returns a post-tap screenshot by default and verifies visual change via before/after diff. Use `native=true` for coordinate taps without React Native connection (system dialogs, non-RN apps) |
-| `ocr_screenshot` | Extract all visible text with tap-ready coordinates (works on iOS/Android) |
+## Available Tools
 
-**Examples:**
-```
-tap with text="Submit"                    # Finds and taps by visible text
-tap with testID="login-btn"               # Finds by testID prop
-tap with component="HamburgerIcon"        # Finds by React component name
-tap with x=300 y=600                      # Taps at pixel coordinates (auto-converts)
-tap with text="Menu" strategy="ocr"       # Forces OCR strategy only
-tap with x=300 y=600 native=true          # Taps directly via ADB/simctl (no RN connection needed)
-```
+See the [full tool reference](docs/tools.md) for all tools with descriptions. Key tools:
 
-### Android (ADB)
-
-| Tool                        | Description                                                   |
-| --------------------------- | ------------------------------------------------------------- |
-| `list_android_devices`      | List connected Android devices and emulators via ADB          |
-| `android_screenshot`        | Take a screenshot from an Android device/emulator             |
-| `android_install_app`       | Install an APK on an Android device/emulator                  |
-| `android_launch_app`        | Launch an app by package name                                 |
-| `android_list_packages`     | List installed packages (with optional filter)                |
-| `android_long_press`        | Long press at specific coordinates                            |
-| `android_swipe`             | Swipe from one point to another                               |
-| `android_input_text`        | Type text at current focus point                              |
-| `android_key_event`         | Send key events (HOME, BACK, ENTER, etc.)                     |
-| `android_get_screen_size`   | Get device screen resolution                                  |
-| `android_describe_all`      | Get full UI accessibility tree via uiautomator                |
-| `android_describe_point`    | Get UI element info at specific coordinates                   |
-| `android_find_element`      | Find element by text/contentDesc/resourceId (no screenshot)   |
-| `android_wait_for_element`  | Wait for element to appear (useful for screen transitions)    |
-
-### iOS (Simulator)
-
-| Tool                    | Description                                                     |
-| ----------------------- | --------------------------------------------------------------- |
-| `list_ios_simulators`   | List available iOS simulators                                   |
-| `ios_screenshot`        | Take a screenshot from an iOS simulator                         |
-| `ios_install_app`       | Install an app bundle (.app) on a simulator                     |
-| `ios_launch_app`        | Launch an app by bundle ID                                      |
-| `ios_open_url`          | Open a URL (deep links or web URLs)                             |
-| `ios_terminate_app`     | Terminate a running app                                         |
-| `ios_boot_simulator`    | Boot a simulator by UDID                                        |
-| `ios_swipe`             | Swipe gesture (requires IDB)                                    |
-| `ios_input_text`        | Type text into active field (requires IDB)                      |
-| `ios_button`            | Press hardware button: HOME, LOCK, SIRI (requires IDB)          |
-| `ios_key_event`         | Send key event by keycode (requires IDB)                        |
-| `ios_key_sequence`      | Send sequence of key events (requires IDB)                      |
-| `ios_describe_all`      | Get full accessibility tree (requires IDB)                      |
-| `ios_describe_point`    | Get element at point (requires IDB)                             |
-| `ios_find_element`      | Find element by label/value (requires IDB, no screenshot)       |
-| `ios_wait_for_element`  | Wait for element to appear (requires IDB)                       |
+| Tool | Description |
+| ---- | ----------- |
+| `scan_metro` | **Start here** — scan for Metro servers and auto-connect |
+| `get_logs` / `search_logs` | Capture and search console logs with filtering and summaries |
+| `get_network_requests` | Monitor HTTP requests with method/status filtering |
+| `tap` | **Unified tap** — auto-detects platform, tries fiber → accessibility → OCR → coordinates |
+| `execute_in_app` | Run JS expressions in the app runtime (REPL-style) |
+| `ios_screenshot` / `android_screenshot` | Take device screenshots |
 
 ## Usage
 
@@ -352,826 +206,27 @@ tap with x=300 y=600 native=true          # Taps directly via ADB/simctl (no RN
     Use get_logs to see recent console output
     ```
 
-### `get_logs` Tool Reference
-
-The `get_logs` tool has multiple parameters for controlling output size and format. Here's the complete reference:
-
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `maxLogs` | number | 50 | Maximum number of logs to return |
-| `level` | string | "all" | Filter by level: `all`, `log`, `warn`, `error`, `info`, `debug` |
-| `startFromText` | string | - | Start from the last log containing this text |
-| `maxMessageLength` | number | 500 | Max chars per message (0 = unlimited) |
-| `verbose` | boolean | false | Disable all truncation, return full messages |
-| `format` | string | "text" | Output format: `text` or `tonl` (30-50% smaller) |
-| `summary` | boolean | false | Return counts + last 5 messages only |
-
-#### Recommended Usage Patterns
-
-```
-# Quick overview (always start here)
-get_logs with summary=true
-
-# Recent errors only
-get_logs with level="error" maxLogs=20
-
-# Logs since last app reload
-get_logs with startFromText="Running app" maxLogs=100
-
-# Full messages for debugging specific issues
-get_logs with maxLogs=10 verbose=true
-
-# Token-efficient format for large outputs
-get_logs with format="tonl" maxLogs=100
-
-# Compact overview with shorter messages
-get_logs with maxMessageLength=200 maxLogs=50
-```
-
-### Filtering Logs
-
-```
-get_logs with maxLogs=20 and level="error"
-```
-
-Available levels: `all`, `log`, `warn`, `error`, `info`, `debug`
-
-### Start from Specific Line
-
-```
-get_logs with startFromText="iOS Bundled" and maxLogs=100
-```
-
-This finds the **last** (most recent) line containing the text and returns logs from that point forward. Useful for getting logs since the last app reload.
-
-### Search Logs
-
-```
-search_logs with text="error" and maxResults=20
-```
-
-Case-insensitive search across all log messages.
-
-### Token-Optimized Output
-
-The tools include several options to reduce token usage when working with AI assistants.
-
-#### Summary Mode (Recommended First Step)
-
-**Always start with `summary=true`** - it gives you the full picture in ~10-20 tokens instead of potentially thousands:
-
-```
-get_logs with summary=true
-```
-
-Returns:
-- **Total count** - How many logs are in the buffer
-- **Breakdown by level** - See if there are errors/warnings at a glance
-- **Last 5 messages** - Most recent activity (truncated to 100 chars each)
-
-Example output:
-
-```
-Total: 847 logs
-
-By Level:
-  LOG: 612
-  WARN: 180
-  ERROR: 55
-
-Last 5 messages:
-  14:32:45 [LOG] User clicked button...
-  14:32:46 [WARN] Slow query detected...
-  14:32:47 [ERROR] Network request failed...
-```
-
-#### Why Summary First?
-
-| Approach | Tokens | Use Case |
-|----------|--------|----------|
-| `summary=true` | ~20-50 | Quick health check, see if errors exist |
-| `level="error"` | ~100-500 | Investigate specific errors |
-| `maxLogs=50` (default) | ~500-2000 | General debugging |
-| `verbose=true` | ~2000-10000+ | Deep dive into specific data |
-
-**Recommended workflow:**
-1. `summary=true` → See the big picture
-2. `level="error"` or `level="warn"` → Focus on problems
-3. `startFromText="..."` → Get logs since specific event
-4. `verbose=true` with low `maxLogs` → Full details when needed
-
-#### Message Truncation
-
-Long log messages are truncated by default (500 chars). Adjust as needed:
-
-```
-# Shorter for overview
-get_logs with maxMessageLength=200
-
-# Full messages (use with lower maxLogs)
-get_logs with maxLogs=10 verbose=true
-
-# Unlimited
-get_logs with maxMessageLength=0
-```
-
-#### TONL Format
-
-Use TONL (Token-Optimized Notation Language) for ~30-50% smaller output:
-
-```
-get_logs with format="tonl"
-```
-
-Output:
-
-```
-[Format: TONL - compact token-optimized format. Fields in header, values in rows.]
-{logs:[{time:"14:32:45",level:"LOG",msg:"App started"},{time:"14:32:46",level:"WARN",msg:"Slow query"}]}
-```
-
-TONL is also available for `search_logs`, `get_network_requests`, and `search_network`.
-
-## Network Tracking
-
-### SDK for Full Network Capture (Recommended)
-
-For complete network capture including **startup requests**, **full headers**, and **response bodies**, install the companion SDK in your React Native app:
-
-```bash
-npm install react-native-ai-devtools-sdk
-```
-
-Add to your app's entry file (e.g., `index.js` or `app/_layout.tsx`) — **must be the first import**:
-
-```js
-import { init } from 'react-native-ai-devtools-sdk';
-if (__DEV__) {
-  init();
-}
-```
-
-**What the SDK captures that basic mode doesn't:**
-
-| | Without SDK | With SDK |
-|---|---|---|
-| Startup requests (auth, config) | Missed | Captured |
-| Request/response headers | Partial | Full |
-| Request body (GraphQL queries) | No | Full |
-| Response body | No | Full |
-| Works on Bridgeless (Expo SDK 52+) | Partial | Full |
-| Setup required | None | One import |
-
-The SDK patches `fetch` at import time and stores data in an in-app buffer. The MCP tools automatically detect the SDK and read from it — no configuration needed.
-
-**Without the SDK**, network tracking still works via CDP (Chrome DevTools Protocol) on supported targets, but may miss early requests and won't include response bodies.
-
-### View Recent Requests
-
-```
-get_network_requests with maxRequests=20
-```
-
-### Filter by Method
-
-```
-get_network_requests with method="POST"
-```
-
-### Filter by Status Code
-
-Useful for debugging auth issues:
-
-```
-get_network_requests with status=401
-```
-
-### Search by URL
-
-```
-search_network with urlPattern="api/auth"
-```
-
-### Get Full Request Details
-
-After finding a request ID from `get_network_requests`:
-
-```
-get_request_details with requestId="sdk-abc-1"
-```
-
-Shows full headers, request body, response headers, response body, and timing.
-
-Body is truncated by default (500 chars). For full body:
-
-```
-get_request_details with requestId="sdk-abc-1" verbose=true
-```
-
-### Summary Mode (Recommended First Step)
-
-Get statistics overview before fetching full requests:
-
-```
-get_network_requests with summary=true
-```
-
-This returns the same output as `get_network_stats` - counts by method, status, and domain.
-
-### TONL Format
-
-Use TONL for ~30-50% smaller output:
-
-```
-get_network_requests with format="tonl"
-```
-
-### View Statistics
-
-```
-get_network_stats
-```
-
-Example output:
-
-```
-Total requests: 47
-Completed: 45
-Errors: 2
-Avg duration: 234ms
-
-By Method:
-  GET: 32
-  POST: 15
-
-By Status:
-  2xx: 43
-  4xx: 2
-
-By Domain:
-  api.example.com: 40
-  cdn.example.com: 7
-```
-
-## Debug Web Dashboard
-
-The MCP server includes a built-in web dashboard for viewing logs and network requests in your browser. This is useful for real-time monitoring without using MCP tools.
-
-### Getting the Dashboard URL
-
-Use the `get_debug_server` tool to find the dashboard URL:
-
-```
-get_debug_server
-```
-
-The server automatically finds an available port starting from 3456. Each MCP instance gets its own port, so multiple Claude Code sessions can run simultaneously.
-
-### Available Pages
-
-| URL        | Description                                    |
-| ---------- | ---------------------------------------------- |
-| `/`        | Dashboard with overview stats                  |
-| `/logs`    | Console logs with color-coded levels           |
-| `/network` | Network requests with expandable details       |
-| `/apps`    | Connected React Native apps                    |
-
-### Features
-
--   **Auto-refresh** - Pages update automatically every 3 seconds
--   **Color-coded logs** - Errors (red), warnings (yellow), info (blue), debug (gray)
--   **Expandable network requests** - Click any request to see full details:
-    -   Request/response headers
-    -   Request body (with JSON formatting)
-    -   Timing information
-    -   Error details
--   **GraphQL support** - Shows operation name and variables in compact view:
-    ```
-    POST  200  https://api.example.com/graphql         1ms  ▶
-               GetMeetingsBasic (timeFilter: "Future", first: 20)
-    ```
--   **REST body preview** - Shows JSON body preview for non-GraphQL requests
-
-### JSON API Endpoints
-
-For programmatic access, JSON endpoints are also available:
-
-| URL                  | Description                   |
-| -------------------- | ----------------------------- |
-| `/api/status`        | Server status and buffer sizes |
-| `/api/logs`          | All logs as JSON              |
-| `/api/network`       | All network requests as JSON  |
-| `/api/bundle-errors` | Metro bundle errors as JSON   |
-| `/api/apps`          | Connected apps as JSON        |
-
-## App Inspection
-
-### Discover Debug Globals
-
-Find what debugging objects are available in your app:
-
-```
-list_debug_globals
-```
-
-Example output:
-
-```json
-{
-    "Apollo Client": ["__APOLLO_CLIENT__"],
-    "Redux": ["__REDUX_STORE__"],
-    "Expo": ["__EXPO_ROUTER__"],
-    "Reanimated": ["__reanimatedModuleProxy"]
-}
-```
-
-### Inspect an Object
-
-Before calling methods on an unfamiliar object, inspect it to see what's callable:
-
-```
-inspect_global with objectName="__EXPO_ROUTER__"
-```
-
-Example output:
-
-```json
-{
-    "navigate": { "type": "function", "callable": true },
-    "push": { "type": "function", "callable": true },
-    "currentPath": { "type": "string", "callable": false, "value": "/" },
-    "routes": { "type": "array", "callable": false }
-}
-```
-
-### Execute Code in App
+## Detailed Guides
 
-Run simple JavaScript expressions using globals discovered via `list_debug_globals`:
-
-```
-execute_in_app with expression="__DEV__"
-// Returns: true
-
-execute_in_app with expression="__APOLLO_CLIENT__.cache.extract()"
-// Returns: Full Apollo cache contents
-
-execute_in_app with expression="__EXPO_ROUTER__.navigate('/settings')"
-// Navigates the app to /settings
-```
-
-**Limitations (Hermes engine):**
-- No `require()` or `import` — only pre-existing globals are available
-- No `async/await` syntax — use simple expressions or promise chains (`.then()`)
-- No emoji or non-ASCII characters in string literals — causes parse errors
-- Keep expressions simple and synchronous when possible
-
-## React Component Inspection
-
-Inspect React components at runtime via the React DevTools hook. These tools let you debug component state, verify layouts, and understand app structure without adding console.logs.
-
-### Recommended Workflow (Token-Efficient)
-
-**Always use the 2-step approach:**
-
-1. **Step 1: Get focused screen overview** (~1-3KB)
-   ```
-   get_component_tree with focusedOnly=true structureOnly=true
-   ```
-
-2. **Step 2: Drill down** into specific components as needed
-   ```
-   inspect_component with componentName="HomeScreen"
-   # or
-   find_components with pattern="Button" includeLayout=true
-   ```
-
-This approach uses **~10-20x fewer tokens** than getting full details upfront.
-
-### Token Consumption Comparison
-
-| Approach | Tokens | Use Case |
-|----------|--------|----------|
-| `focusedOnly=true, structureOnly=true` | ~1-3KB | **Recommended** - active screen structure only |
-| `structureOnly=true` | ~15-25KB | Full tree structure (includes navigation, overlays) |
-| `inspect_component` | ~1-2KB | Deep dive into specific component |
-| `find_components` | ~2-5KB | Targeted search with layout |
-| `get_screen_layout` | ~20-50KB+ | Full layout (use sparingly) |
-
-### Focused Screen Mode (`focusedOnly`)
-
-The `focusedOnly` parameter dramatically reduces output by returning only the active screen subtree:
-
-- **Skips navigation wrappers** - Providers, NavigationContainers, SafeAreaProviders
-- **Skips global overlays** - BottomSheet, Modal, Toast, Snackbar components
-- **Returns just the focused screen** - Components matching `*Screen` or `*Page` pattern
-
-```
-get_component_tree with focusedOnly=true structureOnly=true
-```
-
-Output:
-
-```
-Focused: HomeScreen
-
-HomeScreen
-  Header
-    Logo
-    SearchBar
-  FlatList
-    ListItem (×12)
-  Footer
-```
-
-**When to skip `focusedOnly`:**
-- Debugging navigation structure itself
-- Investigating which screens are mounted
-- Checking global overlay state
-
-### Inspecting Overlays (BottomSheet, Modal, Toast)
-
-Since `focusedOnly` skips global overlays by design, use this workflow to debug them:
-
-1. **Find the overlay component:**
-   ```
-   find_components with pattern="BottomSheet|Modal|Toast"
-   ```
-
-2. **Inspect its state/props:**
-   ```
-   inspect_component with componentName="MyBottomSheet"
-   ```
-
-This targeted approach uses ~2-4KB vs ~20KB+ for the full tree.
-
-### Step 1: Get Component Tree
-
-View the React component hierarchy with minimal data:
-
-```
-# Focused screen only (recommended)
-get_component_tree with focusedOnly=true structureOnly=true
-
-# Full tree structure
-get_component_tree with structureOnly=true
-```
-
-Output (ultra-compact):
-
-```
-Focused: HomeScreen
-
-HomeScreen
-  Header
-  FlatList
-  Footer
-```
-
-This gives you the focused screen structure in just 1-3KB.
-
-### Step 2a: Inspect Specific Component
-
-After identifying a component in the structure, drill down:
-
-```
-inspect_component with componentName="HomeScreen"
-```
-
-Output:
-
-```json
-{
-  "component": "HomeScreen",
-  "path": "... > Navigator > HomeScreen",
-  "props": {
-    "navigation": "[Object]",
-    "route": { "name": "Home", "key": "home-xyz" }
-  },
-  "hooks": [
-    { "hookIndex": 0, "value": false },
-    { "hookIndex": 3, "value": 42 }
-  ]
-}
-```
-
-Options:
-- `includeChildren=true` - Include children tree
-- `childrenDepth=2` - How deep to show children (1=direct only, 2+=nested tree)
-- `includeState=false` - Skip hooks/state (faster)
-- `index=1` - Inspect 2nd instance if multiple exist
-
-### Step 2b: Find Components by Pattern
-
-Search for components and optionally get their layout:
-
-```
-find_components with pattern="Screen$" includeLayout=true
-```
-
-Output:
-
-```
-pattern: Screen$
-found: 5
-#found{component,path,depth,key,layout}
-HomeScreen|... > Navigator > HomeScreen|45|paddingHorizontal:16|
-SettingsScreen|... > Navigator > SettingsScreen|45|flex:1|
-```
-
-Options:
-- `includeLayout=true` - Include flex, padding, margin values
-- `summary=true` - Get counts only (e.g., "HomeScreen: 1")
-- `maxResults=10` - Limit number of results
-
-### Full Layout (Use Sparingly)
-
-For detailed layout of all visible components:
-
-```
-get_screen_layout
-```
-
-**Warning**: This returns ~20-50KB for complex screens. Use `find_components` with `includeLayout=true` instead for targeted queries.
-
-### Use Cases
-
-**Figma Alignment / Layout Verification**
-```
-# Step 1: See focused screen structure
-get_component_tree with focusedOnly=true structureOnly=true
-
-# Step 2: Get layout for specific components
-find_components with pattern="Header|Footer|Button" includeLayout=true
-```
-
-**Debug State Changes**
-```
-# Check hook values before action
-inspect_component with componentName="LoginForm"
-# → hookIndex 2: false (isLoading)
-
-# After user action, check again
-inspect_component with componentName="LoginForm"
-# → hookIndex 2: true (isLoading changed!)
-```
-
-**Debug Navigation Issues**
-```
-# Find which screen is currently mounted (use full tree)
-get_component_tree with structureOnly=true
-# or
-find_components with pattern="Screen$"
-
-# Check if a screen rendered multiple times (memory leak)
-find_components with pattern="HomeScreen" summary=true
-```
-
-**Debug Overlays (BottomSheet, Modal, Toast)**
-```
-# Find and inspect overlay components
-find_components with pattern="BottomSheet|Modal"
-
-# Get overlay props/state
-inspect_component with componentName="PaywallModal"
-```
-
-**Understand Unfamiliar Codebase**
-```
-# Quick focused screen overview
-get_component_tree with focusedOnly=true structureOnly=true
-
-# Full app structure (navigation, providers)
-get_component_tree with structureOnly=true
-
-# Find all button variants
-find_components with pattern="Button"
-
-# Find all context providers
-find_components with pattern="Provider$"
-```
-
-## Device Interaction
-
-### Android (requires ADB)
-
-List connected devices:
-
-```
-list_android_devices
-```
-
-Take a screenshot:
-
-```
-android_screenshot
-```
-
-Tap on screen:
-
-```
-tap with x=540 y=960
-```
-
-Swipe gesture:
-
-```
-android_swipe with startX=540 startY=1500 endX=540 endY=500
-```
-
-Type text (tap input field first):
-
-```
-tap with x=540 y=400
-android_input_text with text="hello@example.com"
-```
-
-Send key events:
-
-```
-android_key_event with key="BACK"
-android_key_event with key="HOME"
-android_key_event with key="ENTER"
-```
-
-### iOS Simulator (requires Xcode)
-
-List available simulators:
-
-```
-list_ios_simulators
-```
-
-Boot a simulator:
-
-```
-ios_boot_simulator with udid="XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
-```
-
-Take a screenshot:
-
-```
-ios_screenshot
-```
-
-Launch an app:
-
-```
-ios_launch_app with bundleId="com.example.myapp"
-```
-
-Open a deep link:
-
-```
-ios_open_url with url="myapp://settings"
-```
-
-## UI Interaction
-
-### Unified `tap` Tool (Recommended)
-
-The `tap` tool is the simplest way to interact with UI elements. It automatically tries multiple strategies and handles platform detection and coordinate conversion:
-
-```
-# By visible text — tries fiber tree, accessibility, then OCR
-tap with text="Submit"
-
-# By testID prop
-tap with testID="login-btn"
-
-# By React component name (fiber tree only)
-tap with component="HamburgerIcon"
-
-# By pixel coordinates from screenshot (auto-converts to points on iOS)
-tap with x=300 y=600
-
-# Force a specific strategy
-tap with text="Menu" strategy="ocr"
-```
-
-**Fallback chain:** fiber tree (direct `onPress`) → accessibility tree → OCR → error with suggestion.
-
-On failure, the response includes an actionable `suggestion` telling the agent exactly what to try next.
-
-**Screenshot & verification:** By default, `tap` captures and returns a post-tap screenshot (`screenshot=true`). For coordinate, accessibility, and OCR strategies, it also runs a before/after screenshot diff to verify the tap had a meaningful visual effect (`verify=true` by default for these strategies, `false` for fiber). Set `screenshot=false` to skip screenshots entirely for fastest execution, or `verify=false` to skip the diff check.
-
-### Platform-Specific Tools
-
-For gestures beyond tapping, use platform-specific tools:
-
-```
-# Swipe
-ios_swipe with startX=200 startY=400 endX=200 endY=100
-android_swipe with startX=540 startY=1500 endX=540 endY=500
-
-# Text input (tap input field first)
-tap with text="Email"
-ios_input_text with text="hello@example.com"
-
-# Key events
-android_key_event with key="BACK"
-ios_button with button="HOME"
-```
-
-### Wait for Screen Transitions
-
-```
-android_wait_for_element with text="Dashboard" timeoutMs=15000
-ios_wait_for_element with label="Home" timeoutMs=10000
-```
-
-## OCR Text Extraction
-
-The `ocr_screenshot` tool extracts all visible text from a screenshot with tap-ready coordinates. This is useful when accessibility labels are missing or when you need to find text that isn't exposed in the accessibility tree.
-
-### Why OCR?
-
-| Approach | Pros | Cons |
-|----------|------|------|
-| Accessibility tree (`find_element`) | Fast, reliable, low token usage | Only finds elements with accessibility labels |
-| Screenshot + Vision | Visual layout understanding | High token usage, slow |
-| **OCR** | Works on ANY visible text, returns tap coordinates | Requires text to be visible, may miss small text |
-
-### Usage
-
-```
-ocr_screenshot with platform="ios"
-```
-
-Returns all visible text with tap-ready coordinates:
-
-```json
-{
-  "platform": "ios",
-  "engine": "cloud",
-  "processingTimeMs": 550,
-  "elementCount": 24,
-  "elements": [
-    { "text": "Settings", "confidence": 95, "tapX": 195, "tapY": 52 },
-    { "text": "Login", "confidence": 95, "tapX": 187, "tapY": 420 }
-  ]
-}
-```
-
-Then tap the element:
-
-```
-tap with x=187 y=420
-```
-
-### OCR Engine
-
-OCR uses **Google Cloud Vision API** via a cloud proxy for fast, accurate text recognition (~97%+ accuracy, ~0.5s processing time). This works out of the box with no local dependencies.
-
-Screenshots are sent over HTTPS to our cloud endpoint for processing and immediately deleted after recognition — no images are stored.
-
-### Offline Fallback (EasyOCR)
-
-If the cloud endpoint is unreachable (no internet, timeout), OCR falls back to local EasyOCR (Python-based). This requires Python 3.6+:
-
-```bash
-# macOS
-brew install python@3.11
-
-# Ubuntu/Debian
-sudo apt install python3
-```
-
-EasyOCR and its Python dependencies are installed automatically by `node-easyocr`. The local fallback is slower (~2-3s) and less accurate (~85-90%) but works offline.
-
-### OCR Language Configuration
-
-Google Cloud Vision automatically detects and recognizes text in most languages without configuration.
-
-For the offline EasyOCR fallback, set `EASYOCR_LANGUAGES` to add language support:
-
-```bash
-EASYOCR_LANGUAGES=es,fr
-```
-
-### Recommended Workflow
-
-1. **Use unified `tap`** - Handles fallback chain automatically
-2. **Fall back to OCR** - When `tap` suggests using coordinates
-3. **Use screenshot** - For visual debugging or layout verification
-
-```
-# Simplest approach — tap handles everything
-tap with text="Submit"
-
-# If tap fails, use OCR to find coordinates
-ocr_screenshot with platform="android"
-
-# Then tap using coordinates from OCR result
-tap with x=540 y=1200
-```
+| Guide | Description |
+| ----- | ----------- |
+| [Console Logging](docs/logging.md) | `get_logs` parameters, filtering, summary mode, TONL format, token optimization |
+| [Network Tracking](docs/network.md) | SDK setup for full capture, filtering, request details, statistics |
+| [App Inspection](docs/app-inspection.md) | Debug globals (Apollo, Redux, Expo Router), `execute_in_app`, limitations |
+| [Device Interaction](docs/device-interaction.md) | Unified `tap`, platform-specific gestures, text input, key events |
+| [OCR Text Extraction](docs/ocr.md) | Cloud Vision OCR, offline fallback, language config, workflows |
+| [Claude Code Skills](docs/skills.md) | Pre-built skills for session setup, debugging, and automation |
+| [Full Tool Reference](docs/tools.md) | Complete list of all 40+ tools with descriptions |
 
 ## Supported React Native Versions
 
-| Version        | Runtime                 | Status     |
-| -------------- | ----------------------- | ---------- |
-| Expo SDK 54+   | React Native Bridgeless | ✓          |
-| RN 0.70 - 0.76 | Hermes React Native     | ✓          |
-| RN < 0.70      | JSC                     | Not tested |
+| Version | Architecture | Engine | Status |
+| ------- | ------------ | ------ | ------ |
+| Expo SDK 54+ | Bridgeless (New Arch) | Hermes | ✓ Fully supported |
+| RN 0.76+ | Bridgeless (New Arch) | Hermes | ✓ Fully supported |
+| RN 0.73 - 0.75 | Bridge (Old Arch) | Hermes | ✓ Fully supported (best network capture via CDP) |
+| RN 0.70 - 0.72 | Bridge (Old Arch) | Hermes / JSC | ✓ Supported |
+| RN < 0.70 | Bridge | JSC | Not tested |
 
 ## How It Works