nccgs 1.0.0

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

@@ -0,0 +1,239 @@
+# Convert Essential Kit Billing to Unity IAP 5
+
+## Table of Contents
+
+- [Trigger Phrases](#trigger-phrases)
+- [Important Constraints](#important-constraints)
+- [Step 1 — Verify Essential Kit Billing Is Active](#step-1--verify-essential-kit-billing-is-active)
+- [Step 2 — Extract Product Definitions](#step-2--extract-product-definitions)
+- [Step 3 — Migration Report (produce before any edits)](#step-3--migration-report-produce-before-any-edits)
+- [Step 4 — Add Unity IAP 5](#step-4--add-unity-iap-5)
+- [Step 5 — Disable Essential Kit Billing](#step-5--disable-essential-kit-billing)
+- [Step 6 — Remove Conflicting Gradle Dependency](#step-6--remove-conflicting-gradle-dependency)
+- [Step 7 — Essential Kit → Unity IAP Concept Mapping](#step-7--essential-kit--unity-iap-concept-mapping)
+- [Step 8 — Verification Report](#step-8--verification-report)
+
+Use this reference when the project uses Essential Kit (VoxelBusters) Billing Services and needs to be converted to `com.unity.purchasing` (Unity IAP 5). Always install the latest stable version of Unity IAP.
+
+---
+
+## Trigger Phrases
+
+- "Convert Essential Kit billing function to Unity IAP"
+- "Replace VoxelBusters Essential Kit IAP with Unity IAP"
+- "Migrate from Essential Kit in-app purchases to Unity IAP"
+- "Remove Essential Kit billing and use Unity IAP"
+
+---
+
+## Important Constraints
+
+- **Do not delete any Essential Kit source files.** Disabling the Billing service toggle in settings is sufficient to prevent Essential Kit from initializing native billing at runtime. No C# source changes are needed.
+- **Leave all other Essential Kit services completely untouched.** Only the Billing service and its Gradle dependency are affected.
+- **Do not change product IDs.** The same IDs used in Essential Kit must be used in Unity IAP to preserve store history and existing purchases.
+- **Do not change backend validation endpoints** unless the receipt format change makes it unavoidable — document any required backend change.
+- **This path covers store billing (Apple App Store / Google Play) only.** Do not consider IAP D2C Capabilities / third-party payment provider migration here.
+
+---
+
+## Step 1 — Verify Essential Kit Billing Is Active
+
+### 1a — Confirm Essential Kit is installed
+
+Search `Packages/manifest.json` for `com.voxelbusters.essentialkit` and check that `Assets/Plugins/VoxelBusters/` exists.
+
+### 1b — Check Billing service is enabled
+
+Read `Resources/EssentialKitSettings.asset` (Unity YAML serialized file). Search for the Billing Services enabled flag:
+
+```
+billingServicesEnabled|isBillingServicesEnabled|BillingServices.*enabled: 1
+```
+
+Also inspect the file for any `BillingServicesSettings` section.
+
+If the Billing service flag is **not set to enabled (1)**, stop and report:
+
+> "Essential Kit Billing Services is not enabled in Project Settings (Window > Voxel Busters > Essential Kit > Open Settings → Services). There is nothing to convert."
+
+Do not proceed.
+
+### 1c — Check Unity IAP package status
+
+Search `Packages/manifest.json` for `com.unity.purchasing`. If absent or outdated, install the latest stable version via Package Manager before continuing.
+
+---
+
+## Step 2 — Extract Product Definitions
+
+Read `Resources/EssentialKitSettings.asset` and locate the products array under `BillingServicesSettings`. Each product entry contains:
+
+| Essential Kit Field | Description |
+|---|---|
+| `Id` | Internal product identifier used in code (e.g., `coins_100`) |
+| `PlatformId` | Common store product ID across platforms |
+| `PlatformIdOverrides` | Per-platform IDs — separate entries for iOS (`AppleAppStore`) and Android (`GooglePlay`) |
+| `ProductType` | `Consumable`, `NonConsumable`, or `Subscription` |
+| `Title` | Display name |
+| `Description` | User-facing description |
+
+If **no products are defined** in the settings asset, stop and report:
+
+> "No billing products found in Essential Kit Billing Settings. There is nothing to convert."
+
+Do not proceed.
+
+### Product type mapping
+
+| Essential Kit `BillingProductType` | Unity IAP `ProductType` |
+|---|---|
+| `Consumable` | `ProductType.Consumable` |
+| `NonConsumable` | `ProductType.NonConsumable` |
+| `Subscription` | `ProductType.Subscription` |
+
+### Store-specific IDs
+
+If `PlatformIdOverrides` has separate Apple and Google IDs, use `StoreSpecificIds` in the `ProductDefinition`:
+
+```csharp
+new ProductDefinition("coins_100", ProductType.Consumable,
+    new StoreSpecificIds
+    {
+        { AppleAppStore.Name, "apple_coins_100" },
+        { GooglePlay.Name, "google_coins_100" }
+    })
+```
+
+If only a single `PlatformId` is used, pass it directly as the product ID.
+
+---
+
+## Step 3 — Migration Report (produce before any edits)
+
+Generate all sections before touching any file.
+
+1. **Essential Kit billing architecture** — event-based (`OnTransactionStateChange`), auto-finish vs manual-finish mode (`AutoFinishTransactions` setting)
+2. **Files using Essential Kit Billing** — C# files referencing `BillingServices`, scene/prefab shop UI
+3. **Product catalog extracted** — all products with ID, type, and store-specific IDs
+4. **Auto Finish Transactions setting** — if disabled, the project uses server-side verification; document the receipt field mapping change (see Step 7)
+5. **Backend validation mapping** — how receipt data sent to backend changes
+6. **Restore flow mapping** — `RestorePurchases()` → `store.RestoreTransactions()` + `store.FetchPurchases()`
+7. **UI wiring** — shop buttons and callbacks that will need rewiring to Unity IAP events
+8. **Proposed Unity IAP architecture** — new files, product catalog definition
+9. **Files to create / modify**
+10. **Manual steps required** — listed in Step 8
+
+---
+
+## Step 4 — Add Unity IAP 5
+
+Use the product catalog extracted in Step 2 as input and follow **`path-add-iap-to-new-project.md`** for the full Unity IAP 5 implementation. Specifically:
+
+- Match the project's existing patterns for the IAPManager (Step 4 of that file).
+- Apply the save-before-confirm contract (Step 5 of that file).
+- Apply product type behavior rules (Step 6 of that file) — note that consumable restore rules are the same: do not restore old consumable orders.
+- Use the existing save system found in the project (Step 7 of that file).
+- Rewire existing shop UI buttons to `IAPManager.Buy(productId)` (Step 8 of that file).
+
+Do not duplicate content from `path-add-iap-to-new-project.md` — reference it.
+
+---
+
+## Step 5 — Disable Essential Kit Billing
+
+After Unity IAP is in place, disable the Essential Kit Billing service to prevent it from initializing its own native billing layer (which would conflict with Unity IAP at runtime).
+
+**Edit `Resources/EssentialKitSettings.asset`** — set the Billing Services enabled flag to `0`:
+
+```yaml
+# Before
+billingServicesEnabled: 1
+
+# After
+billingServicesEnabled: 0
+```
+
+Do not modify any other field in this file. Do not delete the file. Do not touch any other section of the settings asset.
+
+This single change prevents Essential Kit from calling `BillingClient.startConnection()` (Android) or initializing StoreKit (iOS) at startup. All Essential Kit C# billing source files remain in place and will compile normally — the service simply will not be initialized.
+
+---
+
+## Step 6 — Remove Conflicting Gradle Dependency
+
+Search `Assets/Plugins/VoxelBusters/EssentialKit/Essentials/Editor/CrossPlatformEssentialKitDependencies.xml` for `com.android.billingclient`. If the file does not exist or contains no `com.android.billingclient` entries, **skip this step entirely**.
+
+If found, Essential Kit's billing Gradle dependency conflicts with Unity IAP's own BillingClient. Remove only the billing dependency line(s):
+
+```xml
+<!-- Remove these lines -->
+<androidPackage spec="com.android.billingclient:billing:VERSION" />
+<androidPackage spec="com.android.billingclient:billing-ktx:VERSION" />
+```
+
+Leave all other `<androidPackage>` entries in the file untouched.
+
+After editing, run **Assets > External Dependency Manager > Android Resolver > Resolve** (or Force Resolve) to regenerate the Gradle dependency list.
+
+---
+
+## Step 7 — Essential Kit → Unity IAP Concept Mapping
+
+### API mapping
+
+| Essential Kit | Unity IAP 5 |
+|---|---|
+| `BillingServices.InitializeStore()` | `store.Connect()` → `store.FetchProducts(definitions)` |
+| `BillingServices.OnInitializeStoreComplete` | `store.OnStoreConnected` + `store.OnProductsFetched` |
+| `BillingServices.BuyProduct(product, options)` | `store.PurchaseProduct(product)` |
+| `BillingServices.OnTransactionStateChange` (Purchased) | `store.OnPurchasePending` |
+| `BillingServices.OnTransactionStateChange` (Failed) | `store.OnPurchaseFailed` |
+| `BillingServices.OnTransactionStateChange` (Deferred) | `store.OnPurchaseDeferred` |
+| `BillingServices.FinishTransactions(transactions)` | `store.ConfirmPurchase(pendingOrder)` |
+| `BillingServices.RestorePurchases(forceRefresh)` | `store.RestoreTransactions(callback)` (user-triggered) + `store.FetchPurchases()` (startup) |
+| `BillingServices.OnRestorePurchasesComplete` | `store.OnPurchasesFetched` + `store.RestoreTransactions` callback |
+| `BillingServices.IsProductPurchased(id)` | `store.CheckEntitlement(product)` + `store.OnCheckEntitlement` |
+| `BillingServices.CanMakePayments()` | `store.AppleStoreExtendedService?.canMakePayments` (Apple only) |
+| `BillingServices.GetProductWithId(id)` | `store.GetProductById(id)` |
+| `BillingServices.GetTransactions()` | `store.GetPurchases()` |
+| `IBillingProduct` | `Product` |
+| `IBillingTransaction` | `PendingOrder` (on `OnPurchasePending`) |
+| `product.Price.LocalizedText` | `product.metadata.localizedPriceString` |
+| `product.LocalizedTitle` | `product.metadata.localizedTitle` |
+| `product.LocalizedDescription` | `product.metadata.localizedDescription` |
+
+### Receipt / validation mapping
+
+| Essential Kit | Unity IAP 5 |
+|---|---|
+| `transaction.Receipt` (iOS JWS token) | `pendingOrder.Info.Apple?.jwsRepresentation` |
+| `transaction.RawData` JSON (`transaction` + `signature` fields, Android) | `pendingOrder.Info.Receipt` (contains the full Google receipt JSON) |
+
+If the project sends `transaction.RawData` to a backend, document the receipt format change — the backend must now parse `order.Info.Receipt` instead.
+
+### Auto Finish Transactions
+
+Essential Kit's `AutoFinishTransactions` setting maps to Unity IAP's two-step flow:
+
+| EK Setting | Unity IAP equivalent |
+|---|---|
+| `AutoFinishTransactions = true` | Call `ConfirmPurchase(pendingOrder)` immediately after granting content |
+| `AutoFinishTransactions = false` (server verification) | Hold the `PendingOrder` reference, send receipt to server, call `ConfirmPurchase` only after server confirms — never confirm before grant |
+
+---
+
+## Step 8 — Verification Report
+
+After applying changes, produce a report with these sections:
+
+1. **Files changed** — list with nature of each change
+2. **Product catalog** — all product IDs, types, and store-specific IDs
+3. **Essential Kit Billing service** — confirmed disabled in `EssentialKitSettings.asset`
+4. **Gradle dependency** — confirmed `com.android.billingclient:billing` removed from `CrossPlatformEssentialKitDependencies.xml`
+5. **Receipt / backend mapping** — any backend changes required
+6. **Manual steps still required:**
+   - Run **Assets > External Dependency Manager > Android Resolver > Force Resolve** after editing the dependencies XML
+   - Verify no duplicate `BillingClient` classes in the Android build (`./gradlew dependencies` or check Unity build log)
+   - Confirm Essential Kit Billing service is visually disabled in **Window > Voxel Busters > Essential Kit > Open Settings → Services**
+   - Verify all existing App Store Connect / Google Play Console product IDs match the Unity IAP catalog exactly
+   - Test with sandbox/license test accounts

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

@@ -0,0 +1,275 @@
+# RevenueCat — 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 — Platform Support Check](#step-3--platform-support-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 — Blocker Detected (Amazon or Unsupported Features)](#case-2--blocker-detected-amazon-or-unsupported-features)
+- [Case 3 — No Blockers, Conversion Is Viable](#case-3--no-blockers-conversion-is-viable)
+
+Use this reference when the project has RevenueCat (`com.revenuecat.purchases-unity`) installed and the user wants to **replace or remove RevenueCat** and switch to Unity IAP 5 (`com.unity.purchasing`). This path does not cover adding Unity IAP 5 alongside RevenueCat for non-IAP purposes (e.g., IAP D2C Capabilities).
+
+---
+
+## Trigger Phrases
+
+- "Replace RevenueCat with Unity IAP"
+- "Remove RevenueCat and use Unity IAP"
+- "Migrate from RevenueCat to Unity IAP"
+- "Convert RevenueCat to Unity IAP 5"
+- "Stop using RevenueCat"
+
+---
+
+## Overview
+
+RevenueCat is architecturally independent from Unity IAP — it calls Apple StoreKit and Google BillingClient directly via its own native SDKs. Because of this, there is no simple "swap" — conversion requires assessing what RevenueCat features the project uses, what platforms it targets, and how much of RevenueCat's value Unity IAP 5 can actually replace.
+
+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** | Blocker found: Amazon store targeted, or RevenueCat-only features in use | Report blockers, present two choices |
+| **3** | No blockers — no Amazon, no RevenueCat-only features | 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 RevenueCat observer mode configuration
+
+Search `Assets/**/*.cs` for:
+
+```
+PurchasesAreCompletedBy\.MyApp|PurchasesAreCompletedBy\.YourApp|observerMode\s*=\s*true|SetPurchasesAreCompletedBy
+```
+
+If found, observer mode is active.
+
+**If both Unity IAP 5 is installed AND observer mode is active → this is Case 1. Skip Steps 2–3 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 RevenueCat features that have **no Unity IAP 5 equivalent**. Record every feature found.
+
+### 2a — Remote Paywalls / Offerings
+
+```
+GetOfferings|Offerings|Offering\b|Package\b.*revenuecat|RevenueCatUI|PaywallView|PresentPaywall
+```
+
+Also check `Packages/manifest.json` for `com.revenuecat.purchases-ui-unity`.
+
+**What it means:** RevenueCat's Offerings system lets you configure products and paywall layouts remotely without an app update. Unity IAP 5 has no remote paywall or Offerings system — all products must be defined in code or a local catalog.
+
+### 2b — A/B Testing / Experiments
+
+```
+GetCurrentOffering|Experiments|currentOffering
+```
+
+**What it means:** RevenueCat Experiments allows server-side A/B testing of product prices and paywall layouts. Unity IAP 5 has no A/B testing capability.
+
+### 2c — Cross-Platform Entitlement Sync
+
+```
+LogIn|LogOut|Purchases\.SharedPurchases|appUserId|CustomerInfo
+```
+
+Specifically look for `LogIn` being called with a user ID — this indicates the project relies on RevenueCat 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 — each platform's receipt is independent.
+
+### 2d — Webhook-Driven Backend Events
+
+Search `Assets/**/*.cs` for patterns suggesting server-side subscription event handling:
+
+```
+webhook|SubscriptionStatusChange|EntitlementRevoked|BillingIssue
+```
+
+Also ask the user: *"Does your backend receive RevenueCat webhook events for subscription renewals, cancellations, or billing issues?"* If yes, flag this — Unity IAP 5 delivers no server-side lifecycle events.
+
+### 2e — Offline Entitlement Caching
+
+```
+offlineCustomerInfo|OfflineEntitlements|entitlementVerification
+```
+
+**What it means:** RevenueCat's offline entitlement feature processes and caches entitlements during server outages. Unity IAP 5 has no equivalent — if the store is unreachable, entitlement state is unavailable.
+
+---
+
+## Step 3 — Platform Support Check
+
+### 3a — Native Google BillingClient detection
+
+Search the following for custom native billing code alongside RevenueCat:
+
+- `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 RevenueCat. 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 native BillingClient code is active and not just scaffolding.
+
+### 3b — Amazon Appstore detection
+
+Search the following for Amazon signals:
+
+- `Packages/manifest.json` and `Packages/packages-lock.json` for: `amazon`
+- `Assets/**/*.cs` for: `useAmazon|SetUseAmazon|AmazonStore|SyncAmazonPurchase`
+- `ProjectSettings/ProjectSettings.asset` for Amazon as an enabled build target
+
+**If found:** Amazon is a hard blocker. Unity IAP 5 has removed Amazon Appstore support entirely. RevenueCat observer mode is also broken for Amazon — `syncPurchases()` does not work on Amazon builds and requires `syncAmazonPurchase()` with full purchase details.
+
+---
+
+## Step 4 — Route to Outcome
+
+Evaluate findings from Steps 2 and 3:
+
+```
+If Amazon detected (Step 3b)                    → Case 2
+If native BillingClient detected (Step 3a)      → 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 RevenueCat already configured in observer mode.
+
+Report and stop:
+
+> "This project already has Unity IAP 5 installed and RevenueCat is running in observer mode (`PurchasesAreCompletedBy.MyApp`). The two SDKs are already co-operating — Unity IAP 5 handles purchase transactions and RevenueCat validates and tracks them server-side.
+>
+> If you want to remove RevenueCat entirely, re-run this skill and specify that you want to stop using RevenueCat. That will route to a full removal assessment."
+
+Do not make any changes.
+
+---
+
+## Case 2 — Blocker Detected (Amazon or Unsupported Features)
+
+**Condition:** Amazon store is targeted, or one or more RevenueCat-only features are in active use.
+
+Produce a blockers report listing every issue found, then present two choices:
+
+> "The following blockers were found that prevent a clean conversion to Unity IAP 5:
+>
+> [List all detected blockers, e.g.:]
+> - **Amazon Appstore**: Unity IAP 5 does not support Amazon. RevenueCat observer mode does not work on Amazon builds either — `syncPurchases()` is broken for Amazon and requires manual `syncAmazonPurchase()` calls. Dropping Amazon support is the only viable path if Unity IAP 5 is the sole billing backend.
+> - **Cross-platform entitlement sync** (`LogIn` 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.
+> - **Remote Paywalls / Offerings**: Unity IAP 5 has no remote paywall system. All products and paywall layouts must be defined in code or a local catalog.
+> - **Subscription webhooks**: Your backend appears to receive RevenueCat webhook events. Unity IAP 5 delivers no server-side lifecycle events — you would need to build your own subscription tracking infrastructure.
+>
+> **Your options:**
+>
+> **(a) Stop conversion (recommended)** — Keep RevenueCat as the billing backend. The features and platforms 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 for Google Play and Apple App Store. RevenueCat switches to observer mode and continues server-side validation and lifecycle tracking. You accept the following consequences:
+> - Amazon Appstore billing will stop working.
+> - [List each unsupported feature and its consequence.]
+> - BillingClient Gradle conflict between Unity IAP 5 and RevenueCat 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 Amazon support, no RevenueCat-only features detected.
+
+Present two choices:
+
+> "No blockers were found. The project uses RevenueCat only for basic purchase flow (no remote paywalls, no cross-platform entitlements, no Amazon). Two conversion paths are available:
+>
+> **(a) Observer mode + Unity IAP 5** — Unity IAP 5 handles purchase transactions. RevenueCat stays in observer mode for server-side validation and subscription lifecycle tracking. Lower risk — RevenueCat's `CustomerInfo` and webhook delivery continue to work.
+>
+> **(b) Full removal — Unity IAP 5 only** — RevenueCat is removed entirely. Unity IAP 5 handles all billing. You lose RevenueCat's server-side receipt validation, subscription lifecycle tracking, and analytics. Simpler architecture, no RevenueCat 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 RevenueCat's and leave the Android build with no BillingClient at all.
+
+   Instead, remove only RevenueCat's copy:
+   - Locate RevenueCat's EDM4U dependency file (typically `Assets/RevenueCat/Editor/RevenueCatDependencies.xml` or similar) and delete the `<androidPackage spec="com.android.billingclient:billing:..."/>` entry, **or**
+   - After Force Resolve, delete the RevenueCat-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. **Switch RevenueCat to observer mode.** In the `Purchases` configuration call, set:
+
+   ```csharp
+   var config = PurchasesConfiguration.Builder.Init("your_api_key")
+       .SetPurchasesAreCompletedBy(PurchasesAreCompletedBy.MyApp)
+       .Build();
+   Purchases.Configure(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 the existing RevenueCat `Purchases.GetOfferings()` or hardcoded product IDs found in the codebase.
+
+5. **Call `syncPurchases()` after every confirmed purchase.** In the Unity IAP `OnPurchasePending` handler, after granting content and saving, call:
+
+   ```csharp
+   Purchases.SharedPurchases.SyncPurchases();
+   ```
+
+   This registers the purchase token with RevenueCat's backend so it can validate the receipt and update `CustomerInfo`.
+
+6. **Produce a verification report** covering:
+   - Files changed
+   - Gradle conflict resolution confirmed
+   - RevenueCat observer mode configuration location
+   - `SyncPurchases()` call location in purchase flow
+   - Manual steps: verify RevenueCat dashboard shows purchases from the updated build in sandbox
+
+---
+
+### Path B — Full Removal of RevenueCat
+
+1. **Extract the product catalog** from existing RevenueCat usage — search for hardcoded product ID strings and `GetOfferings()` calls.
+
+2. **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.
+
+3. **Remove RevenueCat SDK references from code.** Search `Assets/**/*.cs` for `using RevenueCat;` and all `Purchases.*` calls. Replace with the Unity IAP 5 equivalents from the new `IAPManager`.
+
+4. **Remove RevenueCat packages** from `Packages/manifest.json`:
+   - `com.revenuecat.purchases-unity`
+   - `com.revenuecat.purchases-ui-unity` (if present)
+
+   Remove the OpenUPM scoped registry entry for `com.revenuecat` from `manifest.json` if no other RevenueCat packages remain.
+
+5. **Run Assets > External Dependency Manager > Android Resolver > Force Resolve** after package removal to clean up RevenueCat's native dependencies.
+
+6. **Produce a verification report** covering:
+   - Files changed and RevenueCat references removed
+   - Product catalog — confirm all product IDs are preserved in Unity IAP 5
+   - Manual steps: remove the RevenueCat project from the RevenueCat dashboard if no longer needed; verify no orphaned RevenueCat Gradle entries remain in the Android build

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

@@ -0,0 +1,145 @@
+# UniPay IAP — Assessment and Guidance
+
+## Table of Contents
+
+- [Trigger Phrases](#trigger-phrases)
+- [Overview](#overview)
+- [Step 1 — Detect UniPay Version and Unity IAP Version](#step-1--detect-unipay-version-and-unity-iap-version)
+- [Step 2 — Detect Platform Targets](#step-2--detect-platform-targets)
+- [Step 3 — Route Based on Findings](#step-3--route-based-on-findings)
+
+Use this reference when the project has UniPay (FLOBUK) installed and the user asks to migrate, convert, or upgrade IAP. This path does **not** perform a conversion — it assesses the project state and either confirms no action is needed, stops with upgrade advice, or stops due to unsupported platforms.
+
+---
+
+## Trigger Phrases
+
+- "Migrate from UniPay"
+- "Convert UniPay to Unity IAP"
+- "Remove UniPay"
+- "Upgrade UniPay"
+- "Replace UniPay with Unity IAP"
+
+---
+
+## Overview
+
+UniPay wraps `com.unity.purchasing` (Unity IAP) as its underlying billing layer for Apple App Store, Google Play, and Amazon Appstore. It also ships its own separate plugins for Steam, Meta Quest/Oculus, PayPal, and Facebook Instant Games — these platforms have **no Unity IAP equivalent** and cannot be migrated.
+
+Because UniPay already uses Unity IAP under the hood, there is no "conversion" to perform for Apple/Google/Amazon billing. The assessment stops at one of three outcomes:
+
+| Outcome | Condition |
+|---|---|
+| **Unsupported platform — stop** | Project targets Steam, Meta Quest, PayPal, or Facebook Instant Games |
+| **Upgrade required — stop** | UniPay is present with Unity IAP v4 |
+| **No action needed** | UniPay 6.2.0+ with Unity IAP v5 already installed |
+
+---
+
+## Step 1 — Detect UniPay Version and Unity IAP Version
+
+### 1a — Locate UniPay version
+
+Search for UniPay's version in this order:
+
+1. `Assets/Plugins/UniPay/package.json` — read the `"version"` field.
+2. `Assets/Plugins/SIS/package.json` — legacy path (UniPay was formerly "Simple IAP System").
+3. `Assets/Plugins/UniPay/Scripts/IAPManager.cs` or any file containing a `VersionNumber` or `version` constant string.
+4. `ProjectSettings/ProjectSettings.asset` — search for `UniPay` or `SIS` version keys.
+
+If the version cannot be determined from any of the above, report:
+
+> "UniPay is installed but its version could not be determined. Please check **Edit > Project Settings > UniPay In-App Purchasing** for the installed version and confirm whether it is 6.2.0 or later."
+
+Do not stop — proceed to Step 1b with the version marked as unknown.
+
+### 1b — Check Unity IAP version
+
+Read `Packages/manifest.json` and find the `com.unity.purchasing` entry.
+
+| Result | Note |
+|---|---|
+| Version matches `4\.` | Unity IAP v4 — see routing in Step 3 |
+| Version matches `5\.` | Unity IAP v5 — see routing in Step 3 |
+| Absent | Unexpected — UniPay requires Unity IAP; report the missing dependency and stop |
+
+---
+
+## Step 2 — Detect Platform Targets
+
+Search `ProjectSettings/ProjectSettings.asset` for the enabled build targets. Also search `Assets/**/*.cs` and `Assets/Plugins/` for integration signals:
+
+| Signal to search for | Platform implied |
+|---|---|
+| `Steamworks|SteamManager|SteamAPI|com\.rlabrecque\.steamworks` | Steam (Standalone PC/Mac) |
+| `OculusSDK|OVRManager|com\.oculus|Meta Quest|com\.unity\.xr\.oculus` | Meta Quest / Oculus |
+| `PayPal|PayPalManager|PAYPAL` in C# or prefabs | PayPal (WebGL) |
+| `FacebookSDK|FB\.Init|com\.facebook\.sdk` | Facebook Instant Games |
+
+These platforms use UniPay's own billing plugins — **Unity IAP 5 has no equivalent for any of them.** If any are detected, they must be flagged as blockers (see Step 3, Route C).
+
+---
+
+## Step 3 — Route Based on Findings
+
+Apply the first matching route below.
+
+---
+
+### Route A — Unsupported Platform Detected (stop)
+
+**Condition:** Step 2 found Steam, Meta Quest, PayPal, or Facebook Instant Games signals.
+
+Stop and report:
+
+> "This project uses UniPay's [platform] integration. Unity IAP 5 does not support [platform] — there is no migration path for this billing backend. No changes will be made.
+>
+> If you want to continue using [platform] billing, keep UniPay. If you are dropping [platform] support entirely, remove the platform-specific UniPay integration manually first, then re-run this skill."
+
+List every unsupported platform found. Do not proceed with any changes.
+
+---
+
+### Route B — Upgrade Required (Unity IAP v4 detected)
+
+**Condition:** `com.unity.purchasing` version matches `4\.`, regardless of UniPay version.
+
+Stop and report:
+
+> "This project uses Unity IAP v4 as UniPay's billing backend. UniPay 6.2.0+ requires Unity IAP v5 and Unity 6.
+>
+> **Required upgrades before any IAP work can proceed:**
+> 1. Upgrade the Unity Editor to the latest stable Unity 6 release.
+> 2. Upgrade `com.unity.purchasing` to the latest stable v5 release via **Window > Package Manager**.
+> 3. Upgrade UniPay to version 6.2.0 or later — purchase the latest version from the Unity Asset Store and follow FLOBUK's upgrade instructions.
+>
+> Once all three upgrades are complete, re-run this skill."
+
+Do not make any code or package changes. Do not proceed.
+
+---
+
+### Route C — No Action Needed (UniPay 6.2.0+ with IAP v5)
+
+**Condition:** Unity IAP v5 is installed and UniPay version is 6.2.0 or later (or version is unknown but IAP v5 is confirmed).
+
+Check the exact `com.unity.purchasing` version from `Packages/manifest.json` and include it in the report:
+
+**If `com.unity.purchasing` is v5.0–5.3:**
+
+> "This project already uses UniPay [version] with Unity IAP v5.x as its billing backend. UniPay handles the IAP layer — no migration or conversion is needed.
+>
+> Note: IAP D2C Capabilities (third-party payment providers such as Stripe or Coda) require Unity IAP v5.4+. If you plan to add D2C support in the future, you will need to upgrade `com.unity.purchasing` to v5.4+ via **Window > Package Manager**.
+>
+> If you want to add new products, modify purchase logic, or handle platform-specific billing behavior, work within UniPay's API (see FLOBUK documentation). If you want to remove UniPay entirely and use Unity IAP 5 directly, that is a manual refactor — ask specifically for that and describe which UniPay features you are replacing."
+
+**If `com.unity.purchasing` is v5.4+:**
+
+> "This project already uses UniPay [version] with Unity IAP v5.4+ as its billing backend. UniPay handles the IAP layer — no migration or conversion is needed.
+>
+> If you want to add new products, modify purchase logic, or handle platform-specific billing behavior, work within UniPay's API (see FLOBUK documentation). If you want to remove UniPay entirely and use Unity IAP 5 directly, that is a manual refactor — ask specifically for that and describe which UniPay features you are replacing."
+
+Do not make any changes. This is an informational stop.
+
+---
+