docs: document native v4/v3 adoption — linking, claim validation, build floors

Covers the consumer-facing docs carved out of SDK-10039/SDK-10040 (SDK-10615):

- README: correct iOS floor to 15.1 (min_ios_version_supported), state
  Android minSdk 26 / compileSdk 36 / JDK 17, and make the Expo requirement
  consistently SDK 55 for v6.
- README: add iOS use_frameworks! linkage guidance. Verified by building the
  example app under both USE_FRAMEWORKS=static and =dynamic (pod install + iOS
  simulator build succeeded in each).
- MIGRATION_GUIDE §9: document the opt-in ID-token claim validation state on
  direct token requests, with per-flow accuracy (passkey signin validates on
  both platforms; passkey signup, Custom Token Exchange, MFA, passwordless
  validate on neither — deliberate iOS/Android parity).

SDK-10615

Author: NandanPrabhu

MIGRATION_GUIDE.md

@@ -235,6 +235,21 @@ Two codes were added for the new Auth0.swift cases, both iOS-only: `AUTHENTICATI
 
 `SSO_EXCHANGE_FAILED` (iOS and Android) and `CLEAR_FAILED` (iOS) are now reported instead of being collapsed into a generic credentials-manager error. No action is required unless you exhaustively match on these codes.
 
+#### ID-token claim validation is now opt-in on direct token requests
+
+Auth0.swift 3.0 made ID-token claim validation **opt-in** on `TokenRequestable` (`.validateClaims()`), matching the long-standing behaviour on Auth0.Android. Web Authentication (`authorize()`) is unaffected — the browser-based flow still validates the ID token internally on both platforms. What changed is only the **direct token-request** paths, where the SDK now opts in per flow. The current state is:
+
+| Flow                               | ID-token claims validated? |
+| :--------------------------------- | :------------------------: |
+| Web Authentication (`authorize()`) |    ✅ (both platforms)     |
+| Passkey **signin**                 |    ✅ (both platforms)     |
+| Passkey **signup**                 |    ❌ (both platforms)     |
+| Custom Token Exchange              |    ❌ (both platforms)     |
+| MFA challenge/verify               |    ❌ (both platforms)     |
+| Passwordless                       |    ❌ (both platforms)     |
+
+The `❌` rows are **deliberate iOS/Android parity**, not an oversight — these flows validate on neither platform, so behaviour is identical everywhere. No action is required; this is documented so you know exactly which responses carry a validated ID token.
+
 ### 10. Interfaces no longer use the `I` prefix ✅
 
 The platform contracts in `src/core/interfaces/` dropped their `I` prefix, so the interface now takes the plain name and the implementations keep their platform prefix (`Auth0Client` is the contract; `NativeAuth0Client` and `WebAuth0Client` implement it).

README.md

@@ -36,23 +36,25 @@ This SDK targets apps that are using React Native SDK version `0.82.0` and up. I
 
 React Native `0.82` is the first React Native release that runs **entirely on the New Architecture**. As of v6, this SDK is **New Architecture-only** — the Legacy Architecture is no longer supported. If your app has not yet moved to the New Architecture, upgrade to React Native `0.82`+ or stay on v5.x. For Expo, this SDK requires **Expo SDK 55 or higher** (Expo 54 ships React Native `0.81`, below the `0.82` floor).
 
-> ⚠️ **Warning**: If you are using Expo version less than 53, you need to use react-native-auth0 version 4.x or earlier. Version 5.x supports Expo 53 and above.
+> ⚠️ **Warning**: For Expo, this version requires **Expo SDK 55 or higher** (Expo 54 ships React Native `0.81`, below the `0.82` floor). If you are on an earlier Expo version, upgrade Expo or stay on react-native-auth0 `5.x` (Expo 53–54) or `4.x` (below Expo 53).
 
 ### Platform compatibility
 
 The following shows platform minimums for running projects with this SDK:
 
-| Platform | Minimum version |
-| -------- | :-------------: |
-| iOS      |      14.0       |
-| Android  |       35        |
+| Platform |   Minimum version    |
+| -------- | :------------------: |
+| iOS      |         15.1         |
+| Android  | API 26 (Android 8.0) |
 
-Our SDK requires a minimum iOS deployment target of 14.0. In your project's ios/Podfile, ensure your platform target is set to 14.0.
+**iOS.** This SDK requires a minimum iOS deployment target of `15.1`, inherited from the React Native `0.82`+ Pods (`min_ios_version_supported`). In your project's `ios/Podfile`, set the platform accordingly — following the older `14.0` value will fail `pod install`:
 
-```
-platform :ios, '14.0'
+```ruby
+platform :ios, '15.1'
 ```
 
+**Android.** This SDK requires **`minSdkVersion` 26** (Android 8.0). It compiles against **`compileSdkVersion` 36** and must be built with **JDK 17**. Raise these in your app's `android/build.gradle` (and verify your toolchain with `java -version`) if you are coming from an earlier setup. See the [Migration Guide](https://github.com/auth0/react-native-auth0/blob/master/MIGRATION_GUIDE.md) for details.
+
 The iOS pod ships a privacy manifest (`PrivacyInfo.xcprivacy`) that declares no tracking, no required-reason API usage, and a user identifier collected only for app functionality. Xcode includes it automatically when you generate a privacy report, so you don't have to describe this SDK's behavior yourself. You are still responsible for reviewing that report and for keeping your App Store Connect privacy answers accurate for your app as a whole, including the data this SDK collects.
 
 ### Installation
@@ -71,6 +73,26 @@ Then, you need to run the following command to install the ios app pods with Coc
 
 `$ cd ios && pod install`
 
+#### iOS framework linkage (`use_frameworks!`)
+
+This SDK's native dependencies — Auth0 3.0.1, JWTDecode 4.0.0, and SimpleKeychain 1.3.0 — are Swift pods. They install with the default React Native static-library linkage (no `use_frameworks!`), so **most apps need no extra Podfile changes**.
+
+If your project requires `use_frameworks!` (for example, because another dependency ships as a framework), both linkage modes are supported — this was verified by building the example app under each:
+
+```ruby
+# Static frameworks
+use_frameworks! :linkage => :static
+
+# ...or dynamic frameworks
+use_frameworks! :linkage => :dynamic
+```
+
+No additional `post_install` step is required for this SDK beyond what React Native already generates. After changing linkage, run a clean install:
+
+```bash
+cd ios && rm -rf Pods Podfile.lock && pod install --repo-update
+```
+
 ### Configure the SDK
 
 You need to make your Android, iOS or Expo applications aware that an authentication result will be received from the browser. This SDK makes use of the Android's Package Name and its analogous iOS's Product Bundle Identifier to generate the redirect URL. Each platform has its own set of instructions.
@@ -679,12 +701,12 @@ instead — for example [Custom Token Exchange](EXAMPLES.md#custom-token-exchang
 the raw OAuth error from the token endpoint — don't get a normalized `type`; there, `code` is the
 correct (and only) thing to switch on.
 
-| Property  | Use it for                                                                                                                                             |
-| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `type`    | **Control flow** for the six normalized subclasses. A normalized code, stable across platforms. Compare against the `…ErrorCodes` constants.             |
+| Property  | Use it for                                                                                                                                                                                                   |
+| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `type`    | **Control flow** for the six normalized subclasses. A normalized code, stable across platforms. Compare against the `…ErrorCodes` constants.                                                                 |
 | `code`    | **Diagnostics** for the normalized subclasses (raw code from the underlying platform SDK or wire response, varies by platform); **control flow** for plain `AuthError` flows that have no normalized `type`. |
-| `message` | Human-readable description. Not stable — do not parse it.                                                                                                 |
-| `status`  | HTTP status, when the failure came from an HTTP response (`0` otherwise).                                                                                 |
+| `message` | Human-readable description. Not stable — do not parse it.                                                                                                                                                    |
+| `status`  | HTTP status, when the failure came from an HTTP response (`0` otherwise).                                                                                                                                    |
 
 Each of the six normalized classes ships a companion constants object and a matching TypeScript
 union. Handle every value explicitly (no `default` branch) and TypeScript enforces exhaustiveness