@aqian0/dsh-unity 0.0.0-stage → 0.1.0

package/skills/generate-editor-search-query/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: generate-editor-search-query
+description: Generates Unity Search queries and opens the Search window to find assets or scene objects. Use when the user asks to find, filter, or list assets, GameObjects, components, or references in the Editor, not on disk.
+enabled: true
+modes: [agent, ask]
+---
+
+Translate natural-language Unity Editor search requests into useful Unity Search queries, explain them briefly, and open the Unity Search window with the query when appropriate.
+
+## Default Behavior
+
+If the prompt explicitly says Unity Search, Quick Search, Search window, open Search, or asks for a Unity Search query, handle the search request with this skill even when the target belongs to another domain such as lighting, UI, physics, audio, or animation.
+
+For requests such as "find", "search", "locate", "list", "filter", "look up", "where is", "which assets use", or "what references" concrete Unity assets or scene objects:
+
+1. Determine whether the request is primarily about project assets, scene objects, or both.
+2. Build one concise Unity Search query.
+3. Show the query in the response before or while opening Search.
+4. Open Unity Search by running the Editor-side snippet unless the user explicitly asks for query text only.
+5. If opening Search fails, return the query and tell the user to paste it into Unity Search manually.
+
+Do not open Search when the user says "do not open Search", "query only", "what query should I use", "just give me the query", or similar.
+
+If the user asks for a general explanation, project overview, folder-structure summary, architecture walkthrough, gameplay-system summary, or "how do I" programming answer, do not use this skill unless the prompt explicitly asks for Unity Search, a Search query, or opening the Search window.
+
+If the user refers to "this", "selected", or "current" without an attached asset, scene object, visible name, or path, ask for the name/path instead of inventing one.
+
+## Scope
+
+Scope read-only Unity Search / Quick Search queries to:
+
+- project assets such as materials, textures, prefabs, scenes, scripts, shaders, audio clips, sprites, meshes, models, animations, fonts, render textures, and ScriptableObject assets
+- scene objects and components such as Cameras, Lights, Rigidbodies, Colliders, Renderers, Canvas objects, UI components, ParticleSystems, AudioSources, Animators, Terrain objects, and named GameObjects
+- path, label, type, filename, keyword, and reference-oriented asset searches
+- selected or named assets when the name/path is available from the conversation or attachment
+
+Do not install packages, run menu commands, edit assets, modify scenes, search external documentation, search repository text, inspect build logs, delete results, fix search results, or perform dependency graph analysis. If the user asks to act on results, first open Search or provide the query, then ask for confirmation before any separate modifying skill or workflow.
+
+## References
+
+Before generating non-trivial queries, read [references/query-patterns.md](references/query-patterns.md).
+
+Before opening the Search window, read [references/open-search-window.md](references/open-search-window.md).
+
+Official English references:
+
+- [Unity Search](https://docs.unity3d.com/Manual/search-overview.html)
+- [Search expressions](https://docs.unity3d.com/Manual/search-expressions.html)
+- [SearchService.ShowWindow](https://docs.unity3d.com/6000.0/Documentation/ScriptReference/Search.SearchService.ShowWindow.html)
+
+## Passing C# to `script eval`
+
+`script eval` compiles a **statement block, not a file**. Two consequences, both compile errors:
+
+- **No `using` directives.** The compiler reads `using UnityEditor;` as a resource-disposal
+  statement and rejects it (`CS0210`).
+- **Types must be fully qualified.** A bare `SearchService` does not resolve (`CS0246`), and a
+  bare `Object` is ambiguous with `object` (`CS0104`).
+
+The `unity-cli` skill owns the prerequisites — installing the CLI, confirming a connected Editor,
+adding the project's `com.unity.pipeline` package, and discovering the command catalog. You need
+`script eval` in particular; if it is absent, generate the query text and say the window can't be opened.
+
+## Query Generation Rules
+
+Use the simplest query that is likely to produce the requested result.
+
+- Prefer type filters for asset and component requests, such as `t:material`, `t:texture`, `t:prefab`, `t:scene`, `t:script`, `t:shader`, `t:Light`, or `t:Rigidbody`.
+- Preserve user-provided names and keywords as plain query terms unless they need quoting.
+- Use `dir:` when the user gives a folder or says "in Assets/..." or "under ...".
+- Use `l:` when the user asks for a Unity asset label.
+- Use `ref=` when the user asks what references, uses, depends on, contains, or is connected to an asset.
+- Use Search expressions only when they clearly improve the query, such as `t:prefab ref={t:texture}` or `t:scene ref={t:prefab}`.
+- For selected/current wording, use the known selected asset name or path only if it is present in the chat context; otherwise ask for it.
+- For broad relationship requests such as "where is Rigidbody used", use a simple keyword or component query first, then mention that a scripted audit is separate if the user needs exhaustive code/property analysis.
+- For requests that mix Search with repair work, generate and open the query first; do not modify results unless the user explicitly confirms a separate follow-up action.
+- Do not invent unsupported filters for uncertain requests. If a request cannot be expressed reliably with Unity Search syntax, open the closest safe query and state the limitation.
+
+## Opening Unity Search
+
+Run C# in the Editor only to open the Search window. This is an Editor UI action and must not change project assets or scene contents.
+
+When opening Search:
+
+1. Base64-encode the query (UTF-8) and embed only the base64 text in the generated C# string, decoding it back to a string inside the snippet.
+2. Prefer asset and scene providers for this v1 skill.
+3. Fall back to active providers if a provider is unavailable.
+4. Log the query that was opened.
+5. Never claim Search opened if the command failed.
+
+## Response Format
+
+Keep the user-facing response short:
+
+```text
+Query: `t:material`
+Opened Unity Search with that query.
+```
+
+If not opening Search:
+
+```text
+Query: `t:prefab ref={t:texture}`
+Paste this into Unity Search.
+```
+
+If the request is ambiguous but still searchable, choose the most likely query and mention the assumption. Ask a question only when the search target cannot be inferred, such as "find the thing" with no asset, scene, type, name, or context.
+
+## Validation Checklist
+
+Before reporting success:
+
+- the generated query is shown to the user
+- the query targets assets, scene objects, or both
+- Search was opened only when the user did not opt out
+- any fallback or uncertainty is stated plainly
+- no asset, scene, package, project setting, or search result was modified

package/skills/generate-editor-search-query/references/open-search-window.md

@@ -0,0 +1,70 @@
+# Open Unity Search Window
+
+Use this pattern when the skill should open Unity Search pre-populated with a generated query.
+
+This is a read-only Editor UI action. It must not create, modify, delete, import, install, or save anything.
+
+## Editor-side snippet
+
+Base64-encode the generated Unity Search query (UTF-8) and embed only the base64 text, decoding it
+back to a string inside the snippet. Never embed the raw query text in the C# string or in the
+shell command: a query containing `"` would break out of a verbatim C# string, and a query
+containing `'` would break the shell's single-quoting around `--code`. Base64's alphabet
+(`A-Z a-z 0-9 + / =`) cannot close either quote, so it stays safe in both places at once.
+
+Encode it without putting the raw query on a command line either. Write the query to a
+temporary file with your file-writing tool (not with `echo` or a shell variable), then encode
+that file, stripping the newline `base64` adds:
+
+```sh
+base64 < query.txt | tr -d '\n'
+```
+
+Delete the temporary file afterwards.
+
+Replace `QUERY_BASE64` with that output.
+
+Run it through the Editor with `unity command script eval --caller plugin --skill generate-editor-search-query --code '<snippet>'`. Fully qualified, with no
+`using` directives, because `script eval` compiles a statement block rather than a file.
+
+```csharp
+var query = System.Text.Encoding.UTF8.GetString(System.Convert.FromBase64String("QUERY_BASE64"));
+
+var candidates = new[]
+{
+    UnityEditor.Search.SearchService.GetProvider("asset"),
+    UnityEditor.Search.SearchService.GetProvider("scene")
+};
+var preferredProviders = System.Linq.Enumerable.ToArray(
+    System.Linq.Enumerable.Where(candidates, provider => provider != null));
+
+var context = preferredProviders.Length > 0
+    ? new UnityEditor.Search.SearchContext(preferredProviders, query)
+    : new UnityEditor.Search.SearchContext(UnityEditor.Search.SearchService.GetActiveProviders(), query);
+
+UnityEditor.Search.SearchService.ShowWindow(context);
+return $"Opened Unity Search with query: {query}";
+```
+
+## Fallback Behavior
+
+If compilation or execution fails:
+
+1. Do not claim Search opened.
+2. Show the query to the user.
+3. Tell the user to paste it into Unity Search manually.
+4. If the error indicates `UnityEditor.Search` is unavailable, say the project/editor version may not expose the Modern Search API used by the opener.
+
+## Provider Choice
+
+For v1, prefer the `asset` and `scene` providers because this skill is scoped to project assets and scene objects.
+
+Use active providers only as a fallback when one or both preferred providers are unavailable.
+
+## Safety Rules
+
+- Do not call APIs that act on search results.
+- Do not select, ping, rename, delete, move, import, or edit results.
+- Do not save assets or scenes.
+- Do not create project scripts or editor windows.
+- Do not run package, menu, settings, or dependency searches as v1 behavior.

package/skills/generate-editor-search-query/references/query-patterns.md

@@ -0,0 +1,124 @@
+# Unity Search Query Patterns
+
+Use these patterns to translate common natural-language requests into Unity Search queries. Keep queries simple unless the user asks for a more complex relationship.
+
+## Table of Contents
+
+- [Asset Queries](#asset-queries)
+- [Reference Queries](#reference-queries)
+- [Scene Queries](#scene-queries)
+- [Natural-Language Mapping](#natural-language-mapping)
+- [Mixed Asset And Scene Queries](#mixed-asset-and-scene-queries)
+- [Unsupported Or Risky Requests](#unsupported-or-risky-requests)
+- [Query Quality Rules](#query-quality-rules)
+
+## Asset Queries
+
+| User intent | Query |
+| --- | --- |
+| Find all materials | `t:material` |
+| Find all textures | `t:texture` |
+| Find materials and textures | `t:[material, texture]` |
+| Find prefabs | `t:prefab` |
+| Find scenes | `t:scene` |
+| Find scripts | `t:script` |
+| Find shaders | `t:shader` |
+| Find sprites | `t:sprite` |
+| Find audio clips | `t:audioclip` |
+| Find animation clips | `t:animationclip` |
+| Find meshes/models | `t:mesh` |
+| Find fonts | `t:font` |
+| Find render textures | `t:rendertexture` |
+| Find ScriptableObject assets | `t:ScriptableObject` |
+| Find assets in a folder | `dir:Assets/FolderName` |
+| Find prefabs in a folder | `t:prefab dir:Assets/FolderName` |
+| Find materials in a folder | `t:material dir:Assets/FolderName` |
+| Find assets by label | `l:LabelName` |
+| Find assets by name or keyword | `keyword` |
+
+If the user gives an asset extension or filename pattern, include it as a keyword or glob-style term when useful, such as `*.prefab`, `*.mat`, or `Player`.
+
+## Reference Queries
+
+Use `ref=` when the request is about usage, references, dependencies, or "what uses this".
+
+| User intent | Query |
+| --- | --- |
+| Find prefabs that reference textures | `t:prefab ref={t:texture}` |
+| Find scenes that reference prefabs | `t:scene ref={t:prefab}` |
+| Find assets that reference a named asset | `ref=AssetName` |
+| Find scenes referencing a specific prefab path | `t:scene ref="Assets/Path/Prefab.prefab"` |
+| Find prefabs that use a material | `t:prefab ref=MaterialName` |
+| Find materials that use a texture | `t:material ref=TextureName` |
+| Find scenes that use a script or component name | `t:scene ScriptOrComponentName` |
+| Find prefabs that mention a script or component name | `t:prefab ScriptOrComponentName` |
+
+If the user gives a specific selected asset but the exact path is unknown, use the visible asset name first and say that a path-specific query will be more precise.
+
+## Scene Queries
+
+Scene-object searches should use component type names or object-name keywords. These queries are intended for the scene provider.
+
+| User intent | Query |
+| --- | --- |
+| Find Lights | `t:Light` |
+| Find Cameras | `t:Camera` |
+| Find Rigidbodies | `t:Rigidbody` |
+| Find Colliders | `t:Collider` |
+| Find Canvas UI objects | `t:Canvas` |
+| Find UI Buttons | `t:Button` |
+| Find TextMeshPro UI text | `t:TextMeshProUGUI` |
+| Find RectTransforms | `t:RectTransform` |
+| Find Particle Systems | `t:ParticleSystem` |
+| Find AudioSources | `t:AudioSource` |
+| Find Animators | `t:Animator` |
+| Find MeshRenderers | `t:MeshRenderer` |
+| Find SkinnedMeshRenderers | `t:SkinnedMeshRenderer` |
+| Find NavMeshAgents | `t:NavMeshAgent` |
+| Find Terrain objects | `t:Terrain` |
+| Find objects by name | `ObjectName` |
+
+For scene object requests that mention both a name and a component, combine them, for example `Enemy t:Rigidbody`.
+
+## Natural-Language Mapping
+
+Map common phrases to stable query forms:
+
+| User wording | Query strategy |
+| --- | --- |
+| "where is X" | Use `X` as a keyword query unless X is clearly a type. |
+| "which prefabs use X" | Use `t:prefab ref=X` when X is an asset name; otherwise use `t:prefab X`. |
+| "what references this texture" | Use `ref=TextureName`, or `ref="Assets/Path/Texture.png"` if a path is available. |
+| "what references the selected material" | Use the selected asset name/path if provided; otherwise ask for the material name or path. |
+| "show all X in Assets/UI" | Use `t:x dir:Assets/UI` when X maps to an asset type. |
+| "find scene objects with X" | Use `t:X` when X is a component type; otherwise use `X`. |
+| "find current scene objects named X" | Use `X` with scene providers; add a component type only when the user specifies one. |
+| "query only" | Return the query and do not open Search. |
+
+## Mixed Asset And Scene Queries
+
+If the user asks broadly, such as "find everything related to Rigidbody", open Search with active asset and scene providers and use the plain keyword plus likely type:
+
+- `Rigidbody`
+- `t:Rigidbody`
+- `Player Rigidbody`
+
+For "materials using Standard shader" or other property-specific material questions, Unity Search may not expose every material shader property consistently across versions. Prefer a query such as `t:material Standard` and state that it narrows to likely matches; a scripted audit is a separate task.
+
+## Unsupported Or Risky Requests
+
+Do not pretend Unity Search can reliably express every inspection.
+
+- Missing script detection might need a scripted scan. Use a broad query such as `missing script` or `t:prefab missing` only as a starting point and state the limitation.
+- Deep dependency graph questions are not this skill's scope. Provide a Search reference query if possible, then suggest dependency analysis as a separate workflow.
+- Repository text search, build log analysis, web documentation lookup, package installation, menu command search, settings search, and result actions are outside v1 scope.
+- If the user asks to "find and fix" assets, open Search for the find step only. Ask for confirmation before any separate modifying workflow.
+- If the user asks about a selected/current asset but no selection details are visible, ask for the asset name or path rather than guessing.
+
+## Query Quality Rules
+
+- Prefer lowercase asset type names such as `t:material`, `t:texture`, and `t:prefab`.
+- Use Unity type names for scene components, such as `t:Light` and `t:Camera`.
+- Quote paths with spaces, for example `ref="Assets/My Folder/Player.prefab"`.
+- Do not combine many speculative terms. One good query is better than a long fragile query.
+- If multiple plausible queries exist, choose one and mention alternatives only when helpful.

package/skills/implement-in-app-purchases/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: implement-in-app-purchases
+description: Implements, configures, and debugs Unity In-App Purchases, including subscriptions, receipt validation, and direct-to-customer payments via Stripe or Coda. Use when asked about real-money purchases or microtransactions, or migrating from native store billing, RevenueCat, Adapty, Essential Kit, or UniPay.
+---
+
+# Unity In-App Purchasing
+
+Namespace: `UnityEngine.Purchasing` | Security: `UnityEngine.Purchasing.Security`
+Package: `com.unity.purchasing`
+
+**Unity IAP has its own initialization path** via `UnityIAPServices.StoreController()` → `store.Connect()`. It does not require `UnityServices.InitializeAsync()`, but they can coexist if your project uses other UGS services. If Analytics is present and `InitializeAsync()` is called, IAP will automatically send transaction events.
+
+## Important
+
+- Use the unity cli (`unity command --format json`) and the `unity-cli` and `unity-pipeline` skills for each step.
+- Before making changes, establish a baseline of the current behavior so you can tell whether a later result is actually caused by your change.
+- Create a restore point you can roll back to if your changes fail.
+- Do only what's asked. Don't change unrelated assets or files.
+- Never leave verification code in the user's script. Never build logging or detection they didn't ask for. See [Final step](#final-step).
+- Avoid long explanations.
+
+## Before You Start
+
+**Always read [references/pre-check.md](references/pre-check.md) first.** It scans the project for third-party IAP packages, native Google Billing, and existing Unity IAP versions, then routes to the correct path. Do not read any other reference file or make any changes until routing is resolved.
+
+## Full topic map
+
+Documentation pages and API entry points: [references/topic-map.md](references/topic-map.md).
+## Detailed References
+
+- **Project scan and path routing (read first):** See [references/pre-check.md](references/pre-check.md)
+- **Common v5 API mistakes and where to read each API topic:** See [references/api-notes.md](references/api-notes.md)
+- **Platform extension gotchas (Apple, Google):** See [references/platform-notes.md](references/platform-notes.md)
+- **Editing `IAPProductCatalog.json` (schema, decimal serialization, refresh):** See [references/codeless-catalog.md](references/codeless-catalog.md)
+- **v4 → v5 migration:** See [references/migration-v4-to-v5.md](references/migration-v4-to-v5.md)
+- **Convert native Google BillingClient to Unity IAP 5:** See [references/path-convert-native-google-billing.md](references/path-convert-native-google-billing.md)
+- **Convert native iOS StoreKit plugin to Unity IAP 5:** See [references/path-convert-native-storekit.md](references/path-convert-native-storekit.md)
+- **Convert Essential Kit billing to Unity IAP 5:** See [references/convert-essentialkit.md](references/convert-essentialkit.md)
+- **UniPay (FLOBUK) — assessment and guidance:** See [references/convert-unipay.md](references/convert-unipay.md)
+- **RevenueCat — conversion assessment and guidance:** See [references/convert-revenuecat.md](references/convert-revenuecat.md)
+- **Adapty — conversion assessment and guidance:** See [references/convert-adapty.md](references/convert-adapty.md)
+- **Add Unity IAP 5 to a project with no existing IAP:** See [references/path-add-iap-to-new-project.md](references/path-add-iap-to-new-project.md)
+- **Implement IAP D2C Capabilities (third-party payment provider — Stripe/Coda, requires v5.4+):** See [references/path-implement-iap-d2c.md](references/path-implement-iap-d2c.md)
+
+Read reference files on demand — only when you need the API gotchas, platform extension details, or migration mappings.
+
+## Core rules
+
+Read the linked page for the flow and sample code before writing each part, and reread it if the code fails. The rules below are the mistakes agents make that the pages don't stop them making.
+
+## API details
+
+Initialization, purchases, restore, receipt validation, ownership/subscriptions, and compile errors: [references/api-details.md](references/api-details.md).
+## Final step
+
+Do the following checks:
+
+1. Check the project has zero console errors. Use `console_status` for counts.
+2. Stop there unless the user asked you to prove it works or you suspect a specific fault.
+3. If you do enter Play mode, do it once only to chase a fault you already suspect. Read the world through `eval` rather than adding logging. Take no screenshots, because they take too much time.
+
+If a check fails, go back and reread the [docs pages](#full-topic-map) to find out what you missed.
+
+After writing code that uses this package, also read the code back and check it, because IAP code can compile cleanly and still lose or double-grant purchases:
+
+1. Confirm all API calls match the v5 signatures on the [API reference](references/topic-map.md#api-reference) pages for the installed version — do NOT use v4 legacy patterns (`IStoreListener`, `UnityPurchasing.Initialize`, `ConfigurationBuilder`).
+2. Check the "Anti-Hallucination: Common v5 Mistakes" table in [api-notes.md](references/api-notes.md) — do NOT use `OnStoreConnectionFailed` (use `OnStoreDisconnected`), do NOT pass callbacks to `FetchProducts`/`FetchPurchases` (use events), do NOT use `product.receipt` (use `order.Info.Receipt`).
+3. Check that all required events are subscribed **before** calling `Connect()` (see [Initialization](references/api-details.md#initialization)).
+4. Verify the two-step purchase flow: `OnPurchasePending` → grant content → `ConfirmPurchase(pendingOrder)`.
+5. Confirm both success and failure events are subscribed for every async operation (`OnProductsFetched`/`OnProductsFetchFailed`, `OnStoreConnected`/`OnStoreDisconnected`, etc.).
+6. If handling subscriptions, verify `IsSubscribed()` is compared with `== Result.True`, not cast to `bool`.
+7. If updated files coexist with legacy versions in the same project, use a unique namespace (e.g., add `.Updated` suffix) to avoid CS0101/CS0111 compilation errors.
+8. If the project subscribes to `OnAuthAccountChanged` (v5.4+): verify the handler re-fetches products and purchases from scratch — Unity IAP clears both caches before raising this event. Do not read `GetProducts()` or `GetPurchases()` inside the handler.
+
+## Final report
+
+Report the following to the user, in this order:
+
+1. What changed: each file you changed, with the old and new API calls or values where they apply (for example, `IStoreListener.ProcessPurchase` → `OnPurchasePending`).
+2. How you verified it: the outcome of each Final step check, including the console error count and anything you read through `eval` in Play mode.
+3. Incidental side effects: anything you touched beyond the requested change, such as packages you installed or upgraded, project or Services settings you changed, generated files (for example tangle classes or `IAPProductCatalog.json`), and temporary files you created or removed.
+4. Follow-up the user must do, for example product setup in App Store Connect or the Google Play Console, and sandbox testing on a device. Include the manual steps that the path reference file lists.

package/skills/implement-in-app-purchases/references/api-details.md

@@ -0,0 +1,41 @@
+# Initialization
+
+Read [Initialize Unity IAP](https://docs.unity.com/en-us/iap/set-up-in-app-purchasing.md) and [Create your catalog programmatically](https://docs.unity.com/en-us/iap/code-catalog.md).
+
+- Subscribe to every event **before** `await store.Connect()`, because pending purchases from a previous session can fire as soon as the store connects. Initialize in `Awake()` so IAP is ready before other `Start()` methods.
+- Subscribe to the failure event of every call (`OnStoreDisconnected`, `OnProductsFetchFailed`, `OnPurchasesFetchFailed`, `OnPurchaseFailed`) and to `OnPurchaseDeferred`. Missing failure events cause runtime warnings, and a missing `OnPurchaseDeferred` silently drops Ask-to-Buy and Google deferred purchases.
+- `GetProducts()` and `GetPurchases()` return caches. Call `FetchProducts()` / `FetchPurchases()` first; `FetchPurchases()` overwrites the whole cached list.
+
+# Purchases
+
+Read [Purchases](https://docs.unity.com/en-us/iap/purchases.md).
+
+- `store.PurchaseProduct(product)` leads to `OnPurchasePending` with a `PendingOrder`. Grant the content, save it, then call `store.ConfirmPurchase(pendingOrder)`, because unconfirmed purchases are re-delivered on the next launch.
+- `OnPurchasePending` can fire more than once for the same purchase (for example, after a restart before confirmation). Check whether the content was already granted before granting it.
+- Confirmed consumables are NOT returned by `FetchPurchases()`. Track consumable grants yourself, for example in Cloud Save or Economy.
+- On `OnPurchaseDeferred`, show a pending state and don't grant. The purchase arrives later through `OnPurchasePending` if approved.
+
+# Restore
+
+Read [Restore purchases](https://docs.unity.com/en-us/iap/restore-purchases.md).
+
+- `store.RestoreTransactions(callback)` re-delivers non-consumables and renewable subscriptions, each through `OnPurchasePending`. Add a "Restore Purchases" button on iOS, because Apple's review guidelines require one.
+- Apple non-renewable subscriptions can't be restored through `RestoreTransactions`, so track them server-side.
+
+# Receipt validation
+
+Read [Receipt validation](https://docs.unity.com/en-us/iap/receipt-validation.md).
+
+- Google Play: validate locally with `CrossPlatformValidator(GooglePlayTangle.Data(), Application.identifier)`. Generate the tangle with **Services > In-App Purchasing > Receipt Validation Obfuscator**.
+- Apple StoreKit 2: local validation is a no-op. Send `order.Info.Apple?.jwsRepresentation` to a server for validation.
+
+# Ownership and subscriptions
+
+Read the [EntitlementStatus API](https://docs.unity3d.com/Packages/com.unity.purchasing@<VERSION>/api/UnityEngine.Purchasing.EntitlementStatus.html) and the [SubscriptionInfo class reference](https://docs.unity.com/en-us/iap/subscriptioninfo-class-reference.md).
+
+- To check whether the player owns a product, call `store.CheckEntitlement(product)`, handle `store.OnCheckEntitlement`, and compare with `EntitlementStatus.FullyEntitled`. This replaces v4's `product.hasReceipt`.
+- Subscription info is on `order.Info.PurchasedProductInfo`, NOT on `CartItem`. `IsSubscribed()` returns `Result`, not `bool`, so compare with `== Result.True`.
+
+# Compile errors
+
+- `ProductFetchFailed` has `.FailureReason` and `.FailedFetchProducts`, not `.Message`, and `StoreConnectionFailureDescription` has `.Message`, not `.reason`. A wrong name causes CS1061. The full table and the other common v5 mistakes are in [api-notes.md](../references/api-notes.md).

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

@@ -0,0 +1,105 @@
+# Unity IAP API Notes
+
+This file lists only the API mistakes agents commonly make with Unity IAP v5. It is not an API reference. For signatures, members and code samples, look the type up in the package's `xrefmap.yml` (see the skill's API reference section) and read its page, and read the matching manual page from the skill's Full topic map. Read the page before writing the code and again if it fails to compile, because your training data may describe v4 or an older v5 minor version.
+
+## Table of Contents
+
+- [Anti-Hallucination: v5 vs Legacy API](#anti-hallucination-v5-vs-legacy-api)
+- [Anti-Hallucination: Common v5 Mistakes](#anti-hallucination-common-v5-mistakes)
+- [Where to read each topic](#where-to-read-each-topic)
+- [OnAuthAccountChanged clears the caches (v5.4+)](#onauthaccountchanged-clears-the-caches-v54)
+- [Purchase flow gotchas](#purchase-flow-gotchas)
+- [Subscription info access path](#subscription-info-access-path)
+- [Platform extension gotchas](#platform-extension-gotchas)
+- [Failure description property names](#failure-description-property-names)
+- [Receipt validation gotchas](#receipt-validation-gotchas)
+
+## Anti-Hallucination: v5 vs Legacy API
+
+The v4 API is `[Obsolete]` in v5. Don't use legacy patterns, because they compile with warnings but bypass the v5 two-step flow. For the full mapping, read [Upgrade from IAP v4 to v5](https://docs.unity.com/en-us/iap/upgrade-to-iap-v5.md).
+
+| WRONG (Legacy v4) | CORRECT (v5) |
+|---|---|
+| `UnityPurchasing.Initialize(listener, builder)` | `UnityIAPServices.StoreController()` then `store.Connect()` |
+| `IStoreListener.OnInitialized(controller, extensions)` | `store.OnStoreConnected` event |
+| `IStoreListener.ProcessPurchase(args)` | `store.OnPurchasePending` event |
+| `controller.InitiatePurchase(product)` | `store.PurchaseProduct(product)` |
+| `controller.ConfirmPendingPurchase(product)` | `store.ConfirmPurchase(pendingOrder)` |
+| `extensions.GetExtension<IAppleExtensions>()` | `store.AppleStoreExtendedService` / `store.AppleStoreExtendedPurchaseService` |
+| `extensions.GetExtension<IGooglePlayStoreExtensions>()` | `store.GooglePlayStoreExtendedService` / `store.GooglePlayStoreExtendedPurchaseService` |
+| `ConfigurationBuilder.Instance(...)` | Not needed; pass a `ProductDefinition` list to `FetchProducts` |
+
+## Anti-Hallucination: Common v5 Mistakes
+
+These are NOT real APIs. Don't use them:
+
+| WRONG (does not exist) | CORRECT |
+|---|---|
+| `store.OnStoreConnectionFailed` | `store.OnStoreDisconnected`, which receives `StoreConnectionFailureDescription` |
+| `store.FetchProducts(defs, successCb, failCb)` | `store.FetchProducts(List<ProductDefinition>)`, then subscribe to `OnProductsFetched` / `OnProductsFetchFailed` separately |
+| `store.FetchPurchases(successCb, failCb)` | `store.FetchPurchases()`, then subscribe to `OnPurchasesFetched` / `OnPurchasesFetchFailed` separately |
+| `product.receipt` | `order.Info.Receipt`. The receipt is on the order, not the product |
+| `product.hasReceipt` | `store.CheckEntitlement(product)` + `OnCheckEntitlement` |
+| `new SubscriptionManager(product, introJson)` | `order.Info.PurchasedProductInfo`. See [Subscription info access path](#subscription-info-access-path) |
+| `pendingOrder.OrderInfo.Apple.jwsRepresentation` | `pendingOrder.Info.Apple?.jwsRepresentation`. Note `Info`, not `OrderInfo`, and the null check |
+| `cartItem.subscriptionInfo` | `CartItem` only has `Product` and `Quantity`. See [Subscription info access path](#subscription-info-access-path) |
+
+## Where to read each topic
+
+Replace `<VERSION>` with the major.minor of `com.unity.purchasing` in `Packages/packages-lock.json`.
+
+| Topic | Read |
+|---|---|
+| `StoreController` members, events and extension properties | [StoreController API](https://docs.unity3d.com/Packages/com.unity.purchasing@<VERSION>/api/UnityEngine.Purchasing.StoreController.html) |
+| Initialization order and a full sample | [Initialize Unity IAP](https://docs.unity.com/en-us/iap/set-up-in-app-purchasing.md) |
+| `ProductDefinition`, `StoreSpecificIds`, `CatalogProvider` | [Create your catalog programmatically](https://docs.unity.com/en-us/iap/code-catalog.md) |
+| Pending, confirmed, failed and deferred orders | [Purchases](https://docs.unity.com/en-us/iap/purchases.md) |
+| `RestoreTransactions` | [Restore purchases](https://docs.unity.com/en-us/iap/restore-purchases.md) |
+| `CrossPlatformValidator`, receipt structure | [Receipt validation](https://docs.unity.com/en-us/iap/receipt-validation.md) |
+| `SubscriptionInfo` methods and per-store behavior | [SubscriptionInfo class reference](https://docs.unity.com/en-us/iap/subscriptioninfo-class-reference.md) |
+| `EntitlementStatus` values | [EntitlementStatus API](https://docs.unity3d.com/Packages/com.unity.purchasing@<VERSION>/api/UnityEngine.Purchasing.EntitlementStatus.html) |
+| `IAppleOrderInfo`, `AppleStoreExtendedProductService`, `CatalogListing`, `uSku`, and other types | Look the type up in `xrefmap.yml` |
+
+## OnAuthAccountChanged clears the caches (v5.4+)
+
+Unity IAP clears the cached product list and purchase list **before** it raises `OnAuthAccountChanged`, so any `Product` or `Order` you held is stale and `GetProducts()` / `GetPurchases()` return empty inside the handler. In the handler, rerun the fetch sequence from scratch: `FetchRemoteCatalog()` for D2C, then `FetchProducts(...)` and `FetchPurchases()`.
+
+## Purchase flow gotchas
+
+- `OnPurchaseConfirmed` receives the `Order` base type. Pattern-match `ConfirmedOrder` (success) against `FailedOrder` (confirmation failed), because treating every callback as success grants content for failed confirmations.
+- Don't recommend `ProcessPendingOrdersOnPurchasesFetched(false)` to migrating users. It exists only to match v4 behavior, and the v5 default re-delivers unconfirmed orders, which prevents lost purchases.
+- When a product has `CatalogListings` (v5.4+), purchase by the `CatalogListing` directly to avoid a second lookup. `product.definition.id` still works for existing code.
+
+## Subscription info access path
+
+Subscription info is on `IPurchasedProductInfo`, reached through `order.Info.PurchasedProductInfo`, filtered by `productId`. It is NOT on `CartItem`.
+
+`IsSubscribed()` and the other state queries return the `Result` enum (`True` / `False` / `Unsupported`), not `bool`. Compare with `== Result.True`, because that is also null-safe when `subscriptionInfo` is missing.
+
+`AppleProductMetadata` does NOT expose `introductoryPrice`, `introductoryPriceLocale`, `introductoryNumberOfPeriods` or `subscriptionPeriod`. Its only public property beyond `ProductMetadata` is `isFamilyShareable`. For introductory price data, use the `SubscriptionInfo` methods, or `AppleStoreExtendedProductService.GetIntroductoryPriceDictionary()` for raw JSON.
+
+## Platform extension gotchas
+
+- The extension properties on `StoreController` (`AppleStoreExtendedService`, `AppleStoreExtendedPurchaseService`, `GooglePlayStoreExtendedService`, `GooglePlayStoreExtendedPurchaseService`, `AppleStoreExtendedProductService`) are `null` on other platforms and in the Editor. Null-check with `if`, because `?.` doesn't work with `+=`.
+- `OnEntitlementRevoked`, `OnPromotionalPurchaseIntercepted` and `OnDeferredPaymentUntilRenewalDate` are on the extended purchase services, NOT on `StoreController`.
+- `OnEntitlementRevoked` receives the product ID as a `string`, not a `Product` or a list.
+- On `AppleStoreExtendedProductService` (v5.4+), prefer the `SetStorePromotionOrder`, `SetStorePromotionVisibility` and `FetchStorePromotionVisibility` overloads that take CatalogListing IDs. The `Product` overloads are convenience wrappers.
+
+For more platform gotchas, see the platform notes reference file.
+
+## Failure description property names
+
+Each type has public lowercase fields and PascalCase read-only properties. Both compile, so prefer the properties. A wrong name causes CS1061:
+
+| Type | Field (lowercase) | Property (PascalCase) | NOT |
+|---|---|---|---|
+| `StoreConnectionFailureDescription` | `.message` | `.Message` | ~~`.reason`~~ |
+| `ProductFetchFailed` | — | `.FailureReason`, `.FailedFetchProducts` | ~~`.Message`~~ |
+| `FailedOrder` | — | `.FailureReason`, `.Details` | — |
+| `PurchasesFetchFailureDescription` | `.message`, `.failureReason` | `.Message`, `.FailureReason` | — |
+
+## Receipt validation gotchas
+
+- Use the Google-only `CrossPlatformValidator(GooglePlayTangle.Data(), Application.identifier)` constructor. Apple local validation and `AppleTangle.Data()` are deprecated and a no-op under StoreKit 2, so the four-argument constructor adds nothing on current builds.
+- `Validate` throws `IAPSecurityException` on an invalid receipt. Don't grant content in that case.
+- For Apple, send `order.Info.Apple?.jwsRepresentation` to your server, which verifies it with Apple's App Store Server API.