prompttest-mobile 1.5.1

package/docs/USER_MANUAL.md

@@ -0,0 +1,764 @@
+# 📖 PromptTest — Comprehensive User Manual & Reference Guide
+
+Welcome to the **PromptTest** User Manual! This guide provides detailed documentation, syntax references, real-world examples, and best practices for writing and executing autonomous mobile QA tests in plain English.
+
+---
+
+## 📑 Table of Contents
+
+1. [Introduction & Architecture](#1-introduction--architecture)
+2. [Installation & Setup](#2-installation--setup)
+3. [CLI Command Reference](#3-cli-command-reference)
+4. [PromptTest Syntax Specification](#4-prompttest-syntax-specification)
+   - [Tapping & Gestures](#tapping--gestures)
+   - [Text Entry & Form Inputs](#text-entry--form-inputs)
+   - [Assertions & Verifications](#assertions--verifications)
+   - [Navigation, Scrolling & Swiping](#navigation-scrolling--swiping)
+   - [App Lifecycle & Permissions](#app-lifecycle--permissions)
+5. [Dynamic & Conditional Testing](#5-dynamic--conditional-testing)
+   - [Regular Expression / Pattern Matching](#regular-expression--pattern-matching)
+   - [Multi-Alternative (OR) Matching](#multi-alternative-or-matching)
+   - [Optional / Conditional Actions](#optional--conditional-actions)
+   - [Dynamic Variables & Generators](#dynamic-variables--generators)
+6. [Autonomous Record & Replay](#6-autonomous-record--replay)
+7. [Autonomous Exploration & State-Graph Crawler (Mode 2)](#7-autonomous-exploration--state-graph-crawler-mode-2)
+8. [Self-Healing & Resilience Engine](#8-self-healing--resilience-engine)
+9. [Multi-Device Matrix & CI/CD Pipelines](#9-multi-device-matrix--cicd-pipelines)
+10. [Advanced Features & SDK](#10-advanced-features--sdk)
+
+- [Checkpointing & Resume](#checkpointing--resume)
+- [Visual Baselines](#visual-baselines)
+- [Custom Reporters](#custom-reporters)
+- [APK Auto-Install](#apk-auto-install)
+- [Device Locking](#device-locking)
+- [Programmatic SDK](#programmatic-sdk)
+
+11. [Real-World Domain Recipes](#11-real-world-domain-recipes)
+
+- [EdTech & Coaching Portals](#edtech--coaching-portals)
+- [E-Commerce & Food Delivery](#e-commerce--food-delivery)
+- [FinTech & Banking](#fintech--banking)
+- [Social & Messaging](#social--messaging)
+
+12. [Mode Expectations, Capabilities & Limitations](#12-mode-expectations-capabilities--limitations)
+
+---
+
+## 1. Introduction & Architecture
+
+**PromptTest** is an AI-native autonomous mobile testing framework for Android. It enables developers, QA engineers, and product teams to write executable test specs in plain English without writing fragile XPath selectors or maintaining complex Appium setups.
+
+### Key Architecture Components:
+
+- **`AndroidDriver` (ADB Layer):** Direct, zero-latency communication with physical Android devices and emulators over USB or Wi-Fi.
+- **`HierarchyCrawler` (Visual UI Engine):** Extracts, cleans, and indexes on-screen Android view trees.
+- **`PromptRunner` (Execution Brain):** Parses plain-English instructions, performs label-to-input pairing, auto-scrolls viewports, and executes resilient assertions.
+- **`MemoryEngine` (Autonomous Knowledge Graph):** Learns screen aliases and component identifiers across test runs for instant 0ms lookups.
+- **`AutonomousRecorder` (Interactive Record-and-Play):** Live-monitors screen interactions and auto-generates test specs.
+
+---
+
+## 2. Installation & Setup
+
+### Requirements
+
+- **Node.js**: v18.0.0 or higher
+- **Android SDK Platform Tools**: `adb` must be available in your system `PATH`.
+- **Target Device**: Physical Android device (with USB debugging enabled) or Android Emulator.
+
+### Running via npx (Zero Installation)
+
+```bash
+npx prompttest devices
+npx prompttest run specs/my_test.txt
+```
+
+### Installing Locally in Your Repository
+
+```bash
+npm install --save-dev prompttest
+```
+
+Add scripts to your `package.json`:
+
+```json
+{
+  "scripts": {
+    "test:mobile": "prompttest run specs/regression_suite.txt",
+    "test:fresh": "prompttest run specs/regression_suite.txt --fresh",
+    "test:matrix": "prompttest run specs/regression_suite.txt --all-devices"
+  }
+}
+```
+
+---
+
+## 3. CLI Command Reference
+
+| Command                           | Description                                     | Example                                    |
+| --------------------------------- | ----------------------------------------------- | ------------------------------------------ |
+| `prompttest devices`              | Scans and lists all connected Android devices   | `npx prompttest devices`                   |
+| `prompttest wifi [ip[:port]]`     | Connects to a device wirelessly over Wi-Fi      | `npx prompttest wifi 192.168.1.50`         |
+| `prompttest disconnect [ip]`      | Disconnects wireless device                     | `npx prompttest disconnect`                |
+| `prompttest status`               | Inspects foreground application & UI components | `npx prompttest status`                    |
+| `prompttest record [spec.txt]`    | Interactive record-and-play session             | `npx prompttest record specs/login.txt`    |
+| `prompttest run <spec.txt>`       | Executes plain-English test spec (Fail-Fast)    | `npx prompttest run specs/teacher.txt`     |
+| `prompttest watch <spec.txt>`     | Continuously re-runs test upon spec file save   | `npx prompttest watch specs/login.txt`     |
+| `prompttest doctor`               | Runs full workstation & ADB readiness diagnosis | `npx prompttest doctor`                    |
+| `prompttest repl`                 | Launches interactive live testing shell         | `npx prompttest repl`                      |
+| `prompttest benchmark`            | Profiles ADB hierarchy, screencap, & matching   | `npx prompttest benchmark`                 |
+| `prompttest merge-reports [dir]`  | Merges multi-device results into Atto dashboard | `npx prompttest merge-reports output`      |
+| `prompttest explore [pkg]`        | Autonomous crawler exploration (forms/tabs)     | `npx prompttest explore host.exp.exponent` |
+| `prompttest memory [pkg]`         | Views learned component aliases & confidence    | `npx prompttest memory host.exp.exponent`  |
+| `prompttest memory stats [pkg]`   | Displays learned knowledge health statistics    | `npx prompttest memory stats`              |
+| `prompttest memory export [pkg]`  | Exports learned memory to a JSON file           | `npx prompttest memory export host.exp`    |
+| `prompttest memory import <file>` | Imports/merges learned memory from JSON file    | `npx prompttest memory import mem.json`    |
+| `prompttest memory clear [pkg]`   | Clears learned knowledge cache                  | `npx prompttest memory clear`              |
+| `prompttest init-ci`              | Generates GitHub Actions CI workflows           | `npx prompttest init-ci`                   |
+
+### CLI Execution Flags
+
+#### Filtering, Flow Control & Debugging
+
+- `--dry-run`: Validates and parses test spec syntax without device interaction.
+- `--list-steps`: Prints a structured table of the parsed step AST to stdout and exits.
+- `--only="<range>"`: Executes only matching step numbers or ranges (e.g. `--only="1-3,5"`).
+- `--tags="<tag>"`: Filters execution to specs matching tagged directives (e.g. `--tags="smoke"`).
+- `--continue` or `--continue-on-error`: Continues running remaining steps even if an upstream step fails.
+- `--fresh` or `--cold-start`: Force-stops and restarts target app before test begins.
+- `--resume`: Resumes test execution from the last recorded checkpoint upon failure.
+- `--var:KEY=VALUE`: Injects inline dynamic variables (e.g. `--var:ROLE=TEACHER`).
+
+#### Observability, Reporting & Live Monitoring
+
+- `--json`: Outputs machine-readable execution report JSON directly to stdout.
+- `--serve [port]`: Streams live test execution events over HTTP/SSE dashboard (default: `http://localhost:4040`).
+- `--embed-screenshots`: Inlines base64 screenshots into standalone HTML report for zero-asset portability.
+- `--screenshots` or `--all-screenshots`: Captures full screenshots on every step (default: on-failure only).
+- `--video`: Records the entire test session to high-definition MP4 video via native ADB screenrecord.
+- `--reporters=json,html,junit,md`: Generates specific output report formats.
+- `--reporter=<path>`: Loads a custom reporter module implementing the `Reporter` interface.
+
+#### Data-Driven & Localization
+
+- `--data=<path.csv|json>`: Executes data-driven tests across multiple rows/parameter sets.
+- `--iterations=N`: Repeats the test suite across N iterations or data rows.
+- `--only-row=N`: Executes only the specified 1-indexed data row.
+- `--locale=<code>`: Sets active taxonomy locale dictionary (e.g. `'en'`, `'es'`, `'hi'`).
+
+#### AI, Resilience & Visual Regression
+
+- `--heal`: Enables automatic element locator self-healing via offline synonyms and heuristic memory.
+- `--no-ai`: Disables third-party LLM providers, forcing offline-only heuristic matching.
+- `--expand`: Previews AI natural-language macro intent expansion without modifying the file.
+- `--expand-apply`: Expands high-level macro steps and writes concrete actions directly to the spec file.
+- `--save-baseline`: Saves screen layout screenshots as visual baseline.
+- `--compare-baseline`: Compares live screens against saved baseline using perceptual diffing.
+- `--baseline-threshold=N`: Sets perceptual diff variance threshold (0.0–1.0, default: `0.02`).
+- `--apk=<path>`: Automatically installs or updates the target APK before test execution if absent.
+- `--all-devices`: Runs test suite concurrently across all connected online devices.
+- `-s <id>` or `--serial=<id>`: Targets a specific connected Android device by serial.
+
+### Environment Diagnostic Tool (`prompttest doctor`)
+
+Run `prompttest doctor` whenever setting up a new workstation, troubleshooting device connectivity, or configuring a CI runner:
+
+- Validates the `adb` binary presence and version in system `PATH`.
+- Confirms USB/Wi-Fi debugging authorization and platform-tools integrity.
+- Verifies physical screen dimensions, orientation, and battery readiness.
+
+### Interactive Live Sandbox (`prompttest repl`)
+
+Use `prompttest repl` to prototype actions, debug ambiguous locators, or interactively explore screens without writing full spec files:
+
+- `inspect`: Dumps actionable buttons, text fields, and tabs on the current screen.
+- `tap '<label>'`: Taps element matching target text or descriptor.
+- `type '<value>' into '<target>'`: Enters text into an input field.
+- `screenshot [path]`: Captures screen evidence instantly.
+
+---
+
+## 4. PromptTest Syntax Specification
+
+PromptTest specs are plain-text files (e.g. `specs/checkout.txt`). Steps can be numbered or written as bullet points. Lines starting with `#` are treated as comments.
+
+### Spec Tagging & Categorization
+
+You can annotate test specs with tags using `# @tag: <name>` directives at the top of the file:
+
+```txt
+# @tag: smoke
+# @tag: regression
+# @tag: payments
+
+1. Tap 'Cart'
+2. Tap 'Checkout'
+```
+
+Run only specs matching your tag filter:
+
+```bash
+npx prompttest run specs/checkout.txt --tags="smoke"
+```
+
+### Tapping & Gestures
+
+```txt
+# Basic Tap / Click
+Tap 'Sign In'
+Click "Add to Cart"
+Press 'Submit'
+
+# Ordinal Tapping (when multiple matching elements exist)
+Tap 1st 'View Details'
+Click 2nd 'Export Report'
+Tap last 'Delete'
+
+# Proximity Tapping (targets element near an anchor)
+Tap 'Delete' next to 'Rohan Gupta'
+Click 'Edit' near 'Batch Grade 10'
+
+# Long Press
+Long press 'Mid-Term Examination Schedule'
+Press and hold 'Voice Message'
+```
+
+### Text Entry & Form Inputs
+
+PromptTest automatically associates input fields with their preceding labels and distinguishes between password and email/text fields.
+
+```txt
+# Entering Credentials
+Type 'ramesh@coachconnect.app' into 'Email Address'
+Type 'Teacher@1234' into 'Password'
+
+# Entering Search Queries
+Type 'Mathematics' into 'Search by batch, subject, or teacher...'
+
+# Clearing and Re-entering
+Type 'New York' into 'City'
+```
+
+### Assertions & Verifications
+
+```txt
+# Visibility Assertions
+Verify 'Apex Coaching Academy' is visible
+Ensure 'Dr. Ramesh Sharma' appears
+Assert 'Order Confirmed' exists
+
+# Component State Assertions
+Verify 'Submit' is disabled
+Verify 'Pay Now' is enabled
+```
+
+### Navigation, Scrolling & Swiping
+
+```txt
+# System Back Navigation
+Press back
+Go back
+
+# Vertical Scrolling
+Scroll down
+Scroll up
+
+# Directional Swipes (for Carousels, Tabs, Bottom Sheets)
+Swipe left
+Swipe right
+Swipe left on 'Featured Courses'
+Swipe down on 'Modal Sheet'
+```
+
+### App Lifecycle & Permissions
+
+```txt
+# Explicit App Management
+Launch app 'host.exp.exponent'
+Restart app 'com.example.myapp'
+Terminate app
+Clear app data for 'com.example.myapp'
+
+# System Permissions
+Grant permission 'android.permission.CAMERA'
+Grant permission 'android.permission.ACCESS_FINE_LOCATION' to 'com.example.myapp'
+
+# Deep Links
+Open deep link 'myapp://batches/grade-10'
+```
+
+---
+
+## 5. Dynamic & Conditional Testing
+
+### Regular Expression / Pattern Matching
+
+When asserting dynamic numbers, timestamps, currencies, or roll numbers that vary at runtime:
+
+```txt
+# Percentages (e.g. 40%, 75%, 100%)
+Verify pattern '\d+%' is visible
+
+# Counters and Ratios (e.g. "5 Students", "5 / 30")
+Verify pattern '\d+\s*(Students|Batches)' is visible
+Verify pattern '\d+\s*/\s*\d+' is visible
+
+# Currencies (e.g. "$49.99", "₹1,499")
+Verify pattern '[$₹€]\s*\d+([.,]\d{2})?' is visible
+
+# Formatted IDs / Roll Numbers
+Verify pattern 'STD-\d{4}-\d{4}' is visible
+Verify pattern 'INV-[A-Z0-9]+' is visible
+```
+
+### Multi-Alternative (OR) Matching
+
+```txt
+Verify '100%|90%|80%|75%' is visible
+Verify 'Active|Present|Enrolled' is visible
+Verify 'In Stock|Limited Stock' is visible
+```
+
+### Optional / Conditional Actions
+
+Steps marked `(optional)` or `(if present)` will execute if the element is on screen, but will **never fail the test** if absent:
+
+```txt
+Tap 'Dismiss' (optional)
+Tap 'Allow' (if present)
+Tap 'Skip Tour' (optional)
+```
+
+### Dynamic Variables & Generators
+
+PromptTest supports built-in generators and custom runtime variable injection.
+
+#### Built-in Dynamic Generators
+
+```txt
+Type '$RANDOM_EMAIL' into 'Email Address'    # Generates: test_492019@prompttest.io
+Type '$RANDOM_NAME' into 'Full Name'         # Generates: User_8302
+Type '$RANDOM_PHONE' into 'Phone Number'     # Generates: 9849201832
+Type '$TIMESTAMP' into 'Reference Note'      # Generates: 1788839201
+Type '$UUID' into 'Transaction ID'           # Generates: e9a2c-f901
+```
+
+#### Custom CLI Variables
+
+In your spec file:
+
+```txt
+Type '$USER_EMAIL' into 'Email Address'
+Type '$USER_PASSWORD' into 'Password'
+Verify '$EXPECTED_ROLE' is visible
+```
+
+Execute with values:
+
+```bash
+npx prompttest run spec.txt --var:USER_EMAIL=ramesh@coachconnect.app --var:USER_PASSWORD=Teacher@1234 --var:EXPECTED_ROLE=TEACHER
+```
+
+---
+
+## 6. Autonomous Record & Replay
+
+Record complex end-to-end user journeys interactively on your device with enterprise-grade safety:
+
+### Basic Recording
+
+```bash
+npx prompttest record specs/recorded_journey.txt
+```
+
+- **Auto-Package Tagging:** Automatically detects the foreground app and writes `# Package: <package>` to the spec header for zero-config replay.
+- **Auto-Backup Protection:** If the file already exists, PromptTest automatically preserves a safety backup as `specs/recorded_journey.txt.bak` before saving.
+- **Auto-Increment Defaults:** Running `npx prompttest record` without a filename will automatically generate `specs/recorded_suite_1.txt`, `specs/recorded_suite_2.txt`, etc., preventing collisions.
+
+### Appending to Existing Flows (`--append`)
+
+To extend an existing test suite (e.g., adding sidebar FAQ checks to an existing 25-step test):
+
+```bash
+npx prompttest record specs/recorded_journey.txt --append
+```
+
+1. PromptTest reads existing steps (e.g. 25 steps) and creates a backup.
+2. It starts numbering new recorded steps continuously from `#26`.
+3. It appends the new session with clear timestamped divider comments upon saving.
+
+### Intelligent Live Filtering
+
+- **Password Bullet Filtering:** Automatically strips security masking characters (`••••`).
+- **Parent Label Association:** Links input fields to their visual labels rather than duplicating input contents.
+- **Keystroke Debouncing:** Captures the final entered value instead of recording each character keystroke.
+- **Tap Jitter Deduplication:** Filters out accidental rapid double-taps on the same UI element.
+
+### Replay
+
+```bash
+npx prompttest run specs/recorded_journey.txt
+```
+
+- Automatically checks device app installation, launches the app if not in foreground, and executes the suite.
+
+---
+
+## 7. Autonomous Exploration & State-Graph Crawler (Mode 2)
+
+PromptTest's **Autonomous Explorer v3** is a zero-script state-graph crawler designed to traverse, test, and map your mobile application automatically without writing test specs.
+
+### Basic Autonomous Exploration
+
+```bash
+# Auto-detects the active foreground app and starts autonomous crawling
+npx prompttest explore
+
+# Target a specific installed package on a specific connected device
+npx prompttest explore host.exp.exponent --serial=GEVKDEUWOJWC89OR
+```
+
+### The 5-Step State-Graph Exploration Pipeline
+
+1. **Foreground Verification & Auto-Launch**: Ensures the target application is running and in the foreground. If absent, launches the app and verifies launch readiness.
+2. **Semantic Form Detection & Auto-Filling**: Identifies username, email, password, and phone input fields, auto-populates them with realistic test data, dismisses the soft keyboard (`KEYCODE_ESCAPE`), and submits the form.
+3. **Action Buttons & Toggle Testing**: Taps standalone action buttons, flips toggle switches and checkboxes, opens side navigation drawers, and records observable UI outcomes (`NAVIGATED`, `STATE_MUTATED`, or `NO_OP` warning).
+4. **Master-Detail List Exploration & Vertical Scrolling**: Identifies scrollable lists and feeds (`RecyclerView`, `ScrollView`), scrolls vertically to discover off-screen elements below the fold, dives into detail views, and unwinds back via `KEYCODE_BACK`.
+5. **Bottom Navigation Tab Traversal & Sub-Crawling**: Traverses root-level navigation tabs with bottom gesture bar tap-clamping, recursively testing sub-actions under each tab while tracking visited screens in a state graph.
+
+---
+
+### Safety Policy Engine (`--safety-mode`)
+
+To protect production data, shared testing environments, and user accounts from accidental deletion or modification, PromptTest enforces a multi-tiered safety policy:
+
+```bash
+# Strict mode (default): Blocks auth drop, checkout/payments, and all deletions
+npx prompttest explore host.exp.exponent --safety-mode=strict
+
+# Moderate mode: Blocks account loss & auth, allows local in-app draft/item deletions
+npx prompttest explore host.exp.exponent --safety-mode=moderate
+
+# Interactive mode: Prompts user in console before executing risky actions
+npx prompttest explore host.exp.exponent --safety-mode=interactive
+
+# Disabled mode: Unrestricted sandbox exploration (isolated environments only)
+npx prompttest explore host.exp.exponent --safety-mode=disabled
+```
+
+| Policy Mode          | Description                                                  | Default Protections                                                                                              |
+| :------------------- | :----------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------- |
+| `strict` _(Default)_ | Maximum safety for production or shared test backends.       | Blocks logout, signout, account deletion, data wipe, payments, checkout, and generic item deletions.             |
+| `moderate`           | Recommended for active development and staging environments. | Shields account deletion, user wipe, and auth termination, but permits localized draft and test item deletion.   |
+| `interactive`        | Hybrid human-in-the-loop testing.                            | Prompts `[y/N]` before touching destructive elements. Failsafe: automatically falls back to skip in headless CI. |
+| `disabled`           | Isolated sandboxes and ephemeral emulators only.             | Bypasses all safety pattern checks.                                                                              |
+
+---
+
+### Configurable Safety Blacklists (`--safety-blacklist`)
+
+You can define custom blacklist keywords to protect domain-specific critical actions (e.g. "Publish", "Transfer", "Revoke"):
+
+```bash
+# Via CLI argument (comma-separated keywords)
+npx prompttest explore host.exp.exponent --safety-blacklist="Transfer,Revoke,Publish,Notice"
+```
+
+Or configure permanent safety rules in your `.prompttestrc.json`:
+
+```json
+{
+  "safety": {
+    "mode": "strict",
+    "customBlacklist": ["Transfer Funds", "Revoke Access", "Publish Live"]
+  }
+}
+```
+
+---
+
+### External Intent Filtering & Package Jailing (`packageJailGuard`)
+
+Mobile applications often contain links that trigger external apps (e.g. "Rate Us" opening Google Play Store, "Terms of Service" opening Chrome, or external OAuth portals).
+
+- **Proactive Intent Filter**: The crawler automatically detects and bypasses elements matching `EXTERNAL_INTENT_PATTERNS` (`Rate Us`, `Play Store`, `Privacy Policy`, `https://`, `share via`).
+- **Package Jail Guard**: If an unclassified action causes the device to escape the target app into Chrome or Google Play, PromptTest detects the foreign package, executes `pressBack()`, and if needed, force re-launches the target app to restore containment immediately.
+
+---
+
+### Development Console & Overlay Auto-Triage
+
+In React Native and hybrid apps, runtime warnings or unhandled promise rejections often pop up overlays (LogBox, RedBox, Flutter exception banners, Android ANR alerts) that block underlying UI buttons and stall ordinary automation:
+
+1. **Auto-Detection**: Scans the view hierarchy for LogBox overlays and ANR dialogs.
+2. **Stack Trace Extraction**: Captures the exact error message and logs it as a critical defect in the executive report.
+3. **Auto-Dismissal**: Taps the "Dismiss" or "Close" button so autonomous exploration can continue testing the rest of the application.
+
+---
+
+### Budgets & Performance Controls
+
+```bash
+# Deep crawl: up to 50 unique screens, 5 levels deep, 100 interaction steps
+npx prompttest explore host.exp.exponent --max-screens=50 --max-depth=5 --step-budget=100
+
+# Fast crawl with lazy failure-only screenshots (slashes execution time by 3-5x)
+npx prompttest explore host.exp.exponent --screenshots=failure-only
+```
+
+| Flag                   | Default        | Description                                                                                                               |
+| :--------------------- | :------------- | :------------------------------------------------------------------------------------------------------------------------ |
+| `--max-screens=N`      | `20`           | Maximum unique screen states to index in the state graph.                                                                 |
+| `--max-depth=N`        | `3`            | Maximum recursion depth for nested screen diving.                                                                         |
+| `--step-budget=N`      | `40`           | Total interaction steps before completing exploration.                                                                    |
+| `--screenshots=<mode>` | `state-change` | Visual capture policy: `state-change` (only when screen updates), `failure-only` (only on errors), or `all` (every step). |
+
+---
+
+## 8. Self-Healing & Resilience Engine
+
+PromptTest is built with multi-layered self-healing mechanisms:
+
+1. **Pre-Authentication Fast-Forwarding:**
+   - If a test starts with a login verification (`Verify 'Welcome Back'`), but the app is already authenticated on the dashboard, PromptTest scans ahead and **fast-forwards** past the redundant login steps automatically.
+2. **Cursor-Independent Input Flushing:**
+   - Uses `MOVE_END` + `DEL` + `MOVE_HOME` + `FORWARD_DEL` keycodes to reliably clear inputs regardless of initial cursor position or password visibility toggle icons.
+3. **Viewport Auto-Scroll:**
+   - Detects if an asserted element is clipped above or below screen boundaries and smoothly scrolls it into view.
+4. **Bottom Tab Bar Coordinate Normalization:**
+   - Automatically clamps vertical tap coordinates strictly within the element's actual physical bounds (`[bounds.y1 + 2, bounds.y2 - 2]`), preventing taps from landing outside the viewport or inadvertently triggering Android system gesture navigation bars.
+
+---
+
+## 9. Multi-Device Matrix & CI/CD Pipelines
+
+### Concurrent Multi-Device Execution
+
+Test your app across multiple Android models, resolutions, and OS versions concurrently with a single command:
+
+```bash
+npx prompttest run specs/smoke_suite.txt --all-devices
+```
+
+### GitHub Actions CI Workflow Setup
+
+Run `npx prompttest init-ci` to automatically generate two production-ready GitHub Actions workflows under `.github/workflows/`:
+
+- **`unit.yml`**: Headless Node.js 18 & 20 quality gates (Prettier check, ESLint, TypeScript typecheck, Vitest headless test suite with code coverage, and npm audit).
+- **`device.yml`**: Android Emulator API 33 live spec execution with hardware KVM acceleration, automated JUnit XML publishing, and artifact capture.
+
+```bash
+npx prompttest init-ci
+```
+
+### Central Multi-Device Report Aggregation & Atto Quality Scoring
+
+When running tests across multiple physical devices or emulators using `--all-devices`, individual result JSON files (`*-results.json`) are produced per device. PromptTest can merge these results into a unified matrix dashboard:
+
+```bash
+npx prompttest merge-reports output
+```
+
+The generated `output/aggregated-dashboard.html` and `output/aggregated-results.json` feature:
+
+- **Atto-Inspired Release Confidence Score (0–100%)**: An enterprise quality index calculated from weighted pass rates, critical-path assertion coverage, and device diversity.
+- **Cross-Device Comparison Matrix**: Detailed side-by-side grid comparing execution status and timing for each step across every device model.
+- **Consolidated Defect Summary**: Highlighting visual or functional regressions that appear on specific device form factors.
+
+---
+
+## 10. Advanced Features & SDK
+
+### Checkpointing & Resume
+
+Long test suites can fail halfway due to network or environment issues. PromptTest automatically checkpoints progress after each successful step.
+You can use the `--resume` flag to skip previously passed steps and continue execution from the exact point of failure:
+
+```bash
+npx prompttest run specs/regression_suite.txt --resume
+```
+
+### Visual Baselines
+
+PromptTest can capture visual baselines and perform perceptual diffing to detect unintended UI changes.
+
+- `--save-baseline`: Saves the current screen layout as a visual baseline for future comparisons.
+- `--compare-baseline`: Compares the current screen layout against the saved baseline and fails if differences exceed the threshold.
+- `--baseline-threshold=N`: Adjusts the diffing tolerance as a ratio from `0` to `1` (e.g., `--baseline-threshold=0.05` for 5%).
+
+### Custom Reporters
+
+You can integrate custom test reporters by supplying a path to your reporter module:
+
+```bash
+npx prompttest run specs/suite.txt --reporter=./reporters/my-custom-reporter.js
+```
+
+Custom reporters must implement the `Reporter` interface for pluggable report formats (e.g., Slack, DataDog, HTML).
+
+### APK Auto-Install
+
+For CI environments, you can automatically install a specific APK before running tests:
+
+```bash
+npx prompttest run specs/suite.txt --apk=./build/app-release.apk
+```
+
+PromptTest will verify the device architecture and seamlessly deploy the build prior to execution.
+
+### Device Locking
+
+PromptTest includes a cross-process, file-based mutex lock (`lib/lock.ts`) that guarantees concurrent safety. If multiple test processes try to control the same physical device or emulator simultaneously, they will wait in a queue until the lock is released.
+
+### Programmatic SDK & Cross-Platform Drivers
+
+PromptTest exposes a clean programmatic API using factory functions and a unified `DriverInterface`. Both Android and iOS drivers share the identical driver abstraction:
+
+```typescript
+import { createPromptRunner, createAndroidDriver, IosDriver } from 'prompttest';
+
+async function runCrossPlatformTests() {
+  // 🤖 Android Execution
+  const androidDriver = createAndroidDriver('DEVICE_SERIAL');
+  const androidRunner = createPromptRunner(androidDriver);
+  const androidReport = await androidRunner.runSpec('specs/login.txt', 'com.example.app');
+
+  // 🍎 iOS Execution (Simulator or Physical Device)
+  const iosDriver = new IosDriver({
+    udid: '00008101-001234567890',
+  });
+  const iosRunner = createPromptRunner(iosDriver);
+  const iosReport = await iosRunner.runSpec('specs/login.txt', 'com.example.app');
+
+  console.log(`Android passed: ${androidReport.passed}, iOS passed: ${iosReport.passed}`);
+}
+
+runCrossPlatformTests();
+```
+
+### Cross-Platform Driver Architecture (`DriverInterface`)
+
+PromptTest decouples test execution from OS-level automation protocols. Custom mobile environments (e.g. Flutter desktop, HarmonyOS, or cloud device farms) can implement the minimal `DriverInterface`:
+
+- `getUiHierarchy(serial?)`: Returns the XML / accessibility view hierarchy.
+- `tap(x, y, serial?)`: Dispatches a tap event at screen coordinates.
+- `inputText(text, serial?)`: Inputs text into the active field.
+- `pressKey(keyCode, serial?)`: Sends hardware key codes (e.g., BACK, ENTER).
+- `takeScreenshot(outputPath, serial?)`: Captures screen image artifact.
+
+---
+
+## 11. Real-World Domain Recipes
+
+### EdTech & Coaching Portals
+
+```txt
+# 1. Sign In as Faculty
+1. Verify 'Welcome Back' is visible
+2. Type 'ramesh@coachconnect.app' into 'Email Address'
+3. Type 'Teacher@1234' into 'Password'
+4. Tap 'Sign In'
+5. Wait 2s
+
+# 2. Verify Batches & Class Schedulers
+6. Tap 'Batches'
+7. Verify 'Batches & Schedules' is visible
+8. Verify 'Grade 10 Mathematics' is visible
+9. Verify pattern '\d+\s*/\s*30' is visible
+
+# 3. Attendance Hub
+10. Tap 'Attendance'
+11. Verify 'Attendance Hub' is visible
+12. Verify 'Rohan Gupta' is visible
+13. Verify pattern '\d+%' is visible
+14. Tap 'Export Report'
+15. Verify 'Export Attendance Report' is visible
+16. Press back
+
+# 4. Sign Out
+17. Tap 'Profile'
+18. Tap 'Sign Out'
+19. Tap 'Sign Out'
+20. Verify 'Welcome Back' is visible
+```
+
+### E-Commerce & Food Delivery
+
+```txt
+# 1. Search & Browse
+1. Type 'Wireless Headphones' into 'Search products...'
+2. Tap 1st 'Add to Cart'
+3. Tap 'Cart'
+4. Verify 'Shopping Cart' is visible
+5. Verify pattern 'Total:\s*₹\d+' is visible
+
+# 2. Checkout & Address
+6. Tap 'Proceed to Checkout'
+7. Type '42 HSR Layout, Sector 2' into 'Delivery Address'
+8. Type '560102' into 'Pincode'
+9. Tap 'Cash on Delivery|UPI Payment'
+10. Tap 'Place Order'
+11. Verify 'Order Confirmed' is visible
+```
+
+### FinTech & Banking
+
+```txt
+# 1. Biometric / PIN Auth
+1. Verify 'Secure Login' is visible
+2. Type '1234' into 'Enter 4-digit PIN'
+3. Tap 'Continue'
+
+# 2. Balance & Transactions
+4. Verify 'Account Overview' is visible
+5. Verify pattern 'Balance:\s*₹[\d,]+(\.\d{2})?' is visible
+6. Tap 'Transaction History'
+7. Verify 'Recent Transactions' is visible
+8. Verify pattern 'TXN-\d{8}' is visible
+```
+
+---
+
+## 🎯 12. Mode Expectations, Capabilities & Limitations
+
+> **Read first:** Full details in **[`docs/MODE_EXPECTATIONS.md`](MODE_EXPECTATIONS.md)**. This section is the honest contract for what each mode can and cannot do.
+
+PromptTest is a **fast UI-tree automation engine over ADB**. It "sees" what `uiautomator dump` exposes — not pixels. This one fact drives every limit below.
+
+### Which mode should I use?
+
+| Mode                          | Command                                | Best for                                                     | Not for                             |
+| ----------------------------- | -------------------------------------- | ------------------------------------------------------------ | ----------------------------------- |
+| **Instructed (`run`)**        | `prompttest run specs/foo.txt <pkg>`   | Regression gates, CI, verifying a known flow with assertions | Exploratory discovery               |
+| **Autonomous (`explore`)**    | `prompttest explore <pkg>`             | Unattended state-graph discovery and safety-guarded sweeps   | Replacing asserted regression tests |
+| **Hybrid (`record` → `run`)** | `prompttest record` → `prompttest run` | Turning a manual walkthrough into a repeatable script        | — (review the generated spec first) |
+
+### What you should honestly expect
+
+- ✅ **`run`**: executes plain-English steps, polls for elements, asserts visibility/state, self-heals broken locators, reuses offline memory to speed repeat runs. Deterministic per step, CI-friendly.
+- ✅ **`explore`**: **State-Graph Crawler v3** — systematically traverses forms, toggles switches/checkboxes, inspects side navigation drawers, discovers off-screen content via vertical scrolling, dives into master-detail lists, and traverses bottom navigation tabs with sub-crawling. Protected by configurable safety blacklists, external package jailing, and dev overlay auto-dismissal.
+- ⚠️ **Performance**: "sub-second" = per **step**, not per whole suite.
+
+### Autonomous `explore` — capabilities and architecture
+
+- **State-Graph Crawling**: Uses BFS/DFS graph indexing via hierarchy hashing (`computeHierarchyHash`) and offline `MemoryEngine` caching to track visited screens, detect loops, and fast-forward past redundant paths.
+- **Safety Policy Enforcement**: Hierarchical safety modes (`strict`, `moderate`, `interactive`, `disabled`) ensure dangerous buttons (delete account, checkout, logout) are blocked and reported in the audit hit-list.
+- **Domain Containment**: `packageJailGuard` prevents the crawler from leaving the app when tapping external intent links (Rate Us, Store URLs, Web browsers).
+- **Overlay Triage**: Automatically extracts errors from React Native LogBox, RedBox, Flutter exception views, and Android ANRs, logging them as defects and dismissing the overlay.
+- **Zero third-party AI required**: 100% heuristic and offline execution using the in-repo `HeuristicResolver` + `MemoryEngine`. Runs in air-gapped CI environments without network latency.
+
+### Honest limitations (apply to every mode)
+
+1. **Accessibility-tree dependency.** An element with no `text`, `content-desc`, `resource-id`, or clickable bounds is invisible or only tappable "blind."
+2. **Games / canvas / fully-drawn content** may expose no hierarchy → PromptTest cannot inspect or assert it.
+3. **OS overlays & Secure/FLAG_SECURE screens** can block dumps/capture.
+4. **Determinism ceiling.** Timers, real services, and animations can cause flakiness; wait for a stable state in your spec.
+5. **Zero third-party AI required.** All capabilities — including autonomous crawling — work fully offline via heuristics + memory. LLM is an optional, gated enhancement, never a prerequisite.
+
+---
+
+## 💡 Support & Contribution
+
+- **Community Repository**: [github.com/shriramsingh/prompttest-community](https://github.com/shriramsingh/prompttest-community)
+- **Issues & Requests**: [File an Issue](https://github.com/shriramsingh/prompttest-community/issues)
+- **License**: Business Source License 1.1 (BSL 1.1)