@wireai/activation 0.1.0

package/AGENTS.md

@@ -0,0 +1,73 @@
+# AGENTS.md — wireai-onboarding (agent integration brief)
+
+> For an AI agent asked to **install / integrate / consume** this package in a host app.
+> Everything you need to wire it correctly without reading the source is here.
+> (Editing this kit's *own* source instead? Read `CLAUDE.md` — different job.)
+> Full prose + examples: `README.md` → "How to include it in an app (end-to-end)".
+
+## What it is (the goal)
+
+A **drop-in React Native onboarding kit** over the OSS `wireai-rn` SDK. One component,
+`<WireOnboarding>`, runs an entire **AI-driven, backend-orchestrated** first-run flow:
+themed native cards (chosen by an LLM, one per turn over A2A), a progress bar, a mid-flow
+value screen, per-step validation, and a completion recap — ending with the user's
+structured answers for the app to persist. The host supplies a tenant config, a theme,
+and brand artwork; the kit owns the flow. **Nearly pure JS — no reanimated, no SVG/icon
+deps.** Peers: `react`, `react-native`, `wireai-rn`, `zod`, and `react-native-safe-area-context`
+(>=4.0.0, for safe-area insets; the host must render a `SafeAreaProvider` ancestor — every
+Expo/RN app already ships it).
+
+Use it whenever someone wants "AI / dynamic / personalized onboarding" in an RN/Expo app.
+
+## Public API (import from `wireai-onboarding`)
+
+- `WireOnboarding` — the component (props below).
+- `DemoOnboarding` — dev/QA modal trigger to run the flow on demand (no account, re-runnable; place in a `__DEV__` Settings row). Props: `config` (or `null`), `theme`, `illustrations`, `label?`, `onComplete?`, `renderTrigger?`.
+- `wireConfigFromEnv({ appId })` — build `config` from `EXPO_PUBLIC_WIREAI_*` env; returns `null` if keys missing (use as your gate).
+- `themeFromBrand({ primary })` — derive a full theme from one brand color.
+- `mergeTheme`, `defaultOnboardingTheme`, `OnboardingThemeProvider`, `useOnboardingTheme`.
+- `defaultIllustrations` — dependency-free fallback art; spread your own over it.
+- Types: `OnboardingTheme`, `OnboardingResult`, `OnboardingEvent`, `WireOnboardingConfig`, `StepValidator`, `OnboardingCopy`, `IllustrationRegistry`.
+
+## `<WireOnboarding>` props
+
+| Prop | Type | Required | Notes |
+|---|---|---|---|
+| `config` | `{ apiKey, serverUrl, appId, metadata? }` | ✅ | A2A transport. `apiKey` (`wai_…`) resolves the tenant server-side; get it from the getwireai console / `register_<app>.py`. |
+| `onComplete` | `(result: { answers, raw }) => void` | ✅ | Terminal recap CTA tapped. Persist `answers` via your profile-update path, then navigate on. |
+| `theme` | `Partial<OnboardingTheme>` | – | Colors + font family names + radius/spacing, deep-merged over a neutral default. For dark/light, pass a different theme per app theme-state. |
+| `illustrations` | `Record<string, ReactNode>` | – | Host artwork for `InterstitialCard`, keyed by name. `{ ...defaultIllustrations, ...myArt }`. |
+| `validators` | `Record<string, StepValidator>` | – | Per base-question key (e.g. `username`). Blocks advance + inline error. |
+| `onSkip` | `() => void` | – | User skipped → navigate on. |
+| `onError` | `(err) => void` | – | Backend error/timeout → host recovery (e.g. static onboarding). Without it, inline retry. |
+| `onEvent` | `(e: OnboardingEvent) => void` | – | `started` / `turn` / `error` — for analytics (kit owns the loop). |
+| `copy` | `Partial<OnboardingCopy>` | – | Localize built-in English strings. |
+| `approxScreens` | `number` | – | Paces the bar; backend `progress.total` wins, so usually unneeded. |
+| `components` | `WireAIComponent[]` | – | Override registered cards (default `onboardingComponents`). |
+| `startMessage` | `string` | – | First backend message. Default `"start"`. |
+| `startTimeoutMs` | `number` | – | First-card watchdog. Default `15000`. |
+
+## Integration steps (ordered)
+
+1. **Tenant key** — create the app in the getwireai console (or run `register_<app>.py`) → `wai_…` key + server URL. Nothing renders without both.
+2. **Install** — `npm install wireai-onboarding wireai-rn` (react + react-native are peers). A tarball or `git+ssh://…` works for pre-publish/pinned builds.
+3. **Metro** — `module.exports = withWireOnboarding(getDefaultConfig(__dirname))` (from `wireai-onboarding/metro`); pins one React/RN/wireai-rn/zod copy.
+4. **Config** — set `EXPO_PUBLIC_WIREAI_API_KEY` / `_SERVER_URL` / `_APP_ID`; build via `wireConfigFromEnv({ appId })`.
+5. **Fonts** — host must load the font families named in `theme.fonts.regular/medium/bold` (e.g. `expo-font`), else text falls back to system font.
+6. **Theme** — `themeFromBrand({ primary })` or a full `Partial<OnboardingTheme>`; for dark/light, pick the theme by the app's theme state.
+7. **Render + continuation** — drop `<WireOnboarding>` into the signup flow; `onComplete` → persist + navigate, `onSkip` → navigate.
+8. **Gate** — wrap behind a flag (env for dev, remote config for prod) **AND** `config != null`; fall through to existing onboarding when off/unconfigured. Decide who sees it (e.g. new signups only) in host nav logic.
+
+## Gotchas (do not miss)
+
+- **EAS / cloud builds:** install via **git URL or registry**, never a local `file:` path *outside the app repo* — EAS won't resolve it.
+- **Single React copy:** always use the `withWireOnboarding` Metro helper (a 2nd React instance crashes RN).
+- **No native rebuild for the kit's own code** (JS + one prebuilt native peer, `react-native-safe-area-context`, that every RN/Expo app already ships). A rebuild is only needed if *your* gating mechanism is a native module (e.g. Firebase Remote Config), or if the app didn't already have safe-area-context installed.
+- **New cards:** registering a card in the kit is not enough — the backend validates emissions; add it to the server `KNOWN_COMPONENTS` + the tenant `allowed_components` (see README → "Backend coupling").
+- **Secrets:** the `apiKey` is a tenant key (safe in the bundle); never log host secrets in `onEvent`.
+
+## Fastest path
+
+Run the **`wire-rn-integration`** Claude skill — it performs all the steps above
+automatically (detect conventions → register tenant → install → Metro → theme →
+scaffold screen → wire navigation + fallback → typecheck).