@wireai/activation 0.14.3 → 0.16.0

package/INTEGRATION_PROMPT.md

@@ -3,12 +3,9 @@
 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, the same job
-> fully automated. Use this prompt when you don't have that skill installed.
-
 ---
 
-```
+```text
 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/activation
@@ -16,14 +13,20 @@ after install) before writing code.
 
 MY VALUES:
 - WIREAI_SERVER_URL: <paste the backend URL, e.g. https://...fly.dev>
-- WIREAI_API_KEY:    <paste the wai_… app key from the getwireai console / register_<app>.py>
+- WIREAI_API_KEY:    <paste the wai_… app key from your app's Integrate tab in the console:
+                     sign up at https://getwireai.com/signup (app name + email, then
+                     confirm by email and set a password: that step is what creates the app
+                     and its key), then copy the key from
+                     https://getwireai.com/console/<app-id>/integrate. The server URL is the
+                     serverUrl line of the init snippet on that same tab, NOT the "Server
+                     URL" in that tab's Add MCP dialog, which is a different host>
 - APP_ID:           <paste my app id, e.g. my-app>
 
 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/activation` and `wireai-rn` (react + react-native are already peers). Use my
-   package manager (yarn/npm/pnpm, detect it).
+2. Install: `npm install @wireai/activation wireai-rn zod react-native-safe-area-context` (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/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.
@@ -31,9 +34,11 @@ STEPS (do them in order, stop and ask if a convention is ambiguous):
  to my env files and my env typing.
 5. Theme: build a theme from my brand with `themeFromBrand({ primary: "<my brand color>" })` or a
    Partial<OnboardingTheme>; match my dark/light.
-6. Screen: scaffold an onboarding screen that renders
-   `<WireOnboarding config={wireConfigFromEnv({ appId: APP_ID })} theme={...} illustrations={...}
-     onComplete={persist} fallbackFlow={<MyExistingStaticOnboarding/>} onEvent={logEvent} />`.
+6. Screen: scaffold an onboarding screen. Build the config ONCE and gate on it first, because
+   `wireConfigFromEnv` returns `null` when the env is unset while `config` is a required non-null
+   prop: `const config = wireConfigFromEnv({ appId: APP_ID }); if (!config) return <MyExistingStaticOnboarding/>;`
+   Then render
+   `<WireOnboarding config={config} theme={...} illustrations={...} onComplete={persist} fallbackFlow={<MyExistingStaticOnboarding/>} onEvent={logEvent} />`.
    - Gate entry with `isOnboardingEnabled({ remote })` (wire my remote-config boolean if I have one).
    - `persist`: write ALL of `result.answers` (use `deriveAnswers(result.raw)` to fill gaps) through
      my normal profile-update path. Do NOT re-ask anything a dedicated screen already owns.
@@ -48,9 +53,17 @@ STEPS (do them in order, stop and ask if a convention is ambiguous):
    - Analytics: log via `toAnalyticsEvent(e)` → my logger, using the canonical `wire_onboarding_*` names.
 7. Navigation: mount the screen in my first-run/signup flow; branch to the static flow when the gate
    is off or config is missing.
-8. Lifecycle (do NOT skip): mount `useLifecycleEvents(config, { deviceKey, sessionCount, userId })`
-   ONCE at my app root, above the navigator, before anything else touches analytics. Pass
-   `config.storage`. It is the only path that emits `app.first_open`, it registers the per-open
+8. Lifecycle (do NOT skip): mount
+   `useLifecycleEvents({ serverUrl, apiKey, appId, storage }, { deviceKey, sessionCount, userId })`
+   ONCE at my app root, above the navigator, before anything else touches analytics.
+   `sessionCount` is MINE to own: a counter I persist and increment once per app open, starting at
+   1 on the very first launch. Hardcoding `1` compiles, ships, and pins every user at `returning:
+   false` forever with nothing reporting an error. If I have no such counter yet, create one
+   (read, increment, write) in the same storage I pass above, or say so instead of inventing a
+   constant. That first
+   argument is a `LifecycleConfig` built from explicit fields, NOT the config from step 6:
+   `wireConfigFromEnv` can return `null`, and `storage` is not a field of `WireOnboardingConfig`.
+   It is the only path that emits `app.first_open`, it registers the per-open
    session id every other surface correlates to, and with storage it stamps the kit's persisted auto
    `device_key` on `app.session_started`, which is what the server counts `min_sessions` from. If my
    storage adapter throws or rejects, the kit treats it as no storage and stamps no auto key at all
@@ -62,11 +75,26 @@ STEPS (do them in order, stop and ask if a convention is ambiguous):
    `journal_done`. On my home/gate screen call
    `const { track, sessionId, revalidation } = useWireActivation({ serverUrl: WIREAI_SERVER_URL, apiKey: WIREAI_API_KEY, appId: APP_ID, deviceKey })`
    from `@wireai/activation`, fetch the gate decision in a `useEffect` keyed on `[revalidation]`
-   (`fetchReviewDecision({ serverUrl, apiKey }, { sessionId, deviceKey })` → set it into
-   `useReviewGate({ config, decision })`; questionnaires use `fetchQuestionnaireDecision` +
-   `useQuestionnaireGate` the same way), and at the action site call `await track("journal_done")`.
-   Do NOT hand-roll the session id or the POST; `wire.track` owns both and revalidates the gate on
-   a successful 2xx.
+   (`fetchReviewDecision({ serverUrl, apiKey }, { sessionId, deviceKey })`), and at the action site
+   call `await track("journal_done")`. Do NOT hand-roll the session id or the POST; `wire.track`
+   owns both and revalidates the gate on a successful 2xx. Questionnaires use
+   `fetchQuestionnaireDecision` + `useQuestionnaireGate` the same way, with the same three rules:
+   - THE GATE NEEDS SYNCHRONOUS STORAGE. Pass `storage` to the hook (or mount `CoachmarkProvider`
+     with one above it) as a `CoachmarkStorage`, whose `getItem(key)` returns `string | null` and
+     NOT a Promise. This is a different shape from `<WireOnboarding storage>`, which takes the
+     AsyncStorage-style adapter. Without it the app-open counter is pinned at 1 forever, the
+     fail-closed `minSessions` default of 2 can never be met, and the gate silently never fires;
+     an ASYNC adapter is detected and substituted with a fail-closed store, same outcome. Use my
+     app's existing synchronous store (MMKV or similar). If I have none, say so.
+   - THE HOOK'S `config` IS THE GATE'S CONFIG, not the kit transport config from step 6: it needs
+     an `id`. Write `useReviewGate({ config: { id: "post_win" }, decision: served ?? undefined, storage: gateStorage })`.
+     The `?? undefined` is not optional either: the fetch resolves `ReviewDecisionResponse | null`
+     and the option is `decision?: ReviewDecision`, so the raw result does not type-check.
+   - WIRE THE COMPONENT, not just the hook. `<ReviewGate>` has no `gate` prop. Render it when
+     `gate.visible` and pass `onShown={gate.markShown}` and `onResolved={gate.markResolved}`.
+     Those two write the cooldown timestamp and the once-per-version seen gate; leave them out and
+     it compiles, shows, and re-prompts the same user on every open. The full wiring example is the
+     "Wiring `<ReviewGate>`" block in AGENTS.md.
 10. RevenueCat (only if my app sells subscriptions through `react-native-purchases`): wire my paywall
    to the same event stream with `createRevenueCatBridge({ analytics, entitlementId: "<my
    entitlement, e.g. pro>" })` from `@wireai/activation`. Do NOT add or import
@@ -75,17 +103,27 @@ STEPS (do them in order, stop and ask if a convention is ambiguous):
    hand-rolled paywall analytics calls with `paywallShown` / `checkoutStarted` / `purchaseCompleted`
    / `purchaseFailed` / `purchasesRestored`, and call `syncPlanTier(customerInfo)` once at launch.
    THE JOIN KEY: pass the SAME device key to the analytics instance AND to onboarding via
-   `<WireOnboarding userContext={activationJoinContext(deviceKey)} />`, because purchases join to
+   `<WireOnboarding userContext={activationJoinContext(deviceKey)} ... />`, because purchases join to
    onboarding on `user_context.device_key` and never on `session_id` (those are separate id spaces
    and intersecting them returns zero rows). If my app has no single stable device key yet, say so
    instead of inventing one.
 11. Verify: type-check (and lint the changed files); test the flag-off + backend-error paths. Then
    prove the events wiring actually works, because `/v1/events` answers 200 for a batch it discards:
    behind an `if (__DEV__)` guard, call
-   `wireDoctor({ target: { serverUrl: WIREAI_SERVER_URL, apiKey: WIREAI_API_KEY }, storage })` from
-   `@wireai/activation/analytics` once at app root and log the report. Every check must come back
-   `ok`. A failing `round_trip` names the field the server refused. Remove the call, or leave it
-   dev-gated, once the report is green.
+   `wireDoctor({ target: { serverUrl: WIREAI_SERVER_URL, apiKey: WIREAI_API_KEY }, storage, join: {
+   appId: WIREAI_APP_ID, userContext } })` from `@wireai/activation/analytics` once at app root and
+   log the report. Every check must come back `ok`. A failing `round_trip` names the field the
+   server refused. Remove the call, or leave it dev-gated, once the report is green.
+   PASS `join`. Without it the `join_key` check reports NOT EVALUATED and fails the report on
+   purpose: a report that never looked at the join has not earned a green.
+   READ THE SCOPE OF THAT GREEN. `wireDoctor` runs five checks: `target` (the shape of the url +
+   key), `reachability`, `storage` (writability), `round_trip` (one probe event the server
+   acknowledges as written), and `join_key` (this session will carry a `user_context.device_key`,
+   yours or the kit's auto-injected one, step 7). It still does NOT check that the lifecycle hook
+   is mounted, and it does NOT check `min_sessions`. So an integration that skipped step 8's
+   lifecycle mount passes every check green while its `activated` funnel stays permanently at zero.
+   A green doctor means "events reach the server and can be joined"; it does not mean "the funnel
+   works". Verify step 8 by reading the code, not by reading the report.
 
 Report back: the files you changed (path:line), the typecheck result, and anything you couldn't
 infer about my conventions.

package/README.md

@@ -41,20 +41,53 @@ library? Pass your own nodes through the `icons` prop.
 
 ## How to include it in an app (end-to-end)
 
-> Fastest path: run the **`wire-rn-integration`** Claude skill — it does all of the
-> steps below automatically (detects your conventions, wires Metro, derives a theme,
-> scaffolds the screen, type-checks). The manual steps, in order:
+> Fastest path: paste [`INTEGRATION_PROMPT.md`](./INTEGRATION_PROMPT.md) into your coding
+> agent — it ships in this package and does all of the steps below automatically (detects
+> your conventions, wires Metro, derives a theme, scaffolds the screen, type-checks). The
+> manual steps, in order:
 
-**0. Register the app on the backend → get a tenant key.** The kit talks to the
+**0. Get your `apiKey` and `serverUrl` from the console.** The kit talks to the
 multi-tenant backend over A2A; the **`apiKey` is per-app and resolves the tenant
-server-side**. Create the app in the getwireai **console** (or run the backend's
-`register_<app>.py`) → it mints a `wai_…` key. Note the **server URL** (e.g. the fly
-dev/prod URL). Nothing renders without these two.
+server-side**. Nothing renders without both values. Two stops in the browser with an
+email round trip between them:
+
+1. **Create an account** → **<https://getwireai.com/signup>**. You give your app's name
+   and an email; the confirmation link is where you choose a password. That one step
+   creates the account, your **first app** and its `wai_…` key, and lands you inside the
+   console already signed in.
+2. **Copy both values** from that app's **Integrate** tab
+   (`https://getwireai.com/console/<your-app-id>/integrate`). The **API key** is a copy
+   field; the **server URL** is the `serverUrl` line of the ready-made init snippet on
+   that same tab. The key stays readable there on every visit, so there is nothing to
+   catch as it goes past.
+
+> ⚠️ **Two different things are called "Server URL" in that console.** The one you want is
+> the `serverUrl` in the init snippet. The **Add MCP** dialog on the same tab also shows a
+> copy field labelled "Server URL", and that is the **MCP endpoint on a different host** —
+> it is for pointing an AI client at your account, and it is *not* a valid
+> `EXPO_PUBLIC_WIREAI_SERVER_URL`.
+
+Later: sign back in at **<https://getwireai.com/login>**, and register a second app at
+**<https://getwireai.com/console/register>** if you need one — signup already made the
+first.
+
+> **Keys are per environment.** A key's label *is* its environment (`dev` / `prod` /
+> `staging` / custom), so use a different key in dev than in production and your analytics
+> split by that label. The **Keys and environments** section of the same **Integrate** tab
+> lists your keys and can **revoke** one. Issuing a new key is **not self-serve yet**, so
+> ask for an extra environment via the console's **Support** section.
+
+> ⚠️ **The `apiKey` is a tenant key, not a login.** It resolves your app server-side and is
+> *expected to ship inside your app bundle* — the documented path below puts it in
+> `EXPO_PUBLIC_WIREAI_API_KEY`, which Metro inlines at build time. It cannot authenticate a
+> console session; an app key presented on a console route is refused. Do still read it from
+> an env var rather than a committed literal, so a build can point at a different
+> environment's key without a code change.
 
 **1. Install the package** (plus its peers):
 
 ```bash
-npm install @wireai/activation wireai-rn
+npm install @wireai/activation wireai-rn zod react-native-safe-area-context
 # react + react-native are peers (already in any RN/Expo app)
 ```
 
@@ -74,7 +107,7 @@ module.exports = withWireOnboarding(getDefaultConfig(__dirname));
 
 **3. Config from env** (so you can flip backends without a code change):
 
-```
+```env
 EXPO_PUBLIC_WIREAI_API_KEY=wai_…
 EXPO_PUBLIC_WIREAI_SERVER_URL=https://…
 EXPO_PUBLIC_WIREAI_APP_ID=my-app
@@ -107,6 +140,8 @@ just navigate onward:
   theme={theme}
   illustrations={{ ...defaultIllustrations, ...myIllustrations }}
   validators={{ username: checkUsernameAvailable }}
+  storage={storage}
+  fallbackFlow={<MyExistingStaticOnboarding />}
   onComplete={(r) => { persist(r.answers); goNext(); }}
   onSkip={goNext}
   onError={fallBackToStaticOnboarding}
@@ -138,11 +173,11 @@ Install the package and wire Metro with the one-call helper:
 
 ```bash
 # from npm (public)
-npm install @wireai/activation
-# …or from a tarball (see Distribution below)
-npm install ./@wireai/activation-0.1.3.tgz
-# …or over SSH
-npm install git+ssh://git@github.com/<org>/@wireai/activation.git
+npm install @wireai/activation wireai-rn zod react-native-safe-area-context
+# …or, for a pre-publish or pinned build only (see Distribution below):
+#   `x.y.z` is a placeholder — use the version `npm run pack:tarball` actually produced.
+npm install ./wireai-activation-x.y.z.tgz
+npm install git+ssh://git@github.com/<org>/<repo>.git
 ```
 
 ```js
@@ -154,7 +189,9 @@ module.exports = withWireOnboarding(getDefaultConfig(__dirname));
 ```
 
 ```tsx
-// 3-line minimal usage — themed from a brand color, config from env, default art
+// Minimal usage. "Minimal" still carries `fallbackFlow` and a join key, because omitting
+// either fails SILENTLY: no fallback dead-ends the user on a backend error, and no join key
+// leaves the `activated` funnel reading zero forever with no error anywhere.
 import { WireOnboarding, themeFromBrand, wireConfigFromEnv, defaultIllustrations } from "@wireai/activation";
 
 export function Onboarding() {
@@ -165,7 +202,10 @@ export function Onboarding() {
       config={config}
       theme={themeFromBrand({ primary: "#15B0B0" })}
       illustrations={defaultIllustrations}
+      storage={storage}
+      fallbackFlow={<MyExistingStaticOnboarding />}
       onComplete={(r) => persist(r.answers)}
+      onSkip={goNext}
     />
   );
 }
@@ -204,21 +244,23 @@ returns the same config. `options.appRoot` defaults to `process.cwd()`.
 ## Distribution
 
 `npm run pack:tarball` runs the build (via `prepack`) and produces
-`@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
+`wireai-activation-x.y.z.tgz` containing `dist` + `src` + `metro` + README +
+CHANGELOG. The primary channel is **npm** (the install line above); 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/activation";
+import { WireOnboarding, activationJoinContext } from "@wireai/activation";
 
 <WireOnboarding
   config={{ apiKey, serverUrl, appId: "my-app" }}
   theme={myBrandTheme}
   illustrations={{ momentum: <MyMomentumSvg /> }}
   validators={{ username: checkUsernameAvailable }}
+  userContext={activationJoinContext(deviceKey)}
+  fallbackFlow={<MyExistingStaticOnboarding />}
   onComplete={(result) => persist(result.answers)}
   onSkip={skip}
   onError={() => fallBackToStaticOnboarding()}
@@ -252,7 +294,7 @@ import { WireOnboarding } from "@wireai/activation";
 | `persistKey` | `string` | Override the storage key (default `wireai:session:<appId>`). Scope per-user if one device can onboard multiple accounts mid-flow. With `storage` only. |
 | `retainSessionOnComplete` | `boolean` | Opt IN: keep the persisted session seed alive across completion. A multi-stage signup that re-enters onboarding (typically a `key=` remount) then resumes the SAME session instead of minting a fresh `metadata.sessionId`, which the backend adopts as a second `contextId` and double-counts as a `session_started`. Omitted or `false` clears the seed on completion, the legacy single-stage behavior, so leaving it unset changes nothing. With `true`, freshness comes from `sessionTtlMs` plus an explicit new-run signal (scope a new `persistKey`, e.g. a per-signup id). With `storage` only. |
 | `userContext` | `Record<string, string \| number \| boolean>` | **This is where the join key goes.** `user_context.device_key` is the only thing that joins this onboarding session to the app's later events, so pass `userContext={activationJoinContext(deviceKey)}`. If your app owns no device id, pass a working `storage` and leave this prop alone: the kit injects its own key, and only after it has confirmed the key actually persists. ⛔ Do not hand-build that key with `activationJoinContext(resolveAutoDeviceKey({ appId, storage }))`, because `resolveAutoDeviceKey` is synchronous by contract (it hands back a fresh mint and adopts the persisted id a storage read later) and it cannot tell you whether the id survives the launch at all. Since 0.12.2, omitting it no longer empties the funnel silently: with `storage`, the kit injects its own key (see [The join key](#the-join-key-device_key-never-session_id) and `autoJoinKey` below). Second job: any other non-PII context the app already knows (signup method, referral, plan, a HASHED user id), forwarded on session metadata + client events for funnel segmentation. **No PII on THIS prop** (no raw emails/names); primitives only; the server caps size/keys. See [Device & user context](#device--user-context). ⚠️ Distinct from the analytics/activation **`WireUserContext`** object (`createAnalytics` / `useWireActivation`), which additionally accepts an opt-in raw `userEmail` — see [Rich user context & PII](#rich-user-context--pii). |
-| `autoJoinKey` | `boolean` | Opt OUT of the automatic join key. Default `true`. When this prop is left alone, `storage` is present **and actually persists** (0.13.0: a `storage` adapter that rejects or throws is treated exactly like no `storage` — the kit declines and says so, because a key it cannot persist is a different key on every launch, which corrupts `min_sessions` rather than merely leaving the join empty), and `userContext` carries no `device_key`, the kit injects its own per-install key (the same id `createAnalytics` / `createWireActivation` mint and persist), so the `activated` funnel joins with no host wiring. Pass `autoJoinKey={false}` if you genuinely want an UNLINKED onboarding session: that restores the pre-0.12.2 behavior exactly, and the dev warning fires again. It never overrides a `device_key` you passed, and it cannot inject without `storage` (see [The join key](#the-join-key-device_key-never-session_id)). |
+| `autoJoinKey` | `boolean` | Opt OUT of the automatic join key. Default `true`. When this prop is left alone, `storage` is present **and actually persists** (0.13.0: a `storage` adapter that rejects or throws is treated exactly like no `storage` — the kit declines and says so, because a key it cannot persist is a different key on every launch, which corrupts `min_sessions` rather than merely leaving the join empty), and `userContext` carries no `device_key`, the kit injects its own per-install key (the same id `createAnalytics` / `createWireActivation` mint and persist), so the `activated` funnel joins with no host wiring. Pass `autoJoinKey={false}` if you genuinely want an UNLINKED onboarding session: that restores the pre-0.12.2 behavior exactly, and the dev warning fires again. It never overrides a `device_key` you actually supplied, and it cannot inject without `storage` (see [The join key](#the-join-key-device_key-never-session_id)). The kit counts yours as supplied only when it is a string with at least one non-whitespace character, so a non-string or an all-whitespace `device_key` is treated as absent and the auto key is merged over it. |
 | `userId` | `string` | Your own OPAQUE user id, so onboarding sessions reconcile to real users later (console sessions to your user table / GA4 users). Optional and supports **late binding**: present at mount it rides the session-start metadata; if it changes mid-session (the user just registered) the kit emits an `identify` event; available only after the flow, use `identifyOnboarding(...)`. **No PII** (not an email/name/phone); trimmed and capped at 128 chars. See [User identity](#user-identity). |
 
 ## Helpers (the reusable substrate)
@@ -273,7 +315,7 @@ You rarely hand-roll config, gating, analytics, or attribution — the kit ships
 
 > **`onEvent`** fires `started` / `resumed` / `turn` / `error` / `retry` / `fallback` / `permission` (the kit owns the loop, so this is how you recover per-turn analytics). `resumed` fires INSTEAD of `started` when a persisted session was restored (see the `storage` prop) — don't count both as flow starts. Since 0.13.6 the `turn` event also carries `variant`, the experiment arm the backend assigned, from the first card that declares one onwards; that is how you read the arm DURING the flow rather than waiting for `onComplete`. The key is absent when no experiment is running, and the kit never attaches the arm to an analytics event, so arm-segmented funnels are the host's job. Completion is signalled via `onComplete`, not `onEvent` — log `WIRE_ONBOARDING_EVENTS.completed` there. `started` and `resumed` also carry a `contextId` (the A2A session id): capture it if you might bind a `userId` after the flow finishes (see [User identity](#user-identity)).
 
-**Integrating with an AI agent?** See [`INTEGRATION_PROMPT.md`](./INTEGRATION_PROMPT.md) (copy-paste prompt for Claude Code) and [`llms.txt`](./llms.txt). Fastest of all: the `wire-rn-integration` Claude skill.
+**Integrating with an AI agent?** See [`INTEGRATION_PROMPT.md`](./INTEGRATION_PROMPT.md) (copy-paste prompt for Claude Code) and [`llms.txt`](./llms.txt).
 
 ## Device & user context
 
@@ -331,7 +373,7 @@ setUserId(newUser.id); // the kit fires `identify` and binds the running session
 ```tsx
 import { identifyOnboarding } from "@wireai/activation";
 
-const contextIdRef = useRef<string>();
+const contextIdRef = useRef<string | undefined>(undefined);
 
 <WireOnboarding
   config={config}
@@ -378,6 +420,8 @@ await clearUserContext({ storage, appId }); // the wire/activation path (then re
 
 **3. The auto `device_key` is a per-install identifier.** When you supply no `deviceKey`, the analytics and activation surfaces auto-mint a stable per-install `device_key`, persist it via `storage` (`wireai:analytics:deviceKey:<appId>`), and stamp it on every event so the server's review/questionnaire gating and A/B stickiness work out of the box. It carries no hardware id, no IDFA/GAID, and cannot be joined across apps (the privacy category of a first-party cookie), but it IS a persistent per-install id. If you adopt these surfaces, declare it in your App Privacy / Data Safety accordingly. Supply your own `deviceKey` to override it.
 
+**The review gate is on that list too, even if it is the only surface you mount.** Since 0.15.0 `<ReviewGate>` stamps `meta.device_key` onto its `POST /v1/reviews` body when you passed none. That id is the unit the server scopes the review's idempotency key to, and a post without it gets the key discarded. The gate adopts whatever per-install id the analytics and activation surfaces already registered in this process, so it never opens a second id space. On a reviews-only host, where nothing else registered one, it mints its own instead. `<ReviewGate>` takes no `storage` prop, so that minted id is process-scoped: a fresh value on each launch, never persisted, rather than a stable per-install one. Either way it leaves the device inside a review payload. Declare it. Pass your own non-blank `meta.device_key` and it is forwarded verbatim instead.
+
 ### Do not pass `sessionId` to `createAnalytics`
 
 `CreateAnalyticsConfig.sessionId` is an opt-out knob, not a default. Set it and **every** event that
@@ -387,6 +431,7 @@ following the live per-open session the kit registers from `app.session_started`
 collapse onto a single device-scoped id: one "first open" for the life of the install, however many
 times the user comes back. The kit warns about it in dev builds.
 
+<!-- doc-check: skip - two ALTERNATIVE call shapes shown side by side; one file cannot declare the same const twice -->
 ```tsx
 const analytics = createAnalytics({ serverUrl, apiKey, storage, appId });  // ✅ follows each app-open
 const analytics = createAnalytics({ serverUrl, apiKey, sessionId: myId }); // ⚠️ frozen for good
@@ -569,6 +614,7 @@ that name (so an app can ship brand SVG/Lottie the kit never imports), and other
 renders the backend `imageUrl` via RN `<Image>`. Leave a dashboard image's URL empty
 to mean "the app provides this one by name."
 
+<!-- doc-check: skip - a single JSX ATTRIBUTE, not a statement; there is no expression form for it -->
 ```tsx
 illustrations={{
   "before-after": <BeforeAfterIllustration width={300} />, // your SVG component
@@ -611,6 +657,7 @@ waiting on every shipped app to update.
 native rebuild (most Expo apps already ship it). Skip it and the cards render fine without them.
 Or skip it and bring your own brand nodes, keyed by the same vocabulary names:
 
+<!-- doc-check: skip - a single JSX ATTRIBUTE, not a statement; there is no expression form for it -->
 ```tsx
 icons={{
   instagram: <BrandInstagram />,   // override one name with your own mark
@@ -680,6 +727,7 @@ An `afterCard` the flow never reaches **clamps to `"beforeEnd"`** instead of sil
 
 The kit ships English good enough to ship. Override any single line and the rest of the default stays:
 
+<!-- doc-check: skip - one OBJECT PROPERTY of a permission screen, not a statement -->
 ```tsx
 copy: { title: "Never miss a session", primaryLabel: "Turn on reminders" }
 ```
@@ -705,7 +753,15 @@ The gap between `wire_permission_screen_shown` and `wire_permission_primer_accep
 ## Backend coupling
 
 The backend (`wire-rn/examples/dynamic-onboarding/server`) is the source of truth
-for what the agent may emit. To make a new card emittable you must, server-side:
+for what the agent may emit.
+
+> ℹ️ **This section is a VENDOR operation, not something you can do from your app.** Both
+> steps below run against the hosted backend and end in a deploy, so if you need a card
+> that is not in the list above, ask via the console's **Support** section rather than
+> trying to perform them. It is documented here because it explains *why* an unknown card
+> is never emitted, which is otherwise a confusing silence.
+
+To make a new card emittable you must, server-side:
 
 1. add it to `app/wire.py` `KNOWN_COMPONENTS` + `COMPONENT_DOCS`, **and**
 2. add its name to the tenant's `allowed_components` (the `register_*.py` script),
@@ -743,12 +799,14 @@ useEffect(() => {
   wireDoctor({
     target: { serverUrl: DRIVELINE_SERVER_URL, apiKey: DRIVELINE_API_KEY },
     storage: AsyncStorage,
+    // The same values you pass <WireOnboarding>. Omit `join` and the join_key check FAILS.
+    join: { appId: DRIVELINE_APP_ID, userContext },
   }).then((report) => console.log(report.ok, report.checks));
 }, []);
 ```
 
 It resolves `{ ok, checks: [{ name, ok, detail }] }` and **never throws**, whatever the target, the
-storage adapter or the network does. Four independent checks:
+storage adapter or the network does. Five independent checks:
 
 | `name` | What it proves |
 |---|---|
@@ -756,9 +814,23 @@ storage adapter or the network does. Four independent checks:
 | `reachability` | `GET /v1/events/contract` answers, so the URL really points at a Wire server. |
 | `storage` | The offline queue can persist, via a write / read / delete probe on its own key. Your pending backlog is never read, overwritten or deleted. |
 | `round_trip` | One synthetic event survives real server validation. It goes out with `dry_run`, so nothing is written and no metric moves. The verdict is `written === 1 && skipped === 0`, read from the ack body, because the status code cannot tell you. |
+| `join_key` | The events will be **joinable**: this session will carry a `user_context.device_key`, either the one you supplied or the one the kit auto-injects. Needs `join`. |
 
 A `ts`-shaped drift shows up as `skipped=1` carrying the server's own `field: ts`.
 
+**Why `join_key` is its own check.** The first four all answer one question — *does an event leave
+and get accepted?* None of them answers *can it be joined?* `user_context.device_key` is the only
+thing that stitches an onboarding session to everything the app reports later, so an integration
+without one writes every event, passes all four, and still reports a permanent **zero** in the
+`activated` funnel. Two real consumers shipped exactly that.
+
+**Omitting `join` fails the check** rather than skipping it, for the same reason a release build
+reports `dev_only` as a failure: a report that never looked at the join has not earned a green.
+
+`join_key` is **strictly read-only** — one `getItem`, plus pure predicates. It never mints a key,
+never writes the identity registry and never persists anything, so running the doctor cannot itself
+create the split-identity defect it exists to detect.
+
 **Dev-only by contract.** The `__DEV__` guard is the first statement in the function, so a release
 build does nothing at all: no network call, no storage write. In that case the report says it was
 skipped rather than reporting a pass it never earned. A host that never imports `wireDoctor` does not
@@ -818,8 +890,10 @@ below) — nothing to rewire.
 **1. Mount the provider once, around your `NavigationContainer`.** It renders the
 overlay host as a root sibling so a ring can paint _above_ the bottom tab bar
 (which react-navigation draws over screen components). It takes a **synchronous**
-storage adapter — gate reads must not be async or a ring flashes before the
-"already seen" check resolves. An MMKV wrapper is three lines:
+storage adapter — gate reads resolve during render. An async adapter (e.g.
+AsyncStorage handed straight in) is caught by a probe and the gates FAIL CLOSED:
+coachmarks, showcases and the review/questionnaire gates all stay silent, and a
+dev-build warning names the fix. An MMKV wrapper is three lines:
 
 ```tsx
 import { CoachmarkProvider } from "@wireai/activation/coachmarks";
@@ -857,9 +931,9 @@ 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/activation/coachmarks";
+import { useCoachmarkTour, type CoachmarkStep } from "@wireai/activation/coachmarks";
 
-const steps = useMemo(
+const steps = useMemo<CoachmarkStep[]>(
   () => [
     { id: "feed_scroll", message: "Swipe to explore.", gesture: "swipe_up" },
     { id: "group_tab", message: "Your groups live here.", anchorId: "group_tab",
@@ -951,6 +1025,7 @@ const catalog = [
 
 // Sequence: WireOnboarding → onComplete(result) → select from answers → FeatureShowcase → app
 <WireOnboarding
+  config={config}
   onComplete={(result) => {
     persist(result.answers);
     setSlides(selectShowcaseSlides(catalog, idsFromAnswers(result.answers)));
@@ -1029,6 +1104,7 @@ own analytics; the four moments are `review_prompt_shown`, `review_rating_select
 `stars`), `store_review_requested`, and `review_feedback_submitted`. No PII rides in events.
 Feedback text goes only in the POST body.
 
+<!-- doc-check: skip - a COMPONENT BODY fragment: the `return` needs an enclosing component, which the surrounding prose supplies -->
 ```tsx
 import { ReviewGate, useReviewGate } from "@wireai/activation/reviews";
 
@@ -1070,7 +1146,10 @@ import { fetchReviewDecision, useReviewGate } from "@wireai/activation/reviews";
 // so deviceKey is the identity that matters. sessionId is optional.
 const decision = await fetchReviewDecision(target, { deviceKey });
 
-const gate = useReviewGate({ config, decision: decision ?? undefined, storage });
+// `config` here is the GATE's config (it has an `id`), not the kit transport config, and
+// `gateStorage` is a SYNCHRONOUS store (`getItem`/`setItem` returning values, not promises) —
+// the same shape `CoachmarkProvider` takes, not the async adapter `<WireOnboarding storage>` wants.
+const gate = useReviewGate({ config: { id: "post_onboarding" }, decision: decision ?? undefined, storage: gateStorage });
 ```
 
 It returns the full `{ fire, reason, arm }` on a 2xx and `null` on anything else. That
@@ -1166,7 +1245,7 @@ useEffect(() => {
   fetchReviewDecision(target, { sessionId, deviceKey }).then((d) => setDecision(d ?? undefined));
 }, [revalidation]);
 
-const gate = useReviewGate({ config: { id: "home", minSessions: 2 }, decision, storage });
+const gate = useReviewGate({ config: { id: "home", minSessions: 2 }, decision, storage: gateStorage });
 
 // …elsewhere, on the triggering action. Awaiting it means the re-fetch sees the event:
 await track("journal_done"); // POST stored → revalidation bumps → effect re-fetches → gate can fire
@@ -1245,7 +1324,7 @@ Skip the onboarding half and the purchase events are still valid on their own, t
 
 Three rules govern it:
 
-- **Your key always wins.** Any non-empty `device_key` you pass is forwarded verbatim and nothing is merged over it. Existing integrations see a byte-identical payload.
+- **Your key always wins.** A `device_key` you pass is forwarded verbatim, untrimmed, and nothing is merged over it — as long as it is a string with at least one non-whitespace character, which is the kit's entire test for "the host supplied one" (the trim is used only to decide presence). A non-string (the `userContext` type also allows numbers and booleans) or an all-whitespace value is not a usable join key: it is treated as absent and the auto key is merged over it. Existing integrations that pass a real key see a byte-identical payload.
 - **It needs `storage`.** Without persistence the kit's id is minted fresh on every launch, and a per-launch key is worse than no key: the server counts `min_sessions` by distinct app-opens grouped on `device_key`, so it corrupts the counter instead of leaving the join empty. With no `storage` the kit declines to inject and warns in dev.
 - **You can opt out.** `autoJoinKey={false}` restores the pre-0.12.2 behavior for a host that genuinely wants an unlinked session. The dev warning fires again there, naming the opt-out as the reason nothing was injected.
 

package/dist/analytics/index.d.mts

@@ -1,10 +1,10 @@
-export { R as ReportAppEventOptions, r as reportAppEvent } from '../transport-j5gFfJhK.mjs';
-import { C as ClientEventTarget, W as WireUserContext, E as EventQueueOptions } from '../currentSession-CUvTOchb.mjs';
-export { A as AUTO_DEVICE_ID_PREFIX, a as AnalyticsEvent, b as ClearUserContextOptions, c as ClientEvent, d as ClientEventType, e as ContextEnvelope, f as ContextEnvelopeInput, D as DeviceKeyStorage, g as EnvelopeSource, h as EventQueue, R as ResolveAutoDeviceKeyOptions, i as WIRE_ONBOARDING_EVENTS, j as WireOnboardingEventName, k as analyticsUserIdStorageKey, l as buildContextEnvelope, m as clearPiiFromContext, n as clearUserContext, o as createEventQueue, p as deviceIdStorageKey, q as ensureCurrentSessionId, r as getCurrentSessionId, s as looksLikeEmail, t as makeSessionId, u as reportClientEvent, v as reportClientEventAwait, w as reportClientEvents, x as reportClientEventsAwait, y as resetAutoDeviceKeys, z as resetCurrentSessionId, B as resetEventQueueKeys, F as resolveAutoDeviceKey, G as setCurrentSessionId, H as toAnalyticsEvent } from '../currentSession-CUvTOchb.mjs';
+export { R as ReportAppEventOptions, r as reportAppEvent } from '../transport-s5QxA-ci.mjs';
+import { C as ClientEventTarget, W as WireUserContext, E as EventQueueOptions } from '../currentSession-Bz7G6lno.mjs';
+export { A as AUTO_DEVICE_ID_PREFIX, a as AnalyticsEvent, b as ClearUserContextOptions, c as ClientEvent, d as ClientEventType, e as ContextEnvelope, f as ContextEnvelopeInput, D as DeviceKeyStorage, g as EnvelopeSource, h as EventQueue, R as ResolveAutoDeviceKeyOptions, i as WIRE_ONBOARDING_EVENTS, j as WireOnboardingEventName, k as analyticsUserIdStorageKey, l as buildContextEnvelope, m as clearPiiFromContext, n as clearUserContext, o as createEventQueue, p as deviceIdStorageKey, q as ensureCurrentSessionId, r as getCurrentSessionId, s as looksLikeEmail, t as makeSessionId, u as reportClientEvent, v as reportClientEventAwait, w as reportClientEvents, x as reportClientEventsAwait, y as resetAutoDeviceKeys, z as resetCurrentSessionId, B as resetEventQueueKeys, F as resolveAutoDeviceKey, G as setCurrentSessionId, H as toAnalyticsEvent } from '../currentSession-Bz7G6lno.mjs';
 import { W as WireOnboardingStorage } from '../types-BpwiRpA8.mjs';
-import '../types-Cju-1_jT.mjs';
+import '../types-Byx306Kv.mjs';
 import '../types-BKfpdZzX.mjs';
-import '../types-BcmagF6K.mjs';
+import '../types-D_0B0yay.mjs';
 import 'react';
 import 'wireai-rn';
 import 'react-native';
@@ -105,13 +105,18 @@ declare const useScreenTracking: (navigationRef: NavigationRefLike | undefined,
  * numeric `ts` did exactly that through 0.13.0. This turns that class of loss from something you
  * discover in a funnel report weeks later into something the first run tells you.
  *
- * SHAPE: four independent checks, each a `{name, ok, detail}` unit that can be read (and tested)
+ * SHAPE: five independent checks, each a `{name, ok, detail}` unit that can be read (and tested)
  * without the others. The report is data, never a thrown error and never a side effect on the host:
  *
  *   1. `target`      : is there a server URL and a key, and do they look like a key and a URL?
  *   2. `reachability`: is the server actually there? (`GET /v1/events/contract`, public and cheap)
  *   3. `storage`      : can the offline queue persist? (a write / read / delete probe)
  *   4. `round_trip`   : does a REAL event survive REAL server validation? (a `dry_run` POST)
+ *   5. `join_key`     : will those events be JOINABLE? (read-only; needs `join`)
+ *
+ * Checks 1-4 all answer "does an event leave and get accepted". NONE of them answers "can it be
+ * joined", and an integration with no `user_context.device_key` writes every event, passes every
+ * one of those four, and still reports a permanent ZERO in the activated funnel. That is check 5.
  *
  * NEVER THROWS, under any input, any network condition, or any hostile response object. A doctor
  * that can crash the screen it is diagnosing is worse than no doctor.
@@ -131,6 +136,9 @@ declare const useScreenTracking: (navigationRef: NavigationRefLike | undefined,
  *   const report = await wireDoctor({
  *     target: { serverUrl: "https://api.example.com", apiKey: DRIVELINE_KEY },
  *     storage: AsyncStorage,
+ *     // The same values you hand <WireOnboarding>. Omit `join` and the join_key check FAILS,
+ *     // because a report that never looked at the join cannot honestly read green.
+ *     join: { appId: WIRE_APP_ID, userContext },
  *   });
  *   console.log(report.ok, report.checks);
  */
@@ -138,7 +146,8 @@ declare const useScreenTracking: (navigationRef: NavigationRefLike | undefined,
 /** One diagnosis. `name` is stable and machine-readable; `detail` is for a human reading a console. */
 type WireDoctorCheck = {
     /**
-     * Stable id: `target` | `reachability` | `storage` | `round_trip` | `dev_only` | `internal_error`.
+     * Stable id: `target` | `reachability` | `storage` | `round_trip` | `join_key` | `dev_only` |
+     * `internal_error`.
      *
      * `dev_only` means ONE thing and only that thing: `__DEV__` is unset or false, so nothing ran.
      * `internal_error` is the separate catch-all for a failure that got past every check's own
@@ -155,6 +164,19 @@ type WireDoctorReport = {
     ok: boolean;
     checks: WireDoctorCheck[];
 };
+/**
+ * What the join check needs: the same three values the host hands `<WireOnboarding>`. Pass the very
+ * props you pass the component — anything reconstructed here would diagnose a DIFFERENT integration
+ * than the one that ships.
+ */
+type WireDoctorJoinTarget = {
+    /** The same `config.appId`. It namespaces the persisted auto key, so the wrong one reads the wrong slot. */
+    appId?: string;
+    /** The same `userContext` prop. Only `device_key` is read; nothing else is inspected or reported. */
+    userContext?: Record<string, string | number | boolean>;
+    /** The same `autoJoinKey` prop. `false` is the documented opt-out from the kit's auto-join. */
+    autoJoinKey?: boolean;
+};
 /** Input for {@link wireDoctor}. `storage` is optional: without it the queue runs in-memory only. */
 type WireDoctorOptions = {
     /** The same `{serverUrl, apiKey}` the kit is configured with. */
@@ -164,6 +186,11 @@ type WireDoctorOptions = {
      * check reports the DEGRADED in-memory mode rather than failing.
      */
     storage?: WireOnboardingStorage;
+    /**
+     * The join-key inputs. OMITTING THIS FAILS THE `join_key` CHECK — deliberately, and see
+     * {@link checkJoinKey} for why a skipped join check may not read as a pass.
+     */
+    join?: WireDoctorJoinTarget;
 };
 /**
  * Run the full diagnosis. Resolves a report; NEVER throws and NEVER rejects.
@@ -283,11 +310,6 @@ type Analytics = {
  */
 declare const createAnalytics: (config: CreateAnalyticsConfig, options?: AnalyticsOptions) => Analytics;
 
-/**
- * Build a per-mount analytics instance. `config`/`options` are read once at first render (the
- * instance is stable for the component's lifetime, held in a ref). Returns the {@link Analytics}
- * surface so the component can `track` / `screen` / `identify` and drive `notifyOnline` on reconnect.
- */
 declare const useAnalytics: (config: CreateAnalyticsConfig, options?: AnalyticsOptions) => Analytics;
 
-export { type Analytics, type AnalyticsOptions, type AnalyticsProps, ClientEventTarget, type CreateAnalyticsConfig, EventQueueOptions, type NavigationRefLike, type NavigationRouteLike, type NavigationStateLike, type ScreenTracker, type ScreenTrackerOptions, type WireDoctorCheck, type WireDoctorOptions, type WireDoctorReport, createAnalytics, createScreenTracker, getActiveRouteName, screenTrackingHandler, useAnalytics, useScreenTracking, wireDoctor };
+export { type Analytics, type AnalyticsOptions, type AnalyticsProps, ClientEventTarget, type CreateAnalyticsConfig, EventQueueOptions, type NavigationRefLike, type NavigationRouteLike, type NavigationStateLike, type ScreenTracker, type ScreenTrackerOptions, type WireDoctorCheck, type WireDoctorJoinTarget, type WireDoctorOptions, type WireDoctorReport, createAnalytics, createScreenTracker, getActiveRouteName, screenTrackingHandler, useAnalytics, useScreenTracking, wireDoctor };