@getrheo/rheo-skill 2.6.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

@@ -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,7 +12,7 @@ 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`, `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).
@@ -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 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,55 +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: "RheoSwiftUISuperwall", 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.
-- 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.
-- 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:

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

@@ -74,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).