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..a29e40d
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,125 @@
+# AGENTS.md — Qonversion Unity SDK
+
+You are working in the repository of the Qonversion Unity 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/unity-sdk/releases/latest --jq .tag_name` — the latest release tag.
+2. `https://package.openupm.com/com.qonversion.unity` — `dist-tags.latest` on OpenUPM.
+
+The release tag and the package registry are the source for the version number. The install
+page, `https://documentation.qonversion.io/docs/unity-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
+
+```
+openupm add com.qonversion.unity
+# or, in Packages/manifest.json:
+"com.qonversion.unity": "https://github.com/qonversion/unity-sdk.git#9.11.0"
+```
+
+`9.11.0` is current at the time of writing; for the Git URL take the latest tag from the releases.
+
+Native dependencies come from the External Dependency Manager for Unity (EDM4U). Without EDM4U in
+the project the native modules are not installed and the build fails. On EDM4U 1.2.189+ the iOS
+part links as a Swift package; older EDM4U versions fall back to CocoaPods.
+
+## Initialize
+
+```csharp
+using QonversionUnity;
+
+var config = new QonversionConfigBuilder(
+ "your_project_key",
+ LaunchMode.SubscriptionManagement
+).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
+
+```csharp
+using UnityEngine;
+
+Qonversion.GetSharedInstance().CheckEntitlements((entitlements, error) =>
+{
+ if (error != null) return;
+ Debug.Log(entitlements.TryGetValue("premium", out var p) && p.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/unity-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` (`Runtime/Scripts/Dto/Environment.cs`); read it from the SDK, not from memory.
+
+## Sample
+
+The sample project lives in a separate repository, `https://github.com/qonversion/unity-sdk-sample` (`Assets/Scripts/SampleApp.cs`). It loads the SDK from a sibling checkout (`file:../../unity-sdk`), so clone this repository next to it. It runs in the sandbox environment, so it is not the reference for initialization — the Initialize snippet above is. The public surface is declared in `Runtime/Scripts/IQonversion.cs` in this repository; read it before calling a method you are unsure about.
+
+## Requirements
+
+Unity 2021.3 (the `unity` field in `package.json` still says 2018.3 — older versions are not supported or tested) · EDM4U 1.2.189 for the Swift Package Manager path · iOS deployment target 13.0 · Android `minSdkVersion` 23.
+
+## 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 d298794..5fd7a0f 100644
--- a/README.md
+++ b/README.md
@@ -1,119 +1,159 @@
-
- Qonversion
-
+
-Qonversion - In-app subscription monetization: implement subscriptions and grow your app’s revenue with A/B experiments
+# Qonversion Unity 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 Unity SDK: the
+part that runs inside your app.
-
- 
-
-
-
-[](https://openupm.com/packages/com.qonversion.unity/)
+[](https://github.com/qonversion/unity-sdk/releases)
+[](https://openupm.com/packages/com.qonversion.unity/)
[](LICENSE)
+[](https://documentation.qonversion.io/docs/unity-sdk)
+## Quickstart
-## In-App Subscription Implementation & Management
-
-
- 
-
-
-
-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.
-
-See the [quick start guide documentation](https://documentation.qonversion.io/docs/quickstart).
-
-## Analytics
-
-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.
-
-
- 
-
-
+Create a project in the [dashboard](https://dash.qonversion.io) and connect your stores first — nothing validates until then.
+**1. Install**
-## A/B Experiments
+```bash
+openupm add com.qonversion.unity
+```
-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:
+Or by Git URL in `Packages/manifest.json`: `"com.qonversion.unity": "https://github.com/qonversion/unity-sdk.git#9.11.0"` — current at the time of writing; take the latest tag from [Releases](https://github.com/qonversion/unity-sdk/releases).
+Native dependencies are resolved by the External Dependency Manager for Unity (EDM4U) — it must be
+in the project, otherwise the native modules are not installed and the build fails.
-* 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
+**2. Initialize**
+```csharp
+using QonversionUnity;
-
- 
-
-
+var config = new QonversionConfigBuilder(
+ "your_project_key",
+ LaunchMode.SubscriptionManagement
+).Build();
-See more details [here](https://documentation.qonversion.io/docs/paywall-experiments).
+Qonversion.Initialize(config);
+```
-## Integrations
+The project key is in the dashboard under **Settings → Developer → Keys**.
-Send user-level subscription data to your favorite platforms.
+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.
-* Amplitude
-* Mixpanel
-* Appsflyer
-* Adjust
-* Singular
-* CleverTap
-* [All other integrations here](https://qonversion.io/integrations)
+**3. Check what the user has access to**
-
- 
-
-
+```csharp
+Qonversion.GetSharedInstance().CheckEntitlements((entitlements, error) =>
+{
+ if (error != null) return;
-## Why Qonversion?
+ if (entitlements.TryGetValue("premium", out var premium) && premium.IsActive)
+ {
+ // unlock premium features
+ }
+});
+```
-* **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 the slow or interrupting network connection.
-* **Webhooks.** You can easily send all of the data to your server with Qonversion webhooks.
-* **Customer support.** You can always reach out to our customer support and get the help required.
+Full walk-through, both modes and the store setup: [Quick start](https://documentation.qonversion.io/docs/quickstart).
-Convinced? Let's go!
+### iOS native dependencies
-## Installation
+With EDM4U 1.2.189 and newer the iOS part is linked as a Swift package; older EDM4U versions fall
+back to CocoaPods — see
+[Install Native Dependencies](https://documentation.qonversion.io/docs/unity-sdk#install-native-dependencies).
-Follow the [installation guide](https://documentation.qonversion.io/docs/unity-sdk). Native dependencies are resolved by the External Dependency Manager for Unity (EDM4U); with EDM4U 1.2.189+ on Unity 2021.3+ the iOS part is linked as a Swift package, older setups fall back to CocoaPods — see [Install Native Dependencies](https://documentation.qonversion.io/docs/unity-sdk#install-native-dependencies).
-
-> 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).
+> 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).
## Documentation
-Check the [full documentation](https://documentation.qonversion.io/docs/quickstart) to learn about implementation details and available features.
-
-#### Help us improve the documentation
-
-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:
-
-* 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.
+* [Welcome](https://documentation.qonversion.io/docs/qonversion-platform) — what the platform does and the three ways to start.
+* [Unity setup](https://documentation.qonversion.io/docs/unity-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
+
+* **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.
+
+What happens when something fails — the standby service, fallback files and the uptime commitment
+behind the platform: [reliability](https://qonversion.io/reliability).
+
+## For agents
+
+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.
+
+**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.
+
+**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`.
+
+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).
+
+## Sample app
+
+A Unity project that initializes the SDK, lists products, makes a purchase and reads entitlements
+lives in a separate repository: [qonversion/unity-sdk-sample](https://github.com/qonversion/unity-sdk-sample)
+(`Assets/Scripts/SampleApp.cs`). It loads the SDK from a sibling checkout (`file:../../unity-sdk`), so
+clone this repository next to it. It runs in the sandbox environment; for your own initialization, use
+the Quickstart snippet above.
+
+## Requirements
+
+| | Minimum |
+|---|---|
+| Unity | 2021.3 |
+| EDM4U for the Swift Package Manager path | 1.2.189 |
+| iOS deployment target | 13.0 |
+| Android `minSdkVersion` | 23 (inherited from the Android SDK) |
+
+The `unity` field in `package.json` still says 2018.3; Unity versions below 2021.3 are not supported
+or tested.
+
+## Help
+
+Contact us via [issues on GitHub](https://github.com/qonversion/unity-sdk/issues) or the
+[contact form](https://qonversion.io/contact-us) on our site.
## Contributing
@@ -125,11 +165,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/unity-sdk/issues) or the [contact form](https://qonversion.io/contact-us) on our site.
-
## License
-Qonversion SDK is available under the MIT license.
\ No newline at end of file
+Qonversion SDK is available under the MIT license. See [LICENSE](LICENSE).