@getrheo/rheo-skill 2.5.0 → 3.0.0

package/rheo/rheo-best-practices/references/product-model.md

@@ -0,0 +1,66 @@
+# Product model
+
+Rheo is one SDK and one Customer. Analytics, Convert, and Engage are products on that SDK. Install once. Wire only the products the user asked for.
+
+| Product | Host implements | Dashboard owns |
+| --- | --- | --- |
+| **Analytics** | `RheoProvider` (sessions, page or screen views, `logEvent`), web consent, `setUserId`, `setBillingIdentity` | Visitors, retention, revenue reports |
+| **Convert** | `Flow` / `FlowView` on a **channel** public id, terminal callbacks, Integration Nodes and External Surface Nodes | Canvas, experiments, channels, publish |
+| **Engage** | `identify` for email and marketing consent. `track` for automation triggers on web and React Native | Email provider, broadcasts, automations, preference center |
+| **Customers** | A stable `userId`, plus `identify` when email or consent exists | Profiles, segments, consent |
+
+Customers are the shared record. The same id filters Analytics and targets Engage. Segments are dashboard (or CLI) objects. Do not invent a second user id per product.
+
+## One provider
+
+Mount `RheoProvider` once, high enough that the screens you care about sit under it. Product analytics starts when the provider mounts, including when no flow is on screen. A Convert-only request still gets Analytics unless the user opts out with `analytics={{ enabled: false }}` (web and React Native) or `analyticsEnabled: false` (SwiftUI `RheoConfig`).
+
+Do not add a second product-analytics SDK, a second onboarding SDK, or a Rheo-owned email sender.
+
+## Three event pipes
+
+These are different APIs. Sending a product event does not start an automation.
+
+| Call | Where it goes | Starts Engage automations |
+| --- | --- | --- |
+| Flow funnel events (`flow_started`, `step_viewed`, …) | `POST /v1/sdk/events` | No |
+| `logEvent`, `screen`, automatic `session_start` / `page_view` / `first_visit` / `first_open` | `POST /v1/sdk/analytics/events` | No |
+| `track` (web and React Native) | `POST /v1/sdk/track` | Yes |
+
+Use `logEvent` when the event should show up in Analytics. Use `track` only when that event should enroll an Engage automation or match a segment rule. Call both only when the user asked for a report and a journey from the same action.
+
+`unknown` marketing consent does not send. Granted consent is required for live email and webhook delivery; email also needs an address. See [engage.md](engage.md).
+
+## Identity
+
+| Input | Sets | Does not set |
+| --- | --- | --- |
+| `userId` on provider config | `appUserId` for analytics, experiment bucketing, and identify | Email or consent |
+| `setUserId` / `customUserId` | CRM id on later product events | `appUserId` |
+| `identify` | Email, marketing consent, optional topic consents on the Customer | A product-analytics event |
+| `setBillingIdentity('revenuecat' \| 'superwall', id)` | Billing id used to attach webhook revenue to this person | A purchase by itself |
+
+Email typed into a flow, or stuffed into event properties, is not marketing consent. Call `identify` after the person actually opts in or opts out.
+
+When email is sent, `marketingConsent` is required (`granted`, `denied`, or `unknown`). `granted` requires an email.
+
+Web and React Native `identify` also accept `attributes` (shallow-merged onto the Customer) and an IANA `timezone` for Engage quiet hours. SwiftUI `RheoRuntime.identify` takes email, consent, topic consents, and `customUserId` only.
+
+## Revenue
+
+Dollars come from the provider webhook, not from the device. After the host calls RevenueCat `logIn` / `Purchases.configure` or Superwall `identify`, call `setBillingIdentity` with that same id. Stripe on the web SDK records the charge from `checkout.session.completed` on the app webhook. There is no `setBillingIdentity('stripe', …)`.
+
+One revenue source per store. App Store and Play are RevenueCat or Superwall. Web can be Stripe.
+
+## Platforms this skill installs
+
+| Stack | Package | Analytics | Convert | `identify` | Engage `track` |
+| --- | --- | --- | --- | --- | --- |
+| React Native + Expo | `@getrheo/react-native-expo` | Yes | Yes | Yes | Yes |
+| React Native bare | `@getrheo/react-native-bare` | Yes | Yes | Yes | Yes |
+| React web | `@getrheo/react` | Yes, consent required | Yes | Yes | Yes |
+| SwiftUI | `RheoSwiftUI` | Yes | Yes | Yes | No |
+
+Install one React Native flavor, never both. The web package is separate and can sit beside a native app. It is not a second flavor of the same binary.
+
+Flutter exposes product analytics and `identify` in `rheo_flutter`. This skill has no Flutter install guide. Engage push and outbound webhooks are not SDK surfaces yet. Engage email sends through the app's own SES, Resend, Postmark, or SendGrid account, configured in the dashboard.

package/rheo/rheo-best-practices/references/react-native-bare.md

@@ -15,7 +15,7 @@ pnpm add @getrheo/react-native-bare \
   react-native-safe-area-context react-native-in-app-review react-native-video
 ```
 
-**Integrations (host only):** `react-native-appsflyer`, `react-native-purchases`, `react-native-purchases-ui` when needed. External Surface Nodes use `Flow` `externalSurfaces` (no extra native peer).
+**Integrations (host only):** `react-native-appsflyer`, `react-native-purchases`, `react-native-purchases-ui`, `@superwall/react-native-superwall` when needed. External Surface Nodes use `Flow` `externalSurfaces` (no extra native peer).
 
 ## Minimal Runtime
 
@@ -38,5 +38,7 @@ export const OnboardingHost = () => (
 ## Notes
 
 - Do **not** install `@getrheo/react-native-expo` in the same app.
+- `RheoProvider` starts Analytics even when `Flow` is omitted. Pass a channel public id only for Convert, never a flow id.
+- `logEvent` / `screen` / `setUserId` / `setBillingIdentity` are Analytics. `identify` and `track` are Engage. Same exports as Expo. See [analytics.md](analytics.md) and [engage.md](engage.md).
 - **Production:** default API is `https://api.getrheo.io`; omit `apiBaseUrl` unless self-hosting.
 - Link native modules (permissions, video, reanimated babel plugin) per upstream docs.

package/rheo/rheo-best-practices/references/react-native-expo.md

@@ -12,10 +12,10 @@ pnpm add @getrheo/react-native-expo \
   react-native-permissions react-native-gesture-handler react-native-reanimated \
   react-native-linear-gradient react-native-svg lottie-react-native \
   react-native-vector-icons @react-native-async-storage/async-storage \
-  react-native-safe-area-context expo-store-review expo-video
+  react-native-safe-area-context expo-store-review expo-video expo-notifications
 ```
 
-**Integrations (host only, not SDK peers):** `react-native-appsflyer`, `react-native-purchases`, `react-native-purchases-ui` when the flow uses attribution or RevenueCat Integration Nodes. External Surface Nodes use `Flow` / `useFlow` `externalSurfaces` (no extra native peer).
+**Integrations (host only, not SDK peers):** `react-native-appsflyer`, `react-native-purchases`, `react-native-purchases-ui`, `expo-superwall` / `@superwall/react-native-superwall` when the flow uses attribution, RevenueCat, or Superwall Integration Nodes. External Surface Nodes use `Flow` / `useFlow` `externalSurfaces` (no extra native peer).
 
 ## Minimal Runtime
 
@@ -43,7 +43,8 @@ export const OnboardingHost = () => (
 ## Notes
 
 - Do **not** install `@getrheo/react-native-bare` in the same app.
-- Pass channel public id, not flow id.
+- `RheoProvider` starts Analytics even when `Flow` is omitted. Pass a channel public id only for Convert, never a flow id.
+- `logEvent` / `screen` / `setUserId` / `setBillingIdentity` are Analytics. `identify` and `track` are Engage. See [analytics.md](analytics.md) and [engage.md](engage.md).
 - **Production:** default API is `https://api.getrheo.io`; omit `apiBaseUrl` unless self-hosting. Never use localhost with `ob_pk_live_*` keys.
 - Built-in OS permissions need `react-native-permissions` native setup (Expo plugin + Info.plist).
-- Expo Go cannot run native RevenueCat UI; use a dev client.
+- Expo Go cannot run native RevenueCat or Superwall UI; use a dev client.

package/rheo/rheo-best-practices/references/react-web.md

@@ -0,0 +1,78 @@
+# React web
+
+## Detect
+
+A browser app: `react` and `react-dom`, often Vite, Next.js, or Remix. No `react-native` dependency.
+
+## Install
+
+```bash
+pnpm add @getrheo/react
+```
+
+Peers: `react` and `react-dom` ≥ 18.
+
+## Minimal runtime
+
+Analytics-only (no flow). Consent stays pending until the site grants it. See [analytics.md](analytics.md).
+
+```tsx
+import { RheoProvider } from '@getrheo/react';
+
+export const App = () => (
+  <RheoProvider
+    config={{
+      publishableKey: import.meta.env.VITE_RHEO_PUBLISHABLE_KEY,
+      analytics: { consent: 'pending' },
+    }}
+  >
+    {children}
+  </RheoProvider>
+);
+```
+
+Convert: same provider, plus `Flow` and a channel public id. Add the site origin (scheme, host, and port) under **App settings → SDK**. A browser request from an origin the app did not list is rejected.
+
+```tsx
+import { Flow, RheoProvider } from '@getrheo/react';
+
+export const App = () => (
+  <RheoProvider
+    config={{
+      publishableKey: import.meta.env.VITE_RHEO_PUBLISHABLE_KEY,
+      analytics: { consent: 'pending' },
+    }}
+  >
+    <Flow channelId="ch_…" />
+  </RheoProvider>
+);
+```
+
+**Production:** omit `apiBaseUrl` unless self-hosting. Default API is `https://api.getrheo.io`. Never pair `ob_pk_live_*` with localhost.
+
+The snippet uses Vite's `import.meta.env`. Next.js should read `NEXT_PUBLIC_…` (or the project's existing public env) instead.
+
+## Payments
+
+Stripe is the web paywall. Turn **Stripe** on under **App settings → Integrations**, add a Stripe Integration Node whose Payment Link is on `buy.stripe.com` or another `https://*.stripe.com` host, and paste Rheo's webhook URL and signing secret into Stripe. No Stripe adapter on `RheoProvider`. The return restores the session. The webhook writes the charge. The browser does not send a price.
+
+## Engage
+
+`identify` and `track` export from `@getrheo/react`. Call `identify` after a real marketing opt-in. Use `track` for automation or segment triggers. An email typed into a flow answer is not consent. See [engage.md](engage.md).
+
+`registerPush()` registers Web Push after you save a VAPID key under **App settings → Engage settings**.
+
+## Prefetch
+
+Pass `prefetch="all"` or `prefetch={['ch_…']}` on `RheoProvider`, or call `prefetch` / `prefetchAll` / `useRheoPrefetch` to warm the resolve cache (`localStorage` + `If-None-Match`).
+
+## What the web SDK does not do
+
+| Feature | Web behavior |
+| --- | --- |
+| RevenueCat / Superwall / headless external surfaces | Surface fails and follows **Fallback** |
+| `request_os_permission` other than notifications | Treated as denied |
+| `request_app_review` | No-op (`not_shown`) |
+| AppsFlyer | Not supported. First-party UTMs are on by default (`attribution.enabled` not `false`) |
+
+First-touch UTMs stay in memory while consent is pending or denied. `setAnalyticsConsent('granted')` writes them.

package/rheo/rheo-best-practices/references/swiftui.md

@@ -1,53 +1,24 @@
 # SwiftUI
 
+## Status: SDK install coming soon
+
+**Do not install** a SwiftUI SDK package for customers today. Public Swift extract / SwiftPM distribution is paused until the native SDK GA checklist is satisfied. Marketing and the Developer Guide treat SwiftUI as **coming soon**.
+
+If the user asks to install Rheo in a SwiftUI app:
+
+1. Say SwiftUI SDK install is **not customer-available** yet.
+2. Offer supported install stacks instead: Expo, bare React Native, or React web (see those references).
+3. If they have an existing SwiftUI onboarding/paywall to migrate into Convert, route to **rheo-flow-import** (SwiftUI **source → manifest** import is supported; it does not install the SDK).
+
 ## Detect
 
-Look for `Package.swift`, `.xcodeproj`, `.xcworkspace`, SwiftUI `App`, `NavigationStack`, onboarding root views, and coordinators.
-
-## Install
-
-Add the SwiftPM product:
-
-```swift
-.product(name: "RheoSwiftUI", package: "RheoSwiftUI")
-```
-
-Optional products:
-
-```swift
-.product(name: "RheoSwiftUIRevenueCat", package: "RheoSwiftUI")
-.product(name: "RheoSwiftUIAppsFlyer", package: "RheoSwiftUI")
-```
-
-## Minimal Runtime
-
-```swift
-import SwiftUI
-import RheoSwiftUI
-
-struct OnboardingHost: View {
-  var body: some View {
-    RheoProvider(
-      config: RheoConfig(
-        publishableKey: "ob_pk_test_xxx",
-        userId: "user_123",
-        sessionId: "sess_123"
-      )
-    ) {
-      FlowView(channelId: "ch_test_xxx") { snapshot in
-        // Continue host navigation.
-      } onFlowAbandoned: { snapshot in
-        // Continue or restore host navigation.
-      }
-    }
-  }
-}
-```
-
-## Notes
-
-- Use `RheoSwiftUIRevenueCat` for RevenueCat Integration Node presenter helpers.
-- External Surface Nodes: pass `externalSurfaces: [surfId: { ctx in AnyView(...) }]` on `FlowView` (`ctx.onComplete` / `onBack` / `onDismiss`).
-- Use `RheoSwiftUIAppsFlyer` for AppsFlyer attribution providers.
-- Host apps must include Info.plist usage strings for authored permission prompts.
-- Host apps must register branding fonts if relying on downloaded font families.
+Look for `Package.swift`, `.xcodeproj`, `.xcworkspace`, SwiftUI `App`, `NavigationStack`, onboarding root views, and coordinators — useful for **flow import**, not for SDK install.
+
+## Historical snippet (not for install)
+
+The file [examples/swiftui-install-snippet.md](../examples/swiftui-install-snippet.md) is retained for internal / future GA reference only. **Do not** add `RheoSwiftUI` SwiftPM products or edit the host app to mount `RheoProvider` / `FlowView` until GA docs flip from coming soon.
+
+## Engage notes (when GA lands)
+
+- SwiftUI will not export Engage `track` (same as web). Automation triggers must come from React Native or from events the app already sends that Engage can enroll on.
+- Push registration and billing identity helpers are documented in [engage.md](engage.md) / [integrations.md](integrations.md) for when the package is customer-installable.

package/rheo/rheo-best-practices/references/troubleshooting.md

@@ -1,5 +1,18 @@
 # Troubleshooting
 
+## Analytics shows no product events
+
+- Confirm `RheoProvider` is mounted. Sessions start there, not when `Flow` mounts.
+- On web, omitted consent is `pending`. Call `setAnalyticsConsent('granted')` or pass `analytics.consent: 'granted'` when a grant already exists. `analytics.enabled: false` stays off after a grant.
+- `logEvent` before the provider mounts is a no-op. `track` does not write product analytics.
+
+## An Engage automation never enrolls
+
+- `logEvent` and flow events do not start automations. React Native must call `track`.
+- SwiftUI and web do not export Engage `track`.
+- `identify` with `unknown` or missing email does not make the person sendable. Consent has to be `granted`.
+- Provider credentials, suppressions, and topic grants are dashboard state. The SDK cannot repair them.
+
 ## Manifest Fails Validation
 
 Run:
@@ -38,11 +51,11 @@ Fix workflow:
 
 ## Missing Fallback Edge
 
-Every Integration / External Surface Node needs `fallback`. Outcomes that are not explicitly mapped (RevenueCat purchase outcomes or headless `completed` / `back` / `dismissed`) fall through to this target.
+Every Integration / External Surface Node needs `fallback`. Outcomes that are not explicitly mapped (RevenueCat / Superwall purchase outcomes or headless `completed` / `back` / `dismissed`) fall through to this target.
 
 ## Integration Disabled
 
-The manifest may validate locally but fail dashboard import if the target app has RevenueCat disabled or the workspace lacks integration entitlements.
+The manifest may validate locally but fail dashboard import if the target app has RevenueCat / Superwall disabled or the workspace lacks integration entitlements.
 
 ## Wrong Environment
 

package/rheo/rheo-flow-import/SKILL.md

@@ -1,12 +1,14 @@
 ---
 name: rheo-flow-import
-description: Analyze an existing mobile app flow (onboarding, paywall, post-purchase, setup) in a React Native, Expo, or SwiftUI codebase and export it as a compliant Rheo FlowManifest, then validate it against the dashboard publish gates. Use when a user asks to import, migrate, or convert an existing flow into Rheo, generate or scaffold a Rheo manifest, or validate/repair a Rheo manifest. Part of the `rheo` skill. Ships self-contained node scripts — no install step.
+description: Analyze an existing mobile Convert flow (onboarding, paywall, post-purchase, setup) in a React Native, Expo, or SwiftUI codebase and export it as a compliant Rheo FlowManifest, then validate it against the dashboard publish gates. Use when a user asks to import, migrate, or convert an existing flow into Rheo, generate or scaffold a Rheo manifest, or validate/repair a Rheo manifest. Part of the `rheo` skill. Does not install the SDK or configure Analytics or Engage. Ships self-contained node scripts — no install step.
 compatibility: Requires Node.js 20+. All scripts are self-contained (zod, @getrheo/contracts, and @getrheo/flow-runtime are bundled into scripts/lib/rheo-cli.mjs). Internet access fetches the latest Manifest Agent Profile; a bundled fallback works offline.
 ---
 
 # Rheo — Flow Import
 
-Convert an existing app flow into a Rheo `FlowManifest` that imports and publishes in the dashboard with zero blockers. Prefer **source code as truth**; use screenshots/recordings only as supporting evidence unless the user says they are newer.
+This is the **Convert** path. It turns an existing onboarding, paywall, post-purchase, or setup flow into a Rheo `FlowManifest` that imports and publishes in the dashboard with zero blockers. It does not install the SDK, record product analytics, or configure Engage. When the user also wants the app wired, finish the manifest, then follow [rheo-best-practices](../rheo-best-practices/SKILL.md).
+
+Prefer **source code as truth**; use screenshots/recordings only as supporting evidence unless the user says they are newer.
 
 The recommended authoring path is **spec → scaffold → enrich → validate**: describe the flow as a compact [flow spec](references/flow-spec.md), run `scaffold-manifest.mjs` to get a schema-valid skeleton with correct ids/structure, then enrich styling and validate. Hand-authoring full manifest JSON is allowed but error-prone — the scaffold removes the mechanical mistakes (ids, `children` arrays, choice bindings, branching).
 

package/rheo/rheo-flow-import/references/capabilities.md

@@ -27,6 +27,12 @@ Every layer `kind` accepted by the manifest:
 - `text_input`
 - `scale_input`
 - `wheel_picker`
+- `date_time_input`
+- `number_stepper`
+- `number_stepper_button`
+- `number_stepper_value`
+- `phone_input`
+- `address_input`
 - `oauth_provider`
 - `oauth_login`
 - `email_password_auth`
@@ -68,6 +74,7 @@ Valid `action.kind` values on `button` layers:
 - `play_media`
 - `request_app_review`
 - `advance_carousel`
+- `dismiss_banner`
 
 - `FlowGraphNodeJumpTarget` (`scr_*` | `dec_*` | `surf_*`): `go_to_step.screenId`, choice `branching.conditions[].goTo`, loader/lottie/video `onComplete` when mode is `screen`, and `request_os_permission` outcomes (except `continue`/`end`).
 - `go_back_one_screen` and `back_button` accept optional `fallbackScreenId` (`scr_*` only).
@@ -113,8 +120,10 @@ Valid `permissionKey` values for `request_os_permission`:
 
 ## External surface outcomes
 
-Builder add-menu kinds share `externalSurfaceNodes`: **Integration Node** (partner providers such as RevenueCat) and **External Surface Node** (`provider: "headless"`). Every node needs a `fallback` jump target.
+Builder add-menu kinds share `externalSurfaceNodes`: **Integration Node** (partner providers such as RevenueCat / Superwall) and **External Surface Node** (`provider: "headless"`). Every node needs a `fallback` jump target.
 
 **Integration Node / RevenueCat** (`provider: "revenuecat"`): `purchase_completed`, `purchase_cancelled`, `dismissed`, `failed`, `restore_completed`.
 
+**Integration Node / Superwall** (`provider: "superwall"`): `purchase_completed`, `purchase_cancelled`, `dismissed`, `failed`, `restore_completed`.
+
 **External Surface Node / Headless** (`provider: "headless"`): `completed`, `back`, `dismissed`, `failed`. Host apps register UI via `externalSurfaces[hostKey]` (`config.hostKey` or node id) with `onComplete` / `onBack` / `onDismiss`.

package/rheo/rheo-flow-import/references/flow-spec.md

@@ -200,7 +200,7 @@ instead of a plain footer CTA ([carousel-import.md](carousel-import.md)).
 
 `decisions` accepts full `@getrheo/contracts` `DecisionNode` objects (the scaffold
 passes them through). External surfaces use `externalSurfaces` (builder:
-**Integration Node** for `revenuecat`, **External Surface Node** for `headless`):
+**Integration Node** for `revenuecat` / `superwall`, **External Surface Node** for `headless`):
 
 ```jsonc
 {
@@ -213,6 +213,16 @@ passes them through). External surfaces use `externalSurfaces` (builder:
 }
 ```
 
+```jsonc
+{
+  "id": "surf_sw_paywall",
+  "provider": "superwall",
+  "placementId": "campaign_trigger",
+  "outcomes": { "purchase_completed": "scr_done", "restore_completed": "scr_done", "dismissed": "scr_offer2" },
+  "fallback": "scr_offer2"   // required — Integration Node; placementId optional (uses app defaultPlacementId)
+}
+```
+
 ```jsonc
 {
   "id": "surf_custom_step",

package/rheo/rheo-flow-import/references/import-workflow.md

@@ -109,7 +109,7 @@ If the user has not named an entry point, stop after question 1 and wait for an
 18. Generate `rheo-import.manifest.json`:
    - Emit a complete graph with explicit `next.default` edges.
    - Use decision nodes for clear branches.
-   - Use RevenueCat external surfaces for detected RevenueCat paywalls.
+   - Use RevenueCat / Superwall **Integration Nodes** for detected partner paywalls (`provider: "revenuecat"` or `"superwall"`).
    - Prefer fidelity when the user chose visual fidelity: carousels, gradients, shadows, and centered stacks.
    - **Layer ids:** `scr_*` / `lyr_*` only on screens and layers; UUID placeholders **only** for `media.mediaAssetId` and font sidecars ([layer-schema-pitfalls.md](layer-schema-pitfalls.md#layer-ids-vs-media-placeholder-uuids)).
    - **Container layers:** every `button`, `back_button`, `hyperlink`, `stack`, choice input, and auth layer must include its `children` (or `slides`) array ([manifest-rules.md](manifest-rules.md#container-layers-required-children)).

package/rheo/rheo-flow-import/references/manifest-agent-profile-fallback.md

@@ -67,7 +67,7 @@ Use only: `stack`, `text`, `image`, `lottie`, `video`, `icon`, `button`, `back_b
 - Black-and-white fallback is acceptable only when the audit finds no style/token evidence and the user confirms no theme source.
 - Use at most one input layer kind per **active path** (`single_choice`, `multiple_choice`, `text_input`, `scale_input`, `wheel_picker`) — one per screen unless sibling `conditional` branches split the path.
 - Non-reserved `sdk.*` decision keys must be listed in `sdkAttributeKeys`.
-- RevenueCat **Integration Nodes** and headless **External Surface Nodes** both live in `externalSurfaceNodes` and always need `fallback`.
+- RevenueCat / Superwall **Integration Nodes** and headless **External Surface Nodes** both live in `externalSurfaceNodes` and always need `fallback`.
 - Emit complete graph edges for imported flows.
 - Use placeholder UUID media ids and `rheo-import.assets.json`; never put file paths directly in `mediaAssetId`.
 - Do not silently drop media layers. If a traced asset cannot be copied, report the missing file and do not call the import complete.

package/rheo/rheo-flow-import/references/manifest-rules.md

@@ -197,7 +197,7 @@ Use `conditional` when the source renders different content on **one** screen ba
 
 In the builder UI these are two add-menu kinds sharing `externalSurfaceNodes`:
 
-- **Integration Node** — RevenueCat paywalls become nodes with provider `revenuecat`.
+- **Integration Node** — RevenueCat / Superwall paywalls become nodes with provider `revenuecat` or `superwall`.
 - **External Surface Node** — Host-owned custom screens become nodes with provider `headless` (stable `surf_*` id; optional `config.hostKey` for the host `externalSurfaces` registry).
 - Every node needs a `fallback`.
 - Map paywall outcomes to `purchase_completed`, `restore_completed`, `dismissed`, and `failed`.

package/rheo/rheo-flow-import/references/publish-gates.md

@@ -45,9 +45,9 @@ These mirror `apps/web/src/features/builder/validateFlow.ts` and API `preflightP
 
 ### Integrations (default: enabled)
 
-- External surfaces need `config.provider` (not `unspecified`). Integration Nodes use partner providers such as `revenuecat`; External Surface Nodes use `headless`.
+- External surfaces need `config.provider` (not `unspecified`). Integration Nodes use partner providers such as `revenuecat` or `superwall`; External Surface Nodes use `headless`.
 - Every external surface needs `fallback`.
-- RevenueCat surfaces require RevenueCat integration enabled (import assumes enabled).
+- RevenueCat / Superwall surfaces require the matching integration enabled (import assumes enabled).
 - External Surface Nodes (`provider: "headless"`) do not require an App settings toggle; the host must supply `externalSurfaces`.
 
 ### Canvas editor gates (default: all enabled)

package/rheo/rheo-flow-import/references/react-native-source-patterns.md

@@ -84,10 +84,12 @@ Paging is swipe by default; map the pager's own next button to a `button` with
 
 - `react-native-purchases` / `react-native-purchases-ui` / `Purchases.configure`
   / a `<Paywall>` → a RevenueCat **Integration Node** (`provider: "revenuecat"`,
+  required `fallback`). `expo-superwall` / `@superwall/react-native-superwall` /
+  `registerPlacement` → a Superwall **Integration Node** (`provider: "superwall"`,
   required `fallback`). Host-owned custom screens → an **External Surface Node**
   (`provider: "headless"`). See [integrations](../../rheo-best-practices/references/integrations.md).
 - `react-native-appsflyer` → represent stable attribution branches via decision
-  nodes; add keys to `sdkAttributeKeys`. Never include AppsFlyer/RevenueCat secrets.
+  nodes; add keys to `sdkAttributeKeys`. Never include AppsFlyer/RevenueCat/Superwall secrets.
 - OAuth / email-password screens → `oauth_login` / `email_password_auth` (host
   owns the actual auth logic).
 - `react-native-permissions` prompts → a `request_os_permission` button action.

package/rheo/rheo-flow-import/references/swiftui-source-patterns.md

@@ -81,6 +81,8 @@ page. Paging is swipe by default; an explicit Next button becomes a `button` wit
 
 - RevenueCat (`Purchases.configure`, `RevenueCatUI` `PaywallView`, `.presentPaywall`)
   → a RevenueCat **Integration Node** (`provider: "revenuecat"`, required
+  `fallback`). Superwall (`Superwall.configure`, `register(placement:)`)
+  → a Superwall **Integration Node** (`provider: "superwall"`, required
   `fallback`). Host-owned custom screens → an **External Surface Node**
   (`provider: "headless"`). See [integrations](../../rheo-best-practices/references/integrations.md).
 - AppsFlyer (`AppsFlyerLib`) → represent stable attribution branches via decision