@getrheo/rheo-skill 2.5.0 → 2.6.0

package/README.md

@@ -1,6 +1,6 @@
 # @getrheo/rheo-skill
 
-Current release: **`2.5.0`** on npm (`PLATFORM_SDK_VERSION` in `scripts/publish-package-registry.mjs`). Public source: [getrheo/rheo-skill](https://github.com/getrheo/rheo-skill) (mirrored from this private monorepo via `pnpm extract:oss-repos`).
+Current release: **`2.6.0`** on npm (`PLATFORM_SDK_VERSION` in `scripts/publish-package-registry.mjs`). Public source: [getrheo/rheo-skill](https://github.com/getrheo/rheo-skill) (mirrored from this private monorepo via `pnpm extract:oss-repos`).
 
 Source and build tooling for the **`rheo`** agent skill — a single, self-contained
 skill with two sub-skills:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getrheo/rheo-skill",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "type": "module",
   "description": "Rheo agent skill — SDK install guidance and flow manifest import tooling.",
   "main": "./src/index.ts",
@@ -9,8 +9,8 @@
     ".": "./src/index.ts"
   },
   "dependencies": {
-    "@getrheo/contracts": "2.5.0",
-    "@getrheo/flow-runtime": "2.5.0",
+    "@getrheo/contracts": "2.6.0",
+    "@getrheo/flow-runtime": "2.6.0",
     "zod": "^3.23.8"
   },
   "devDependencies": {

package/rheo/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: rheo
-description: Work with Rheo, the headless onboarding/paywall flow engine for mobile apps. Use when a user wants to install or wire the Rheo SDK (React Native, Expo, or SwiftUI), follow Rheo SDK best practices, configure integrations (RevenueCat, AppsFlyer), wire auth/permissions/terminal callbacks, OR import/migrate an existing mobile flow into a compliant Rheo FlowManifest and validate it. Routes to the `rheo-best-practices` and `rheo-flow-import` sub-skills.
+description: Work with Rheo, the headless onboarding/paywall flow engine for mobile apps. Use when a user wants to install or wire the Rheo SDK (React Native, Expo, or SwiftUI), follow Rheo SDK best practices, configure integrations (RevenueCat, Superwall, AppsFlyer), wire auth/permissions/terminal callbacks, OR import/migrate an existing mobile flow into a compliant Rheo FlowManifest and validate it. Routes to the `rheo-best-practices` and `rheo-flow-import` sub-skills.
 compatibility: Requires Node.js 20+. rheo-flow-import scripts are fully self-contained (no install step). Internet access fetches the latest Manifest Agent Profile; a bundled fallback works offline.
 metadata:
-  rheo-version: "2.5.0"
+  rheo-version: "2.6.0"
   manifest-schema-version: "7"
 ---
 
@@ -15,7 +15,7 @@ Rheo is a headless flow engine: a hosted dashboard authors onboarding, paywall,
 
 | The user wants to… | Use sub-skill | Read |
 |--------------------|---------------|------|
-| Install the Rheo SDK, wire `Flow`/`FlowView`, follow SDK best practices, configure RevenueCat / AppsFlyer / auth / permissions / terminal callbacks, or implement Rheo in an existing app | **rheo-best-practices** | [rheo-best-practices/SKILL.md](rheo-best-practices/SKILL.md) |
+| Install the Rheo SDK, wire `Flow`/`FlowView`, follow SDK best practices, configure RevenueCat / Superwall / AppsFlyer / auth / permissions / terminal callbacks, or implement Rheo in an existing app | **rheo-best-practices** | [rheo-best-practices/SKILL.md](rheo-best-practices/SKILL.md) |
 | Analyze an existing mobile onboarding/paywall/setup flow and export it as a compliant Rheo `FlowManifest` (or validate/repair a manifest) | **rheo-flow-import** | [rheo-flow-import/SKILL.md](rheo-flow-import/SKILL.md) |
 
 If a request spans both (e.g. "import my onboarding **and** wire the SDK"), run **rheo-flow-import** to produce the manifest first, then **rheo-best-practices** to implement the SDK — they are independent and can be done in sequence.

package/rheo/rheo-best-practices/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: rheo-best-practices
-description: Install and wire the Rheo SDK in a host app and follow Rheo implementation best practices. Use when a user asks to install Rheo, add @getrheo/react-native-expo or @getrheo/react-native-bare or RheoSwiftUI, wrap a flow host in RheoProvider, render Flow/FlowView, wire terminal callbacks, configure RevenueCat or AppsFlyer integrations, wire OAuth or email/password auth callbacks, request OS permissions, or add in-app review. Part of the `rheo` skill.
+description: Install and wire the Rheo SDK in a host app and follow Rheo implementation best practices. Use when a user asks to install Rheo, add @getrheo/react-native-expo or @getrheo/react-native-bare or RheoSwiftUI, wrap a flow host in RheoProvider, render Flow/FlowView, wire terminal callbacks, configure RevenueCat, Superwall, or AppsFlyer integrations, wire OAuth or email/password auth callbacks, request OS permissions, or add in-app review. Part of the `rheo` skill.
 ---
 
 # Rheo — Best Practices (SDK implementation)
@@ -30,7 +30,7 @@ Only install packages or edit host code when the user explicitly asks for implem
 - **Pass the channel public id**, not a flow id, to `Flow` / `FlowView`.
 - **Preserve the existing onboarding** as a fallback/rollback path (feature flag or route swap) unless the user explicitly asks to remove it.
 - **Read local conventions first** (package manager, navigation, env handling) and keep edits localized to the integration entry point and app config.
-- **RevenueCat and AppsFlyer are host integrations**, not SDK peers — the host configures and owns those SDKs and their secrets. Wire `fallback` for every Integration / External Surface Node.
+- **RevenueCat, Superwall, and AppsFlyer are host integrations**, not SDK peers — the host configures and owns those SDKs and their secrets. Wire `fallback` for every Integration / External Surface Node.
 - **External Surface Nodes** need a host `externalSurfaces` registry keyed by Host key (`config.hostKey` or `surf_*` id; callbacks `onComplete` / `onBack` / `onDismiss`). No App settings toggle.
 - **Do not add `request_app_review`** prompts unless the user explicitly asks; Apple discourages prompting from raw button taps.
 - Run the **narrowest useful verification** (typecheck or a build of the touched module), not a full app build, unless asked.

package/rheo/rheo-best-practices/references/implement-workflow.md

@@ -15,7 +15,7 @@ Use this when the user explicitly asks to install or wire Rheo in a host app.
 6. Replace or gate the existing onboarding entry with the Rheo runtime component.
 7. Preserve old onboarding as a fallback/rollback path unless explicitly told to remove it.
 8. Wire terminal callbacks to continue host navigation.
-9. Install **`@getrheo/react-native-expo`** or **`@getrheo/react-native-bare`** with all required peers (see platform reference). Wire optional auth, RevenueCat, AppsFlyer (host packages only), and resolve fallback when used.
+9. Install **`@getrheo/react-native-expo`** or **`@getrheo/react-native-bare`** with all required peers (see platform reference). Wire optional auth, RevenueCat, Superwall, AppsFlyer (host packages only), and resolve fallback when used.
 10. When `request_app_review` is present, tell the user TestFlight/production may not show prompts every tap and builder preview always advances as `not_shown`.
 11. Run the narrowest useful verification.
 

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

@@ -4,7 +4,7 @@ In the flow builder, partner paywalls and host UI are **two add-menu nodes** tha
 
 | Builder node | Manifest `config.provider` | App settings toggle |
 | --- | --- | --- |
-| **Integration Node** | `revenuecat` (and future partners) | Required |
+| **Integration Node** | `revenuecat`, `superwall` (and future partners) | Required |
 | **External Surface Node** | `headless` | None (host registry) |
 
 ## RevenueCat (Integration Node)
@@ -24,9 +24,22 @@ Manifest mapping:
 
 The host remains responsible for configuring RevenueCat. Rheo does not own purchase SDK secrets or receipt validation.
 
+## Superwall (Integration Node)
+
+Detect source calls such as `Superwall.configure`, `SuperwallProvider`, `expo-superwall`, `@superwall/react-native-superwall`, or `register(placement:)` / `registerPlacement`.
+
+Manifest mapping:
+
+- Create an **Integration Node** with `config.provider: "superwall"`.
+- Preserve the placement id from the Superwall dashboard / source.
+- Wire the same IAP outcomes as RevenueCat (`purchase_completed`, `restore_completed`, `purchase_cancelled`, `dismissed`, `failed`).
+- Always wire `fallback`.
+
+The host remains responsible for configuring Superwall. Rheo registers the placement and maps dismiss / skip / error callbacks to normalized outcomes. Skip / holdout / already-entitled paths map to `dismissed`.
+
 ## External Surface Node (headless host UI)
 
-Use when a source screen is owned by the host (custom native UI, third-party screen Rheo does not ship) rather than a Rheo layer tree or RevenueCat paywall.
+Use when a source screen is owned by the host (custom native UI, third-party screen Rheo does not ship) rather than a Rheo layer tree or a partner paywall.
 
 Manifest mapping:
 
@@ -53,7 +66,7 @@ Host wiring (required for success):
 
 SwiftUI / Flutter: pass the same map on `FlowView` as `externalSurfaces` (builders receive `onComplete` / `onBack` / `onDismiss`). Docs: product Developer Guide → Headless external surfaces.
 
-Do **not** use an External Surface Node to wrap RevenueCat when you need `iap_purchase` commerce events — use an Integration Node with `provider: "revenuecat"`.
+Do **not** use an External Surface Node to wrap RevenueCat or Superwall when you need `iap_purchase` commerce events — use an Integration Node with `provider: "revenuecat"` or `provider: "superwall"`.
 
 ## AppsFlyer
 

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
 

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

@@ -15,7 +15,7 @@ pnpm add @getrheo/react-native-expo \
   react-native-safe-area-context expo-store-review expo-video
 ```
 
-**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
 
@@ -46,4 +46,4 @@ export const OnboardingHost = () => (
 - Pass channel public id, not flow id.
 - **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/swiftui.md

@@ -16,6 +16,7 @@ Optional products:
 
 ```swift
 .product(name: "RheoSwiftUIRevenueCat", package: "RheoSwiftUI")
+.product(name: "RheoSwiftUISuperwall", package: "RheoSwiftUI")
 .product(name: "RheoSwiftUIAppsFlyer", package: "RheoSwiftUI")
 ```
 
@@ -47,6 +48,7 @@ struct OnboardingHost: View {
 ## Notes
 
 - Use `RheoSwiftUIRevenueCat` for RevenueCat Integration Node presenter helpers.
+- Use `RheoSwiftUISuperwall` for Superwall 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.

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

@@ -38,11 +38,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/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`
@@ -113,8 +119,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