docs: document setup, configuration and platform differences

Covers the per-build-type Gradle fallback, the central-repository opt-out, the
arm-only ABI constraint that breaks x86 emulators, and the Android theming
path, none of which are discoverable from the API surface.

README.md

 # myid-sdk
 
-React Native wrapper for the MyID identity verification SDK
+React Native wrapper for the [MyID](https://myid.uz) identity verification SDK.
 
-## Installation
+Wraps MyID Android `3.1.9` and iOS `3.1.3` behind one promise-based API.
+
+```ts
+const result = await start({
+  config: { sessionId, clientHash, clientHashId },
+});
+```
+
+## Requirements
+
+| | |
+|---|---|
+| React Native | New Architecture enabled (`newArchEnabled=true`, the default since 0.76). Verified against 0.86.2. |
+| Android | `minSdkVersion` 24+, `compileSdk` 36 |
+| iOS | Deployment target 13.0+ |
+
+`sessionId` is issued by **your backend** through the MyID API. This library
+never talks to the MyID backend itself — it only launches the SDK.
 
+## Installation
 
 ```sh
 npm install myid-sdk
+# or
+yarn add myid-sdk
+```
+
+### iOS
+
+```sh
+cd ios && pod install
 ```
 
+Add a camera usage description to `ios/<YourApp>/Info.plist` — the app is
+rejected at review without it, and the SDK cannot capture a face:
+
+```xml
+<key>NSCameraUsageDescription</key>
+<string>Camera is used to verify your identity.</string>
+```
+
+### Android
+
+No Gradle changes are needed in the common case. MyID artifacts are not on Maven
+Central, so this library registers the two required repositories
+(`artifactory.aigroup.uz` for the SDK, `developer.huawei.com` for the Huawei
+integrity dependency) on all projects. Both are publicly readable — no
+credentials, no tokens.
+
+See [Android troubleshooting](#android-troubleshooting) if your app manages
+repositories centrally or defines custom build types.
 
 ## Usage
 
+```tsx
+import { start, isMyIdError, MyIdErrorCode } from 'myid-sdk';
+
+async function verify() {
+  try {
+    const result = await start({
+      config: {
+        sessionId,       // from your backend
+        clientHash,      // from the MyID sales team
+        clientHashId,
+        environment: 'PRODUCTION',
+        locale: 'UZBEK',
+      },
+      iosAppearance: {
+        colorPrimary: '#2F6FED',
+        buttonCornerRadius: 12,
+      },
+    });
+
+    // result.code === '100' on success
+    // result.base64 is a base64 JPEG portrait, without a data-URI prefix
+    return result;
+  } catch (error) {
+    if (isMyIdError(error) && error.code === MyIdErrorCode.USER_CANCELLED) {
+      return null; // user backed out — usually not worth surfacing
+    }
+
+    throw error;
+  }
+}
+```
 
-```js
-import { multiply } from 'myid-sdk';
+`start()` rejects for **every** non-success path, including the user simply
+dismissing the flow. Always handle `101`.
+
+## Configuration
+
+Only `sessionId`, `clientHash` and `clientHashId` are required. Every omitted
+option keeps the SDK's own default — this library never substitutes one of its
+own. Options not supported by a platform are ignored there rather than throwing.
+
+| Option | Values | Default | Platform |
+|---|---|---|---|
+| `sessionId` | string | — | both |
+| `clientHash` | string | — | both |
+| `clientHashId` | string | — | both |
+| `minAge` | number | `16` | both |
+| `distance` | number (0..1) | `0.65` android / `0.60` ios | both |
+| `residency` | `USER_DEFINED` `RESIDENT` `NON_RESIDENT` | `RESIDENT` | both |
+| `environment` | `PRODUCTION` `DEBUG` | `PRODUCTION` | both |
+| `entryType` | `IDENTIFICATION` `VIDEO_IDENTIFICATION` `FACE_DETECTION` | `IDENTIFICATION` | both |
+| `locale` | `UZBEK` `UZBEK_CYRILLIC` `KARAKALPAK` `TAJIK` `ENGLISH` `RUSSIAN` | `UZBEK` | see note |
+| `cameraShape` | `CIRCLE` `ELLIPSE` | `CIRCLE` | both |
+| `cameraSelector` | `FRONT` `BACK` | `FRONT` | both |
+| `cameraResolution` | `LOW` `HIGH` | `LOW` | android |
+| `imageFormat` | `JPEG` `PNG` | `PNG` | android |
+| `screenOrientation` | `PORTRAIT` `LANDSCAPE` `FULL` | `PORTRAIT` | android |
+| `withSoundGuides` | boolean | SDK default | android |
+| `huaweiAppId` | string | — | android |
+| `presentationStyle` | `SHEET` `FULL` | `FULL` | ios |
+| `showErrorScreen` | boolean | `true` | both |
+| `organizationDetails` | `{ phone, logo }` | — | both |
+
+**Locale note.** iOS supports only `UZBEK`, `ENGLISH` and `RUSSIAN`.
+`UZBEK_CYRILLIC`, `KARAKALPAK` and `TAJIK` fall back to `UZBEK` there.
+
+**`VIDEO_IDENTIFICATION`** is marked experimental by the Android SDK. Treat it
+as unstable.
+
+**`organizationDetails.logo`** is the name of a *native* asset — an Android
+drawable or an iOS image set — not a path, URL or `require()`. It should fit
+roughly 240x60. `phone` replaces MyID's call-centre number on the error screen.
+
+## Theming
+
+iOS theming is runtime, via `iosAppearance`:
+
+`colorPrimary`, `colorOnPrimary`, `colorError`, `colorOnError`, `colorOutline`,
+`colorDivider`, `colorSuccess`, `colorButtonContainer`,
+`colorButtonContainerDisabled`, `colorButtonContent`,
+`colorButtonContentDisabled`, `colorScanButtonContainer` (all `#RRGGBB` or
+`RRGGBB`), plus `buttonCornerRadius`.
+
+Android theming is **not** runtime — the Android SDK is themed by overriding its
+resources. Declare the same names in your app to replace them:
+
+```xml
+<!-- android/app/src/main/res/values/myid_colors.xml -->
+<resources>
+  <color name="myid_color_primary">#2F6FED</color>
+</resources>
+```
 
-// ...
+`iosAppearance` is ignored on Android.
 
-const result = multiply(3, 7);
+## Error codes
+
+Rejections are `MyIdError` with a string `code`.
+
+| Code | Meaning |
+|---|---|
+| `100` | Success (returned as `result.code`, not an error) |
+| `101` | User cancelled the flow |
+| `102` | Camera permission denied |
+| `103` | SDK, server or wrapper failure |
+| `122` | User banned |
+
+The SDK also emits liveness advice codes (`3`, `14`, `20`–`28`). Compare against
+`error.code` directly rather than assuming the list above is exhaustive — see the
+[MyID error code docs](https://docs.myid.uz/#/ru/embedded?id=javob-kodlar-uz-result_code).
+
+```ts
+import { MyIdError, isMyIdError, MyIdErrorCode } from 'myid-sdk';
 ```
 
+## Android troubleshooting
 
-## Contributing
+**The app defines build types other than `debug`/`release`.**
+This library ships a non-obfuscated debug artifact and an obfuscated release
+one, wired per build type. Custom build types fail to resolve unless they
+declare a fallback:
 
-- [Development workflow](CONTRIBUTING.md#development-workflow)
-- [Sending a pull request](CONTRIBUTING.md#sending-a-pull-request)
-- [Code of conduct](CODE_OF_CONDUCT.md)
+```gradle
+buildTypes {
+  staging {
+    initWith release
+    matchingFallbacks = ["release"]
+  }
+}
+```
 
-## License
+**The app manages repositories centrally.**
+If your `settings.gradle` sets `repositoriesMode = FAIL_ON_PROJECT_REPOS`, this
+library's repository registration will be rejected. Opt out and declare them
+yourself:
 
-MIT
+```properties
+# android/gradle.properties
+myIdSkipRepositoryInjection=true
+```
+
+```gradle
+// android/settings.gradle
+dependencyResolutionManagement {
+  repositories {
+    maven { url "https://artifactory.aigroup.uz/artifactory/myid/" }
+    maven { url "https://developer.huawei.com/repo/" }
+  }
+}
+```
+
+**The app crashes on an emulator.**
+The MyID SDK ships native libraries for `arm64-v8a` and `armeabi-v7a` only. On an
+x86/x86_64 emulator the app installs but crashes when the SDK loads its native
+library. Test on a physical device or an arm64 emulator image.
+
+**Pinning a different SDK version.**
+
+```gradle
+// android/build.gradle
+ext { myIdCaptureSdkVersion = "3.1.9" }
+```
+
+**Huawei devices.** Devices without Google Play Services need a Huawei App ID.
+The integrity dependency is already included transitively — pass `huaweiAppId`
+and add the App ID from AppGallery Connect to your manifest:
+
+```xml
+<meta-data android:name="com.huawei.hms.client.appid" android:value="appid=YOUR_ID" />
+```
+
+## iOS troubleshooting
+
+**`use_frameworks!`.** `MyIdSDK` is distributed as a binary XCFramework and works
+under both static and dynamic linkage.
 
----
+**The SDK does not appear.** It presents from the key window's root view
+controller. If your app already has a modal presented, dismiss it before calling
+`start()`.
 
-Made with [create-react-native-library](https://github.com/callstack/react-native-builder-bob)
+## Example
+
+The `example/` app in this repository is a runnable demo. Credentials are typed
+in at runtime rather than committed.
+
+```sh
+yarn
+yarn example ios      # or: yarn example android
+```
+
+## License
+
+MIT

package.json

@@ -41,7 +41,15 @@
   "keywords": [
     "react-native",
     "ios",
-    "android"
+    "android",
+    "myid",
+    "identity",
+    "verification",
+    "kyc",
+    "biometric",
+    "face-recognition",
+    "uzbekistan",
+    "turbo-module"
   ],
   "repository": {
     "type": "git",