chore: update docs

Author: V3RON

README.md

@@ -13,7 +13,7 @@ Bridge the testing gap: Jest-style tests in real native environments. Get the co
 
 - **Jest-Style Syntax, Native Power**: Write familiar describe/it tests that run in real iOS and Android environments with full native module access.
 - **Best of Both Worlds**: Unlike Jest (Node.js only) or Maestro (UI-based), get convenient test syntax AND native environment execution.
-- **Real Device & Simulator Testing**: Execute tests directly on iOS simulators and Android emulators — catch platform-specific issues Jest can't see.
+- **Real Device, Simulator & Web Testing**: Execute tests on iOS simulators, Android emulators, or in a browser (Web) — catch platform-specific issues Jest can't see.
 - **Native Module Testing**: Test native modules, platform APIs, and device-specific functionality that's impossible with JavaScript-only runners.
 - **Familiar Test Structure**: Use beforeEach, afterEach, describe, it, expect — all the testing patterns you know and love from Jest.
 - **Zero Configuration Setup**: Drop-in replacement for your existing test workflow with TypeScript support and seamless CI/CD integration.
@@ -60,8 +60,10 @@ export default config;
 The documentation is available at [react-native-harness.dev](https://react-native-harness.dev). You can also use the following links to jump to specific topics:
 
 - [Quick Start](https://react-native-harness.dev/docs/getting-started/quick-start)
+- [Configuration](https://react-native-harness.dev/docs/getting-started/configuration) (Metro port, plugins, timeouts, coverage, and more)
 - [Problem Statement](https://react-native-harness.dev/docs/getting-started/problem-statement)
 - [Feature Comparison](https://react-native-harness.dev/docs/feature-comparison)
+- [Running in CI/CD](https://react-native-harness.dev/docs/guides/ci-cd)
 - [API Reference](https://react-native-harness.dev/docs/api/defining-tests)
 
 ## Made with ❤️ at Callstack

packages/github-action/README.md

@@ -10,10 +10,13 @@ GitHub Action that simplifies running React Native Harness tests in CI/CD enviro
 
 ## Action
 
-Use:
+Pin the action ref to the **same release as the `react-native-harness` package** in your project’s `package.json` (for example `1.0.0` in dependencies → `@v1.0.0` on the action). The action and npm releases are cut from the same repo; keeping versions aligned avoids drift between what `pnpm install` / `npm ci` resolves and what the workflow runs.
+
+Use a [release tag](https://github.com/callstackincubator/react-native-harness/releases) for normal CI, or `@main` only if you intentionally track the default branch.
 
 ```yaml
-- uses: callstackincubator/react-native-harness@main
+# Match @v… to the react-native-harness version in package.json
+- uses: callstackincubator/react-native-harness@v1.0.0
 ```
 
 The action reads your `rn-harness.config.mjs` file, resolves the `runner` you pass in, and uses that runner's `platformId` to decide which platform-specific setup to execute.
@@ -52,15 +55,15 @@ Hook behavior:
 
 Runner configuration requirements:
 
-- Android runners must include an `avd` property with `apiLevel`, `profile`, `diskSize`, and `heapSize`
+- Android **emulator** runners must include an `avd` property with `apiLevel`, `profile`, `diskSize`, and `heapSize` (the composite action fails fast if this is missing). Physical Android device runners do not use `avd`.
 - iOS runners must include a `device` property with `name` and `systemVersion`
 
 ## Examples
 
 ### Android runner
 
 ```yaml
-- uses: callstackincubator/react-native-harness@main
+- uses: callstackincubator/react-native-harness@v1.0.0
   with:
     app: './android/app/build/outputs/apk/debug/app-debug.apk'
     runner: 'android'
@@ -77,7 +80,7 @@ Runner configuration requirements:
 ### iOS runner
 
 ```yaml
-- uses: callstackincubator/react-native-harness@main
+- uses: callstackincubator/react-native-harness@v1.0.0
   with:
     app: './ios/build/Build/Products/Debug-iphonesimulator/MyApp.app'
     runner: 'ios'
@@ -91,7 +94,7 @@ Runner configuration requirements:
 ### Web runner
 
 ```yaml
-- uses: callstackincubator/react-native-harness@main
+- uses: callstackincubator/react-native-harness@v1.0.0
   with:
     runner: 'chromium'
     projectRoot: './apps/my-app'

website/src/docs/getting-started/configuration.mdx

@@ -117,6 +117,8 @@ Harness treats `metroPort` as the preferred starting port. If that port is alrea
 Physical iOS devices are the exception: they always use the default Metro port and do not support custom or fallback ports.
 
 When multiple Harness runs target the same device, simulator, emulator, or browser configuration, Harness waits for the existing run to finish before starting the next one.
+
+When a run finishes, Harness clears platform-specific dev settings it applied for the session (for example the Android debug HTTP host override and the iOS simulator JS location override) so your next normal Metro or dev-client launch is not stuck pointing at Harness's port.
 :::
 
 A test runner defines how tests are executed on a specific platform. React Native Harness uses platform-specific packages to create runners with type-safe configurations.

website/src/docs/getting-started/introduction.md

@@ -4,7 +4,7 @@ Before diving deep into React Native Harness and introducing it into your projec
 
 ## What is React Native Harness?
 
-React Native Harness is a testing tool for testing native modules in their native environments (Android, iOS) in a convenient way, using well-known Jest/Vitest syntax. Unlike traditional Jest tests that run in Node.js without access to native functionality, Harness executes your tests directly on real devices and simulators where native modules are available.
+React Native Harness is a testing tool for exercising native and web code in real environments (Android, iOS, and Web via the browser) in a convenient way, using well-known Jest/Vitest syntax. Unlike traditional Jest tests that run in Node.js without access to native functionality, Harness executes your tests directly on real devices and simulators where native modules are available.
 
 For a detailed explanation of the problems with current testing approaches and how Harness solves them, see [Problem Statement](/docs/getting-started/problem-statement).
 

website/src/docs/guides/ci-cd.md

@@ -19,7 +19,7 @@ React Native Harness provides an official GitHub Action that simplifies running
 - `callstackincubator/react-native-harness`
 
 :::tip Versioning
-You can pin to a specific version by appending `@<version>` to the action path (e.g., `@main`, `@v1.0.0`). For production use, we recommend pinning to a specific release tag once available.
+Pin the action to the **same [release tag](https://github.com/callstackincubator/react-native-harness/releases) as the `react-native-harness` version in your `package.json`** (for example package `1.0.0` → `uses: callstackincubator/react-native-harness@v1.0.0`). The composite action and the npm package are released together; matching them avoids subtle mismatches between CLI behavior and the workflow steps.
 :::
 
 The action automatically:
@@ -30,7 +30,7 @@ The action automatically:
 - Runs the tests
 - Uploads crash reports from `.harness/crash-reports/` as workflow artifacts whenever a run produces them
 
-The action reads your `rn-harness.config.mjs` file to determine the selected runner's platform and device configuration, so you don't need to hardcode emulator or simulator settings in your workflow.
+The action reads your `rn-harness.config.mjs` file to determine the selected runner's platform and device configuration, so you don't need to duplicate emulator or simulator settings in your workflow. For **Android emulator** runners, the action still requires a full `avd` block in that config (see the [Android platform guide](/docs/platforms/android)).
 
 ### Action Inputs
 
@@ -135,8 +135,9 @@ jobs:
           path: android/app/build/outputs/apk/debug/app-debug.apk
           key: android-app-${{ hashFiles('android/**/*.gradle*', 'android/**/gradle-wrapper.properties') }}
 
+      # Keep @v… in sync with the react-native-harness version in package.json
       - name: Run React Native Harness
-        uses: callstackincubator/react-native-harness@main
+        uses: callstackincubator/react-native-harness@v1.0.0
         with:
           app: android/app/build/outputs/apk/debug/app-debug.apk
           runner: android
@@ -209,8 +210,9 @@ jobs:
           path: ios/build/Build/Products/Debug-iphonesimulator/YourApp.app
           key: ios-app-${{ hashFiles('ios/Podfile.lock', 'ios/**/*.pbxproj') }}
 
+      # Keep @v… in sync with the react-native-harness version in package.json
       - name: Run React Native Harness
-        uses: callstackincubator/react-native-harness@main
+        uses: callstackincubator/react-native-harness@v1.0.0
         with:
           app: ios/build/Build/Products/Debug-iphonesimulator/YourApp.app
           runner: ios

website/src/docs/platforms/android.mdx

@@ -107,7 +107,11 @@ The first argument is the manufacturer, and the second is the model name. These
 
 ## CI Notes
 
-If you use the official GitHub Action with an Android emulator runner, `cacheAvd` works best when your runner includes the emulator's AVD configuration. This helps the action reuse the correct emulator snapshot between runs.
+:::caution Official GitHub Action + Android emulator
+The unified action [`callstackincubator/react-native-harness`](https://github.com/callstackincubator/react-native-harness) **requires** a full `avd` configuration on **emulator** runners (`apiLevel`, `profile`, `diskSize`, `heapSize`). It validates this before booting the emulator. Local CLI runs can target an emulator by name alone; the action needs the structured `avd` object to create or restore the AVD in CI.
+:::
+
+If you use that action with an Android emulator runner, `cacheAvd` works best when your runner includes the emulator's AVD configuration. This helps the action reuse the correct emulator snapshot between runs.
 
 ## App Launch Options
 

website/src/index.md

@@ -24,7 +24,7 @@ features:
     details: Write tests using familiar describe, it, expect, beforeEach, and afterEach syntax. No new testing patterns to learn.
     icon: <img src="/icons/speed-fast.svg" />
   - title: Truly native environment
-    details: Execute tests directly on iOS simulators and Android emulators where native modules are fully available without mocking.
+    details: Execute tests on iOS simulators, Android emulators, or in a real browser (Web), with native modules available where the platform provides them.
     icon: <img src="/icons/device-phone.svg" />
   - title: Quick integration
     details: Add to existing projects with straightforward configuration steps, TypeScript support and CI/CD compatibility.