@getrheo/rheo-skill 1.0.0

package/README.md

@@ -0,0 +1,76 @@
+# @getrheo/rheo-skill
+
+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).
+
+## The deliverable is `rheo/`
+
+The installable artifact is the [`rheo/`](rheo) directory. It is fully
+self-contained: the rheo-flow-import scripts run with **plain `node`** and need **no
+`pnpm install`**, because the validation/scaffold engine, `zod`, `@getrheo/contracts`,
+and `@getrheo/flow-runtime` are bundled into
+`rheo/rheo-flow-import/scripts/lib/rheo-cli.mjs` at build time.
+
+```text
+rheo/
+├── SKILL.md                      # router → rheo-best-practices / rheo-flow-import
+├── rheo-best-practices/
+│   ├── SKILL.md
+│   ├── references/               # install-* , integrations, implement-workflow, troubleshooting
+│   └── examples/               # install snippets
+└── rheo-flow-import/
+    ├── SKILL.md
+    ├── references/               # import-workflow, flow-spec, capabilities (generated), manifest-rules,
+    │                             #   layer-schema-pitfalls, publish-gates, *-source-patterns, carousel/font/i18n/animation
+    ├── examples/                 # valid manifests + flow-spec.example.json
+    └── scripts/
+        ├── *.mjs                 # thin wrappers (import runCli from lib)
+        └── lib/rheo-cli.mjs      # GENERATED self-contained bundle (committed)
+```
+
+## Source layout (this package)
+
+- `src/` — TypeScript engine (CLI, audit analyzers, scaffold, publish gates,
+  validation, profile fetch). Source of truth for the bundle.
+- `scripts/build-skill.ts` — esbuild bundler → `rheo/rheo-flow-import/scripts/lib/rheo-cli.mjs`.
+- `src/capabilities/generateCapabilities.ts` — regenerates
+  `rheo/rheo-flow-import/references/capabilities.md` from `@getrheo/contracts`.
+- `test/` — vitest suite (scaffold structure, publish gates, validation,
+  capabilities drift, bundle smoke test).
+
+## Commands
+
+```bash
+pnpm --filter @getrheo/rheo-skill build          # gen:capabilities + bundle (run before committing)
+pnpm --filter @getrheo/rheo-skill gen:capabilities
+pnpm --filter @getrheo/rheo-skill bundle
+pnpm --filter @getrheo/rheo-skill test
+pnpm --filter @getrheo/rheo-skill typecheck
+pnpm --filter @getrheo/rheo-skill validate:examples
+pnpm --filter @getrheo/rheo-skill validate:skill-format   # agentskills.io frontmatter (skills-ref)
+```
+
+`validate:skill-format` installs the official [skills-ref](https://github.com/agentskills/agentskills/tree/main/skills-ref) validator into a local `.venv-skills-ref` (gitignored) and checks `rheo/`, `rheo/rheo-best-practices/`, and `rheo/rheo-flow-import/`. Requires Python 3.11+. Set `SKILLS_REF_SKIP=1` to skip (e.g. environments without Python). The same check runs in `pnpm test` via `test/skillFormat.test.ts`.
+
+> Run `build` after any change under `src/` or to `@getrheo/contracts` /
+> `@getrheo/flow-runtime`. When rheo-skill paths change, CI runs `build` and fails if
+> `rheo-cli.mjs` or `capabilities.md` are not committed (`rheo-skill.yml`).
+
+## Manifest profile
+
+rheo-flow-import fetches the latest LLM-friendly Manifest Agent Profile from
+`https://docs.getrheo.io/docs/md/developer-guide/agent-manifest-profile`, falling
+back to `rheo/rheo-flow-import/references/manifest-agent-profile-fallback.md` offline.
+
+## Compatibility
+
+- Manifest schema version: `7`
+- Supported SDK surfaces: React Native / Expo and SwiftUI
+- Requires Node.js 20+

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@getrheo/rheo-skill",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "Source + build tooling for the self-contained `rheo` agent skill (rheo-best-practices + rheo-flow-import sub-skills).",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "dependencies": {
+    "@getrheo/contracts": "1.0.0",
+    "@getrheo/flow-runtime": "1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.1",
+    "esbuild": "^0.24.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.6.3",
+    "vitest": "^3.2.6",
+    "@rheo/config": "0.1.0"
+  },
+  "files": [
+    "README.md",
+    "rheo"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/madeinusmate/onboardly.git",
+    "directory": "packages/rheo-skill"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "gen:capabilities": "tsx src/capabilities/generateCapabilities.ts",
+    "bundle": "tsx scripts/build-skill.ts",
+    "build": "pnpm gen:capabilities && pnpm bundle",
+    "audit": "tsx src/cli.ts audit",
+    "scaffold": "tsx src/cli.ts scaffold",
+    "validate": "tsx src/cli.ts validate",
+    "normalize": "tsx src/cli.ts normalize",
+    "summary": "tsx src/cli.ts summary",
+    "validate:examples": "tsx src/cli.ts validate rheo/rheo-flow-import/examples/linear-onboarding.manifest.json && tsx src/cli.ts validate rheo/rheo-flow-import/examples/branching-onboarding.manifest.json && tsx src/cli.ts validate rheo/rheo-flow-import/examples/revenuecat-paywall.manifest.json",
+    "validate:skill-format": "node scripts/validate-skill-format.mjs"
+  }
+}

package/rheo/SKILL.md

@@ -0,0 +1,32 @@
+---
+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.
+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: "1.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.
+
+## 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) |
+
+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.
+
+## 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.
+
+## 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.
+- 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.

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

@@ -0,0 +1,46 @@
+---
+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.
+---
+
+# 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.
+
+## 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.
+
+## Workflow
+
+1. **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).
+
+## 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`.
+- **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 external surface.
+- **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.
+
+## Final response
+
+When you implement, report:
+
+- 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).
+- Whether the legacy onboarding was preserved as a fallback.
+- Verification run, or why it was skipped.

package/rheo/rheo-best-practices/examples/react-native-install-snippet.md

@@ -0,0 +1,23 @@
+# React Native / Expo Install Snippet
+
+```bash
+pnpm add @getrheo/react-native-expo
+```
+
+```tsx
+import { Flow, RheoProvider } from '@getrheo/react-native-expo';
+
+export const OnboardingHost = () => (
+  <RheoProvider
+    config={{
+      publishableKey: process.env.EXPO_PUBLIC_RHEO_PUBLISHABLE_KEY!,
+      // apiBaseUrl defaults to https://api.getrheo.io — omit in production
+      userId: 'stable-user-id',
+      sessionId: `sess_${Date.now()}`,
+      appVersion: '1.0.0',
+    }}
+  >
+    <Flow channelId={process.env.EXPO_PUBLIC_RHEO_ONBOARDING_CHANNEL_ID!} />
+  </RheoProvider>
+);
+```

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

@@ -0,0 +1,20 @@
+# SwiftUI Install Snippet
+
+```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")
+    }
+  }
+}
+```

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

@@ -0,0 +1,27 @@
+# Implementation Workflow
+
+Use this when the user explicitly asks to install or wire Rheo in a host app.
+
+## 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.
+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.
+
+## Safety
+
+- Do not hard-code secrets.
+- Do not remove legacy onboarding on the first integration unless requested.
+- 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

@@ -0,0 +1,51 @@
+# Integrations
+
+## RevenueCat
+
+Detect source calls such as `Purchases.configure`, `react-native-purchases`, `react-native-purchases-ui`, or existing paywall presentation code.
+
+Manifest mapping:
+
+- Create an external surface with `config.provider: "revenuecat"`.
+- Preserve offering or placement identifiers when visible in source.
+- Wire known outcomes:
+  - `purchase_completed`
+  - `restore_completed`
+  - `dismissed`
+  - `failed`
+- Always wire `fallback`.
+
+The host remains responsible for configuring RevenueCat. Rheo does not own purchase SDK secrets or receipt validation.
+
+## AppsFlyer
+
+Detect `react-native-appsflyer` or Swift attribution setup. Do not include AppsFlyer secrets in manifests.
+
+**React Native:** built-in provider when `react-native-appsflyer` is installed (host still initializes the SDK).
+
+**SwiftUI:** `import RheoSwiftUIAppsFlyer` and `FlowView(..., appsFlyerAttribution: .automatic)` when `AppsFlyerLib` is linked; manual `AppsFlyerAttributionProvider { observe in … }` for advanced hosts.
+
+When source branches on acquisition/deep-link data, represent stable attributes through decision nodes and add the relevant keys to `sdkAttributeKeys`.
+
+## Auth
+
+OAuth and email/password UI can be represented in Rheo manifests, but the host owns authentication logic. When implementing, wire `onOAuthLogin` and `onEmailPasswordAuth` callbacks.
+
+## Permissions
+
+Native permission prompts can map to `request_os_permission` button actions. Verify the host app has native permission declarations before relying on those steps.
+
+## In-app review
+
+- 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 (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}`.
+- Do **not** add review buttons unless the user explicitly asks—Apple discourages spamming prompts from raw button taps. Prefer post-milestone screens.
+
+## Links
+
+Use `hyperlink` layers for static external links. Preserve obvious URL destinations; do not add tracking parameters.

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

@@ -0,0 +1,36 @@
+# React Native (bare)
+
+## Detect
+
+`package.json` with `react-native` but no `expo` dependency; `android/` and `ios/` native projects.
+
+## Install
+
+```bash
+pnpm add @getrheo/react-native-bare \
+  react react-native \
+  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 react-native-in-app-review react-native-video
+```
+
+**Integrations (host only):** `react-native-appsflyer`, `react-native-purchases`, `react-native-purchases-ui` when needed.
+
+## Minimal Runtime
+
+```tsx
+import { Flow, RheoProvider } from '@getrheo/react-native-bare';
+
+export const OnboardingHost = () => (
+  <RheoProvider config={{ publishableKey: '…', userId: '…' }}>
+    <Flow channelId="ch_…" onFlowCompleted={() => {}} />
+  </RheoProvider>
+);
+```
+
+## Notes
+
+- Do **not** install `@getrheo/react-native-expo` in the same app.
+- **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

@@ -0,0 +1,49 @@
+# React Native / Expo
+
+## Detect
+
+Look for `package.json`, `app.json`, `app.config.*`, `expo-router`, `@react-navigation/*`, and existing onboarding route files.
+
+## Install
+
+```bash
+pnpm add @getrheo/react-native-expo \
+  react react-native \
+  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
+```
+
+**Integrations (host only, not SDK peers):** `react-native-appsflyer`, `react-native-purchases`, `react-native-purchases-ui` when the flow uses attribution or RevenueCat paywalls.
+
+## Minimal Runtime
+
+```tsx
+import { Flow, RheoProvider } from '@getrheo/react-native-expo';
+
+export const OnboardingHost = () => (
+  <RheoProvider
+    config={{
+      publishableKey: process.env.EXPO_PUBLIC_RHEO_PUBLISHABLE_KEY!,
+      userId: 'stable-user-id',
+      sessionId: `sess_${Date.now()}`,
+      appVersion: '1.0.0',
+    }}
+  >
+    <Flow
+      channelId={process.env.EXPO_PUBLIC_RHEO_ONBOARDING_CHANNEL_ID!}
+      onFlowCompleted={() => {}}
+      onFlowAbandoned={() => {}}
+    />
+  </RheoProvider>
+);
+```
+
+## Notes
+
+- Do **not** install `@getrheo/react-native-bare` in the same app.
+- 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.

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

@@ -0,0 +1,52 @@
+# SwiftUI
+
+## 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 external surface presenter helpers.
+- 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.

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

@@ -0,0 +1,57 @@
+# Troubleshooting
+
+## Manifest Fails Validation
+
+Run:
+
+```bash
+node scripts/validate-manifest.mjs ./rheo-import.manifest.json
+```
+
+Fix the exact issue paths. Use normalization only for safe shape repairs.
+
+## Dashboard Import Crashes With `Cannot read properties of undefined (reading 'forEach')`
+
+This usually means a container layer is missing its `children` array — most often `back_button` in `regions.header` emitted as `{ "kind": "back_button" }` without nested label content.
+
+Fix in the manifest:
+
+1. Search for `"kind": "back_button"` (and `"kind": "button"`, `"kind": "hyperlink"`).
+2. Ensure each has `"children": [ { "kind": "text", "text": { "default": "..." }, "style": { "color": "..." } } ]` (plus optional `icon` child).
+3. Re-run `validate-manifest.mjs`, then rebuild the ZIP.
+
+`normalize-manifest.mjs` does not repair missing `back_button.children`.
+
+## API Returns `invalid seeded flow manifest` With `invalid_union`
+
+Dashboard import passed asset upload but Zod rejected the manifest. Usually **dozens of issues** at repeating paths:
+
+- `regions.header.children[0]` → invalid **`back_button`** (wrong/missing `variant`, bad ids, missing `children`, nested icon not `ionicons`, or spurious `action`)
+- `regions.body.children[1]` → invalid **`single_choice`** (missing `optionBindings` / `branching` / `fieldKey`, or `"options"` instead of `children`)
+
+Fix workflow:
+
+1. Extract manifest: `unzip -p rheo-import.zip rheo-import.manifest.json > /tmp/manifest.json`
+2. Run `node scripts/validate-manifest.mjs /tmp/manifest.json` and fix **every** path.
+3. Compare failing layers to [layer-schema-pitfalls.md](layer-schema-pitfalls.md).
+4. Re-run validate until exit 0, rebuild ZIP, re-import.
+
+## Missing Fallback Edge
+
+Every external surface needs `fallback`. RevenueCat outcomes that are not explicitly mapped 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.
+
+## Wrong Environment
+
+Publishable keys and channels are environment-scoped. Do not mix test keys with live channels.
+
+## Custom Native UI
+
+If the source flow uses behavior Rheo cannot render, approximate the screen with editable layers and mention the behavior for manual review. Do not invent unsupported layer kinds.
+
+## Resolve Fallback Confusion
+
+`Flow` fallback / `FlowView` fallback is for network or resolve failure. It is not the main mechanism for representing a production legacy onboarding flow in the builder.

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

@@ -0,0 +1,68 @@
+---
+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.
+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.
+
+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).
+
+## Self-contained tooling
+
+The scripts under [scripts/](scripts) run with **plain `node`** — no `pnpm install`, no workspace. The validation/scaffold engine and the Rheo contracts are bundled into `scripts/lib/rheo-cli.mjs`.
+
+> **Run them from the target app's root, not from the skill folder.** The scripts are self-contained, so reference them by path. Pointing the audit at the skill folder only scans the skill's own examples and produces noise.
+>
+> ```bash
+> RHEO=/abs/path/to/rheo/rheo-flow-import          # this skill's rheo-flow-import directory
+> cd <target-app>                              # the app you are importing
+> node "$RHEO/scripts/audit-import.mjs" --entry app/onboarding.tsx --out rheo-import.audit.md
+> ```
+>
+> The audit anchors to the **project root inferred from `--entry`** (the nearest enclosing `package.json` / `app.json` / `Package.swift`), or to `--root <appRoot>` when you pass it. `--entry` may be a **file** (traces its import graph) or a **directory** (scans that subtree only). Repeat `--entry` for multiple entry files. It hard-errors if any entry does not exist or if the root resolves inside the skill — and prints `audit_root` / `audit_entries` / `audit_scope` / `audit_scanned_files` so you can confirm it anchored to the real app. Outputs (`--out`, `--suggest-animations`) are written relative to the current directory.
+
+| Script | Purpose |
+|--------|---------|
+| `node "$RHEO/scripts/audit-import.mjs" --entry <file\|dir> [--entry <file\|dir> ...] --out rheo-import.audit.md` | Crawl imports from entry file(s) or source subtree(s); write an evidence report. Add `--suggest-animations <path>.json` for motion. |
+| `node "$RHEO/scripts/scaffold-manifest.mjs" <flow-spec.json> [--out <path>]` | Expand a flow spec ([references/flow-spec.md](references/flow-spec.md)) into a **schema-valid** manifest skeleton (correct ids, `children`, choice bindings, branching). |
+| `node "$RHEO/scripts/validate-manifest.mjs" <manifest.json>` | Validate schema **and** dashboard publish gates. Must exit `0` before delivering. |
+| `node "$RHEO/scripts/audit-publish-manifest.mjs" <manifest.json> [--out <path>]` | Write `rheo-import.publish-gates.md` (blocking issues + fixes). |
+| `node "$RHEO/scripts/normalize-manifest.mjs" <manifest.json> [--out <path>] [--write]` | Safe legacy repairs only (legacy `button`/`hyperlink` labels) — **not** missing `back_button.children`. |
+| `node "$RHEO/scripts/print-manifest-summary.mjs" <manifest.json>` | Print non-sensitive manifest metadata. |
+| `node "$RHEO/scripts/fetch-profile.mjs" [--offline-profile]` | Report the Manifest Agent Profile source + version. |
+
+All `<manifest.json>` / `<flow-spec.json>` paths and outputs resolve from the **current directory** (your app root), so the artifacts land in the app, not the skill.
+
+## Workflow
+
+1. **Read first:** [references/import-workflow.md](references/import-workflow.md), [references/capabilities.md](references/capabilities.md), [references/layer-schema-pitfalls.md](references/layer-schema-pitfalls.md). For source-reading by stack: [references/react-native-source-patterns.md](references/react-native-source-patterns.md) or [references/swiftui-source-patterns.md](references/swiftui-source-patterns.md).
+2. **Set `$RHEO` and `cd` into the target app.** Point `$RHEO` at this skill's `rheo-flow-import` directory and run every script from the app root (see Self-contained tooling above). All scripts work from anywhere via the `$RHEO/scripts/...` path.
+3. **Profile:** fetch the latest Manifest Agent Profile (`node "$RHEO/scripts/fetch-profile.mjs"`, or the raw docs URL `/docs/md/developer-guide/agent-manifest-profile`). Record the version. Falls back to [references/manifest-agent-profile-fallback.md](references/manifest-agent-profile-fallback.md) offline.
+4. **Mandatory intake (blocking):** ask every question in the Mandatory Intake Questionnaire in [references/import-workflow.md](references/import-workflow.md) and record answers in chat. Do not skip because the repo looks obvious. If the user has not named an entry point, stop after Q1 and wait.
+5. **Audit:** run `node "$RHEO/scripts/audit-import.mjs" --entry <flow-entry> [--entry <other-entry> ...] --out rheo-import.audit.md` (add `--suggest-animations` when intake Q6 is yes). **Confirm the printed `audit_root`/`audit_entries`/`audit_scope` point at the real app** before trusting the evidence. If the audit cannot run, explain why and produce the same sections manually.
+6. **Author:** write a [flow spec](references/flow-spec.md) and run `scaffold-manifest.mjs`, then enrich theme/styles; or hand-author following [references/manifest-rules.md](references/manifest-rules.md). Apply carousel/font/localization/animation guidance from the dedicated references when the audit flags them.
+7. **Validate (blocking):** run `node "$RHEO/scripts/validate-manifest.mjs" ./rheo-import.manifest.json` (exit `0`) **and** `node "$RHEO/scripts/audit-publish-manifest.mjs" ./rheo-import.manifest.json` — fix every blocking issue ([references/publish-gates.md](references/publish-gates.md)).
+8. **Bundle:** if any traced screen references local images, Lottie JSON, video, or fonts, output `rheo-import.zip` (manifest + optional `rheo-import.assets.json` (media only) + optional `rheo-import.fonts.json` (fonts only) + files under `assets/`). Raw JSON only after an explicit asset audit finds nothing local.
+
+## Hard rules (blocking)
+
+- **Validate before zipping.** `node scripts/validate-manifest.mjs` must exit `0`. Do not discover schema errors after upload.
+- **Don't write an ad-hoc scanner** before trying `scripts/audit-import.mjs`. If it can't run, explain why and audit manually with the same sections.
+- **Layer ids:** every screen/layer/decision/surface id uses prefixes `scr_*`, `lyr_*`, `dec_*`, `surf_*`. UUID placeholders are **only** for `media.mediaAssetId` and font sidecars — never as layer ids or `optionBindings.rootLayerId`.
+- **Container `children`:** every container layer **must** include a `children` array (or `slides` for `carousel`) — never omit the key. `button`, `back_button`, and `hyperlink` are containers: label copy goes in nested `text` children (optional leading `icon`). See [references/manifest-rules.md](references/manifest-rules.md#container-layers-required-children).
+- **`back_button`:** header back chrome is `kind: "back_button"` with a required Rheo `variant` (`primary`|`secondary`|`ghost`|`destructive` — map source `outline`/`text`/`link`). **No `action`**. Nested `icon` uses `family: "ionicons"`.
+- **Choice inputs:** `single_choice`/`multiple_choice` require `fieldKey` (snake_case), `children` (≥2 option stacks), `optionBindings` (one per option, `rootLayerId` = child stack `lyr_*` id), and `branching` (`{ "enabled": false, "conditions": [] }` when no branches). Never `"options"`/`"choices"`.
+- **Styling:** when the audit reports colors, populate `manifest.theme` and layer `style` (including `style.color` on every text layer and nested button label). No black-and-white defaults when color evidence exists.
+- **Gradients:** map `LinearGradient`/gradient stops to `screen.containerStyle.backgroundFill.color` as a `linear-gradient(...)` CSS string.
+- **Carousels:** pager/carousel evidence (`infoSteps`, horizontal pager, `pagingEnabled`) → `kind: "carousel"`, one slide per page, swipe-only (no in-pager buttons). See [references/carousel-import.md](references/carousel-import.md).
+- **Fonts:** custom fonts go in `rheo-import.fonts.json` under `assets/fonts/` and `manifest.theme.fontFamily`; **never** in `rheo-import.assets.json`. See [references/font-import.md](references/font-import.md).
+- **Localization:** resolve **default-locale** strings into every `text.default` — never raw translation keys. Set `manifest.defaultLocale`. See [references/localization-import.md](references/localization-import.md).
+- **Animations:** map motion from the audit only when intake Q6 is yes and the plan includes animations ([references/animation-import.md](references/animation-import.md)); otherwise omit all `animations`, `stagger`, `restingMotion`.
+- **No secrets** in manifests.
+
+## Final response
+
+Report: manifest or ZIP path; audit report path (or why audit could not run); the recorded intake answers; Manifest Agent Profile version used (or bundled fallback); validation + publish-gate result (PASS or fixes applied); region/style/gradient/carousel/layout/font/localization/choice-state decisions from audit evidence; assets bundled (or `no local assets found`); and any unmappable native behavior the user should review in the Rheo builder. See [references/import-workflow.md](references/import-workflow.md#completion-gate) for the full completion gate.