@getrheo/rheo-skill 1.0.0

package/rheo/rheo-flow-import/references/layer-schema-pitfalls.md

@@ -0,0 +1,179 @@
+# Layer Schema Pitfalls
+
+Read this before writing `rheo-import.manifest.json`. Dashboard import runs full Zod validation; layers that look "close enough" often fail with `invalid_union` at paths like `regions.header.children[0]` or `regions.body.children[1]`.
+
+Run **`node scripts/validate-manifest.mjs ./rheo-import.manifest.json`** before zipping. Exit code must be **0**.
+
+## Layer IDs vs media placeholder UUIDs
+
+Two different id systems — do not mix them up.
+
+| Use case | Format | Example |
+|----------|--------|---------|
+| Screen / layer / decision ids | `scr_*`, `lyr_*`, `dec_*`, `surf_*` | `lyr_scr_gender_back` |
+| `media.mediaAssetId` in manifest | UUID placeholder | `00000000-0000-0000-0000-000000000101` |
+| `optionBindings[].rootLayerId` | **`lyr_*` layer id** (not UUID) | `lyr_scr_gender_opt_m` |
+
+**Invalid:** `"id": "00000000-0000-0000-0000-000000000101"` on a layer, `"id": "back_btn"`, `"id": "headerBack"`, random strings with punctuation.
+
+Every layer and nested child needs its own unique `lyr_*` id.
+
+## Button and back_button variants
+
+Rheo accepts **only** these `variant` values on `button` and `back_button`:
+
+`primary` | `secondary` | `ghost` | `destructive`
+
+**Invalid variants** (common from Tailwind / shadcn / Material — map them, do not copy literally):
+
+| Source / habit | Map to |
+|----------------|--------|
+| `outline`, `bordered`, `tertiary` | `secondary` or `ghost` |
+| `text`, `link`, `plain` | `ghost` |
+| `default`, `filled` | `primary` |
+| `danger`, `error` | `destructive` |
+
+`variant` is **required** on every `button` and `back_button`.
+
+## back_button (header chrome)
+
+Use in `regions.header` for back/close controls above content.
+
+**Do:**
+
+- `kind: "back_button"` (not `"button"` with a custom back action)
+- `variant` from the allowed enum above
+- `children` array with nested `icon` and/or `text`
+- Unique `lyr_*` ids on the back button and every child
+
+**Do not:**
+
+- Omit `children`
+- Add `action` (back navigation is built-in)
+- Use invalid `variant` values
+- Use non-`lyr_*` layer ids
+
+Chevron-only header control:
+
+```json
+{
+  "id": "lyr_scr_approach_back",
+  "kind": "back_button",
+  "variant": "ghost",
+  "children": [
+    {
+      "id": "lyr_scr_approach_back_icon",
+      "kind": "icon",
+      "family": "ionicons",
+      "iconName": "chevron-back-outline",
+      "style": { "width": 20, "height": 20, "color": "#0A0A0A" }
+    }
+  ]
+}
+```
+
+Icons: **`family` must be `"ionicons"`** with a valid `iconName` (e.g. `chevron-back-outline`, `close-outline`). No SF Symbols, no custom icon font names on `icon` layers.
+
+## single_choice / multiple_choice
+
+Choice inputs are **not** generic option lists. Never emit `"options": [...]`, `"choices": [...]`, `"kind": "choice"`, or `"kind": "radio"`.
+
+**Required on every choice layer:**
+
+| Field | Rule |
+|-------|------|
+| `fieldKey` | snake_case, starts with lowercase letter (`gender`, `language`, `age_range`) |
+| `children` | Array of **≥2** option `stack` layers, each with its own `lyr_*` id |
+| `optionBindings` | One entry per option: `{ "optionId": "<stable id>", "rootLayerId": "<child stack lyr_* id>" }` |
+| `branching` | Always present: `{ "enabled": false, "conditions": [] }` unless source has real branch rules |
+
+`optionBindings.length` must equal `children.length`. Every `rootLayerId` must match a direct child stack's `id`.
+
+Full minimal example:
+
+```json
+{
+  "id": "lyr_scr_gender_choice",
+  "kind": "single_choice",
+  "fieldKey": "gender",
+  "children": [
+    {
+      "id": "lyr_scr_gender_opt_m",
+      "kind": "stack",
+      "direction": "horizontal",
+      "align": "center",
+      "gap": 8,
+      "style": {
+        "border": { "width": 1, "color": "#E5E7EB" },
+        "background": "#F9FAFB",
+        "radius": 12,
+        "padding": 16
+      },
+      "selectedStyle": {
+        "border": { "width": 1, "color": "#6D5DF6" },
+        "background": "#6D5DF610"
+      },
+      "children": [
+        {
+          "id": "lyr_scr_gender_opt_m_text",
+          "kind": "text",
+          "text": { "default": "Male" },
+          "style": { "color": "#0A0A0A" }
+        }
+      ]
+    },
+    {
+      "id": "lyr_scr_gender_opt_f",
+      "kind": "stack",
+      "direction": "horizontal",
+      "align": "center",
+      "gap": 8,
+      "style": {
+        "border": { "width": 1, "color": "#E5E7EB" },
+        "background": "#F9FAFB",
+        "radius": 12,
+        "padding": 16
+      },
+      "selectedStyle": {
+        "border": { "width": 1, "color": "#6D5DF6" },
+        "background": "#6D5DF610"
+      },
+      "children": [
+        {
+          "id": "lyr_scr_gender_opt_f_text",
+          "kind": "text",
+          "text": { "default": "Female" },
+          "style": { "color": "#0A0A0A" }
+        }
+      ]
+    }
+  ],
+  "optionBindings": [
+    { "optionId": "male", "rootLayerId": "lyr_scr_gender_opt_m" },
+    { "optionId": "female", "rootLayerId": "lyr_scr_gender_opt_f" }
+  ],
+  "branching": {
+    "enabled": false,
+    "conditions": []
+  }
+}
+```
+
+## Diagnosing `invalid_union` in API logs
+
+When dashboard import returns `invalid seeded flow manifest` with `code: "invalid_union"`:
+
+| Path pattern | Inspect |
+|--------------|---------|
+| `regions.header.children[0]` | First header layer — usually `back_button`: check `variant`, `children`, `lyr_*` ids, nested `icon.family` |
+| `regions.body.children[1]` | Often `single_choice` on question screens: check `fieldKey`, `optionBindings`, `branching`, option stack ids |
+| Any `children[N]` | Open that layer object; compare to templates in this doc |
+
+Extract and validate locally:
+
+```bash
+unzip -p rheo-import.zip rheo-import.manifest.json > /tmp/rheo-import.manifest.json
+node scripts/validate-manifest.mjs /tmp/rheo-import.manifest.json
+```
+
+Fix every reported path, re-run until exit 0, then rebuild the ZIP.

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

@@ -0,0 +1,128 @@
+# Localization / i18n import
+
+When the host app uses i18n (i18next, react-intl, Lingui, i18n-js, expo-localization + JSON, etc.), Rheo import must still ship **human-readable copy**, not translation keys.
+
+## Hard rule
+
+1. Detect the app's **default / fallback locale** (e.g. `en` from `fallbackLng`, `defaultLocale`, or `locales/en.json`).
+2. Set `manifest.defaultLocale` to that locale (and include it in `manifest.locales`).
+3. For every text layer, button label, placeholder, and choice option: set `text.default` to the **resolved string in that locale**.
+4. **Never** put raw keys in `text.default` (`onboarding.welcome.title`, `COMMON_CONTINUE`, `common:button.next`).
+
+Optional: after defaults are correct, add `text.translations` for other locales from the same source JSON files.
+
+## Wrong vs right
+
+| Source (i18next) | Wrong manifest | Right manifest |
+|------------------|----------------|----------------|
+| `t('onboarding.welcome.title')` | `{ "default": "onboarding.welcome.title" }` | `{ "default": "Welcome to Rheo" }` |
+| `formatMessage({ id: 'cta.continue' })` | `{ "default": "cta.continue" }` | `{ "default": "Continue" }` |
+
+## How to resolve copy
+
+1. Run `audit-import` — check **Localization / i18n Evidence** for detected library, default locale, and sample `t("key") -> "value"` rows.
+2. Open the default locale file (`locales/en.json`, `translations/en.json`, etc.).
+3. For each key used on traced screens, walk nested JSON (`onboarding.welcome.title` → `en.onboarding.welcome.title`).
+4. If the key uses a namespace (`common:save`), load from that namespace object in the locale file.
+5. Use screenshots as a sanity check when JSON is incomplete.
+
+## TypeScript locale modules (`export const en`)
+
+Many Expo/React Native apps keep copy in `.ts` files, not JSON:
+
+```ts
+// i18n/locales/en.ts
+export const en = {
+  onboarding: { stepWelcome: { title: 'Track Your Drinks' } },
+};
+```
+
+When generating a manifest with a Node script (`tsx`, `ts-node`, etc.):
+
+1. **Use the app's i18n library** — e.g. `i18n-js` with the same `defaultLocale`, `enableFallback`, and locale objects as `LocaleContext` / `i18n/index`. Do not hand-roll a dot-path walker unless you have verified it matches nested keys and interpolation.
+2. **Resolve every `t('key')` before writing the manifest** — map each traced key through that library (or an equivalent) and put the return value in `text.default`.
+3. **Optional `text.translations`** — load `de`, `fr`, etc. from sibling locale modules and call `t` per locale for the same keys.
+
+## Script import pitfall (`tsx` + `scripts/`)
+
+If the generator lives under `scripts/` and imports locales with a **relative path** (`../i18n/locales/en.ts`), `tsx` may not expose named exports (`en`, `de`, …). You often get only:
+
+```ts
+{ default: { en: { /* locale tree */ } } }
+```
+
+Symptoms:
+
+- `import { en } from '../i18n/locales/en.ts'` → `does not provide an export named 'en'`
+- `import * as locales from '../i18n/locales/en.ts'` → `locales.en` is `undefined`; only `locales.default` exists
+- A custom `t()` then returns the **key unchanged** → manifest full of `onboarding.stepWelcome.title` strings
+
+**Fix (pick one):**
+
+```ts
+// A) Default import + unwrap (works from scripts/)
+import enModule from '../i18n/locales/en.ts';
+
+const localeFromModule = (mod: unknown, code: string) => {
+  const root = (mod as { default?: Record<string, unknown> }).default ?? mod;
+  const nested = (root as Record<string, unknown>)[code];
+  return (nested ?? root) as Record<string, unknown>;
+};
+
+const en = localeFromModule(enModule, 'en');
+```
+
+```ts
+// B) Import from repo root in a one-liner smoke test (named exports often work here)
+import { en } from './i18n/locales/en.ts';
+```
+
+```ts
+// C) Absolute file URL from repo root (stable for async generators)
+import { pathToFileURL } from 'node:url';
+import { join } from 'node:path';
+
+const mod = await import(pathToFileURL(join(ROOT, 'i18n/locales/en.ts')).href);
+const en = mod.en ?? mod.default?.en ?? mod.default;
+```
+
+**Smoke test before zipping** — must pass with zero matches:
+
+```bash
+grep -E '"default": "(onboarding|common|auth)\.' rheo-import.manifest.json
+# or search the manifest inside the zip the same way
+```
+
+Also log one known key after loading locales, e.g. `onboarding.stepWelcome.trackDrinks.title` → `Track Your Drinks`. If the log prints the key, abort generation and fix imports — do not ship the bundle.
+
+## Manifest shape
+
+```json
+{
+  "defaultLocale": "en",
+  "locales": ["en"],
+  "screens": [
+    {
+      "regions": {
+        "body": {
+          "kind": "text",
+          "text": {
+            "default": "Welcome",
+            "translations": { "fr": "Bienvenue" }
+          }
+        }
+      }
+    }
+  ]
+}
+```
+
+`default` is required and must be the default-locale string. `translations` is optional.
+
+## Intake
+
+When audit reports localization, confirm with the user which locale is the app fallback if ambiguous. Still **always** resolve strings from that locale — do not import keys because other locales exist.
+
+## Validation
+
+`validate-manifest.mjs` warns when `text.default` values look like i18n keys. Fix before zipping for dashboard import.

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

@@ -0,0 +1,74 @@
+# Rheo Manifest Agent Profile
+
+Profile version: bundled-0.1.0
+Manifest schema version: 7
+Audience: AI agents generating Rheo `FlowManifest` JSON.
+
+This bundled profile is fallback guidance. Prefer the latest raw docs profile at `/docs/md/developer-guide/agent-manifest-profile` when available.
+
+## Audit-First Import
+
+Before generating a manifest, run the bundled audit command:
+
+```bash
+node scripts/audit-import.mjs --entry app/onboarding.tsx --out rheo-import.audit.md
+```
+
+Use the audit report for header/footer, style tokens, screen backgrounds, carousels, layout, custom fonts, choice selected states, assets, Lottie, motion, and follow-up questions. If the audit cannot run, explain why and manually cover the same sections.
+
+**Mandatory intake (blocking):** Ask and record answers before generating:
+
+1. Flow entry file/route/coordinator
+2. Business purpose of the flow
+3. Visual fidelity vs editable structure
+4. Source code vs screenshots when they disagree
+5. Native-only steps vs Rheo-approximated steps
+6. Match motion from the codebase (may differ slightly from Rheo presets)? (yes/no)
+
+When intake Q6 is yes and the plan supports animations, read [animation-import.md](animation-import.md) and use `--suggest-animations rheo-import.animations.json` on the audit command.
+
+## Output Contract
+
+Generate one raw JSON `FlowManifest`, normally saved as `rheo-import.manifest.json`. When media assets are used, create `rheo-import.zip` with `rheo-import.manifest.json`, `rheo-import.assets.json`, and files under `assets/`. Asset bundling is mandatory for local images, Lottie JSON, and videos; JSON-only output is acceptable only after confirming no local assets were found. Do not include comments, Markdown, secrets, or source code.
+
+## Required Top-Level Fields
+
+`flowId`, `schemaVersion`, `version`, `defaultLocale`, `locales`, `entryScreenId`, `theme`, `screens`, `decisionNodes`, `externalSurfaceNodes`, `sdkAttributeKeys`.
+
+## IDs
+
+Screens use `scr_*`, layers use `lyr_*`, decisions use `dec_*`, and external surfaces use `surf_*`. UUID placeholders are **only** for `media.mediaAssetId` and font sidecars — never as layer ids.
+
+Before zipping, read [layer-schema-pitfalls.md](layer-schema-pitfalls.md) and run validate until exit 0.
+
+## Layer Kinds
+
+Use only: `stack`, `text`, `image`, `lottie`, `video`, `icon`, `button`, `back_button`, `progress`, `loader`, `counter`, `single_choice`, `multiple_choice`, `text_input`, `scale_input`, `oauth_provider`, `oauth_login`, `email_password_auth`, `email_password_field`, `email_password_submit`, `carousel`, `hyperlink`, `checkbox`.
+
+## Rules
+
+- Text copy goes in `text.default`.
+- Button labels are nested text layers.
+- `button` / `back_button` `variant` must be `primary`, `secondary`, `ghost`, or `destructive` (map source `outline`/`text`/`link` — do not copy). `back_button` has no `action`.
+- `single_choice` / `multiple_choice` require `fieldKey`, `children`, `optionBindings`, and `branching` — never `"options"` arrays.
+- Use `regions.header` for top chrome such as back buttons and progress, `regions.body` for main content, and `regions.footer` for sticky bottom CTAs.
+- Inspect theme/style/token files, StyleSheet, and Tailwind classes before using black-and-white defaults.
+- Set `style.color` on text for dark/saturated screen backgrounds.
+- Gradients: `screen.containerStyle.backgroundFill.color` as `linear-gradient(...)` CSS when `kind` is `color`.
+- In-screen pagers → `kind: "carousel"` with one slide per page; swipe-only; bundle every slide asset. See carousel-import.md in references.
+- Center images with parent stack `align: "center"`; map card borders/shadows to wrapping stacks.
+- Custom fonts: bundle files in `rheo-import.fonts.json` only (never `rheo-import.assets.json`), `manifest.theme.fontFamily`. See `font-import.md`.
+- Choice options: each option stack uses `style` (default) and `selectedStyle` (selected).
+- Publish gates: explicit `style.color` on all text (including button labels), Continue on manual-submit screens, valid entry/completion path. Run `scripts/audit-publish-manifest.mjs` before finishing.
+- 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 screen.
+- Non-reserved `sdk.*` decision keys must be listed in `sdkAttributeKeys`.
+- RevenueCat paywalls are external surface nodes 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.
+- Ask targeted follow-up questions when the audit finds meaningful ambiguity, such as conflicting token files or unclear gradient fidelity.
+
+## Validation
+
+Run `node scripts/validate-manifest.mjs ./rheo-import.manifest.json` before presenting the import as ready.

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

@@ -0,0 +1,197 @@
+# Manifest Rules
+
+Use the fetched Manifest Agent Profile as the current source of truth. These are stable baseline rules.
+
+## Top Level
+
+Required fields: `flowId`, `schemaVersion`, `version`, `defaultLocale`, `locales`, `entryScreenId`, `theme`, `screens`, `decisionNodes`, `externalSurfaceNodes`, `sdkAttributeKeys`.
+
+Use a placeholder UUID only when generating outside the dashboard. The dashboard import replaces `flowId` with the created flow id.
+
+## IDs
+
+- Screens: `scr_*`
+- Layers: `lyr_*`
+- Decisions: `dec_*`
+- External surfaces: `surf_*`
+
+Use readable ids, for example `scr_welcome`, `lyr_welcome_title`, `surf_paywall`.
+
+**UUID placeholders** (`00000000-0000-0000-0000-000000000101`) are **only** for `media.mediaAssetId` in the manifest and font entries in `rheo-import.fonts.json`. Never use UUIDs as layer ids or as `optionBindings[].rootLayerId`.
+
+See [layer-schema-pitfalls.md](layer-schema-pitfalls.md) for common id mistakes that cause `invalid_union` validation failures.
+
+## Layer Kinds
+
+Allowed kinds: `stack`, `text`, `image`, `lottie`, `video`, `icon`, `button`, `back_button`, `progress`, `loader`, `counter`, `single_choice`, `multiple_choice`, `text_input`, `scale_input`, `oauth_provider`, `oauth_login`, `email_password_auth`, `email_password_field`, `email_password_submit`, `carousel`, `hyperlink`, `checkbox`.
+
+## Regions
+
+Screens support `regions.header`, required `regions.body`, and optional `regions.footer`.
+
+- Use `header` for top chrome: back buttons, close buttons, title chrome, step indicators, and progress bars.
+- Use `body` for main content and scrollable content.
+- Use `footer` for sticky bottom CTAs and legal/checklist rows that sit below content.
+- Use `back_button` and `progress` layers instead of rebuilding obvious navigation chrome as generic text/buttons.
+
+## Style Tokens
+
+Before generating a plain black-and-white manifest, inspect the repo for tokens:
+
+- Tailwind/NativeWind config and global CSS.
+- theme files and design-token JSON/TS files.
+- shared `Button`, `Text`, `Typography`, `Screen`, `Header`, and `Footer` primitives.
+- React Native `StyleSheet.create` constants.
+- SwiftUI `Color`, `Font`, and modifier extensions.
+
+Map clear brand values into `manifest.theme` and layer styles. Set `style.color` on text for dark/saturated screen backgrounds.
+
+## Screen Backgrounds And Gradients
+
+- Use `screen.containerStyle.backgroundFill` for per-screen fills.
+- Gradients: `{ "kind": "color", "color": "linear-gradient(180deg, #hex1 0%, #hex2 100%)" }`.
+- Shared shell gradients apply to all default screens unless a screen overrides with a solid color.
+
+## Carousels
+
+- In-screen pagers (`infoSteps`, horizontal pager, dot indicators) → `kind: "carousel"` with one slide stack per page.
+- Do not collapse multi-slide routes to one static screen.
+- `pageControl` is optional dot chrome only. Carousels are swipe-only (no pager buttons).
+- Do not duplicate paging with `regions.footer` Continue when the source footer only increments pager index. See [carousel-import.md](carousel-import.md).
+
+## Layout
+
+- Center images: parent stack `align: "center"`.
+- Card chrome: wrapping stacks with `border`, `shadow`, `background`, `radius`, `padding`.
+
+## Explicit Sizing
+
+Set `style.width` and `style.height` on every layer — do not omit them. `width` accepts `"full"`, `"auto"`, a fraction (`"1/2"`, `"1/3"`, `"2/3"`, `"1/4"`, `"3/4"`), or a pixel number; `height` accepts `"fill"`, `"auto"`, or a pixel number. Use these per-kind defaults unless the design requires otherwise:
+
+| Layer kinds | `width` | `height` |
+|-------------|---------|----------|
+| `stack`, `text_input`, `scale_input`, `oauth_login`, `email_password_auth`, `email_password_field`, `progress`, `loader` | `"full"` | `"fill"` |
+| `button`, `back_button`, `oauth_provider`, `email_password_submit`, `checkbox`, `single_choice`, `multiple_choice` | `"full"` | `"auto"` |
+| `text`, `counter`, `icon`, `hyperlink` | `"auto"` | `"auto"` |
+| `image`, `lottie`, `video` | `"full"` | number (e.g. `160`) |
+| `carousel` | — (no outer `style` sizing) | — |
+
+Dashboard import backfills these defaults automatically, but emitting them explicitly produces higher-fidelity first drafts.
+
+## Container Layers (Required `children`)
+
+Container layers **must always include a `children` array** (use `[]` only when the schema allows an empty container — never omit the key). Omitting `children` produces JSON that may parse but **crashes dashboard import** when motion is stripped (Indie plan) and fails schema validation.
+
+| Layer kind | Required child field | Label / content rule |
+|------------|---------------------|----------------------|
+| `stack` | `children: []` minimum | Nested layers |
+| `button` | `children` | **Required** nested `text` for the label (optional leading `icon`) |
+| `back_button` | `children` | **Required** nested `text` and/or `icon` — never emit header back chrome without `children` |
+| `hyperlink` | `children` | **Required** nested `text` for link copy |
+| `carousel` | `slides` | One stack per slide |
+| `single_choice` / `multiple_choice` | `children` | One option `stack` per choice |
+| `oauth_login` | `children` | Provider rows / chrome |
+| `email_password_auth` / `email_password_submit` | `children` | Field rows and submit label |
+| `oauth_provider` (`variant: "custom"`) | `children` | Custom provider row content |
+
+### Anti-pattern (invalid — do not emit)
+
+```json
+{
+  "id": "lyr_header_back",
+  "kind": "back_button",
+  "variant": "ghost"
+}
+```
+
+### Valid `back_button` (header chrome)
+
+```json
+{
+  "id": "lyr_header_back",
+  "kind": "back_button",
+  "variant": "ghost",
+  "children": [
+    {
+      "id": "lyr_header_back_label",
+      "kind": "text",
+      "text": { "default": "Back" },
+      "style": { "color": "#0A0A0A" }
+    }
+  ]
+}
+```
+
+When source uses a chevron-only back control, still nest an `icon` child (and optional empty/minimal `text` if needed for hit area — prefer visible `icon` + `text` when source shows a label).
+
+`scripts/normalize-manifest.mjs` repairs legacy `button.label` and `hyperlink.text` shapes only — it does **not** invent missing `back_button.children`. Fix those in the manifest before validation.
+
+## Text And Buttons
+
+- Text uses `text: { "default": "..." }`.
+- Do not use `label` on text layers or top-level `label` on `button` layers (use `children` instead).
+- Button labels are nested text children — same for `back_button` and `hyperlink`.
+- **`button` and `back_button` `variant`** must be one of: `primary`, `secondary`, `ghost`, `destructive`. Map source design-system names (`outline`, `text`, `link`, `default`) — do not copy them literally.
+- **`back_button`** has no `action` field; navigation is built-in. Use in `regions.header` for back/close chrome.
+- Prefer `continue`, `skip`, and `end_flow` actions for imported first drafts (on `button` only).
+- **`request_app_review`** is allowed for human/explicit requests only (not default imports): empty action object, requires `screen.next.default`, single CTA after a positive moment.
+
+## Custom Fonts
+
+- When source loads custom fonts (`Font.loadAsync`, `useFonts`, bundled `.ttf`/`.otf`), copy files into `assets/fonts/` and add `rheo-import.fonts.json` ([font-import.md](font-import.md)).
+- Set `manifest.theme.fontFamily` to the primary family name string used in source.
+- Each font style needs a stable placeholder UUID in `rheo-import.fonts.json`; dashboard import uploads files and merges families into app branding.
+- **Never** list font files in `rheo-import.assets.json` — fonts are not `media.mediaAssetId` assets and must not use image MIME types.
+
+## Choice Inputs (single_choice / multiple_choice)
+
+Each choice layer is a **structured input**, not a flat options list. Required fields: `fieldKey`, `children`, `optionBindings`, `branching`.
+
+- Each selectable option is a child **`stack`** on the input layer with its own `lyr_*` id.
+- **`optionBindings`**: one `{ optionId, rootLayerId }` per option; `rootLayerId` must equal the matching child stack's `id`.
+- **`branching`**: always include `{ "enabled": false, "conditions": [] }` unless the source has real per-option navigation.
+- **`fieldKey`**: snake_case (`gender`, `language`, `age_range`) — not PascalCase or camelCase.
+- Never emit `"options"`, `"choices"`, `"kind": "choice"`, or `"kind": "radio"`.
+- Map unselected chrome to `style` and selected chrome to `selectedStyle` on the same stack (border, background, padding, radius).
+- Do not import choice screens with only default styling when source uses selected/unselected ternaries.
+
+Full template: [layer-schema-pitfalls.md](layer-schema-pitfalls.md#single_choice--multiple_choice).
+
+## Inputs
+
+- Use at most one input layer kind per screen.
+- Use stable snake_case `fieldKey` values.
+- Mark text input classification as `safe` or `sensitive`.
+
+## Decisions
+
+- Use decisions for real source-code branches.
+- Non-reserved `sdk.*` keys used in decisions must be listed in `sdkAttributeKeys`.
+- Prefer source semantics over visual guessing.
+
+## External Surfaces
+
+- RevenueCat paywalls become `externalSurfaceNodes` with provider `revenuecat`.
+- Every external surface needs a `fallback`.
+- Map known paywall outcomes to `purchase_completed`, `restore_completed`, `dismissed`, and `failed`.
+
+## Assets
+
+For local images, Lottie JSON, or videos, use valid placeholder UUIDs in `media.mediaAssetId`, then include those files in `rheo-import.zip` with `rheo-import.assets.json`. Do not put file paths directly in `mediaAssetId`. Font binaries belong only in `rheo-import.fonts.json`.
+
+## Localization (i18n)
+
+When source screens use i18n ([localization-import.md](localization-import.md)):
+
+- Set `defaultLocale` and `locales` to match the app fallback (usually `en`).
+- Every `text.default` must be the **resolved default-locale string**, not a translation key.
+- Optional `text.translations` for other locales after defaults are correct.
+
+## Publish Readiness
+
+- `entryScreenId` must point to an existing screen, decision, or external surface.
+- The served graph should have a completion path.
+- Avoid orphaned screens unless intentionally parked for later editing.
+- Run `scripts/audit-publish-manifest.mjs` before finishing — it enforces dashboard **Publish** rules (see [publish-gates.md](publish-gates.md)).
+- Every `text` and `icon` layer needs explicit `style.color` (including nested button label text).
+- Screens with `text_input`, `multiple_choice`, or `scale_input` need a `continue` button.

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

@@ -0,0 +1,91 @@
+# Publish Gates (import completion)
+
+After generating `rheo-import.manifest.json`, run the **publish gate audit** so the manifest matches what the Rheo dashboard **Publish** button enforces. Goal: one-click import and publish with zero blockers.
+
+```bash
+node scripts/audit-publish-manifest.mjs ./rheo-import.manifest.json
+```
+
+`validate-manifest.mjs` now includes the same blocking rules (not only Zod schema).
+
+## What the audit checks
+
+These mirror `apps/web/src/features/builder/validateFlow.ts` and API `preflightPublishManifest` + integration/canvas/plan gates.
+
+### Schema (Zod)
+
+- Valid `FlowManifest` shape, ids, layer kinds, required fields.
+
+### Builder rules (`collectFlowBuilderIssues`)
+
+| Rule | Typical agent mistake |
+|------|------------------------|
+| **Layer ids** | UUIDs or non-`lyr_*` strings used as layer ids or `optionBindings.rootLayerId` (UUIDs are for `mediaAssetId` only). |
+| **Button `variant`** | Source names copied literally (`outline`, `text`, `link`, `default`) instead of Rheo enum (`primary`/`secondary`/`ghost`/`destructive`). |
+| **`back_button` shape** | Missing `variant`, invalid variant, `action` field present, or nested `icon` without `family: "ionicons"`. |
+| **Choice input shape** | `single_choice` / `multiple_choice` missing `optionBindings` or `branching`, using `"options"` instead of `children`, or `fieldKey` not snake_case. |
+| **Container `children`** | `back_button`, `button`, or `hyperlink` emitted without a `children` array (or with label text on the parent instead of nested `text` children). Crashes import on Indie plans during motion strip; fails Zod validation. |
+| **Text/icon `style.color`** | Body text or **button label** (nested text child) left without `style.color` — native does not inherit CSS colors. |
+| **Continue button** | `text_input`, `multiple_choice`, or `scale_input` without a `button` with `action.kind: "continue"`. |
+| **One input per screen** | Multiple inputs, or OAuth/email-password combined with inputs. |
+| **fieldKey** | Missing or non–snake_case on input layers. |
+| **Graph targets** | `go_to_step`, choice `goTo`, permission outcomes, fallbacks point at missing ids. |
+| **Media triggers** | Lottie/video with `autoPlay: false` needs a `play_media` button targeting that layer. |
+| **Screen backgrounds** | Image/video fills need `mediaAssetId`; manual background video needs trigger wiring. |
+
+### Publishable graph (`validatePublishable`)
+
+- At least one screen.
+- `entryScreenId` set and valid.
+- A **completion path** from entry (`end_flow`, terminal `next`, or external surface end).
+- Decision nodes: every case and `elseNext` connected.
+
+### Integrations (default: enabled)
+
+- External surfaces need `config.provider` (not `unspecified`).
+- Every external surface needs `fallback`.
+- RevenueCat surfaces require RevenueCat integration enabled (import assumes enabled).
+
+### Canvas editor gates (default: all enabled)
+
+Import audit assumes all capabilities are on. If the target app disables Lottie, OAuth, email/password, or OS permission buttons, remove those layers or enable the gate in App settings.
+
+**`request_app_review`** is not canvas-gated. When used, ensure the screen has **`next.default`** wired to a valid target.
+
+### Branding gradients
+
+- `$brandGradient:<uuid>` only on background-like fields.
+- Unknown preset ids when branding is known.
+
+## Required styling pattern (buttons)
+
+Primary CTA example — **label text must have explicit color**:
+
+```json
+{
+  "kind": "button",
+  "variant": "primary",
+  "action": { "kind": "continue" },
+  "children": [
+    {
+      "kind": "text",
+      "text": { "default": "Continue" },
+      "style": { "color": "#FFFFFF" }
+    }
+  ]
+}
+```
+
+Body copy on light backgrounds: `"style": { "color": "#0A0A0A" }` or map from `manifest.theme.foreground`.
+
+On dark or saturated screen fills, use `#FFFFFF` or `theme.primaryForeground` on text layers.
+
+## Completion gate (blocking)
+
+Before delivering the import:
+
+- [ ] `node scripts/validate-manifest.mjs` exits 0
+- [ ] `node scripts/audit-publish-manifest.mjs` exits 0 and `rheo-import.publish-gates.md` shows **PASS**
+- [ ] Every blocking issue has been fixed in the manifest (not only explained in chat)
+
+If publish gate audit fails, fix the manifest and re-run until PASS. Do not skip because a weaker model missed button label colors.