@wireai/activation 0.1.0 → 0.2.0

package/AGENTS.md

@@ -1,73 +1,115 @@
-# AGENTS.md — wireai-onboarding (agent integration brief)
+# AGENTS.md: @wireai/activation (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.)
+> (Editing this kit's *own* source instead? Read `CLAUDE.md`, a 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,
+A **drop-in mobile-app 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
+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).
+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, which
+every Expo/RN app already ships).
 
-Use it whenever someone wants "AI / dynamic / personalized onboarding" in an RN/Expo app.
+Use it whenever someone wants "AI / dynamic / personalized onboarding" in a React Native / Expo app.
 
-## Public API (import from `wireai-onboarding`)
+## Subpath entry points (what you can import)
 
-- `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.
+Everything an integration needs lives on the ROOT import (`@wireai/activation`). The other
+subpaths are optional secondary feature modules; import one only if you use it.
+
+- `@wireai/activation` (root): `WireOnboarding`, the helpers/types below, and the app-event/analytics reporters.
+- `@wireai/activation/coachmarks`: in-app coachmark tour (`CoachmarkProvider`, `useCoachmarkTour`).
+- `@wireai/activation/showcase`: post-onboarding feature showcase (`FeatureShowcase`).
+- `@wireai/activation/reviews`: store-review gating (`ReviewGate`, `ReviewModal`).
+- `@wireai/activation/questionnaire`: in-app questionnaire gating (`QuestionnaireGate`).
+- `@wireai/activation/metro`: the `withWireOnboarding` Metro helper (see step 3).
+
+There is no `analytics` subpath: the app-event / analytics API is exported from the ROOT
+(see "App events / analytics" below).
+
+## Public API (import from `@wireai/activation`)
+
+- `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).
+- `isOnboardingEnabled({ remote? })`: the standard entry gate (transport present: `apiKey` + `serverUrl`, plus an optional host-passed kill switch).
+- `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`.
+- `defaultIllustrations`: dependency-free fallback art; spread your own over it.
+- Types: `OnboardingTheme`, `OnboardingResult`, `OnboardingEvent`, `WireOnboardingConfig`, `WireOnboardingProps`, `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`. |
+| `config` | `WireOnboardingConfig` | yes | A2A transport + tenant. See the `config` fields table below. |
+| `onComplete` | `(result: { answers, raw }) => void` | yes | Terminal recap CTA tapped. Persist `answers` via your profile-update path, then navigate on. |
+| `theme` | `Partial<OnboardingTheme>` | no | Colors + font family names + radius/spacing, deep-merged over a neutral default. For dark/light, pass a different theme per app theme-state. |
+| `components` | `WireAIComponent[]` | no | Override registered cards (default `onboardingComponents`). |
+| `illustrations` | `Record<string, ReactNode>` | no | Host artwork for `InterstitialCard`, keyed by name. `{ ...defaultIllustrations, ...myArt }`. |
+| `validators` | `Record<string, StepValidator>` | no | Per base-question key (e.g. `username`). Blocks advance + inline error. |
+| `onSkip` | `() => void` | no | Retained for back-compat. Per-question Skip is now internal (the kit advances one question on `skippable` screens), so this is no longer wired to that control. |
+| `onError` | `(err) => void` | no | Backend error/timeout after retries. Host recovery (e.g. static onboarding). `fallbackFlow` takes precedence over it. |
+| `onEvent` | `(e: OnboardingEvent) => void` | no | Lifecycle events for analytics (kit owns the loop). Variants: `started`, `resumed`, `turn`, `error`, `retry`, `fallback` (see `OnboardingEvent`). |
+| `copy` | `Partial<OnboardingCopy>` | no | Localize built-in English strings. |
+| `approxScreens` | `number` | no | Paces the bar; backend `progress.total` wins, so usually unneeded. |
+| `startMessage` | `string` | no | First backend message. Default `"start"`. |
+| `startTimeoutMs` | `number` | no | First-card watchdog, ms. Default `15000`. |
+| `fallbackFlow` | `ReactNode` | no | Your existing STATIC onboarding, rendered in place when the AI flow fails and retries are exhausted, so a generation/backend/timeout error degrades instead of breaking the app. Takes precedence over `onError`. |
+| `maxRetries` | `number` | no | Consecutive failures to auto-retry before degrading to `fallbackFlow`/`onError`. Default `1`. `0` degrades on the first failure. |
+| `storage` | `WireOnboardingStorage` | no | Host-injected AsyncStorage-compatible storage. When set, the kit caches its session id so an app kill mid-onboarding resumes the SAME backend session (keeps the `started` count honest). Persists the correlation seed only, never answers. |
+| `sessionTtlMs` | `number` | no | How long a persisted session id stays resumable, ms. Default `3600000` (1h). Only meaningful with `storage`. |
+| `persistKey` | `string` | no | Override the storage key (default `wireai:session:<config.appId>`). Scope it per-user if one device runs onboarding for multiple accounts. Only meaningful with `storage`. |
+| `userContext` | `Record<string, string \| number \| boolean>` | no | Host-injected, non-PII context (signup method, referral, plan tier, a hashed user id). Forwarded to the backend + client events for funnel segmentation. No raw PII. |
+| `userId` | `string` | no | The host's OPAQUE PSEUDONYMOUS user id (not an email/name/phone), so onboarding sessions reconcile to real users. Late binding supported (mount, mid-session, or post-flow via `identifyOnboarding`). Capped at 128 chars. |
+
+### `config` fields (`WireOnboardingConfig`)
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `apiKey` | `string` | yes | Tenant key (`wai_…`); resolves the app server-side. Get it from the getwireai console / `register_<app>.py`. |
+| `serverUrl` | `string` | yes | Base server URL; the kit appends `/a2a`. |
+| `appId` | `string` | yes | Passed as the A2A `model` (informational; the key resolves the app). |
+| `metadata` | `Record<string, unknown>` | no | Merged into every A2A request (e.g. install attribution). The kit reserves `sessionId` + `supportedComponents`; do not override them. |
+| `appVersion` | `string` | no | Host app version string (e.g. `"1.4.2"`); forwarded to the backend + client events so analytics can segment the funnel by app version. |
+
+## App events / analytics (root export)
+
+The app-event / analytics API is exported from the ROOT (`@wireai/activation`), NOT a subpath.
+
+- `WIRE_ONBOARDING_EVENTS` + `toAnalyticsEvent(event)`: canonical `wire_onboarding_*` funnel names; log via the app's own analytics.
+- `reportClientEvent(target, event)` / `reportClientEvents(target, events)`: report device-only funnel events. Contract: `POST {serverUrl}/v1/events`, header `Authorization: Bearer {apiKey}`, body `{ "events": [ ... ] }`. `target = { serverUrl, apiKey }` is derived from `WireOnboardingConfig`. Fire-and-forget: never throws into the UI.
+- `makeSessionId()`: a unique-per-onboarding session id (also seeds the A2A `contextId` so client and server events correlate).
+- `ClientEventType` is `"screen_skipped" | "dropped" | "client_fallback" | "identify"`. `<WireOnboarding>` auto-reports `dropped` (unmount without complete) and `client_fallback` (degrade to static). Hosts must NOT double-report fallback.
 
 ## 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.
+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/activation 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/activation/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.
+- **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").
+- **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
+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).

package/CHANGELOG.md

@@ -1,7 +1,22 @@
 # Changelog
 
-All notable changes to `wireai-onboarding`. Consumed from source (unpublished),
-so versions are informational.
+All notable changes to `@wireai/activation` (formerly `wireai-onboarding`).
+Historical entries below the rename keep the old package name on purpose.
+
+## [0.1.0] — 2026-07-12
+
+### Renamed: `wireai-onboarding` is now `@wireai/activation`
+
+- The package name changed to the scoped `@wireai/activation`. Imports change from
+  `wireai-onboarding` to `@wireai/activation`, and every subpath moves with it
+  (`wireai-onboarding/reviews` becomes `@wireai/activation/reviews`, and the same for
+  `coachmarks`, `showcase`, `questionnaire`, `analytics`, `metro`). The `exports` keys are
+  unchanged, so the subpaths themselves are identical.
+- No API change. Same components, hooks, types, and runtime behavior. The Metro helper's
+  internal source alias now maps the `@wireai/activation` specifier; consumers that call
+  `withWireOnboarding({ source })` need no code change beyond the import string.
+- Version reset to `0.1.0` to mark the start of the new package line. The GitHub repository
+  stays `chohra-med/wireai-onboarding`.
 
 ## [0.7.0] — Unreleased
 

package/INTEGRATION_PROMPT.md

@@ -1,17 +1,17 @@
-# Claude integration prompt — wireai-onboarding
+# Claude integration prompt: @wireai/activation
 
 Copy everything in the block below and paste it into Claude Code (or any coding agent) **from the
 root of your React Native / Expo app**. Fill in the two values at the top first.
 
-> Fastest path instead of this prompt: run the **`wire-rn-integration`** Claude skill — same job,
+> Fastest path instead of this prompt: run the **`wire-rn-integration`** Claude skill, the same job
 > fully automated. Use this prompt when you don't have that skill installed.
 
 ---
 
 ```
-You are integrating the `wireai-onboarding` package into THIS React Native / Expo app — a drop-in
+You are integrating the `@wireai/activation` package into THIS React Native / Expo app, a drop-in
 AI onboarding flow. Do it end to end, match my app's existing conventions, and leave it
-type-checking green. Read the package's README.md, llms.txt, and AGENTS.md (in node_modules/wireai-onboarding
+type-checking green. Read the package's README.md, llms.txt, and AGENTS.md (in node_modules/@wireai/activation
 after install) before writing code.
 
 MY VALUES:
@@ -22,11 +22,11 @@ MY VALUES:
 STEPS (do them in order, stop and ask if a convention is ambiguous):
 1. Detect my conventions: navigation lib + where the signup/first-run flow lives, my env-var
    typing, my profile-update / persistence path, my theme tokens (colors/fonts), my path aliases.
-2. Install: `wireai-onboarding` and `wireai-rn` (react + react-native are already peers). Use my
-   package manager (yarn/npm/pnpm — detect it).
+2. Install: `@wireai/activation` and `wireai-rn` (react + react-native are already peers). Use my
+   package manager (yarn/npm/pnpm, detect it).
 3. Metro: set `module.exports = withWireOnboarding(getDefaultConfig(__dirname))` from
-   `wireai-onboarding/metro` in metro.config.js (preserve my existing config). This pins one copy
-   of react/react-native/wireai-rn/zod — do NOT skip it.
+   `@wireai/activation/metro` in metro.config.js (preserve my existing config). This pins one copy
+   of react/react-native/wireai-rn/zod; do NOT skip it.
 4. Env: add EXPO_PUBLIC_WIREAI_API_KEY, EXPO_PUBLIC_WIREAI_SERVER_URL, EXPO_PUBLIC_WIREAI_APP_ID
  to my env files and my env typing.
 5. Theme: build a theme from my brand with `themeFromBrand({ primary: "<my brand color>" })` or a

package/README.md

@@ -1,4 +1,4 @@
-# wireai-onboarding
+# @wireai/activation
 
 A premium, fully-themable **drop-in onboarding kit** on top of the open-source
 [`wireai-rn`](https://github.com/chohra-med/wireai-rn) SDK. You give it a tenant
@@ -6,12 +6,12 @@ config; it runs an entire AI-driven, backend-orchestrated onboarding — themed
 cards, a progress bar, a mid-flow value screen, per-step validation, and a
 completion recap — behind one component.
 
-> MIT-licensed. Install from npm as [`wireai-onboarding`](https://www.npmjs.com/package/wireai-onboarding), or consume **from source** for live kit-edit (as the apps in this repo do).
+> MIT-licensed. Install from npm as [`@wireai/activation`](https://www.npmjs.com/package/@wireai/activation), or consume **from source** for live kit-edit (as the apps in this repo do).
 
 <div align="center">
 
-[![npm](https://img.shields.io/npm/v/wireai-onboarding.svg)](https://www.npmjs.com/package/wireai-onboarding)
-[![license](https://img.shields.io/npm/l/wireai-onboarding.svg)](LICENSE)
+[![npm](https://img.shields.io/npm/v/@wireai/activation.svg)](https://www.npmjs.com/package/@wireai/activation)
+[![license](https://img.shields.io/npm/l/@wireai/activation.svg)](LICENSE)
 
 Created by [**Malik Chohra**](https://getwireai.com?utm_source=github&utm_medium=readme&utm_campaign=creator) · [Code Meet AI newsletter](https://codemeetai.substack.com?utm_source=github&utm_medium=readme&utm_campaign=newsletter)
 
@@ -24,7 +24,7 @@ Sponsored by [AI Mobile Launcher](https://aimobilelauncher.com?utm_source=github
 | Layer | Repo / path | Role |
 |---|---|---|
 | **SDK (OSS)** | `wireai-rn` | `WireAIProvider` + `ComponentRenderer` + `useWireAIThread`; renders whatever components the host registers; A2A transport. |
-| **This kit** | `getwire_ai/wireai-onboarding` | `<WireOnboarding>` — themed cards, sparkle loader, countless stepper, `InterstitialCard` value screen, animated-checkmark completion, validators. **The single onboarding UI engine.** |
+| **This kit** | `getwire_ai/@wireai/activation` | `<WireOnboarding>` — themed cards, sparkle loader, countless stepper, `InterstitialCard` value screen, animated-checkmark completion, validators. **The single onboarding UI engine.** |
 | **Backend** | `wire-rn/examples/dynamic-onboarding/server` | Multi-tenant LangGraph engine. Per-app `product_context` + `allowed_components`; validates every emission against `KNOWN_COMPONENTS`. Live on fly dev. |
 | **Consumers** | Production B2C mobile apps | Each hosts `<WireOnboarding>` with its own theme + illustration registry. |
 
@@ -48,7 +48,7 @@ dev/prod URL). Nothing renders without these two.
 **1. Install the package** (plus its peers):
 
 ```bash
-npm install wireai-onboarding wireai-rn
+npm install @wireai/activation wireai-rn
 # react + react-native are peers (already in any RN/Expo app)
 ```
 
@@ -62,7 +62,7 @@ instance crashes RN):
 
 ```js
 const { getDefaultConfig } = require("expo/metro-config");
-const { withWireOnboarding } = require("wireai-onboarding/metro");
+const { withWireOnboarding } = require("@wireai/activation/metro");
 module.exports = withWireOnboarding(getDefaultConfig(__dirname));
 ```
 
@@ -132,24 +132,24 @@ Install the package and wire Metro with the one-call helper:
 
 ```bash
 # from npm (public)
-npm install wireai-onboarding
+npm install @wireai/activation
 # …or from a tarball (see Distribution below)
-npm install ./wireai-onboarding-0.1.3.tgz
+npm install ./@wireai/activation-0.1.3.tgz
 # …or over SSH
-npm install git+ssh://git@github.com/<org>/wireai-onboarding.git
+npm install git+ssh://git@github.com/<org>/@wireai/activation.git
 ```
 
 ```js
 // metro.config.js — replaces the hand-written ~25-line block
 const { getDefaultConfig } = require("expo/metro-config");
-const { withWireOnboarding } = require("wireai-onboarding/metro");
+const { withWireOnboarding } = require("@wireai/activation/metro");
 
 module.exports = withWireOnboarding(getDefaultConfig(__dirname));
 ```
 
 ```tsx
 // 3-line minimal usage — themed from a brand color, config from env, default art
-import { WireOnboarding, themeFromBrand, wireConfigFromEnv, defaultIllustrations } from "wireai-onboarding";
+import { WireOnboarding, themeFromBrand, wireConfigFromEnv, defaultIllustrations } from "@wireai/activation";
 
 export function Onboarding() {
   const config = wireConfigFromEnv({ appId: "my-app" }); // null if env keys missing
@@ -174,15 +174,15 @@ name: `illustrations={{ ...defaultIllustrations, ...myIllustrations }}`.
 ### 2. Source consumers (your monorepo apps)
 
 Same helper, with `source` pointed at the kit's `src/` (adds it to `watchFolders`
-and maps the `wireai-onboarding` specifier to source). Keep the tsconfig path alias.
+and maps the `@wireai/activation` specifier to source). Keep the tsconfig path alias.
 
 ```js
 const path = require("path");
 const { getDefaultConfig } = require("expo/metro-config");
-const { withWireOnboarding } = require("wireai-onboarding/metro");
+const { withWireOnboarding } = require("@wireai/activation/metro");
 
 module.exports = withWireOnboarding(getDefaultConfig(__dirname), {
-  source: path.join(__dirname, "../../getwire_ai/wireai-onboarding/src"),
+  source: path.join(__dirname, "../../getwire_ai/@wireai/activation/src"),
 });
 ```
 
@@ -191,22 +191,22 @@ module.exports = withWireOnboarding(getDefaultConfig(__dirname), {
 crashes RN), merges with any `extraNodeModules` / `watchFolders` you already set, and
 returns the same config. `options.appRoot` defaults to `process.cwd()`.
 
-> The `"react-native"` export condition resolves `wireai-onboarding` to `src/index.ts`
+> The `"react-native"` export condition resolves `@wireai/activation` to `src/index.ts`
 > for Metro (it transforms the kit's source), while `import`/`require` resolve to the
 > built `dist`. So both npm consumers and source consumers work; the dist build is additive.
 
 ## Distribution
 
 `npm run pack:tarball` runs the build (via `prepack`) and produces
-`wireai-onboarding-x.y.z.tgz` containing `dist` + `src` + `metro` + README +
-CHANGELOG. The primary channel is **npm** (`npm install wireai-onboarding`); a
-tarball (`npm install ./wireai-onboarding-x.y.z.tgz`) or a `git+ssh://…` install
+`@wireai/activation-x.y.z.tgz` containing `dist` + `src` + `metro` + README +
+CHANGELOG. The primary channel is **npm** (`npm install @wireai/activation`); a
+tarball (`npm install ./@wireai/activation-x.y.z.tgz`) or a `git+ssh://…` install
 work too for pre-publish or pinned builds.
 
 ## Quick start
 
 ```tsx
-import { WireOnboarding } from "wireai-onboarding";
+import { WireOnboarding } from "@wireai/activation";
 
 <WireOnboarding
   config={{ apiKey, serverUrl, appId: "my-app" }}
@@ -315,7 +315,7 @@ setUserId(newUser.id); // the kit fires `identify` and binds the running session
 **3. The user registers after the flow.** Capture the `contextId` from the `started` (or `resumed`) `onEvent` while onboarding runs, then call `identifyOnboarding(...)` once you have the id. Completion clears the persisted session, so the captured `contextId` is the reliable handle.
 
 ```tsx
-import { identifyOnboarding } from "wireai-onboarding";
+import { identifyOnboarding } from "@wireai/activation";
 
 const contextIdRef = useRef<string>();
 
@@ -384,7 +384,7 @@ If your app already keeps a session counter (Myelino and Morrow do), call the pl
 from your own "app opened" path and pass the counter value:
 
 ```tsx
-import { reportSessionStart } from "wireai-onboarding";
+import { reportSessionStart } from "@wireai/activation";
 
 // In your app-open effect (or wherever you bump your session counter):
 reportSessionStart({
@@ -401,7 +401,7 @@ to the foreground after at least 30 minutes in the background (a real new open,
 app-switch):
 
 ```tsx
-import { useSessionStart } from "wireai-onboarding";
+import { useSessionStart } from "@wireai/activation";
 
 useSessionStart(
   { serverUrl: config.serverUrl, apiKey: config.apiKey, appVersion },
@@ -430,7 +430,7 @@ flow in a modal, runs it once, and closes (no loop, no account, no navigation si
 effects). Put it behind `__DEV__` anywhere — a Settings row is typical:
 
 ```tsx
-import { DemoOnboarding, wireConfigFromEnv } from "wireai-onboarding";
+import { DemoOnboarding, wireConfigFromEnv } from "@wireai/activation";
 
 {__DEV__ && (
   <DemoOnboarding
@@ -488,10 +488,10 @@ server validates every emission and replaces unknown components with a safe
 
 The monorepo apps resolve the kit from source. In each app:
 
-- **`tsconfig.json`** → `"paths": { "wireai-onboarding": ["<rel>/wireai-onboarding/src/index.ts"], "wireai-onboarding/*": ["<rel>/wireai-onboarding/src/*"] }`
+- **`tsconfig.json`** → `"paths": { "@wireai/activation": ["<rel>/@wireai/activation/src/index.ts"], "@wireai/activation/*": ["<rel>/@wireai/activation/src/*"] }`
 - **`metro.config.js`** → use the `withWireOnboarding` helper with `source` (see
   [Installation → source consumers](#2-source-consumers-your-monorepo-apps)). It
-  watches the kit `src`, maps the `wireai-onboarding` specifier to it, and pins
+  watches the kit `src`, maps the `@wireai/activation` specifier to it, and pins
   `react` / `react-native` / `wireai-rn` / `zod` to the app's own `node_modules`
   (a second React instance crashes RN) — the same wiring the apps spell out by hand.
 
@@ -510,10 +510,10 @@ consuming app, since the kit has no local TS install).
 ## Coachmarks & guided tours
 
 The kit ships a performance-first guided-tour engine on a **subpath** so the main
-barrel stays dependency-free — import it from `wireai-onboarding/coachmarks`. It
+barrel stays dependency-free — import it from `@wireai/activation/coachmarks`. It
 pulls in two **optional** peers only when you use it: `react-native-reanimated`
 (UI-thread gesture + ring animation) and `expo-blur` (the frosted spotlight).
-Source consumers get it through the existing `wireai-onboarding/*` tsconfig path
+Source consumers get it through the existing `@wireai/activation/*` tsconfig path
 mapping; installed apps resolve the subpath export.
 
 The split: **the kit owns the animation/blur/ring/measure/queue**, the **app
@@ -528,7 +528,7 @@ storage adapter — gate reads must not be async or a ring flashes before the
 "already seen" check resolves. An MMKV wrapper is three lines:
 
 ```tsx
-import { CoachmarkProvider } from "wireai-onboarding/coachmarks";
+import { CoachmarkProvider } from "@wireai/activation/coachmarks";
 import { storage } from "./mmkv"; // your MMKV instance
 
 const coachmarkStorage = {
@@ -551,7 +551,7 @@ survives measurement). Pass `null` to register nothing (e.g. only the first row
 of a list):
 
 ```tsx
-import { useCoachmarkAnchor } from "wireai-onboarding/coachmarks";
+import { useCoachmarkAnchor } from "@wireai/activation/coachmarks";
 
 const groupTab = useCoachmarkAnchor("group_tab");
 <View ref={groupTab} collapsable={false}>{tabButton}</View>;
@@ -563,7 +563,7 @@ storage, so the app keeps only its own domain gates. Steps must be a memoized
 array; step callbacks are held in a ref (parent re-renders never re-fire a step):
 
 ```tsx
-import { useCoachmarkTour } from "wireai-onboarding/coachmarks";
+import { useCoachmarkTour } from "@wireai/activation/coachmarks";
 
 const steps = useMemo(
   () => [
@@ -606,7 +606,7 @@ captured intent; you pass it straight to `selectTourSteps(catalog, selection)` a
 nothing else changes — same contract, AI is a drop-in:
 
 ```ts
-import { selectTourSteps } from "wireai-onboarding/coachmarks";
+import { selectTourSteps } from "@wireai/activation/coachmarks";
 
 // catalog = your feature map; each entry has a stable `id`
 const catalog = [
@@ -625,7 +625,7 @@ duplicates ignored).
 
 ## Feature showcase (the personalized value bridge)
 
-`wireai-onboarding/showcase` wraps [`@blazejkustra/react-native-onboarding`](https://github.com/software-mansion-labs/react-native-onboarding)
+`@wireai/activation/showcase` wraps [`@blazejkustra/react-native-onboarding`](https://github.com/software-mansion-labs/react-native-onboarding)
 (the **optional** peer) as a small deck of declarative slides. You supply a
 `ShowcaseConfig`; the kit maps it to the package's API, bakes in the onboarding
 theme colors, and gates once through the same storage as the tours
@@ -640,7 +640,7 @@ Duolingo / Headspace pattern). Select them from the answers with
 `selectShowcaseSlides`:
 
 ```tsx
-import { FeatureShowcase, selectShowcaseSlides } from "wireai-onboarding/showcase";
+import { FeatureShowcase, selectShowcaseSlides } from "@wireai/activation/showcase";
 
 // The app declares the full slide catalog once (stable ids):
 const catalog = [
@@ -694,7 +694,7 @@ don't read it simply ignore it (backward-safe).
 
 ## In-app reviews (sentiment gate)
 
-`wireai-onboarding/reviews` is the drop-in in-app review flow. It asks one neutral
+`@wireai/activation/reviews` is the drop-in in-app review flow. It asks one neutral
 question, then splits honestly on the rating:
 
 - **5 stars** route to the native store review. It calls the **optional** peer
@@ -718,7 +718,7 @@ own analytics; the four moments are `review_prompt_shown`, `review_rating_select
 Feedback text goes only in the POST body.
 
 ```tsx
-import { ReviewGate, useReviewGate } from "wireai-onboarding/reviews";
+import { ReviewGate, useReviewGate } from "@wireai/activation/reviews";
 
 // The gate owns WHEN to show. v1 uses the local rules below; pass a server `decision`
 // object and it overrides them (the AI seam, see below).
@@ -806,7 +806,7 @@ Mount `WireFeaturesProvider` once near your root and every gated surface below i
 resolved flags from context (one fetch serves all modules):
 
 ```tsx
-import { WireFeaturesProvider } from "wireai-onboarding";
+import { WireFeaturesProvider } from "@wireai/activation";
 
 <WireFeaturesProvider config={{ serverUrl, apiKey, appId, storage }}>
   <App />
@@ -878,7 +878,7 @@ Then add it to your agent client's MCP config:
   "mcpServers": {
     "wireai": {
       "command": "node",
-      "args": ["<abs-path>/wireai-onboarding/mcp/dist/index.js"],
+      "args": ["<abs-path>/@wireai/activation/mcp/dist/index.js"],
       "env": {
         "WIREAI_SERVER_URL": "https://<your-backend>.fly.dev",
         "WIREAI_API_KEY": "wai_<tenant-key>",

package/dist/analytics/index.d.mts

@@ -0,0 +1,92 @@
+export { R as ReportAppEventOptions, r as reportAppEvent } from '../transport-BeO_Brcu.mjs';
+export { A as AnalyticsEvent, C as ClientEvent, a as ClientEventTarget, b as ClientEventType, c as ContextEnvelope, d as ContextEnvelopeInput, E as EnvelopeSource, e as EventQueue, f as EventQueueOptions, W as WIRE_ONBOARDING_EVENTS, g as WireOnboardingEventName, h as buildContextEnvelope, i as createEventQueue, m as makeSessionId, r as reportClientEvent, j as reportClientEvents, t as toAnalyticsEvent } from '../eventQueue-CxKi7Qd5.mjs';
+import '../types-A6pTxIZV.mjs';
+import '../types-BKfpdZzX.mjs';
+import '../types-GL_hQ0TN.mjs';
+import '../types-CMuOexw0.mjs';
+import 'react';
+import 'wireai-rn';
+import 'react-native';
+
+/** A single route inside a React-Navigation-shaped state (structural — no `@react-navigation`). */
+interface NavigationRouteLike {
+    name: string;
+    /** A nested navigator's own state, when this route hosts one. */
+    state?: NavigationStateLike;
+    /** Route params are intentionally left `unknown` — this helper never reads them. */
+    params?: unknown;
+}
+/** A React-Navigation-shaped navigator state (structural type; no library import). */
+interface NavigationStateLike {
+    /** Index of the active route within `routes`. */
+    index?: number;
+    routes?: NavigationRouteLike[];
+}
+/** Options for {@link createScreenTracker}. */
+interface ScreenTrackerOptions {
+    /**
+     * Where to POST. `{ serverUrl, apiKey }` — same shape the kit's review/analytics config
+     * exposes. When omitted, the tracker still de-dups and fires `onScreen`, but sends nothing.
+     */
+    target?: {
+        serverUrl: string;
+        apiKey: string;
+    };
+    /** The onboarding/session id to correlate screen views with, when known. */
+    sessionId?: string;
+    /** A stable, non-PII device id — groups a device's sessions server-side. */
+    deviceKey?: string;
+    /** Called on every REAL screen change (after de-dup), before the network emit. */
+    onScreen?: (screen: string) => void;
+    /**
+     * Per-screen filter. Return `false` to skip the NETWORK emit for a screen (last-screen memory
+     * is still advanced + `onScreen` still fires) — e.g. to keep a sensitive route out of analytics.
+     */
+    shouldTrack?: (screen: string) => boolean;
+}
+/** The screen tracker returned by {@link createScreenTracker}. */
+interface ScreenTracker {
+    /** Report the active screen. Ignores `undefined`/empty and de-dups repeats of the last screen. */
+    track: (screen: string | undefined) => void;
+    /** Clear the last-screen memory (e.g. on logout) so the next `track` always emits. */
+    reset: () => void;
+}
+/**
+ * Walk a React-Navigation-shaped state to the DEEPEST active route and return its NAME (never
+ * its params). Recurses `routes[index]` while a nested `.state` exists. Returns `undefined` for
+ * a missing/empty/malformed state — the caller treats that as "nothing to report".
+ */
+declare const getActiveRouteName: (state: NavigationStateLike | undefined) => string | undefined;
+/**
+ * Build a stateful screen tracker. `track` de-dups against the last reported screen so only a
+ * REAL change emits; `reset` clears that memory. Fire-and-forget throughout — a missing `target`
+ * skips the network but keeps the de-dup + `onScreen` behaviour intact.
+ */
+declare const createScreenTracker: (options?: ScreenTrackerOptions) => ScreenTracker;
+/**
+ * Adapt a tracker into a React-Navigation `onStateChange` handler — the one-place wiring:
+ *
+ *   <NavigationContainer onStateChange={screenTrackingHandler(tracker)}>
+ *
+ * It resolves the deepest active route name and hands it to `tracker.track` (which de-dups).
+ */
+declare const screenTrackingHandler: (tracker: ScreenTracker) => (state: NavigationStateLike | undefined) => void;
+
+/**
+ * The structural slice of a React-Navigation container ref this hook needs — no
+ * `@react-navigation` import. `getCurrentRoute` yields the active route; `addListener("state", …)`
+ * fires on every navigation state change and returns its own unsubscribe.
+ */
+interface NavigationRefLike {
+    getCurrentRoute?: () => {
+        name?: string;
+    } | undefined;
+    addListener?: (type: "state", callback: () => void) => () => void;
+}
+/**
+ * Subscribe screen tracking to a host navigation ref. Safe to call with a not-yet-ready ref
+ * (the effect no-ops until `addListener` exists). Returns nothing — it wires side effects only.
+ */
+declare const useScreenTracking: (navigationRef: NavigationRefLike | undefined, options?: ScreenTrackerOptions) => void;
+
+export { type NavigationRefLike, type NavigationRouteLike, type NavigationStateLike, type ScreenTracker, type ScreenTrackerOptions, createScreenTracker, getActiveRouteName, screenTrackingHandler, useScreenTracking };