docs: improve README introduction and iOS testing guidance

.github/ISSUE_TEMPLATE/ios-validation.yml

@@ -0,0 +1,108 @@
+name: iOS validation report
+description: Report physical-device validation results for the iOS/iPadOS Wi-Fi Aware implementation.
+title: "[iOS validation]: "
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for helping validate the Apple implementation.
+
+        Physical-device results are especially useful because the Wi-Fi Aware implementation cannot be fully validated in the simulator. Please include enough detail for failures to be reproduced.
+
+  - type: checkboxes
+    id: prerequisites
+    attributes:
+      label: Prerequisites
+      options:
+        - label: I tested on a physical iPhone or iPad.
+          required: true
+        - label: The app was signed with an Apple Developer account and the required Wi-Fi Aware entitlement.
+          required: true
+        - label: I declared the tested service in `WiFiAwareServices` in the host app's `Info.plist`.
+          required: true
+
+  - type: input
+    id: library-version
+    attributes:
+      label: Library version or commit
+      description: npm version, tag, branch, or commit SHA used for the test.
+      placeholder: e.g. 0.1.0-alpha.1 or abc1234
+    validations:
+      required: true
+
+  - type: input
+    id: device
+    attributes:
+      label: Apple device
+      placeholder: e.g. iPhone 15 Pro
+    validations:
+      required: true
+
+  - type: input
+    id: os-version
+    attributes:
+      label: iOS/iPadOS version
+      placeholder: e.g. iOS 26.0
+    validations:
+      required: true
+
+  - type: dropdown
+    id: scenario
+    attributes:
+      label: Test scenario
+      options:
+        - iOS/iPadOS → iOS/iPadOS discovery and pairing
+        - iOS/iPadOS → iOS/iPadOS network connection
+        - Android → iOS/iPadOS interoperability
+        - iOS/iPadOS → Android interoperability
+        - Capability detection only
+        - Other
+    validations:
+      required: true
+
+  - type: input
+    id: peer-device
+    attributes:
+      label: Peer device
+      description: Device model and OS/API level of the other device, if applicable.
+      placeholder: e.g. iPhone 14 / iOS 26.0 or Pixel 9 / Android 17
+
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps performed
+      description: Describe the exact sequence you used so the result can be reproduced.
+    validations:
+      required: true
+
+  - type: dropdown
+    id: result
+    attributes:
+      label: Result
+      options:
+        - Passed
+        - Failed
+        - Partially passed
+    validations:
+      required: true
+
+  - type: textarea
+    id: observed
+    attributes:
+      label: Observed behavior
+      description: What happened? Include errors, unexpected behavior, or where the flow stopped.
+    validations:
+      required: true
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Relevant logs
+      description: Paste relevant Metro, Xcode, device-console, or native logs. Remove secrets or identifying information first.
+      render: shell
+
+  - type: textarea
+    id: notes
+    attributes:
+      label: Additional notes
+      description: Entitlement details, service names, networking observations, screenshots, or anything else that may help.

CONTRIBUTING.md

@@ -75,16 +75,29 @@ To fix formatting errors, run the following:
 yarn lint --fix
 ```
 
+## iOS physical-device validation
 
+The Apple implementation still needs broader physical-device validation. If you have an Apple Developer account and supported iPhone or iPad hardware, validation reports are valuable even when you do not plan to change the code.
+
+Use the **iOS validation report** issue template when reporting results. Please include:
+
+- the library version, branch, or commit tested;
+- Apple device model and iOS/iPadOS version;
+- the peer device and OS/API level, when applicable;
+- whether you tested iOS-to-iOS or Android-to-iOS behavior;
+- the exact steps performed and whether they passed, failed, or partially passed;
+- relevant Xcode, device-console, Metro, or native logs for failures.
+
+Do not include signing certificates, private keys, provisioning profiles, account identifiers, or other secrets in reports.
 
 ### Scripts
 
 The `package.json` file contains various scripts for common tasks:
 
 - `yarn`: setup project by installing dependencies.
 - `yarn typecheck`: type-check files with TypeScript.
-  - `yarn lint`: lint files with [ESLint](https://eslint.org/).
-    - `yarn example start`: start the Metro server for the example app.
+- `yarn lint`: lint files with [ESLint](https://eslint.org/).
+- `yarn example start`: start the Metro server for the example app.
 - `yarn example android`: run the example app on Android.
 - `yarn example ios`: run the example app on iOS.
 

README.md

@@ -1,8 +1,8 @@
 # react-native-wifi-aware
 
-An open-source React Native library for a modern, capability-aware Wi-Fi Aware (NAN) abstraction.
+A React Native implementation of Wi-Fi Aware, also known as Neighbor Awareness Networking (NAN), for peer-to-peer discovery and communication on Android and iOS.
 
-The project uses a TypeScript TurboModule API with Kotlin on Android and an Objective-C++ bridge for a future Apple implementation. It supports bare React Native; Expo development builds can consume native code, while Expo Go cannot.
+Wi-Fi Aware lets compatible nearby devices discover each other and establish direct connections without joining the same Wi-Fi network or relying on internet connectivity. That makes it useful for offline collaboration, local multiplayer, device-to-device transfer, companion apps, nearby messaging, and other experiences that should work without cloud infrastructure.
 
 ## Status
 
@@ -18,14 +18,33 @@ Apple-compatible connection. See the [roadmap](docs/ROADMAP.md),
 [architecture](docs/ARCHITECTURE.md), and [research notes](docs/README.md)
 before relying on it.
 
-## Installation
+## Help test iOS and interoperability
+
+The iOS implementation still needs physical-device validation. If you have an
+Apple Developer account and supported hardware running iOS or iPadOS 26+, your
+test results would be especially useful.
+
+Current validation goals are:
+
+- iOS-to-iOS discovery and pairing
+- iOS-to-iOS network connections
+- documenting runtime differences or failures that do not appear in simulator builds
+- Android-to-iOS interoperability once the Android framework-paired path is available
+
+To help, clone the repository, run the example app on physical Apple devices,
+configure the required Wi-Fi Aware entitlements and `WiFiAwareServices` entries,
+and report the exact devices, OS versions, test flow, result, and relevant native
+logs in a GitHub issue. Reproduction details and focused pull requests are welcome.
 
+The Apple path should currently be treated as provisional until those physical
+validation gates are complete.
+
+## Installation
 
 ```sh
 npm install react-native-wifi-aware
 ```
 
-
 Native Android permissions supplied by the library merge into the consuming app. Platform availability remains a runtime capability question.
 
 ## Initial API
@@ -73,7 +92,6 @@ yarn prepare
 
 The example app lives in `example/`. For Android device testing, start Metro with `yarn example start`, ensure `adb reverse tcp:8081 tcp:8081` for a USB-connected device, then run `yarn example android`.
 
-
 ## Contributing
 
 - [Development workflow](CONTRIBUTING.md#development-workflow)