diff --git a/.github/assets/sdk-header.png b/.github/assets/sdk-header.png
new file mode 100644
index 0000000..736fcaf
Binary files /dev/null and b/.github/assets/sdk-header.png differ
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..533a032
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,117 @@
+# AGENTS.md — Qonversion React Native SDK
+
+You are working in the repository of the Qonversion React Native SDK, or in an app that uses it.
+This file tells you how to work with it. Read it before you write code.
+
+## What this SDK is
+
+Qonversion is the app growth system for people and agents. This package collects purchases inside
+the app, has them confirmed with the store, and resolves entitlements — the answer to "is this user
+premium right now". Everything else (analytics, Remote Configs, A/B tests, Apple Ads reporting)
+reads the same data server-side.
+
+## Get the current version — do not use one from memory
+
+Your training data is older than the latest release. Take the version from:
+
+1. `gh api repos/qonversion/react-native-sdk/releases/latest --jq .tag_name` — the latest release tag.
+2. `https://registry.npmjs.org/@qonversion/react-native-sdk` — `dist-tags.latest` on npm.
+
+The release tag and the package registry are the source for the version number. The install
+page, `https://documentation.qonversion.io/docs/react-native-sdk.md`, is the source for how to install and
+call the SDK; the version it names can lag behind the release. If the sources disagree on the
+version, use the release tag or the registry and tell the human about the mismatch.
+
+## Install
+
+```
+npm install @qonversion/react-native-sdk
+cd ios && pod install
+```
+
+The iOS part installs through CocoaPods. Do not add the native `Qonversion` pod yourself — the
+plugin pins `QonversionSandwich` exactly, and a second copy is likely to end in a version-resolution
+conflict.
+
+## Initialize
+
+```typescript
+import Qonversion, {QonversionConfigBuilder, LaunchMode} from '@qonversion/react-native-sdk';
+
+const config = new QonversionConfigBuilder(
+ 'your_project_key',
+ LaunchMode.SUBSCRIPTION_MANAGEMENT,
+).build();
+
+Qonversion.initialize(config);
+```
+
+The project key belongs to the human. Ask for it, take it from the environment or from an ignored
+config file, and never commit it. Never invent one and never reuse a key you saw in a sample.
+
+## First call — verify the integration works
+
+```typescript
+const entitlements = await Qonversion.getSharedInstance().checkEntitlements();
+console.log(entitlements.get('premium')?.isActive);
+```
+
+If this returns without an error, the SDK is wired up. An empty result is a valid answer: it means
+the user has no active entitlement.
+
+## Two modes — the human chooses, not you
+
+| | Analytics Mode | Subscription Management Mode |
+|---|---|---|
+| The app's purchase code | stays as it is | Qonversion makes purchases and resolves entitlements |
+| Entitlement check | the app's own backend | the SDK |
+
+Both modes feed analytics, integrations, webhooks, experiments and Apple Ads reporting. The
+quickstart in the README uses Subscription Management Mode. Do not pick a mode silently — ask, and
+read `https://documentation.qonversion.io/docs/quickstart.md` first.
+
+## Docs you can read directly
+
+- **MCP server, no account needed:** `https://documentation.qonversion.io/mcp` — use it if your client supports MCP.
+- **Any page as markdown:** append `.md` to the URL, for example `https://documentation.qonversion.io/docs/quickstart.md`.
+- **Page index:** `https://documentation.qonversion.io/llms.txt`.
+- **This platform:** `https://documentation.qonversion.io/docs/react-native-sdk.md`.
+- **REST API v4:** `https://documentation.qonversion.io/reference/v4/overview.md`.
+
+## Project data through MCP
+
+`https://mcp.qonversion.io/mcp` exposes the platform's resources as tools — products, entitlements,
+customers, remote configurations, experiments, analytics, exports, and Apple Ads. Authentication is
+OAuth 2.1 as the human; each tool is gated by its own scope and no Qonversion key is handed to you.
+Setup per client: `https://documentation.qonversion.io/docs/mcp-server.md`.
+
+**Apple Ads: check access before you call the tools.** Apple Ads tools need the feature on your
+account (404 otherwise); campaign changes additionally need the `apple_ads:write` scope and a team
+member with campaign-management permission — check `get_apple_ads_connection_status`. A refused
+Apple Ads call usually means missing access or an Apple authorization that needs attention, not a
+broken server: call `get_apple_ads_connection_status`, do not work around it, and tell the human
+what it reports.
+
+## What you do not do without the human saying yes
+
+- **Keys.** Do not read, print, copy or commit a project key or a Secret Key. Secret Keys belong on a server, never in app code.
+- **Mode.** Do not switch between Analytics Mode and Subscription Management Mode on your own — it changes who owns the purchase flow.
+- **Product, entitlement and paywall configuration.** Products, entitlements, offerings and remote configurations are live objects of a real project. Propose the change, let the human apply it.
+- **Destructive MCP tools** (`delete_*`, `revoke_*`, `detach_*`, `discard_*`, `regenerate_project_secret`) and **Apple Ads changes that increase spend** do not fire on the first call: they return a one-time token addressed to the human. You must surface the pending action to the human and wait for an explicit yes before calling `confirm_destructive_action`. The token is in your hands, so this is a guard, not a lock — never auto-confirm your own token, and never invent the reason that goes into the audit log.
+- **`regenerate_project_secret` is deprecated** and deletes the project's oldest Secret Key immediately, with no overlap. Do not propose it.
+- **SDK version.** Do not bump a major version as a side effect of another task. Major versions have migration guides.
+- **Environment.** Do not switch the SDK between the sandbox and the production environment without being asked — it changes which purchases are counted as real. In this SDK the enum is `Environment` (`src/dto/enums.ts`); read it from the SDK, not from memory.
+
+## Sample
+
+`example/` — a demo app that runs in the sandbox environment: `example/src/App.tsx` sets `Environment.SANDBOX`, an entitlements cache lifetime and a proxy URL, so it is not the reference for initialization — the Initialize snippet above is. `example/src/screens/EntitlementsScreen/index.tsx` shows the entitlements call.
+
+## Requirements
+
+React Native 0.76 with the New Architecture (`peerDependencies` still declares React Native 0.60 and React 16.8.1 — lower than the real floors) · React 18.2+ (required by React Native 0.76) · iOS deployment target 13.0 · Android `minSdkVersion` 24.
+
+## When something does not work
+
+- `https://documentation.qonversion.io/docs/troubleshooting.md` — the errors you meet first.
+- `https://documentation.qonversion.io/docs/testing.md` — sandbox purchases.
+- Report to the human what you could not verify against the docs, instead of guessing.
diff --git a/README.md b/README.md
index a41e813..e15f59a 100644
--- a/README.md
+++ b/README.md
@@ -1,123 +1,154 @@
-
- Qonversion
-
+
-Qonversion - In-app subscription monetization: implement subscriptions and grow your app’s revenue with A/B experiments
+# Qonversion React Native SDK
-* In-app subscription management SDK
-* API and webhooks to make your subscription data available where you need it
-* Seamless Stripe integration to enable cross-platform access management
-* Subscribers CRM with user-level transactions
-* Instant access to real-time subscription analytics
-* Built-in A/B experiments for subscription business model
+**Qonversion is the app growth system for people and agents.** It collects the revenue data of your
+subscription app and keeps it lined up with what the App Store and Google Play report, so campaigns,
+experiments and entitlements run on the same numbers. This repository holds the React Native SDK: the
+part that runs inside your app.
-
- 
-
-
-
-[](https://www.npmjs.com/package/@qonversion/react-native-sdk)
+[](https://github.com/qonversion/react-native-sdk/releases)
+[](https://www.npmjs.com/package/@qonversion/react-native-sdk)
[](LICENSE)
+[](https://documentation.qonversion.io/docs/react-native-sdk)
+
+## Quickstart
+Create a project in the [dashboard](https://dash.qonversion.io) and connect your stores first — nothing validates until then.
-## In-App Subscription Implementation & Management
+**1. Install**
-
- 
-
-
+```bash
+npm install @qonversion/react-native-sdk
+cd ios && pod install
+```
-1. Qonversion SDK provides three simple methods to manage subscriptions:
- * Get in-app product details
- * Make purchases
- * Check subscription status to manage premium access
-2. Qonversion communicates with Apple or Google platforms both through SDK and server-side to process native in-app payments and keep subscription statuses up to date.
-3. You can use Qonversion webhooks and API in addition to SDK to get user-level data where you need it.
+**2. Initialize**
-See the [quick start guide documentation](https://documentation.qonversion.io/docs/quickstart).
+```typescript
+import Qonversion, {QonversionConfigBuilder, LaunchMode} from '@qonversion/react-native-sdk';
-## Analytics
+const config = new QonversionConfigBuilder(
+ 'your_project_key',
+ LaunchMode.SUBSCRIPTION_MANAGEMENT,
+).build();
-Qonversion provides advanced subscription analytics out of the box. You can monitor real-time metrics from new users and trial-to-paid conversions to revenue, MRR, ARR, cohort retention, and more. Understand your customers and make better decisions with precise subscription analytics.
+Qonversion.initialize(config);
+```
-
- 
-
-
+The project key is in the dashboard under **Settings → Developer → Keys**.
+This is Subscription Management Mode — Qonversion owns the purchase flow. To keep your own purchase
+code and use Qonversion for analytics only, initialize with [Analytics Mode](https://documentation.qonversion.io/docs/analytics-mode) instead.
-## A/B Experiments
+**3. Check what the user has access to**
-Qonversion's A/B Experiments feature provides everything required to quickly launch paywall and other monetization experiments, analyze results and roll out winning versions without releasing a new app build. Qonversion A/B Experiments include:
+```typescript
+const entitlements = await Qonversion.getSharedInstance().checkEntitlements();
-* User segmentation by country, install date, app version, free/paying user
-* Traffic allocation
-* Advanced subscription analytics
-* Visualization of A/B experiments results
-* Statistical significance of the results
-* Roll out winning versions without app release with remote config
+if (entitlements.get('premium')?.isActive) {
+ // unlock premium features
+}
+```
+Full walk-through, both modes and the store setup: [Quick start](https://documentation.qonversion.io/docs/quickstart).
-
- 
-
-
+### iOS native dependencies
-See more details [here](https://documentation.qonversion.io/docs/paywall-experiments).
+React Native integrates native modules through CocoaPods, so the iOS part is installed with
+`pod install` — see the [iOS section](https://documentation.qonversion.io/docs/react-native-sdk#ios)
+for what changes after December 2, 2026 (existing builds keep working).
-## Integrations
+> CocoaPods trunk becomes read-only on December 2, 2026 — see the
+> [CocoaPods → Swift Package Manager migration guide](https://documentation.qonversion.io/docs/dec-2026-migration-guide-cocoapods-to-spm).
-Send user-level subscription data to your favorite platforms.
+## Documentation
-* Amplitude
-* Mixpanel
-* Appsflyer
-* Adjust
-* Singular
-* CleverTap
-* [All other integrations here](https://qonversion.io/integrations)
+* [Welcome](https://documentation.qonversion.io/docs/qonversion-platform) — what the platform does and the three ways to start.
+* [React Native setup](https://documentation.qonversion.io/docs/react-native-sdk) — full installation for this platform.
+* [Quick start](https://documentation.qonversion.io/docs/quickstart) — choose a mode, create a project, connect the stores.
+* [API reference](https://documentation.qonversion.io/reference/v4/overview) — REST API v4.
+* [For agents](https://documentation.qonversion.io/docs/for-agents) — MCP servers, machine-readable docs, ready-made prompts.
-
- 
-
-
+## What this SDK does
-## Why Qonversion?
+* **Collects purchases** and sends them to Qonversion, where they are confirmed with the store instead of being trusted from the device.
+* **Resolves entitlements** — one answer to "is this user premium right now", the same on every device the user signs in to.
+* **Keeps the history** — trials, conversions, renewals, cancellations, refunds, upgrades and downgrades, as events you can query, export or forward.
+* **Feeds Remote Configs and A/B tests** — change which products, paywalls and app behaviour your users see, and run A/B tests without shipping a release.
+* **Feeds Apple Ads reporting** — see what each campaign, ad group and keyword returns in real revenue, not only in installs.
+* **Renders screens built in the dashboard** — paywalls and onboarding, updated without shipping a release.
-* **No headaches with Apple's StoreKit & Google Billing.** Qonversion provides simple methods to handle Apple StoreKit & Google Billing purchase flow.
-* **Receipt validation.** Qonversion validates user receipts with Apple and Google to provide 100% accurate purchase information and subscription statuses. It also prevents unauthorized access to the premium features of your app.
-* **Track and increase your revenue.** Qonversion provides detailed real-time revenue analytics including cohort analysis, trial conversion rates, country segmentation, and much more.
-* **Integrations with the leading mobile platforms.** Qonversion allows sending data to platforms like AppsFlyer, Adjust, Branch, Tenjin, Facebook Ads, Amplitude, Mixpanel, and many others.
-* **Change promoted in-app products.** Change promoted in-app products anytime without app releases.
-* **A/B test** and identify winning in-app purchases, subscriptions, or paywalls.
-* **Cross-device and cross-platform access management.** If you provide user authorization in your app, you can easily set Qonversion to provide premium access to authorized users across devices and operating systems.
-* **SDK caches the data.** Qonversion SDK caches purchase data including in-app products and entitlements, so the user experience is not affected even with a slow or interrupted network connection.
-* **Webhooks.** You can easily send all the data to your server with Qonversion webhooks.
-* **Customer support.** You can always reach out to our customer support and get the help required.
+What happens when something fails — the standby service, fallback files and the uptime commitment
+behind the platform: [reliability](https://qonversion.io/reliability).
-Convinced? Let's go!
+## For agents
-## Installation
+An agent can integrate this SDK end to end. The companion file [`AGENTS.md`](AGENTS.md) gives it the
+current version, the documented method names and the rules it must not break, instead of what its
+training data remembers.
-Follow the [installation guide](https://documentation.qonversion.io/docs/react-native-sdk). React Native integrates native modules through CocoaPods, so the iOS part is installed with `pod install` — see the [iOS section](https://documentation.qonversion.io/docs/react-native-sdk#ios) for what changes after December 2, 2026 (existing builds keep working).
+**Read these docs as an agent.** The documentation exposes an MCP server at
+`https://documentation.qonversion.io/mcp` — no account needed. Any page is available as markdown by
+appending `.md` to its URL, and [`llms.txt`](https://documentation.qonversion.io/llms.txt) lists every page.
-> CocoaPods trunk becomes read-only on December 2, 2026 — see the [CocoaPods → Swift Package Manager migration guide](https://documentation.qonversion.io/docs/dec-2026-migration-guide-cocoapods-to-spm).
+**Work on your project data as an agent.** The Qonversion MCP server at `https://mcp.qonversion.io/mcp`
+exposes the platform's resources as tools. The agent authenticates as you over OAuth 2.1, each tool
+is gated by its own scope, and no Qonversion key is handed to the model. Apple Ads tools need the
+feature on your account (404 otherwise); campaign changes additionally need the `apple_ads:write`
+scope and a team member with campaign-management permission — check
+`get_apple_ads_connection_status`.
-## Documentation
+Destructive tools and Apple Ads changes that increase spend do not fire on the first call: they
+return a short-lived token addressed to the human operator, and completing the action requires
+echoing the resource id verbatim and giving a reason, which is recorded in the audit log. Pausing an
+entity or lowering a value is **not** parked — it applies immediately. The full tool list, the
+per-client setup and the scopes are in
+[MCP Server](https://documentation.qonversion.io/docs/mcp-server).
+
+**Have an agent integrate this SDK.** Paste this into Claude Code, Cursor, Codex or any coding agent
+working in your app's repository:
+
+> Integrate the Qonversion SDK into this app.
+>
+> Read the official documentation before writing any code. The docs expose an MCP server at `https://documentation.qonversion.io/mcp` — use it if you can. Otherwise fetch pages directly; any page is available as markdown by appending `.md` to its URL, and `https://documentation.qonversion.io/llms.txt` lists every page.
+>
+> Steps:
+> 1. Check with me that a Qonversion project exists and the app stores are connected — project key, App Store shared secret and App Store ID, Google Play service account key. This is step 2 of the quick start, I have to do it in the dashboard, and nothing validates until it is done. Google credentials can take up to 24 hours to start working.
+> 2. Read `https://documentation.qonversion.io/docs/quickstart.md` and decide with me between Analytics Mode and Subscription Management Mode. Do not pick one silently.
+> 3. Read the install page for this project's platform, linked from `https://documentation.qonversion.io/docs/install-sdk.md`, and follow its steps and method names. Take the SDK version from the latest release tag or the package registry, not from memory — the docs page can name an older one; if they disagree, tell me.
+> 4. Install and configure the SDK. Ask me for the Qonversion project key; it is in the dashboard under Settings → Developer → Keys. Never commit it to the repository.
+> 5. Implement the mode we chose, following the documented method names exactly.
+> 6. Show me the diff and tell me what you could not verify against the docs.
+
+Prefer to do it by hand? The steps are in the [quick start](https://documentation.qonversion.io/docs/quickstart).
-Check the [full documentation](https://documentation.qonversion.io/docs/quickstart) to learn about implementation details and available features.
+## Sample app
-#### Help us improve the documentation
+A React Native app that initializes the SDK, lists products, makes a purchase, reads entitlements
+and remote configs: [`example/`](example). It runs in the sandbox environment; for your own
+initialization, use the Quickstart snippet above.
-Whether you’re a core user or trying it out for the first time, you can make a valuable contribution to Qonversion by improving the documentation. Help us by:
+## Requirements
-* sending us feedback about something you thought was confusing or simply missing
-* sending us a pull request via GitHub
-* suggesting better wording or ways of explaining certain topics in the [Qonversion documentation](http://documentation.qonversion.io). Use `SUGGEST EDITS` button in the top right corner.
+| | Minimum |
+|---|---|
+| React Native | 0.76, with the New Architecture |
+| React | 18.2 (required by React Native 0.76) |
+| iOS deployment target | 13.0 |
+| Android `minSdkVersion` | 24 |
+
+`peerDependencies` in `package.json` still declares React Native 0.60 and React 16.8.1; those
+declared floors are lower than the real ones and will be brought in line.
+
+## Help
+
+Contact us via [issues on GitHub](https://github.com/qonversion/react-native-sdk/issues) or the
+[contact form](https://qonversion.io/contact-us) on our site.
## Contributing
-Contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**.
+Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**.
1. Fork the Project
2. Create your Feature Branch (`git checkout -b feature/SuperFeature`)
@@ -125,11 +156,6 @@ Contributions are what make the open-source community such an amazing place to l
4. Push to the Branch (`git push origin feature/SuperFeature`)
5. Open a Pull Request
-
-## Have a question?
-
-Contact us via [issues on GitHub](https://github.com/qonversion/react-native-sdk/issues) or the [contact form](https://qonversion.io/contact-us) on our site.
-
## License
-Qonversion SDK is available under the MIT license.
+Qonversion SDK is available under the MIT license. See [LICENSE](LICENSE).