@getrheo/rheo-skill 2.5.0 → 3.0.0

package/README.md

@@ -1,16 +1,19 @@
 # @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: **`3.0.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:
-
-- **`rheo/rheo-best-practices`** — how to install and wire the Rheo SDK (React Native,
-  Expo, SwiftUI), integrations, auth, and implementation best practices. Pure
-  guidance, no scripts.
-- **`rheo/rheo-flow-import`** — how to analyze an existing mobile flow and export it as
-  a compliant Rheo `FlowManifest`, plus self-contained `node` scripts (audit,
-  scaffold, validate, audit-publish, normalize, summary, profile).
+skill with two sub-skills. Rheo is one SDK and one Customer across **Analytics**,
+**Convert**, and **Engage**.
+
+- **`rheo/rheo-best-practices`** — how to install and wire that SDK on **Expo**,
+  **bare React Native**, and **React web** (SwiftUI / Flutter SDK install is
+  coming soon): product analytics, Convert flows, Engage `identify` / `track`,
+  integrations, and auth. Pure guidance, no scripts.
+- **`rheo/rheo-flow-import`** — the Convert authoring path: analyze an existing
+  mobile flow and export it as a compliant Rheo `FlowManifest`, plus self-contained
+  `node` scripts (audit, scaffold, validate, audit-publish, normalize, summary,
+  profile).
 
 ## The deliverable is `rheo/`
 
@@ -25,8 +28,9 @@ rheo/
 ├── SKILL.md                      # router → rheo-best-practices / rheo-flow-import
 ├── rheo-best-practices/
 │   ├── SKILL.md
-│   ├── references/               # install-* , integrations, implement-workflow, troubleshooting
-│   └── examples/               # install snippets
+│   ├── references/               # product-model, analytics, engage, react-web,
+│   │                             #   install-* , integrations, implement-workflow, troubleshooting
+│   └── examples/               # install snippets (RN, SwiftUI, web)
 └── rheo-flow-import/
     ├── SKILL.md
     ├── references/               # import-workflow, flow-spec, capabilities (generated), manifest-rules,
@@ -74,5 +78,6 @@ back to `rheo/rheo-flow-import/references/manifest-agent-profile-fallback.md` of
 ## Compatibility
 
 - Manifest schema version: `7`
-- Supported SDK surfaces: React Native / Expo and SwiftUI
+- SDK surfaces this skill installs today: React Native (Expo and bare), React web (`@getrheo/react`). SwiftUI / Flutter SDK install is coming soon; SwiftUI **flow import** remains in rheo-flow-import
+- Engage `identify` and `track` ship on web (`@getrheo/react`) and React Native
 - Requires Node.js 20+

package/package.json

@@ -1,16 +1,18 @@
 {
   "name": "@getrheo/rheo-skill",
-  "version": "2.5.0",
+  "version": "3.0.0",
   "type": "module",
-  "description": "Rheo agent skill — SDK install guidance and flow manifest import tooling.",
+  "description": "Rheo agent skill — Analytics, Convert, and Engage SDK guidance, plus flow manifest import tooling.",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
   "exports": {
-    ".": "./src/index.ts"
+    ".": "./src/index.ts",
+    "./flow-import-cli": "./rheo/rheo-flow-import/scripts/lib/rheo-cli.mjs",
+    "./package.json": "./package.json"
   },
   "dependencies": {
-    "@getrheo/contracts": "2.5.0",
-    "@getrheo/flow-runtime": "2.5.0",
+    "@getrheo/contracts": "3.0.0",
+    "@getrheo/flow-runtime": "3.0.0",
     "zod": "^3.23.8"
   },
   "devDependencies": {

package/rheo/SKILL.md

@@ -1,32 +1,41 @@
 ---
 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, a growth platform with one SDK and one Customer across Analytics, Convert, and Engage. Use when a user wants to install or wire the Rheo SDK on Expo, bare React Native, or React web (SwiftUI/Flutter SDK install is coming soon), record product analytics, attribute RevenueCat or Superwall revenue, publish onboarding or paywall flows, wire auth or integrations, identify a customer for lifecycle email, or import an existing mobile flow (React Native or SwiftUI source) into a FlowManifest. 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: "3.0.0"
   manifest-schema-version: "7"
 ---
 
 # Rheo
 
-Rheo is a headless flow engine: a hosted dashboard authors onboarding, paywall, post-purchase, and setup flows as a `FlowManifest`, and the Rheo SDK renders them natively inside a host app. This skill helps an agent do two distinct jobs. Pick the sub-skill that matches the request and read its `SKILL.md` before doing anything else.
+Rheo is a growth platform for mobile and web apps. One SDK and one Customer cover three products:
+
+- **Analytics** records sessions, page and screen views, custom events, and revenue from RevenueCat, Superwall, and Stripe.
+- **Convert** renders onboarding, paywalls, and experiments from a hosted `FlowManifest`. The host passes a channel id. Rheo decides which flow revision or experiment arm to serve.
+- **Engage** sends lifecycle email through the app's own provider. Push and outbound webhooks are not SDK surfaces yet.
+
+The same Customer profile sits behind all three. Start with the product the user asked for. Turning on the next one reuses the provider and the id.
+
+This skill helps an agent do two jobs. Pick the sub-skill that matches the request and read its `SKILL.md` before doing anything else.
 
 ## Routing
 
 | 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) |
-| 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) |
+| --- | --- | --- |
+| Install the SDK, record product analytics, attribute revenue, render `Flow` / `FlowView`, wire RevenueCat / Superwall / Stripe / AppsFlyer / auth, or call `identify` / `track` for Engage | **rheo-best-practices** | [rheo-best-practices/SKILL.md](rheo-best-practices/SKILL.md) |
+| Analyze an existing mobile onboarding, paywall, or setup flow and export it as a compliant Convert `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.
+If a request spans both (for example "import my onboarding and wire the SDK"), run **rheo-flow-import** to produce the manifest first, then **rheo-best-practices** to implement the SDK.
 
 ## What each sub-skill is
 
-- **rheo-best-practices** — pure guidance. How to detect the host stack, install the right flavor package (`@getrheo/react-native-expo`, `@getrheo/react-native-bare`, or `RheoSwiftUI`), wire the provider + runtime component, preserve a rollback path, and connect optional integrations and auth. No code is run.
-- **rheo-flow-import** — guidance **plus** self-contained tooling. References for the manifest contract, source-reading patterns for React Native and SwiftUI, worked examples, and `node` scripts (`audit`, `scaffold`, `validate`, `audit-publish`, `normalize`, `summary`, `profile`) that run with no install step — the validation/scaffold engine and the Rheo contracts are bundled into the skill.
+- **rheo-best-practices** is guidance for the host app. It detects the stack, installs one SDK, and wires only the products requested: Analytics on `RheoProvider`, Convert on a channel, Engage via `identify` and `track` (web and React Native). No code is run by the skill itself.
+- **rheo-flow-import** is the Convert authoring path: guidance plus self-contained tooling. It reads React Native or SwiftUI source, scaffolds a manifest, and validates publish gates. It does not install the SDK or configure Analytics or Engage.
 
 ## Shared rules
 
-- Never put secrets, API keys, tokens, or private backend URLs in a manifest or a committed snippet.
-- The Rheo manifest contract is the source of truth. rheo-flow-import ships a generated capability cheat-sheet ([rheo-flow-import/references/capabilities.md](rheo-flow-import/references/capabilities.md)) and a Manifest Agent Profile fetch; trust those over memory.
+- Never put secrets, API keys, tokens, or private backend URLs in a manifest, a snippet, or client code.
+- The Rheo manifest contract is the source of truth for Convert. rheo-flow-import ships a generated capability cheat-sheet ([rheo-flow-import/references/capabilities.md](rheo-flow-import/references/capabilities.md)) and a Manifest Agent Profile fetch. Trust those over memory.
 - Only install packages or edit a host app's code when the user explicitly asks for implementation. Analysis and manifest generation never modify the host app.
+- One React Native flavor per app: `@getrheo/react-native-expo` or `@getrheo/react-native-bare`, never both. Web is `@getrheo/react`. SwiftUI / Flutter **SDK install** is coming soon — do not add those packages for customers yet. SwiftUI **flow import** (source → manifest) remains available via rheo-flow-import.

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

@@ -1,47 +1,60 @@
 ---
 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 for Analytics, Convert, and Engage on Expo, bare React Native, or React web. Use when a user asks to install Rheo, add @getrheo/react-native-expo or @getrheo/react-native-bare or @getrheo/react, mount RheoProvider, record product analytics (logEvent, screen, web consent), render Flow, wire terminal callbacks, configure RevenueCat, Superwall, Stripe, or AppsFlyer, call identify for marketing consent, or call track for Engage automations on web or React Native. Do not install RheoSwiftUI or Flutter — those SDK installs are coming soon. Part of the `rheo` skill.
 ---
 
 # Rheo — Best Practices (SDK implementation)
 
-Use this sub-skill when the user wants Rheo **running in their app**. The goal is a minimal, reversible integration that wraps the flow host, renders the Rheo runtime, and wires the callbacks the host owns — without hard-coding secrets or deleting the existing onboarding on the first pass.
+Use this sub-skill when the user wants Rheo **running in their app**. Read [references/product-model.md](references/product-model.md) first. Rheo is one SDK and one Customer across Analytics, Convert, and Engage. Wire the products they asked for. Leave the others unwired.
+
+The goal is a minimal, reversible integration: one provider, stable identity, and the calls that product actually uses. Do not hard-code secrets. Do not delete the existing onboarding on the first Convert pass.
 
 ## When to act
 
-Only install packages or edit host code when the user explicitly asks for implementation. If they only ask "how would I add Rheo?", explain using these references and stop.
+Only install packages or edit host code when the user explicitly asks for implementation. If they only ask how Rheo would fit, explain using these references and stop.
 
 ## Workflow
 
-1. **Detect the host stack** and read the matching reference:
+1. **Read the product model** in [references/product-model.md](references/product-model.md). Confirm which products this request includes. Analytics starts when `RheoProvider` mounts. Convert needs a channel and `Flow` / `FlowView`. Engage needs `identify`, and `track` on web or React Native.
+2. **Detect the host stack** and read the matching reference:
    - React Native + Expo → [references/react-native-expo.md](references/react-native-expo.md)
    - React Native bare (no `expo` dependency) → [references/react-native-bare.md](references/react-native-bare.md)
-   - SwiftUI → [references/swiftui.md](references/swiftui.md)
-2. Read [references/implement-workflow.md](references/implement-workflow.md) for the shared, stack-agnostic steps (identity inputs, dashboard values, provider wrap, runtime swap, terminal callbacks, verification).
-3. When the flow uses paywalls, attribution, auth, permissions, links, or in-app review, read [references/integrations.md](references/integrations.md) before wiring anything.
-4. Use the install snippets in [examples/](examples) as a starting point, adapted to the project's package manager and conventions.
-5. If something behaves unexpectedly, consult [references/troubleshooting.md](references/troubleshooting.md).
+   - React web → [references/react-web.md](references/react-web.md)
+   - SwiftUI or Flutter → **stop**. SDK install is coming soon ([references/swiftui.md](references/swiftui.md)). Offer Expo / bare / web, or route SwiftUI **source → manifest** work to rheo-flow-import.
+3. Read [references/implement-workflow.md](references/implement-workflow.md) for the shared steps (identity, dashboard values, provider, verification).
+4. **Analytics** → [references/analytics.md](references/analytics.md). On web, leave consent `pending` until the site grants it.
+5. **Convert** → mount `Flow` / `FlowView` with a channel public id, preserve a rollback path, and when the flow uses paywalls, attribution, auth, permissions, links, or in-app review, read [references/integrations.md](references/integrations.md) before wiring anything.
+6. **Engage** → [references/engage.md](references/engage.md). Call `identify` only for a real email and consent choice. Call `track` only for an automation or segment trigger (web or React Native).
+7. Use the install snippets in [examples/](examples) as a starting point, adapted to the project's package manager and conventions.
+8. If something behaves unexpectedly, consult [references/troubleshooting.md](references/troubleshooting.md).
 
 ## Hard rules
 
-- **One flavor per app.** Install **either** `@getrheo/react-native-expo` **or** `@getrheo/react-native-bare`, never both. SwiftUI uses the `RheoSwiftUI` SwiftPM products.
-- **No secrets in code.** `publishableKey` and `channelId` come from env/config or placeholders the user fills in. Never commit real keys.
-- **Production API:** SDK defaults use **`https://api.getrheo.io`** (`RHEO_DEFAULT_SDK_API_BASE_URL`). Omit `apiBaseUrl` / `apiBaseURL` in production unless self-hosting. Never pair **`ob_pk_live_*`** keys with localhost.
-- **Pass the channel public id**, not a flow id, to `Flow` / `FlowView`.
+- **One flavor per native app.** Install **either** `@getrheo/react-native-expo` **or** `@getrheo/react-native-bare`, never both. Web uses `@getrheo/react`. Do **not** install `RheoSwiftUI` or Flutter packages until GA (coming soon).
+- **One provider.** Mount `RheoProvider` once. Product analytics starts there, even when no flow is showing.
+- **Three event pipes.** `logEvent` is Analytics. Flow events are automatic. `track` is Engage (web and React Native). Do not use one to fake another.
+- **Consent is `identify`.** Email on a flow answer or an event property does not grant marketing consent. `unknown` does not send.
+- **No secrets in code.** `publishableKey` and `channelId` come from env/config or placeholders the user fills in. Never commit real keys. Email-provider credentials stay in the dashboard.
+- **Production API:** SDK defaults use **`https://api.getrheo.io`**. Omit `apiBaseUrl` / `apiBaseURL` in production unless self-hosting. Never pair **`ob_pk_live_*`** keys with localhost.
+- **Pass the channel public id**, not a flow id, to `Flow` / `FlowView`. Analytics and Engage do not need a channel.
 - **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.
-- **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.
+- **RevenueCat, Superwall, AppsFlyer, and Stripe are host integrations**, not SDK peers. Wire `fallback` for every Integration / External Surface Node. After RevenueCat or Superwall identify, call `setBillingIdentity` with that same id. Stripe dollars come from the webhook.
+- **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. They fail closed on web.
+- **Do not add `request_app_review`** prompts unless the user explicitly asks. Apple discourages prompting from raw button taps.
+- **Do not scaffold Engage push or outbound webhooks.**
 - Run the **narrowest useful verification** (typecheck or a build of the touched module), not a full app build, unless asked.
 
 ## Final response
 
 When you implement, report:
 
+- Products wired (Analytics, Convert, Engage) and products left unwired.
 - Files changed.
-- SDK surface wired (`RheoProvider` + `Flow`/`useFlow`, or `RheoProvider` + `FlowView`).
-- Dashboard values still needing real values (`publishableKey`, `channelId`).
-- Integrations/auth callbacks wired (or none).
+- SDK surface (`RheoProvider`, and `Flow` / `FlowView` only if Convert was requested).
+- Dashboard values still needing real values (`publishableKey`, `channelId` if Convert, web origin if web).
+- Analytics calls added (`logEvent`, `screen`, web consent) or "provider only".
+- Engage calls added (`identify`, `track`) or none.
+- Integrations and auth callbacks wired, including `setBillingIdentity` when a billing SDK is present.
 - Whether the legacy onboarding was preserved as a fallback.
 - Verification run, or why it was skipped.

package/rheo/rheo-best-practices/examples/swiftui-install-snippet.md

@@ -1,4 +1,6 @@
-# SwiftUI Install Snippet
+# SwiftUI Install Snippet (coming soon — do not use for customer installs)
+
+Public SwiftUI SDK install is **paused**. Do not add these products to a customer app until Developer Guide / marketing flip from “coming soon”. Prefer Expo, bare React Native, or React web install paths. For migrating an existing SwiftUI flow into Convert, use **rheo-flow-import** instead.
 
 ```swift
 import SwiftUI

package/rheo/rheo-best-practices/examples/web-install-snippet.md

@@ -0,0 +1,26 @@
+# React web install snippet
+
+```bash
+pnpm add @getrheo/react
+```
+
+```tsx
+import { Flow, RheoProvider, setAnalyticsConsent } from '@getrheo/react';
+
+export const App = () => (
+  <RheoProvider
+    config={{
+      publishableKey: import.meta.env.VITE_RHEO_PUBLISHABLE_KEY,
+      // apiBaseUrl defaults to https://api.getrheo.io — omit in production
+      analytics: { consent: 'pending' },
+    }}
+  >
+    <Flow channelId={import.meta.env.VITE_RHEO_CHANNEL_ID} />
+  </RheoProvider>
+);
+
+const onAccept = () => setAnalyticsConsent('granted');
+const onReject = () => setAnalyticsConsent('denied');
+```
+
+Drop `Flow` when the task is Analytics only. For Engage, call `identify` after marketing opt-in and `track` for automation triggers.

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

@@ -0,0 +1,104 @@
+# Analytics
+
+Product analytics records what people do in the app or site. It starts when `RheoProvider` mounts, including when no Convert flow is showing. Read [product-model.md](product-model.md) before adding calls. Flow funnel events stay on the flow pipe. Engage `track` stays on the Engage pipe.
+
+## Turn it on
+
+Mount the provider with a publishable key and a stable `userId`. That is enough for sessions.
+
+| SDK | Opt out |
+| --- | --- |
+| Web (`@getrheo/react`) | `analytics={{ enabled: false }}` |
+| Expo and bare React Native | `analytics={{ enabled: false }}` |
+| SwiftUI | `analyticsEnabled: false` on `RheoConfig` |
+
+Do not opt out unless the user asked to disable Analytics.
+
+## Consent (web)
+
+On `@getrheo/react`, an omitted `analytics.consent` is `pending`. Rheo writes no anonymous id, session, or first-touch attribution, and it sends no product events, until the host grants consent. Rheo does not ship a banner. The site decides.
+
+| `analytics.consent` | Behavior |
+| --- | --- |
+| omitted or `pending` | Leave storage untouched. Send nothing until grant. |
+| `granted` | Collect immediately. Use this when a consent tool already stored a grant before paint, so the first page view is kept. |
+| `denied` | Same pause as pending, and delete any analytics id, session, and first-touch values already stored. |
+
+```tsx
+import { RheoProvider, setAnalyticsConsent } from '@getrheo/react';
+
+export const App = () => (
+  <RheoProvider config={{ publishableKey, analytics: { consent: 'pending' } }}>
+    {children}
+  </RheoProvider>
+);
+
+const onAccept = () => setAnalyticsConsent('granted');
+const onReject = () => setAnalyticsConsent('denied');
+```
+
+`setAnalyticsConsent('granted')` starts collection. `setAnalyticsConsent('denied')` stops it and clears storage. Events recorded before a grant are dropped. App SDKs do not use this consent gate.
+
+A flow can still resolve while consent is pending. It uses an in-memory id and writes `rheo_app_user_id` only after consent is granted.
+
+## Automatic events
+
+- `session_start` when there is no session, or the last product event was more than 30 minutes ago.
+- `first_visit` on web, or `first_open` on app SDKs, once per persisted anonymous `appUserId`.
+- `page_view` on web for the first load and later `pushState`, `replaceState`, and `popstate`. The page name is the path.
+
+App navigators differ, so screen views are explicit.
+
+## Calls
+
+`logEvent(name, properties?)` records a custom event. Name at most 120 characters. Properties at most 32KB. `setUserId(id)` sets `customUserId` on later product events. The anonymous `appUserId` stays the device id.
+
+`screen(name)` records `screen_view`. On React Native, `bindNavigationState(state)` reads the focused route from a React Navigation `onStateChange` and calls `screen`.
+
+### Web
+
+```tsx
+import { logEvent, setUserId } from '@getrheo/react';
+
+setUserId('user_123');
+logEvent('workout_logged', { minutes: 30 });
+```
+
+### React Native
+
+```tsx
+import { bindNavigationState, logEvent, screen, setUserId } from '@getrheo/react-native-expo';
+
+setUserId('user_123');
+logEvent('workout_logged', { minutes: 30 });
+screen('Home');
+```
+
+Bare React Native exports the same functions from `@getrheo/react-native-bare`.
+
+### SwiftUI
+
+```swift
+RheoAnalytics.setUserId("user_123")
+RheoAnalytics.logEvent(name: "workout_logged", properties: ["minutes": .number(30)])
+RheoAnalytics.screen("Home")
+```
+
+## Revenue on the same person
+
+After the host identifies RevenueCat or Superwall, register that id so webhook charges join this Customer:
+
+```tsx
+import { setBillingIdentity } from '@getrheo/react-native-expo';
+
+setBillingIdentity('revenuecat', originalAppUserId);
+setBillingIdentity('superwall', superwallUserId);
+```
+
+SwiftUI: `RheoAnalytics.setBillingIdentity(provider:externalId:)`. Web: `setBillingIdentity` from `@getrheo/react` for RevenueCat and Superwall only. Stripe revenue is the webhook. See [integrations.md](integrations.md).
+
+## What you should not do
+
+- Do not call `logEvent` to start an Engage automation. Use `track` on React Native. See [engage.md](engage.md).
+- Do not pass a flow id where a channel id belongs. Analytics does not need a channel.
+- Do not hard-code live publishable keys. Placeholders or env only.

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

@@ -0,0 +1,95 @@
+# Engage
+
+Engage is lifecycle email for people who already use the product. Rheo writes the message and the audience. The app's own Amazon SES, Resend, Postmark, or SendGrid account sends it. Rheo does not send Engage messages from Rheo-owned infrastructure.
+
+Push notifications and outbound webhooks are not SDK surfaces yet. Do not scaffold them.
+
+Dashboard setup (provider credentials, physical mailing address, webhook URL, topics, frequency cap) stays in **App settings → Engage settings** or `rheo engage` in the CLI. Do not put provider secrets in the app or in a manifest.
+
+## When a person can be emailed
+
+All of these must be true:
+
+1. The Customer has an email address.
+2. Global marketing consent is `granted`. `unknown` does not send.
+3. If marketing topics mode is on, the message topic is granted too.
+4. The address is not suppressed (hard bounce, complaint, or unsubscribe).
+
+Topics mode is off by default.
+
+## `identify`
+
+Call `identify` when the app collects an email and a real consent choice. Flow answer fields and event properties do not grant consent.
+
+If you send `email`, you must send `marketingConsent` (`granted`, `denied`, or `unknown`). `granted` requires an email. Published SDK clients may still send deprecated `emailMarketingConsent`. The API accepts that alias and rejects the request when both fields are set and differ.
+
+### React Native
+
+`identify` and the provider `config` (`publishableKey`, `userId`, optional `apiBaseUrl`) are the two arguments. Expo and bare export it from the flavor package.
+
+```tsx
+import { identify } from '@getrheo/react-native-expo';
+
+await identify(
+  {
+    email: 'user@example.com',
+    marketingConsent: 'granted',
+    topicConsents: { product_updates: 'granted' },
+    attributes: { plan: 'pro' },
+    timezone: 'America/Los_Angeles',
+  },
+  config,
+);
+```
+
+`attributes` shallow-merge onto the Customer. `timezone` is an IANA zone used for Engage quiet hours. `appUserId` defaults from `config.userId`.
+
+### SwiftUI
+
+```swift
+try await runtime.identify(
+  email: "user@example.com",
+  marketingConsent: .granted,
+  topicConsents: ["product_updates": .granted]
+)
+```
+
+`RheoRuntime.identify` does not take attributes or timezone. Pass `customUserId` when it differs from `appUserId`.
+
+### Web
+
+Same `identify` shape as React Native, exported from `@getrheo/react`. An email collected in a web flow answer is still not Engage consent. Call `identify` after an explicit opt-in (or send `denied` / `unknown` to match the UI).
+
+```tsx
+import { identify } from '@getrheo/react';
+
+await identify(
+  {
+    email: 'user@example.com',
+    marketingConsent: 'granted',
+    topicConsents: { product_updates: 'granted' },
+  },
+  config,
+);
+```
+
+## `track` (web and React Native)
+
+`track` posts to `POST /v1/sdk/track`. It can enroll automations and match segment rules. It does not write product-analytics events and it does not require a flow or a channel.
+
+```tsx
+import { track } from '@getrheo/react';
+// same export from @getrheo/react-native-expo and @getrheo/react-native-bare
+
+await track({ name: 'trial_started', properties: { plan: 'pro' } }, config);
+```
+
+SwiftUI and Flutter do not export this Engage `track`. On those stacks, do not repurpose flow `track` helpers or `logEvent`. Tell the user the automation trigger has to be emitted from web or React Native, or authored in the dashboard from an event the app already sends.
+
+Use `logEvent` when the same action should appear in Analytics and the user did not ask for a journey. Call both only when they asked for both. See [analytics.md](analytics.md).
+
+## What you should not do
+
+- Do not install an email SDK to "add Engage".
+- Do not set consent to `granted` because an email field exists. Wait for an explicit opt-in, or send `denied` / `unknown` to match what the UI collected.
+- Do not put provider API keys, webhook tokens, or SES secrets in client code.

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

@@ -1,27 +1,32 @@
 # Implementation Workflow
 
-Use this when the user explicitly asks to install or wire Rheo in a host app.
+Use this when the user explicitly asks to install or wire Rheo in a host app. Read [product-model.md](product-model.md) first and wire only the products they named.
 
-## Shared Steps
+## Shared steps
 
-1. Read local conventions, package manager, navigation structure, and current onboarding entry point.
-2. Identify stable identity inputs: anonymous user id, backend user id, session id, app version, and locale.
+1. Read local conventions, package manager, navigation structure, and the current entry point for the product you are adding (onboarding route, app root, or site layout).
+2. Identify stable identity inputs: anonymous or auth user id, backend user id, session id, app version, and locale. One `userId` is the Customer. Do not mint a separate id for Analytics, Convert, and Engage.
 3. Ask for missing Rheo dashboard values or use placeholders:
    - publishable key
-   - channel id
-   - optional API base URL for non-production/dev
-4. Install SDK dependencies using the project package manager.
-5. Wrap the flow host in the Rheo provider.
-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.
-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.
+   - channel id, only when Convert is in scope
+   - web origin, only when the stack is React web
+   - optional API base URL for non-production
+4. Install the one SDK package for this stack, with required peers. See the stack reference.
+5. Mount `RheoProvider` once around the subtree that should be measured. That starts Analytics.
+6. Then branch:
+   - **Analytics only:** stop after the provider, consent (web), `screen` / `logEvent`, and `setUserId` if a CRM id exists. See [analytics.md](analytics.md).
+   - **Convert:** gate the existing onboarding entry with `Flow` / `FlowView`. Preserve the old onboarding as a fallback unless the user asked to remove it. Wire terminal callbacks to continue host navigation. Pass the channel public id.
+   - **Engage:** after a real email and consent choice, call `identify`. On web or React Native, call `track` for automation triggers. See [engage.md](engage.md).
+   - **Revenue:** if the host already configures RevenueCat or Superwall, call `setBillingIdentity` with that provider's user id. See [integrations.md](integrations.md).
+7. Wire optional auth, permissions, and in-app review only when the manifest or the user asks for them.
+8. 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`.
+9. Run the narrowest useful verification.
 
 ## Safety
 
 - Do not hard-code secrets.
-- Do not remove legacy onboarding on the first integration unless requested.
+- Do not remove legacy onboarding on the first Convert integration unless requested.
+- Do not mount `Flow` for an Analytics-only or Engage-only request.
+- Do not call `logEvent` where `track` belongs, or the reverse.
 - Keep edits localized to the integration entry point and app config.
 - Prefer reversible feature flags or route swaps for production apps.

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

@@ -1,10 +1,12 @@
 # Integrations
 
+Partner paywalls, Stripe, and host UI are Convert graph nodes. Revenue from those partners also feeds Analytics once the host registers the billing id. Read [product-model.md](product-model.md) for which pipe each call uses.
+
 In the flow builder, partner paywalls and host UI are **two add-menu nodes** that share the `externalSurfaceNodes` schema:
 
 | Builder node | Manifest `config.provider` | App settings toggle |
 | --- | --- | --- |
-| **Integration Node** | `revenuecat` (and future partners) | Required |
+| **Integration Node** | `stripe`, `revenuecat`, `superwall` | Required |
 | **External Surface Node** | `headless` | None (host registry) |
 
 ## RevenueCat (Integration Node)
@@ -24,9 +26,37 @@ Manifest mapping:
 
 The host remains responsible for configuring RevenueCat. Rheo does not own purchase SDK secrets or receipt validation.
 
+After `Purchases.configure` or `Purchases.logIn`, call `setBillingIdentity('revenuecat', customerInfo.originalAppUserId)` with the id RevenueCat already has. Dollars come from the RevenueCat webhook, not from the device. In **App settings → Integrations**, pick RevenueCat as the revenue source for that store. One source per store.
+
+## 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`.
+
+After `Superwall.identify`, call `setBillingIdentity('superwall', userId)` with that same id. Dollars come from the Superwall webhook. One source per store, shared with RevenueCat: a second source for the same store is rejected.
+
+## Stripe (web Integration Node)
+
+Stripe Payment Links run on `@getrheo/react` only. There is no Stripe adapter on `RheoProvider` and no `setBillingIdentity('stripe', …)`.
+
+- Enable **Stripe** under **App settings → Integrations**.
+- Integration Node `config.provider: "stripe"` with a Payment Link on `buy.stripe.com` or another `https://*.stripe.com` host.
+- Paste Rheo's webhook URL and signing secret into Stripe. The verified `checkout.session.completed` webhook is the purchase record. The browser does not send a price.
+- Always wire `fallback`.
+
+RevenueCat, Superwall, and headless surfaces fail closed on web and follow **Fallback**. See [react-web.md](react-web.md).
+
 ## 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 +83,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, Superwall, or Stripe when the flow should record a paywall outcome. Use an Integration Node with `provider: "revenuecat"`, `provider: "superwall"`, or `provider: "stripe"`. Conversion is `surface_outcome` with `purchase_completed`. Dollars come from that provider's webhook, not from the device.
 
 ## AppsFlyer
 
@@ -78,7 +108,11 @@ Native permission prompts can map to `request_os_permission` button actions. Ver
 - Manifest: `action.kind: "request_app_review"` on a button (no extra fields).
 - Requires **`screen.next.default`** on that screen.
 - Submits inputs like **Continue**; advances only via default next (no branching).
-- **React Native (Expo):** required peer `expo-store-review`.
+- **React Native (Expo):** required peer `expo-store-review`. Push uses required peer `expo-notifications` (`registerPush` after a notifications grant).
+- **React Native (bare):** call `registerPushTokenAdapter`, or pass the device token to `registerPush`.
+- **Web:** `registerPush()` subscribes with the app VAPID key. Set `RheoConfig.push.serviceWorkerUrl` or rely on `navigator.serviceWorker.ready`.
+- **SwiftUI:** after notifications are granted the SDK calls `registerForRemoteNotifications`. Forward `didRegister` with `RheoPush.forward(deviceToken:)`.
+- **Flutter:** call `runtime.registerPush(token:)`, or set `runtime.setPushTokenProvider` so a notifications grant uploads a Firebase token.
 - **React Native (bare):** required peer `react-native-in-app-review`.
 - **SwiftUI:** built-in StoreKit; ~1.5s delay when a prompt may have shown (no dismiss callback on iOS).
 - Analytics: `app_review_prompt_shown`, `app_review_prompt_dismissed`; capture key `app_review:{layerId}`.