feat(integrate-revenuecat): settle how the paywall is built before coding it

revenuecat/skills/integrate-revenuecat/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: integrate-revenuecat
-description: End-to-end RevenueCat integration — sets up the dashboard side via the RevenueCat MCP or the `rc` CLI (project, app, public API key) and installs/configures the Purchases SDK in the app. Use when the user asks to add RevenueCat, integrate Purchases, install the RevenueCat SDK, set up a RevenueCat API key, configure Purchases on launch, or set up a brand new RevenueCat integration on iOS, Android, Kotlin Multiplatform, Flutter, or React Native.
+description: End-to-end RevenueCat integration — sets up the dashboard side via the RevenueCat MCP or the `rc` CLI (project, app, public API key) and installs/configures the Purchases SDK in the app. Use when the user asks to add RevenueCat, hook up RevenueCat, add subscriptions or in-app purchases to an app, integrate Purchases, install the RevenueCat SDK, set up a RevenueCat API key, configure Purchases on launch, or set up a brand new RevenueCat integration on iOS, Android, Kotlin Multiplatform, Flutter, or React Native.
 ---
 
 # integrate-revenuecat: end-to-end RevenueCat integration
@@ -10,6 +10,8 @@ Use this skill when the user wants to add RevenueCat to a project for the first
 1. **Dashboard side** — set up the project, register the app, and obtain the public API key, through the RevenueCat MCP server or the `rc` CLI.
 2. **App side** — install the Purchases SDK, call `Purchases.configure(…)` at app entry, and verify the configuration banner in the logs.
 
+Once the SDK is configured, settle **how the paywall is built** (Section 5c) before writing any paywall code.
+
 Walk them in order. Most integrations need both halves, even when the user asks "just install the SDK" — the SDK needs an API key from the dashboard.
 
 > If a project + app already exist and the user only wants to wire the SDK into code, jump to **Section 3** below.
@@ -119,12 +121,30 @@ Check whether products, entitlements, and offerings are already set up in the pr
 2. **Real-time Developer Notifications (RTDN)** — Set up a Cloud Pub/Sub topic. Configure in Play Console → Monetization setup.
 3. If the user provides this information, register it via `create-app` / `update-app`.
 
-### 5c. Subsequent skills
+### 5c. Choose how the paywall is built
+
+The app still needs a paywall, and there are two ways to build one. This is a product decision, not an implementation detail, so settle it before writing any paywall code.
+
+- **RevenueCat Paywall (recommended default).** Hosted by RevenueCat and rendered by RevenueCatUI. You create it yourself: load the `revenuecat-paywall-design` skill and follow its creating workflow (`create-paywall-ai` via MCP or `rc paywalls generate` via CLI, attached to the current offering and informed by the app's codebase), then present it with `revenuecat-paywall`. The user does not have to design anything in the dashboard; they can refine it later in the paywall builder. Design, copy, and packages change without an app release, and paywall variants can be A/B tested with RevenueCat Experiments.
+- **Custom paywall in code.** The app's own UI, with packages and prices from `getOfferings()` and the purchase handled by `revenuecat-purchase-flow`. Full visual control, but every design change ships in an app release and the paywall design cannot be A/B tested. Price and offering tests still work, because packages come from the offering.
+
+Pick the path:
+
+1. **The user already said which one.** Use it.
+2. **The app has no paywall screen yet.** Recommend a RevenueCat Paywall.
+3. **The app already has a paywall or subscription screen** (a screen listing plans or prices, a subscribe or upgrade button, hardcoded prices or product IDs). The user most likely wants that screen wired to offerings. Recommend keeping it, and mention that a RevenueCat Paywall could replace it.
+
+If you can ask the user, ask one question with both options, the recommended one first, each with a one-line trade-off. If you cannot ask (for example, you are running non-interactively), do not stop: take the recommendation above, and in your summary say which path you took and how to switch to the other.
+
+Do not hand-code a paywall screen by default just because it keeps the work in code. A new RevenueCat Paywall is an unpublished draft: tell the user to review it in the paywall builder, and publish it only when they ask, because the app renders the default fallback layout until a paywall is published and attached to the offering.
+
+### 5d. Subsequent skills
 
 Common follow-ups after `integrate-revenuecat`:
 
+- `revenuecat-paywall-design` — create or edit the dashboard paywall.
 - `revenuecat-paywall` — display a dashboard-configured paywall.
-- `revenuecat-purchase-flow` — implement purchase + restore manually.
+- `revenuecat-purchase-flow` — implement purchase + restore for a custom paywall.
 - `revenuecat-entitlements-gate` — gate features behind active entitlements.
 - `revenuecat-identify-user` — wire `logIn` / `logOut` to the app's auth system.
 - `revenuecat-testing-setup` — set up a sandbox testing channel.

revenuecat/skills/revenuecat-paywall/SKILL.md

@@ -5,7 +5,7 @@ description: Display a RevenueCat paywall inside an app using the RevenueCatUI S
 
 # revenuecat-paywall: display a RevenueCat paywall
 
-Use this skill when the user wants to show a paywall that is built and configured in the RevenueCat dashboard, using the native RevenueCatUI components. This skill does not cover building a custom paywall from scratch. For that, use `revenuecat-purchase-flow` (when available) and `Purchases.getOfferings(…)` directly. To create, edit, evaluate, or audit the dashboard paywall, use `revenuecat-paywall-design`.
+Use this skill when the user wants to show a paywall that is built and configured in the RevenueCat dashboard, using the native RevenueCatUI components. This skill does not cover building a custom paywall from scratch. For that, use `revenuecat-purchase-flow` and `Purchases.getOfferings(…)` directly. If the user has not chosen between the two, see `integrate-revenuecat`, Section 5c. To create, edit, evaluate, or audit the dashboard paywall, use `revenuecat-paywall-design`.
 
 Prerequisite: `integrate-revenuecat` has already run. `Purchases.configure(…)` must succeed before a paywall can load.
 
@@ -31,7 +31,7 @@ If several match (e.g. an `ios/` folder inside a Flutter project), pick the **ou
   - (c) Conditional present on a CTA tap, such as an "Upgrade" button in settings.
 - **RevenueCatUI owns the purchase flow.** Do not call `Purchases.purchase(…)` manually alongside a RevenueCatUI paywall. The paywall calls it internally. Listen for the dismiss or purchase completed callback to react in app code.
 - **Close button is opt in on most platforms.** Pass `displayCloseButton = true` (iOS / Flutter / RN) or `setShouldDisplayDismissButton(true)` (Android / KMP) when the paywall is presented modally and the user needs a way out. Skip it when presenting behind a sheet with its own grabber, or when wrapping the paywall in a navigation controller.
-- **If the app needs a fully custom UI**, do not use this skill. Call `Purchases.getOfferings()` and render your own components. RevenueCatUI is only for dashboard templated paywalls.
+- **If the user has chosen a fully custom UI**, do not use this skill. Call `Purchases.getOfferings()` and render your own components. RevenueCatUI is only for dashboard templated paywalls.
 
 ## 3. Implementation
 

revenuecat/skills/revenuecat-purchase-flow/SKILL.md

@@ -1,12 +1,14 @@
 ---
 name: revenuecat-purchase-flow
-description: Implement the RevenueCat purchase and restore flow. Use when the user asks to buy a package, purchase a subscription, fetch offerings, build paywall purchase logic, handle purchase errors, detect user cancelled, or restore previous purchases on iOS, Android, Kotlin Multiplatform, Flutter, or React Native.
+description: Implement the RevenueCat purchase and restore flow. Use when the user asks to buy a package, purchase a subscription, fetch offerings, build the purchase logic behind a custom (hand-coded) paywall, handle purchase errors, detect user cancelled, or restore previous purchases on iOS, Android, Kotlin Multiplatform, Flutter, or React Native.
 ---
 
 # revenuecat-purchase-flow: buy a package and restore purchases
 
 Use this skill when the user wants to complete the purchase side of RevenueCat: fetch offerings, call `purchase`, deal with cancellation and errors, and expose a "Restore" action. It does not cover rendering a paywall UI (that lives in `revenuecat-paywall`) or gating features (that lives in `revenuecat-entitlements-gate`).
 
+If the app has no paywall yet and the user has not asked for a custom one, settle how the paywall is built first (`integrate-revenuecat`, Section 5c). The default is a RevenueCat Paywall, which handles the purchase itself.
+
 ## 1. Detect the platform
 
 Inspect the working directory and pick the **first** match, from top to bottom: