nccgs 1.0.0

package/.claude/skills/implement-in-app-purchases/references/codeless-catalog.md

@@ -0,0 +1,331 @@
+# Editing `IAPProductCatalog.json`
+
+## Table of Contents
+
+- [Quick reference — minimal safe edit](#quick-reference--minimal-safe-edit)
+- [File location](#file-location)
+- [Schema](#schema)
+- [Serialization rules](#serialization-rules)
+  - [JsonUtility round-trip](#jsonutility-round-trip)
+  - [The `Price.data` decimal array](#the-pricedata-decimal-array)
+  - [Enum integers](#enum-integers)
+  - [Canonical store keys](#canonical-store-keys)
+  - [Non-ASCII characters in descriptions](#non-ascii-characters-in-descriptions)
+- [Validation — run before saving](#validation--run-before-saving)
+- [Post-edit refresh](#post-edit-refresh)
+- [When to escalate to the Editor window](#when-to-escalate-to-the-editor-window)
+- [Catalog as part of Codeless IAP](#catalog-as-part-of-codeless-iap)
+  - [Codeless vs scripted — which to use](#codeless-vs-scripted--which-to-use)
+  - [Auto-init race condition](#auto-init-race-condition)
+  - [Pushing the catalog to the storefronts](#pushing-the-catalog-to-the-storefronts)
+  - [Detection checklist](#detection-checklist)
+
+`Assets/Resources/IAPProductCatalog.json` is a Unity-managed JSON asset deserialized by `JsonUtility.FromJson<ProductCatalog>` (`Runtime/Purchasing/Extension/ProductCatalog.cs`). It can be edited safely outside the Editor as long as the serialization rules below are respected.
+
+## Quick reference — minimal safe edit
+
+1. **Read** the file as raw text. It is canonical JSON, single-line.
+2. **Parse** it into a dict/object.
+3. **Modify** fields using the schema and serialization rules below.
+4. **Write back** as JSON. Field name spelling and casing must match exactly; preserving order is not required.
+5. **Refresh** so the Editor / runtime sees the change (see [Post-edit refresh](#post-edit-refresh)).
+
+Adding a new $1.99 consumable `gems_50` in one operation:
+
+```jsonc
+{
+  "id": "gems_50",
+  "type": 0,
+  "storeIDs": [],
+  "defaultDescription": { "googleLocale": 21, "title": "50 Gems", "description": "A small pouch of gems." },
+  "screenshotPath": "",
+  "applePriceTier": 0,
+  "googlePrice": { "data": [199, 0, 0, 131072], "num": 1.99 },
+  "pricingTemplateID": "",
+  "descriptions": [],
+  "payouts": []
+}
+```
+
+Append to the `products` array, save, then trigger a refresh.
+
+## File location
+
+- **Current:** `Assets/Resources/IAPProductCatalog.json` (constant `ProductCatalog.kCatalogPath`)
+- **Legacy:** `Assets/Plugins/UnityPurchasing/Resources/IAPProductCatalog.json` (constant `ProductCatalog.kPrevCatalogPath`) — auto-migrated on Editor load via `ProductCatalogEditor.MigrateProductCatalog()`. If both exist, the current path wins.
+
+`Resources.Load("IAPProductCatalog")` deserializes it at runtime via `ProductCatalogImpl.LoadDefaultCatalog()`. The asset must remain under a `Resources/` directory for runtime load to succeed.
+
+## Schema
+
+```jsonc
+{
+  "appleSKU": "",                                  // app-level Apple SKU (Apple XML exporter)
+  "appleTeamID": "",                               // Apple team ID (Apple XML exporter)
+  "enableCodelessAutoInitialization": true,        // auto-init Unity IAP at runtime
+  "enableUnityGamingServicesAutoInitialization": false,
+  "products": [
+    {
+      "id": "gold_100",                            // canonical Unity SKU — required, non-empty, unique
+      "type": 0,                                   // ProductType int (see Enum integers)
+      "storeIDs": [                                // per-store override SKUs
+        { "store": "AppleAppStore", "id": "com.example.gold100" }
+      ],
+      "defaultDescription": {                      // required for export
+        "googleLocale": 21,                        // TranslationLocale int (en_US = 21)
+        "title": "",
+        "description": ""
+      },
+      "screenshotPath": "",                        // Apple screenshot path (optional)
+      "applePriceTier": 0,                         // Apple price tier (Apple XML exporter)
+      "googlePrice": { "data": [99,0,0,131072], "num": 0.99 },  // see Price.data
+      "pricingTemplateID": "",                     // Google Play pricing template
+      "descriptions": [                            // additional locale variants
+        { "googleLocale": 30, "title": "...", "description": "..." }
+      ],
+      "payouts": [                                 // optional grant metadata
+        { "t": "Currency", "st": "Gold", "q": 100, "d": "" }
+      ]
+    }
+  ]
+}
+```
+
+Per-product required fields for the runtime to accept the product: `id` (non-empty, trimmed). Everything else is optional at runtime; exporters and the Editor window enforce stricter rules (see [Validation](#validation--run-before-saving)).
+
+## Serialization rules
+
+### JsonUtility round-trip
+
+- Field names are **case-sensitive** and must match the `[SerializeField]` field names in `ProductCatalog.cs` exactly. The visible field names you see in the JSON (e.g. `title`, `description` inside `LocalizedProductDescription`) are the **backing field** names, not the public C# property names (`Title`, `Description`).
+- Unknown fields are silently dropped on the next save.
+- Missing fields deserialize to default values (`0`, `""`, empty list, etc.) — safe to omit defaults, but the Editor window writes them out explicitly.
+- The file is normally a single line — pretty-printing is fine, but JsonUtility re-emits as one line on the next Editor save.
+- Do not change the top-level key set. `appleSKU`, `appleTeamID`, `enableCodelessAutoInitialization`, `enableUnityGamingServicesAutoInitialization`, and `products` are all `[SerializeField]`-bound — removing keys is fine (they default), but renaming silently loses data.
+
+### The `Price.data` decimal array
+
+`Price` is the trickiest field. It serializes a `decimal` via two mirror fields and **`data` is authoritative on read**:
+
+```csharp
+public void OnBeforeSerialize() {
+    data = decimal.GetBits(value);        // int[4]: [low, mid, high, flags]
+    num  = decimal.ToDouble(value);
+}
+public void OnAfterDeserialize() {
+    if (data != null && data.Length == 4)
+        value = new decimal(data);        // num is ignored on read
+}
+```
+
+`data` is the `decimal.GetBits` representation: `[low32 mantissa, mid32 mantissa, high32 mantissa, flags]`.
+
+The `flags` int encodes scale (decimal places) and sign:
+- Bits 16–23: scale (0–28)
+- Bit 31: sign (0 = positive, 1 = negative; negative prices are never valid here)
+- All other bits: unused, must be 0
+
+For scale 2 (cents-style prices): `flags = 0x00020000 = 131072`
+For scale 0 (yen / whole-unit prices): `flags = 0`
+
+| Price (display) | Mantissa | Scale | `data` |
+|---|---|---|---|
+| 0.99 | 99 | 2 | `[99, 0, 0, 131072]` |
+| 1.99 | 199 | 2 | `[199, 0, 0, 131072]` |
+| 2.99 | 299 | 2 | `[299, 0, 0, 131072]` |
+| 4.99 | 499 | 2 | `[499, 0, 0, 131072]` |
+| 9.99 | 999 | 2 | `[999, 0, 0, 131072]` |
+| 19.99 | 1999 | 2 | `[1999, 0, 0, 131072]` |
+| 99.99 | 9999 | 2 | `[9999, 0, 0, 131072]` |
+| 1000 (¥, ₩) | 1000 | 0 | `[1000, 0, 0, 0]` |
+
+Formula for arbitrary positive prices with up to 2³¹−1 unscaled units:
+
+```
+unscaled = round(price * 10^scale)           // e.g. 2.99 with scale=2 → 299
+data     = [unscaled, 0, 0, scale << 16]
+```
+
+Keep `num` in sync with the display price even though it's not read — the Editor reads it diagnostically and the file diffs more readably.
+
+For prices larger than ~$21M (unscaled > 2³¹−1), the high two ints carry the overflow — at that point invoke Unity in batchmode and let `Price.OnBeforeSerialize` do the conversion, rather than constructing the bits by hand.
+
+### Enum integers
+
+`ProductType` (`type` field):
+
+| Int | Enum | Use for |
+|---|---|---|
+| 0 | `Consumable` | Coins, gems, lives, ammo — granted then consumed |
+| 1 | `NonConsumable` | One-time unlocks, remove-ads, character packs |
+| 2 | `Subscription` | Recurring entitlements |
+
+`TranslationLocale` (`googleLocale` field): the int is the zero-based index into the enum declared in `Runtime/Purchasing/Extension/ProductCatalog.cs`. Common values:
+
+| Int | Locale |
+|---|---|
+| 13 | `zh_CN` |
+| 14 | `zh_TW` |
+| 17 | `da_DK` |
+| 18 | `nl_NL` |
+| 21 | `en_US` (default for new descriptions) |
+| 22 | `en_GB` |
+| 30 | `fr_FR` |
+| 33 | `de_DE` |
+| 41 | `it_IT` |
+| 42 | `ja_JP` |
+| 46 | `ko_KR` |
+| 63 | `pl_PL` |
+| 64 | `pt_BR` |
+| 69 | `ru_RU` |
+| 75 | `es_ES` |
+
+For anything outside this list, count from the top of the `TranslationLocale` enum in `ProductCatalog.cs` — the order is the index.
+
+`ProductCatalogPayoutType` (`payouts[].t` field): **serialized as a string**, not an int. Valid values: `"Other"`, `"Currency"`, `"Item"`, `"Resource"`.
+
+### Canonical store keys
+
+`storeIDs[].store` must be one of the keys validated by `ProductCatalogEditor.kStoreKeys`:
+
+- `AppleAppStore`
+- `GooglePlay`
+- `MacAppStore`
+
+Using `"Apple"`, `"apple"`, `"google"`, etc. won't crash but the override will not be picked up by the runtime store routing. An empty `storeIDs` array means the product's `id` is used as the platform SKU on every store.
+
+### Non-ASCII characters in descriptions
+
+`LocalizedProductDescription.Title` / `Description` setters encode any character with code point > 127 as `\uXXXX` (`EncodeNonLatinCharacters` in `ProductCatalog.cs`). The getter regex-decodes both forms. So both representations work on read:
+
+```jsonc
+{ "title": "Caf\\u00e9 Pack" }   // Editor-written form
+{ "title": "Café Pack" }          // raw UTF-8 — also accepted on read
+```
+
+**Prefer the `\uXXXX` form** when writing programmatically, to match what the Editor will round-trip the file into on the next save. Mixed forms in one file are fine but the next Editor save normalizes everything to escaped form.
+
+Subtype `payouts[].st` has a 64-char max (`ProductCatalogPayout.MaxSubtypeLength`). Subtype `payouts[].d` (data) has a 1024-char max (`MaxDataLength`).
+
+## Validation — run before saving
+
+These mirror the Editor window's validation. Verify each before writing:
+
+**Per product:**
+- `id` is non-empty after trim. (`ProductCatalog.allValidProducts` filters on this.)
+- `id` is unique across all products in the array (the Editor flags duplicates).
+- `type` ∈ `{0, 1, 2}`.
+- Every `defaultDescription.googleLocale` and `descriptions[].googleLocale` is a valid int index into `TranslationLocale`.
+- `storeIDs[].store` ∈ canonical store keys.
+- If `googlePrice.data` is present, it is a 4-element int array; sign bit (bit 31 of `data[3]`) is 0.
+
+**Per-exporter (only if export is intended):**
+
+- **Apple XML** (`AppleXMLProductCatalogExporter.Validate`):
+  - Catalog-level: `appleSKU` non-empty, `appleTeamID` non-empty, no duplicate product IDs, no duplicate Apple store IDs, no duplicate runtime IDs.
+  - Per item: `id` non-empty, `defaultDescription.Title` non-empty, `defaultDescription.Description` non-empty, **`screenshotPath` non-empty (required, not optional)**.
+  - `applePriceTier` is written to the XML (`<wholesale_price_tier>`) but not validated — any int is accepted.
+- **Google CSV** (`GooglePlayProductCatalogExporter.Validate`):
+  - Catalog-level: no duplicate product IDs, no duplicate Google store IDs, no duplicate runtime IDs.
+  - Per item: `id` non-empty AND must start with a lowercase letter or digit AND contain only `a-z`, `0-9`, `_`, `.` (same rule applies to `storeIDs[].id` for the `GooglePlay` override).
+  - Description rules (apply to `defaultDescription` and every entry in `descriptions`):
+    - `Title` non-empty; ≤ 55 chars (error if longer); warning if > 25 chars.
+    - `Description` non-empty; ≤ 80 chars (error if longer).
+  - Price: either `googlePrice.value` ≠ 0 (i.e. non-zero `data` mantissa) **or** `pricingTemplateID` non-empty.
+
+**Top-level:**
+- `enableCodelessAutoInitialization` is a bool, not 0/1.
+- If the catalog ends up empty (no products with non-empty `id`), `CodelessIAPStoreListener.InitializeCodelessPurchasingOnLoad` short-circuits — flipping the auto-init flag in that state has no effect until a product is added.
+
+## Post-edit refresh
+
+The Unity Editor caches `IAPProductCatalog` as a `TextAsset` keyed by Resources path. After writing the JSON externally:
+
+- **Editor open, not in Play Mode:** Unity detects external changes on next focus and re-imports the asset automatically (`AssetDatabase`'s file watcher). If you want to force it from the Editor side, run **Assets → Refresh** (Ctrl/Cmd+R). The next `Resources.Load("IAPProductCatalog")` call will see the new contents.
+- **Editor open, in Play Mode:** the runtime `TextAsset` was loaded at play-start and is cached. Changes won't be picked up until play mode is restarted (or you re-call `Resources.Load` after `AssetDatabase.ImportAsset` to bypass the cache).
+- **Editor closed:** edits are picked up next time the Editor opens.
+- **Player build:** the catalog is baked into the build at build-time. Edits after build do nothing — rebuild required.
+
+For batchmode-driven workflows that need a guaranteed refresh:
+
+```
+"<unity>/Unity.exe" -batchmode -quit -projectPath "<path>" -logFile -
+```
+
+Plain batchmode without `-executeMethod` is enough to trigger asset import on startup. The next Editor session will see the change.
+
+## When to escalate to the Editor window
+
+Hand the user back to the IAP Catalog window (Services → In-App Purchasing → IAP Catalog…) when:
+
+- The decimal price is larger than ~$21M (would need the high mantissa ints — let `Price.OnBeforeSerialize` do it).
+- You need to set up many `payouts` with custom subtypes — the Editor has inline validation on lengths.
+- The user wants to use **App Store Export** (Apple XML / Google CSV) — that flow is a Unity dialog with its own validation results panel.
+- You hit a JsonUtility round-trip error you can't diagnose from the schema rules above.
+
+For everything else — adding/removing products, changing prices in normal ranges, toggling auto-init flags, updating descriptions, adding store ID overrides — direct file edits are safe and faster than driving the Editor UI.
+
+---
+
+## Catalog as part of Codeless IAP
+
+The catalog file plays two distinct roles in the package. Knowing which one applies in the current project changes how edits are made and what side-effects to expect.
+
+### Codeless vs scripted — which to use
+
+| Use case | Path |
+|---|---|
+| Ship a buy button with zero C# | **Codeless** — catalog + `CodelessIAPButton` |
+| Custom UI states, server validation, granular control of the purchase flow | **Scripted** — `StoreController` + an `IAPManager` (see [path-add-iap-to-new-project.md](path-add-iap-to-new-project.md)) |
+| Catalog-managed product list + scripted purchase flow | **Mixed** — catalog drives `CodelessIAPStoreListener` for product registration, scripted code subscribes to its events |
+| Export products to Apple Application Loader / Play Console | Codeless catalog — the only built-in export path |
+
+Default recommendation when starting a new project from scratch: scripted IAP. Codeless is convenient for prototypes but couples the project to a global singleton (`CodelessIAPStoreListener.Instance`) and hides the init/purchase flow most production games eventually need to customize.
+
+### Auto-init race condition
+
+If the project has **both** a non-empty `IAPProductCatalog.json` with `enableCodelessAutoInitialization: true` **and** a scripted `StoreController` initialized in user code, two init paths race for the same native store. Symptoms:
+
+- Duplicate `OnPurchasePending` callbacks (one per init's listener set).
+- "Store already connected" warnings on `Connect()`.
+- Unpredictable which init's product list wins.
+
+Mitigations (pick one):
+
+1. **Keep scripted, disable codeless:** set `"enableCodelessAutoInitialization": false` in the catalog JSON. The catalog stays available for `ProductCatalog.LoadDefaultCatalog()` calls.
+2. **Keep codeless, remove scripted init:** delete the user's `StoreController` setup; rely on `CodelessIAPStoreListener.Instance`.
+3. **Empty the catalog:** clear `products` to `[]`. `CodelessIAPStoreListener.InitializeCodelessPurchasingOnLoad` short-circuits on empty catalogs even with the flag on.
+
+Surface this before adding scripted IAP to a project that already has a non-empty catalog.
+
+### Pushing the catalog to the storefronts
+
+The IAP Catalog window's **App Store Export** button opens `ProductCatalogExportWindow`, which generates bulk-import files. Nothing in the package calls App Store Connect or Play Console APIs directly — devs upload the generated files manually.
+
+| Exporter | Output | Upload destination |
+|---|---|---|
+| `AppleXMLProductCatalogExporter` | Application Loader XML | App Store Connect → Transporter / Application Loader |
+| `GooglePlayProductCatalogExporter` | CSV | Play Console → In-app products → Import |
+
+Editing the JSON directly populates the same fields the exporters read; the validation surface in the Editor window (`ExporterValidationResults`) is the user-visible signal that fields are missing.
+
+### Detection checklist
+
+When triaging an IAP issue or planning changes, check in order:
+
+1. Does `Assets/Resources/IAPProductCatalog.json` exist?
+2. Is `enableCodelessAutoInitialization` true? (`grep enableCodelessAutoInitialization Assets/Resources/IAPProductCatalog.json`)
+3. Are there `CodelessIAPButton` or legacy `IAPButton` components in scenes/prefabs?
+4. Does user code construct a `StoreController` directly (or call `UnityIAPServices.StoreController(...)`)?
+5. Does user code reference `CodelessIAPStoreListener.Instance`?
+
+Routing the result:
+
+| Catalog | autoInit | Scripted `StoreController` | Action |
+|---|---|---|---|
+| present (non-empty) | true | absent | Pure codeless — edit the catalog freely. |
+| present (non-empty) | true | present | **Race condition** — surface to the user, apply one of the three mitigations. |
+| present | false | present | Catalog is dormant unless `ProductCatalog.LoadDefaultCatalog()` is called from user code. Edits safe. |
+| present (empty) | true or false | present | Codeless auto-init short-circuits on empty catalog. Treat as scripted-only. |
+| absent | n/a | present | Standard scripted IAP. See [path-add-iap-to-new-project.md](path-add-iap-to-new-project.md). |
+| absent | n/a | absent | No IAP — see [pre-check.md](pre-check.md) routing. |

package/.claude/skills/implement-in-app-purchases/references/convert-adapty.md

@@ -0,0 +1,268 @@
+# Adapty — Conversion Assessment and Guidance
+
+## Table of Contents
+
+- [Trigger Phrases](#trigger-phrases)
+- [Overview](#overview)
+- [Step 1 — Check If Already in Observer Mode](#step-1--check-if-already-in-observer-mode)
+- [Step 2 — Feature Support Check](#step-2--feature-support-check)
+- [Step 3 — Native Google BillingClient Check](#step-3--native-google-billingclient-check)
+- [Step 4 — Route to Outcome](#step-4--route-to-outcome)
+- [Case 1 — Already in Observer Mode with Unity IAP 5](#case-1--already-in-observer-mode-with-unity-iap-5)
+- [Case 2 — Unsupported Features Detected](#case-2--unsupported-features-detected)
+- [Case 3 — No Blockers, Conversion Is Viable](#case-3--no-blockers-conversion-is-viable)
+
+Use this reference when the project has Adapty (`AdaptySDK-Unity`) installed and the user wants to **replace or remove Adapty** and switch to Unity IAP 5 (`com.unity.purchasing`). This path does not cover adding Unity IAP 5 alongside Adapty for non-IAP purposes.
+
+---
+
+## Trigger Phrases
+
+- "Replace Adapty SDK with Unity IAP"
+- "Remove Adapty and use Unity IAP"
+- "Migrate from Adapty to Unity IAP"
+- "Use Unity IAP 5 to handle store purchases and work with Adapty"
+- "Make Adapty work with Unity IAP 5"
+
+---
+
+## Overview
+
+Adapty is architecturally independent from Unity IAP — it has its own native Swift (iOS) and Kotlin (Android) SDKs that call Apple StoreKit and Google BillingClient directly. There is no simple swap. Conversion requires assessing which Adapty features the project uses and whether Unity IAP 5 can replace them.
+
+This path always produces one of three outcomes:
+
+| Case | Condition | Outcome |
+|---|---|---|
+| **1** | Already in observer mode with Unity IAP 5 | Report — no action needed |
+| **2** | Adapty-only features are in active use | Report limitations, present two choices |
+| **3** | No blockers — only basic purchase flow used | Present two conversion choices |
+
+Run Steps 1–3 in order. Collect all findings before routing.
+
+---
+
+## Step 1 — Check If Already in Observer Mode
+
+### 1a — Check Unity IAP 5 is installed
+
+Search `Packages/manifest.json` for `com.unity.purchasing` with a version matching `5\.`. Record whether it is present.
+
+### 1b — Check Adapty observer mode configuration
+
+Search `Assets/**/*.cs` for:
+
+```
+Adapty\.Activate.*observerMode|observerMode\s*=\s*true|AdaptyProfileParameters|ReportTransaction
+```
+
+Also search for `AdaptyObserverModeDelegate` or any class implementing it.
+
+If found, observer mode is active.
+
+**If both Unity IAP 5 is installed AND observer mode is active → this is Case 1. Skip Step 2 and go directly to [Case 1](#case-1--already-in-observer-mode-with-unity-iap-5).**
+
+Otherwise continue to Step 2.
+
+---
+
+## Step 2 — Feature Support Check
+
+Search `Assets/**/*.cs`, `Assets/**/*.prefab`, and `Assets/**/*.unity` for usage of Adapty features that have **no Unity IAP 5 equivalent**. Record every feature found.
+
+### 2a — Remote Paywalls / Paywall Builder
+
+```
+GetPaywall|PaywallView|AdaptyUI|AdaptyPaywall|GetPaywallForDefaultAudience|ShowPaywall|PresentCodeRedemptionSheet
+```
+
+Also check `Packages/manifest.json` or imported packages for `adapty-ui` or `AdaptyUI`.
+
+**What it means:** Adapty's Paywall Builder lets you configure paywall layouts and copy remotely without an app update. Unity IAP 5 has no remote paywall system — all products and UI must be defined in code or a local catalog. **Note: Paywall Builder is also unavailable in Adapty's own Observer Mode**, so even a partial migration loses this feature.
+
+### 2b — A/B Testing / Experiments
+
+```
+variationId|GetPaywall.*audience|LogShowPaywall|LogStartCheckout
+```
+
+**What it means:** Adapty runs A/B tests on paywall layouts and pricing server-side. Unity IAP 5 has no A/B testing capability. In Adapty Observer Mode, A/B testing also requires significant additional coding and is not automatic.
+
+### 2c — Cross-Platform Entitlement Sync
+
+```
+Adapty\.Identify|Adapty\.Profile|AdaptyProfile|accessLevels|isActive
+```
+
+Specifically look for `Adapty.Identify` being called with a customer user ID — this indicates the project relies on Adapty as the cross-platform entitlement source of truth (a user who buys on iOS retains access on Android). Unity IAP 5 has no cross-platform entitlement layer.
+
+### 2d — Webhook-Driven Backend Events
+
+Search `Assets/**/*.cs` for patterns suggesting backend subscription event handling:
+
+```
+webhook|SubscriptionCancelled|BillingIssue|AccessLevelUpdated
+```
+
+Also ask the user: *"Does your backend receive Adapty webhook events for subscription renewals, cancellations, or billing issues?"* If yes, flag this — Unity IAP 5 delivers no server-side lifecycle events.
+
+### 2e — Third-Party Analytics Integrations
+
+```
+AdaptyAttributionNetwork|UpdateAttribution|SetFallbackPaywalls|Amplitude|Mixpanel|AppsFlyer|Adjust
+```
+
+**What it means:** Adapty forwards purchase and paywall events to third-party analytics tools automatically. Unity IAP 5 has no such integration layer — you would need to instrument each event manually.
+
+---
+
+## Step 3 — Native Google BillingClient Check
+
+Search the following for custom native billing code alongside Adapty:
+
+- `Assets/**/*.cs` for: `AndroidJavaObject|AndroidJavaClass|BillingClient|BillingManager|GoogleBilling`
+- `Assets/Plugins/Android/**/*.java`, `*.kt` for: `com\.android\.billingclient`
+
+**If found:** The project has custom native Google BillingClient code in addition to Adapty. This is unusual — flag it to the user. Native BillingClient code will conflict with Unity IAP 5 at runtime and must be removed or replaced as part of the conversion. Add it to the blockers list in Case 2 if active and not just scaffolding.
+
+---
+
+## Step 4 — Route to Outcome
+
+Evaluate findings from Steps 2 and 3:
+
+```
+If native BillingClient detected (Step 3)      → Case 2 (flag as additional blocker)
+If any Step 2 feature detected                 → Case 2
+If no blockers from Steps 2 or 3              → Case 3
+```
+
+If multiple blockers are found, list all of them in the Case 2 report — do not stop at the first.
+
+---
+
+## Case 1 — Already in Observer Mode with Unity IAP 5
+
+**Condition:** Unity IAP 5 installed and Adapty already configured in observer mode.
+
+Report and stop:
+
+> "This project already has Unity IAP 5 installed and Adapty is running in observer mode. Unity IAP 5 handles purchase transactions and Adapty validates and tracks them server-side via `ReportTransaction`.
+>
+> If you want to remove Adapty entirely, re-run this skill and specify that you want to stop using Adapty. That will route to a full removal assessment."
+
+Do not make any changes.
+
+---
+
+## Case 2 — Unsupported Features Detected
+
+**Condition:** One or more Adapty-only features are in active use.
+
+Produce a blockers report listing every issue found, then present two choices:
+
+> "The following Adapty features are in use that have no Unity IAP 5 equivalent:
+>
+> [List all detected blockers, e.g.:]
+> - **Remote Paywalls / Paywall Builder** (`GetPaywall` / `AdaptyUI` detected): Unity IAP 5 has no remote paywall system. Paywall layouts and copy must be hardcoded. Note: Adapty's Paywall Builder is also unavailable in Adapty Observer Mode — switching to observer mode does not preserve this feature.
+> - **A/B Testing** (`variationId` / `logShowPaywall` detected): Unity IAP 5 has no A/B testing. In Adapty Observer Mode, A/B testing requires significant additional manual instrumentation and is not automatic.
+> - **Cross-platform entitlement sync** (`Adapty.Identify` detected): Unity IAP 5 has no cross-platform entitlement layer. A user who purchases on iOS will not retain access on Android without a custom server-side solution.
+> - **Webhook-driven backend events**: Your backend appears to receive Adapty subscription events. Unity IAP 5 delivers no server-side lifecycle events — you would need to build your own subscription tracking infrastructure.
+> - **Third-party analytics integrations**: Adapty forwards purchase events to [detected tools]. Unity IAP 5 has no integration layer — each event would need manual instrumentation.
+>
+> **Your options:**
+>
+> **(a) Stop conversion (recommended)** — Keep Adapty as the billing backend. The features in use have no Unity IAP 5 equivalent. No changes will be made.
+>
+> **(b) Convert to observer mode + Unity IAP 5 anyway** — Unity IAP 5 takes over purchase transactions. Adapty switches to observer mode for server-side validation and lifecycle tracking. You accept the following consequences:
+> - Adapty Paywall Builder stops working — you must build replacement paywall UI in Unity.
+> - [List each unsupported feature and its specific consequence.]
+> - BillingClient Gradle conflict between Unity IAP 5 and Adapty must be resolved by excluding the conflicting dependency.
+>
+> Which would you like to do?"
+
+If the user chooses **(a)**: stop, make no changes.
+
+If the user chooses **(b)**: continue with [Case 3, Path A](#path-a--convert-to-observer-mode--unity-iap-5) but preface the report with a clear warning documenting every accepted consequence.
+
+---
+
+## Case 3 — No Blockers, Conversion Is Viable
+
+**Condition:** No Adapty-only features detected — the project uses Adapty only for basic purchase flow.
+
+Present two choices:
+
+> "No blockers were found. The project uses Adapty only for basic purchase initiation and receipt handling (no remote paywalls, no cross-platform entitlements, no A/B testing). Two conversion paths are available:
+>
+> **(a) Observer mode + Unity IAP 5** — Unity IAP 5 handles purchase transactions. Adapty stays in observer mode, receiving `ReportTransaction` calls for server-side validation and subscription lifecycle tracking. Lower risk — Adapty's subscription event webhooks and analytics continue to work.
+>
+> **(b) Full removal — Unity IAP 5 only** — Adapty is removed entirely. Unity IAP 5 handles all billing. You lose Adapty's server-side receipt validation, subscription lifecycle tracking, and analytics. If the project had any Adapty paywall UI, replacement purchase UI must be built in Unity. Simpler architecture, no Adapty subscription cost.
+>
+> Which path would you like?"
+
+---
+
+### Path A — Convert to Observer Mode + Unity IAP 5
+
+1. **Install Unity IAP 5** if not already present — follow Step 1 of [path-add-iap-to-new-project.md](path-add-iap-to-new-project.md).
+
+2. **Resolve the BillingClient Gradle conflict.** Both SDKs bundle `com.android.billingclient`. Unity IAP 5 declares `com.android.billingclient:billing:9.0.0` via `Plugins/UnityPurchasing/Android/IAPResolver/IAPAndroidDependencies.cs` — do **not** add a project-wide `configurations.all { exclude group: 'com.android.billingclient' }` in `mainTemplate.gradle`, as that will strip Unity IAP's own BillingClient along with Adapty's and leave the Android build with no BillingClient at all.
+
+   Instead, remove only Adapty's copy:
+   - Locate Adapty's EDM4U dependency file (typically `Assets/Adapty/Editor/AdaptyDependencies.xml` or similar) and delete the `<androidPackage spec="com.android.billingclient:billing:..."/>` entry, **or**
+   - After Force Resolve, delete the Adapty-contributed `billing-*.aar` from `Assets/Plugins/Android/` and keep the one contributed by Unity IAP.
+
+   Then run **Assets > External Dependency Manager > Android Resolver > Delete Resolved Libraries**, followed by **Force Resolve**.
+
+3. **Enable Adapty observer mode.** In the `Adapty.Activate` call, set `observerMode: true`:
+
+   ```csharp
+   var config = new AdaptyConfig("YOUR_PUBLIC_SDK_KEY")
+   {
+       ObserverMode = true
+   };
+   Adapty.Activate(config);
+   ```
+
+4. **Implement Unity IAP 5 purchase flow.** Follow [path-add-iap-to-new-project.md](path-add-iap-to-new-project.md) using the product catalog extracted from existing Adapty `GetPaywall` calls or hardcoded product IDs found in the codebase.
+
+5. **Call `Adapty.ReportTransaction()` after every confirmed purchase.** In the Unity IAP `OnPurchasePending` handler, after granting content and saving, report the transaction to Adapty:
+
+   ```csharp
+   Adapty.ReportTransaction(transactionId, null, (error) =>
+   {
+       if (error != null) Debug.LogWarning($"Adapty ReportTransaction failed: {error}");
+   });
+   ```
+
+   On Android, also call `Adapty.RestorePurchases` at app startup to sync any purchases Adapty may have missed.
+
+6. **Produce a verification report** covering:
+   - Files changed
+   - Gradle conflict resolution confirmed
+   - Adapty observer mode configuration location
+   - `ReportTransaction` call location in purchase flow
+   - Manual steps: verify Adapty dashboard shows purchases from the updated build in sandbox; confirm Paywall Builder is no longer used (unavailable in observer mode)
+
+---
+
+### Path B — Full Removal of Adapty
+
+1. **Extract the product catalog** from existing Adapty usage — search for hardcoded product ID strings and `GetPaywall` / `GetPaywallForDefaultAudience` calls.
+
+2. **Identify any Adapty paywall UI** — search for `AdaptyUI`, `PaywallView`, or `ShowPaywall`. These views must be replaced with custom Unity UI wired to `IAPManager.Buy(productId)`. Inform the user that building replacement shop UI is required before removal.
+
+3. **Implement Unity IAP 5** using the extracted catalog — follow [path-add-iap-to-new-project.md](path-add-iap-to-new-project.md) in full.
+
+4. **Remove Adapty SDK references from code.** Search `Assets/**/*.cs` for `using Adapty;` and all `Adapty.*` calls. Replace purchase calls with the Unity IAP 5 equivalents from the new `IAPManager`. Remove paywall presentation calls — these must be replaced by the new shop UI.
+
+5. **Remove the Adapty package.** Delete the imported Adapty `.unitypackage` files from `Assets/` (typically under `Assets/Adapty/`). Remove any EDM4U dependency files Adapty registered.
+
+6. **Run Assets > External Dependency Manager > Android Resolver > Force Resolve** after package removal to clean up Adapty's native dependencies.
+
+7. **Produce a verification report** covering:
+   - Files changed and Adapty references removed
+   - Product catalog — confirm all product IDs are preserved in Unity IAP 5
+   - Paywall UI — confirm replacement UI is in place or listed as a pending TODO
+   - Manual steps: verify no orphaned Adapty Gradle entries remain in the Android build; confirm sandbox purchases succeed end-to-end with Unity IAP 5