nccgs 1.0.0

package/.claude/skills/implement-in-app-purchases/references/platform-notes.md

@@ -0,0 +1,204 @@
+# Unity IAP Platform-Specific Notes
+
+## Table of Contents
+
+- [Apple App Store Extensions](#apple-app-store-extensions)
+- [Google Play Store Extensions](#google-play-store-extensions)
+- [Apple JWS Representation (Server-Side Validation)](#apple-jws-representation-server-side-validation)
+- [SubscriptionInfo Platform Nuances](#subscriptioninfo-platform-nuances)
+- [Cross-Platform Best Practices](#cross-platform-best-practices)
+- [Platform Extension Availability](#platform-extension-availability)
+
+## Apple App Store Extensions
+
+Access via `store.AppleStoreExtendedPurchaseService` (for purchase features) and `store.AppleStoreExtendedService` (for store features).
+
+### Promotional Purchases
+
+Apple can present purchases from the App Store product page. Intercept and handle them:
+
+```csharp
+if (store.AppleStoreExtendedPurchaseService != null)
+{
+    store.AppleStoreExtendedPurchaseService.OnPromotionalPurchaseIntercepted += (product) =>
+    {
+        // Player tapped "Buy" on App Store product page
+        // You can delay the purchase (e.g., show a loading screen first)
+        Debug.Log($"Promotional purchase intercepted: {product.definition.id}");
+
+        // When ready, continue the purchase
+        store.AppleStoreExtendedPurchaseService.ContinuePromotionalPurchases();
+    };
+}
+```
+
+**CRITICAL:** If you subscribe to `OnPromotionalPurchaseIntercepted`, you MUST eventually call `ContinuePromotionalPurchases()` or the purchase will hang indefinitely.
+
+### Ask-to-Buy (Parental Approval)
+
+On devices with Family Sharing and a child account, purchases may require parental approval:
+
+```csharp
+store.OnPurchaseDeferred += (deferredOrder) =>
+{
+    // Purchase is waiting for parental approval
+    // Show UI: "Purchase pending approval"
+    // Do NOT grant content yet
+    Debug.Log("Purchase deferred - awaiting approval");
+};
+```
+
+The purchase will complete later (triggering `OnPurchasePending`) when approved, or fail when rejected.
+
+For testing in sandbox:
+
+```csharp
+// Simulate Ask-to-Buy in the editor/sandbox
+store.AppleStoreExtendedPurchaseService.simulateAskToBuy = true;
+```
+
+### Offer Code Redemption
+
+Present the Apple offer code redemption sheet:
+
+```csharp
+store.AppleStoreExtendedPurchaseService.PresentCodeRedemptionSheet();
+```
+
+### Entitlement Revocation
+
+Listen for revoked entitlements (e.g., refund granted):
+
+```csharp
+store.AppleStoreExtendedPurchaseService.OnEntitlementRevoked += (productId) =>
+{
+    Debug.Log($"Entitlement revoked for: {productId}");
+    // Remove the content/feature from the player
+};
+```
+
+### Store Capabilities
+
+```csharp
+// Check if the device can make payments (parental controls may block)
+bool canPay = store.AppleStoreExtendedService.canMakePayments;
+
+// Set App Account Token for server-to-server verification
+store.AppleStoreExtendedService.SetAppAccountToken(Guid.NewGuid());
+
+// Fetch storefront info (StoreKit 2 only)
+store.AppleStoreExtendedService.FetchStorefront(
+    (storefront) => Debug.Log($"Storefront: {storefront.CountryCode}"),
+    (error) => Debug.LogError($"Storefront error: {error}")
+);
+```
+
+## Google Play Store Extensions
+
+Access via `store.GooglePlayStoreExtendedPurchaseService` (for purchase features) and `store.GooglePlayStoreExtendedService` (for store features).
+
+### Subscription Upgrade/Downgrade
+
+Change a player's subscription tier:
+
+```csharp
+// Get the current subscription order and the new product
+Order currentOrder = /* the player's current subscription order */;
+Product newProduct = store.GetProductById("com.mygame.vip_annual");
+
+store.GooglePlayStoreExtendedPurchaseService.UpgradeDowngradeSubscription(
+    currentOrder,
+    newProduct,
+    GooglePlayReplacementMode.ChargeFullPrice
+);
+```
+
+### GooglePlayReplacementMode Values
+
+| Mode | Behavior |
+|---|---|
+| `UnknownReplacementMode` | Default |
+| `WithTimeProration` | Remaining time is adjusted |
+| `ChargeProratedPrice` | Prorated charge for the upgrade |
+| `WithoutProration` | New plan starts at next billing |
+| `ChargeFullPrice` | Full price charged immediately |
+| `Deferred` | Change takes effect at next billing |
+
+### Obfuscated IDs
+
+Set obfuscated account/profile IDs for fraud detection:
+
+```csharp
+store.GooglePlayStoreExtendedService.SetObfuscatedAccountId("hashed_account_id");
+store.GooglePlayStoreExtendedService.SetObfuscatedProfileId("hashed_profile_id");
+```
+
+Retrieve them from an order:
+
+```csharp
+string accountId = store.GooglePlayStoreExtendedPurchaseService.GetObfuscatedAccountId(order);
+string profileId = store.GooglePlayStoreExtendedPurchaseService.GetObfuscatedProfileId(order);
+```
+
+### Deferred Payment Events
+
+```csharp
+store.GooglePlayStoreExtendedPurchaseService.OnDeferredPaymentUntilRenewalDate += (deferredOrder) =>
+{
+    Debug.Log($"Payment deferred until renewal: {deferredOrder.SubscriptionOrdered.definition.id}");
+};
+```
+
+## Apple JWS Representation (Server-Side Validation)
+
+For server-side Apple receipt validation (replacing the deprecated `CrossPlatformValidator`):
+
+```csharp
+store.OnPurchasePending += (pendingOrder) =>
+{
+    // Access the JWS-signed transaction
+    string jws = pendingOrder.Info.Apple?.jwsRepresentation;
+    // Send to your server for validation with Apple's App Store Server API (v2)
+    ValidateOnServer(jws);
+};
+```
+
+The `jwsRepresentation` contains a signed JSON Web Signature that can be verified using Apple's public keys.
+
+## SubscriptionInfo Platform Nuances
+
+| Method | Apple | Google |
+|---|---|---|
+| `GetPurchaseDate()` | Returns the **renewal date** (most recent renewal) | Returns the **original purchase date** |
+| `GetCancelDate()` | Returns actual cancellation date | Returns `DateTime.MinValue` (not supported) |
+
+Always check `IsSubscribed()` first — if the result is `Result.Unsupported`, the platform doesn't provide that information.
+
+## Cross-Platform Best Practices
+
+| Concern | Recommendation |
+|---|---|
+| Restore button | Required on iOS (Apple guideline). Add a "Restore Purchases" button that calls `store.RestoreTransactions()`. |
+| Receipt validation | **Google Play:** Use `CrossPlatformValidator(GooglePlayTangle.Data(), Application.identifier)` for local validation. **Apple (StoreKit 2):** Local validation via `CrossPlatformValidator` is a **no-op** — use `order.Info.Apple?.jwsRepresentation` for server-side validation instead. |
+| Pending purchases | Always handle `OnPurchasePending` and call `ConfirmPurchase`. Unconfirmed purchases persist across launches. |
+| Product IDs | Use reverse-domain naming: `com.company.game.product` |
+| Testing | Use sandbox accounts (Apple) and license testing accounts (Google) for testing without real charges. |
+| Subscriptions | Always check `IsSubscribed()` at app launch, not just purchase time. Subscriptions can expire or be cancelled externally. |
+
+## Platform Extension Availability
+
+| Extension | iOS | Android | Editor |
+|---|---|---|---|
+| `AppleStoreExtendedService` | Available | `null` | `null` |
+| `AppleStoreExtendedPurchaseService` | Available | `null` | `null` |
+| `GooglePlayStoreExtendedService` | `null` | Available | `null` |
+| `GooglePlayStoreExtendedPurchaseService` | `null` | Available | `null` |
+
+**CRITICAL:** Always null-check platform extensions before use:
+
+```csharp
+if (store.AppleStoreExtendedPurchaseService != null)
+{
+    store.AppleStoreExtendedPurchaseService.OnPromotionalPurchaseIntercepted += HandlePromo;
+}
+```

package/.claude/skills/implement-in-app-purchases/references/pre-check.md

@@ -0,0 +1,205 @@
+# Pre-Check: Project Scan and Path Routing
+
+## Table of Contents
+
+- [Ambiguous Intent](#ambiguous-intent)
+- [IAP D2C Capabilities (Direct-to-Customer, Third-Party Payment Provider)](#iap-d2c-capabilities-direct-to-customer-third-party-payment-provider)
+- [Scan Order (standard IAP paths)](#scan-order-standard-iap-paths)
+- [Routing Summary](#routing-summary)
+
+  Scan steps: [1 — Third-Party IAP Package Check](#1--third-party-iap-package-check-highest-priority) · [2 — Native Google Billing](#2--native-google-billing-check) · [2b — Native iOS StoreKit](#2b--native-ios-storekit-check) · [3 — Unity IAP v4](#3--unity-iap-v4-check) · [4 — Unity IAP v5 Already Installed](#4--unity-iap-v5-already-installed) · [5 — No IAP Detected](#5--no-iap-detected)
+  Third-party sub-checks: [1a Essential Kit](#1a--essential-kit-conversion-supported) · [1b UniPay](#1b--unipay-assessment-path) · [1c RevenueCat](#1c--revenuecat-assessment-path) · [1d Adapty](#1d--adapty-assessment-path)
+
+Run this scan before doing anything else. Do not read any other reference file or make any changes until routing is resolved.
+
+## Ambiguous Intent
+
+If the user's prompt does not clearly indicate which billing backend they want — for example:
+
+- "Add a StoreController for me"
+- "Add a purchase manager"
+- "Set up IAP"
+- "Help me add in-app purchases"
+- "Upgrade to latest IAP"
+
+**Stop and ask before scanning or routing:**
+
+> "Would you like to implement purchasing using:
+> - **Apple App Store / Google Play** (standard platform billing), or
+> - **IAP D2C Capabilities** (third-party payment provider such as Stripe or Coda via Unity Cloud)?"
+
+Do not assume a default. Route only after the user confirms their intent.
+
+---
+
+## IAP D2C Capabilities (Direct-to-Customer, Third-Party Payment Provider)
+
+If the user explicitly asks for IAP D2C Capabilities, Stripe/Coda payment integration, or a third-party payment provider, **do not follow the standard scan order below**. Instead:
+
+- If the project has IAP v4, native Google Billing, or a third-party IAP package → resolve those blockers first using the standard scan order, then return here.
+- If the project has no IAP, or has `com.unity.purchasing` **v5.4+** → route to [path-implement-iap-d2c.md](path-implement-iap-d2c.md).
+- If the project has `com.unity.purchasing` **v5.0–5.3** → inform the user that IAP D2C Capabilities require v5.4+, instruct them to upgrade via Package Manager, and continue once the upgrade is confirmed.
+
+---
+
+## Scan Order (standard IAP paths)
+
+Run scans in this exact order. The first match wins — stop scanning and route immediately.
+
+---
+
+### 1 — Third-Party IAP Package Check (highest priority)
+
+#### 1a — Essential Kit (conversion supported)
+
+Search `Packages/manifest.json` and `Packages/packages-lock.json` for `com.voxelbusters.essentialkit`.
+
+**If found → only one path is valid:**
+
+> Route to [convert-essentialkit.md](convert-essentialkit.md)
+
+Inform the user that Essential Kit was detected and that the conversion path will be used. Do not offer any other path.
+
+---
+
+#### 1b — UniPay (assessment path)
+
+Search `Packages/manifest.json`, `Packages/packages-lock.json`, and `Assets/Plugins/` for UniPay signals:
+
+```
+com\.flobuk\.unipay|UniPay|Assets/Plugins/UniPay|Assets/Plugins/SIS
+```
+
+**If found → only one path is valid:**
+
+> Route to [convert-unipay.md](convert-unipay.md)
+
+Inform the user that UniPay was detected and that the assessment path will be used. Do not offer any other path.
+
+---
+
+#### 1c — RevenueCat (assessment path)
+
+Search `Packages/manifest.json` and `Packages/packages-lock.json` for `com.revenuecat.purchases-unity`.
+
+**If found → only one path is valid:**
+
+> Route to [convert-revenuecat.md](convert-revenuecat.md)
+
+Inform the user that RevenueCat was detected and that the assessment path will be used. Do not offer any other path.
+
+---
+
+#### 1d — Adapty (assessment path)
+
+Search `Packages/manifest.json`, `Packages/packages-lock.json`, and `Assets/` for Adapty signals:
+
+```
+com\.adapty|Assets/Adapty|AdaptySDK
+```
+
+**If found → only one path is valid:**
+
+> Route to [convert-adapty.md](convert-adapty.md)
+
+Inform the user that Adapty was detected and that the assessment path will be used. Do not offer any other path.
+
+---
+
+### 2 — Native Google Billing Check
+
+Search the following locations:
+
+- `Assets/**/*.cs` for: `AndroidJavaObject|AndroidJavaClass|BillingClient|BillingManager|GoogleBilling|BillingBridge`
+- `Assets/Plugins/Android/**/*.java`, `*.kt` for: `com\.android\.billingclient`
+- `mainTemplate.gradle`, `launcherTemplate.gradle`, `baseProjectTemplate.gradle` for: `com\.android\.billingclient:billing`
+
+**If found → only one path is valid:**
+
+> Route to [path-convert-native-google-billing.md](path-convert-native-google-billing.md)
+
+Inform the user that native Google Billing was detected and that the conversion path will be used. If `com.unity.purchasing` is absent or not the latest stable version, instruct the user to install or upgrade to the latest stable version via Package Manager before proceeding.
+
+Do not offer any other path.
+
+---
+
+### 2b — Native iOS StoreKit Check
+
+Search the following for native StoreKit signals:
+
+- `Assets/Plugins/iOS/**/*.m`, `*.mm`, `*.h`, `*.swift` for: `SKProductsRequest|SKPaymentQueue|SKPaymentTransaction|SKPaymentTransactionObserver|Product\.products|Transaction\.currentEntitlements`
+- `Assets/**/*.cs` for: `DllImport.*__Internal` combined with IAP-related method names, or `UnitySendMessage` calls associated with StoreKit
+
+**If found → only one path is valid:**
+
+> Route to [path-convert-native-storekit.md](path-convert-native-storekit.md)
+
+Inform the user that a native iOS StoreKit plugin was detected and that the conversion path will be used. If `com.unity.purchasing` is absent or not the latest stable version, instruct the user to install or upgrade via Package Manager before proceeding.
+
+Do not offer any other path.
+
+---
+
+### 3 — Unity IAP v4 Check
+
+Search `Packages/manifest.json` for `com.unity.purchasing` with a version matching `4\.`.
+
+Also search `Assets/**/*.cs` for legacy v4 API patterns:
+
+```
+IStoreListener|UnityPurchasing\.Initialize|ConfigurationBuilder
+```
+
+**If found → only one path is valid:**
+
+> Route to [migration-v4-to-v5.md](migration-v4-to-v5.md)
+
+Inform the user that Unity IAP v4 was detected and that the v4→v5 migration path will be used. Do not offer any other path.
+
+---
+
+### 4 — Unity IAP v5 Already Installed
+
+If none of the above matched, search `Packages/manifest.json` for `com.unity.purchasing` with a version matching `5\.`:
+
+**If found → inform the user:**
+
+> "This project already has Unity IAP v5 installed. You can extend the existing setup — for example, add new products, add platform-specific features, or integrate IAP D2C Capabilities. What would you like to do?"
+
+Then route based on the user's answer. Do not automatically route to the new-project path — the project already has IAP configured.
+
+---
+
+### 5 — No IAP Detected
+
+If none of the above matched and `com.unity.purchasing` is absent from `manifest.json`:
+
+**→ only one path is valid:**
+
+> Route to [path-add-iap-to-new-project.md](path-add-iap-to-new-project.md)
+
+---
+
+## Routing Summary
+
+| What is detected | Valid path |
+|---|---|
+| Essential Kit (`com.voxelbusters.essentialkit`) | Convert Essential Kit billing → IAP 5 — see convert-essentialkit.md |
+| UniPay (FLOBUK) | Assessment — see convert-unipay.md |
+| RevenueCat | Assessment — see convert-revenuecat.md |
+| Adapty | Assessment — see convert-adapty.md |
+| Native Google BillingClient | Convert native Google Billing → IAP 5 — see path-convert-native-google-billing.md |
+| Native iOS StoreKit plugin (`SKPaymentQueue` / `DllImport("__Internal")`) | Convert native StoreKit → IAP 5 — see path-convert-native-storekit.md |
+| `com.unity.purchasing` v4 or v4 API patterns | Migrate IAP v4 → v5 |
+| `com.unity.purchasing` v5 already installed | Ask user what to extend — do not auto-route |
+| No IAP detected | Add Unity IAP 5 to new project |
+| User explicitly requests IAP D2C Capabilities / payment provider | See IAP D2C Capabilities section above |
+
+---
+
+## Also check: Codeless catalog presence
+
+Regardless of which route above wins, check whether `Assets/Resources/IAPProductCatalog.json` exists. This is the **Codeless IAP** catalog and is independent of the routing decision — but if it is present and `enableCodelessAutoInitialization` is true, adding a scripted `StoreController` creates a race condition with `CodelessIAPStoreListener`.
+
+Surface the catalog's presence and auto-init flag to the user before generating scripted IAP code. See [codeless-catalog.md](codeless-catalog.md) for the race condition details and the three mitigation options.

package/.claude/skills/incident-recovery/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: incident-recovery
+description: Coordinates evidence-preserving response to data loss, corruption, broken builds, failed migrations, or production-impacting Unity incidents.
+allowed-tools: Read, Glob, Grep, Write, Edit, Bash, Task, AskUserQuestion
+---
+
+# Incident Recovery
+
+Read `.nccgs/project.yaml`, `.nccgs/state.md`, and the active context packet when present. Preserve Product Owner authority and unrelated work.
+
+Prioritize containment and evidence preservation. Record incident scope, affected versions/data, current state, timeline, hypotheses, and irreversible-action boundaries. Avoid destructive cleanup and speculative rewrites. Build a recovery graph with backups, reproducible diagnostics, validation, and rollback. Apply only authorized recovery changes; maintain an incident record and follow-up prevention actions. Data deletion or production actions require explicit authority.
+
+Return outcome, evidence, affected records, blockers or decisions, residual risk, and the exact next workflow. Do not claim DONE unless this is the `closure` skill and every configured gate passes.
+

package/.claude/skills/initialize-ai-navigation/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: initialize-ai-navigation
+description: Sets up and configures the Unity AI Navigation system — NavMesh surfaces, NavMesh agents, obstacles, links, modifiers, areas and costs. Use when creating walkable navigation meshes, adding pathfinding agents, setting up patrol routes, configuring obstacle avoidance and carving, connecting separate NavMeshes with links, coupling navigation with animation, or troubleshooting navigation issues.
+---
+
+Determine what the user needs and guide them through navigation setup. See [navigation-system.md](references/navigation-system.md) for expanded component details, API notes, code recipes, and troubleshooting.
+
+### Passing C# to `eval`
+
+`eval` compiles a **statement block, not a file**. Two consequences, both of which cause a
+compile error rather than a warning:
+
+- **No `using` directives.** The compiler reads `using UnityEngine;` as a resource-disposal
+  statement and rejects it (`CS0210`).
+- **Types must be fully qualified.** A bare `AssetDatabase` or `Volume` does not resolve
+  (`CS0246` / `CS0103`), and a bare `Object` is ambiguous with `object` (`CS0104`).
+
+Where a snippet below is written as a file — with usings, for readability, or because it is
+meant to be saved into the project — qualify the types before passing it to `eval`.
+
+## Routing Logic
+
+| User Says | Interpretation |
+|-----------|---------------|
+| "add navigation" / "set up nav" | Full setup: NavMeshSurface + bake + NavMeshAgent |
+| "make this character navigate" | Add NavMeshAgent, ensure NavMesh exists |
+| "add pathfinding" | NavMeshAgent + movement script |
+| "agent won't move" / "path not found" | Troubleshoot — see Troubleshooting Decision Tree in reference |
+| "avoid obstacles" | NavMeshObstacle with carving or avoidance |
+| "connect two areas" / "jump across" | NavMeshLink between areas |
+| "patrol between points" | NavMeshAgent + patrol script |
+| "click to move" | NavMeshAgent + raycast click-to-move script |
+| "animate the character while navigating" | Couple Animator with NavMeshAgent |
+| "different agent sizes" | Configure agent types in Navigation window |
+| "areas and costs" / "restrict areas" | NavMesh area types, modifiers, and agent area masks |
+
+## Workflow
+
+### 0. Package Installation Check
+Before doing anything else, verify that `com.unity.ai.navigation` is installed. If it's missing,
+add it to `Packages/manifest.json` under `dependencies` — Unity resolves it when the Editor next
+regains focus, and this needs no Editor connection:
+
+```json
+"com.unity.ai.navigation": "<current 2.x version>"
+```
+
+Don't invent the version string. Read the current one from the Unity registry —
+`https://packages.unity.com/com.unity.ai.navigation` lists every published version — or copy the version an
+adjacent Unity package in this manifest already uses. A version that doesn't exist makes
+Unity fail resolution **silently**, so a wrong guess looks like nothing happened.
+
+Proceed only once it's confirmed installed. If you have a live Editor to run C# in, see
+[navigation-system.md](references/navigation-system.md) for the `Client.Add` equivalent.
+
+### 1. Pre-Flight: Assess Current Navigation Setup
+Before making changes, inspect what already exists:
+1. Find the existing navigation components. With a connected Editor, query the live scene for
+   `NavMeshSurface`, `NavMeshAgent`, `NavMeshObstacle`, `NavMeshLink` and `NavMeshModifier` — see
+   the `unity-cli` skill for driving a running Editor. Without one, search the scene and prefab
+   files for those component names.
+2. Check configured agent types via **Window > AI > Navigation > Agents tab**.
+3. Summarize ALL detected navigation components before proposing changes.
+
+### 2. Gather Missing Information
+Before creating components, ensure the user has specified: walkable surfaces, agent type/size, agent behavior, obstacles, links, and area/cost requirements. Ask if anything is unclear. See the Information Gathering Checklist in the reference for full details.
+
+### 3. Planning & Execution
+Follow this general order. See the Component Setup Guide in the reference for detailed step-by-step instructions per component:
+1. **NavMesh Surface** — create the walkable mesh (bake it)
+2. **NavMesh Agent** — add pathfinding characters
+3. **NavMesh Obstacle** — add dynamic obstacles
+4. **NavMesh Link** — connect disconnected NavMesh areas
+5. **NavMesh Modifier / Modifier Volume** — fine-tune area types
+6. **Scripts** — movement, patrol, click-to-move, animation coupling (see Common Recipes in reference)
+
+### 4. Validation
+After setup, confirm:
+- NavMesh is baked and visible (blue overlay)
+- NavMeshSurface agent type matches NavMeshAgent agent type
+- Agents have a valid path to their destination
+- Obstacles carve or obstruct correctly
+- Links have both ends connected and Activated is enabled
+- Area masks allow the intended movement
+- No conflicting components (see Mixing Components Guide in reference)
+- If using Rigidbody with NavMeshAgent, Is Kinematic is enabled
+
+### 5. Final Confirmation
+Summarize what was created or changed:
+- NavMesh Surfaces: which GameObject, agent type, geometry mode, bake status
+- NavMesh Agent(s): which GameObject, speed, stopping distance, area mask
+- NavMesh Obstacle(s): which GameObject, shape, carve on/off
+- NavMesh Link(s): start/end, bidirectional, area type
+- Scripts: which scripts attached to which GameObjects
+- Any manual steps required (adjust waypoints, re-bake after scene changes, etc.)