@wireai/activation 0.11.0 → 0.12.1

package/AGENTS.md

@@ -31,16 +31,14 @@ Use it whenever someone wants "AI / dynamic / personalized onboarding" in a Reac
 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` (root): `WireOnboarding`, the helpers/types below, and the device-only event reporters (`reportClientEvent`, `makeSessionId`, `WIRE_ONBOARDING_EVENTS`, see "App events" below).
+- `@wireai/activation/analytics`: the analytics FACADE and its queue: `createAnalytics`, `useAnalytics`, `createScreenTracker`, `reportAppEvent`, `createEventQueue`, `clearUserContext`. These are NOT root exports; importing them from the root does not compile.
 - `@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`, `useReviewGate`, `fetchReviewDecision`).
 - `@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).
@@ -50,6 +48,10 @@ There is no `analytics` subpath: the app-event / analytics API is exported from
 - `themeFromBrand({ primary })`: derive a full theme from one brand color.
 - `mergeTheme`, `defaultOnboardingTheme`, `OnboardingThemeProvider`, `useOnboardingTheme`.
 - `defaultIllustrations`: dependency-free fallback art; spread your own over it.
+- `createRevenueCatBridge({ analytics, entitlementId })`: the RevenueCat purchase funnel (see "RevenueCat" below).
+- `activationJoinContext(deviceKey)`: builds the `userContext` value that joins an onboarding session to the app's later events. Every `<WireOnboarding>` needs it (see step 7).
+- `resolveAutoDeviceKey({ appId, storage })`: the kit's own persisted per-install `device_key`, for a host that owns none.
+- `useLifecycleEvents(config, options)`: the app-root lifecycle hook (see step 8). `useSessionStart` / `reportSessionStart` are the counter-owning alternatives.
 - Types: `OnboardingTheme`, `OnboardingResult`, `OnboardingEvent`, `WireOnboardingConfig`, `WireOnboardingProps`, `StepValidator`, `OnboardingCopy`, `IllustrationRegistry`.
 
 ## `<WireOnboarding>` props
@@ -88,9 +90,10 @@ There is no `analytics` subpath: the app-event / analytics API is exported from
 | `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 | App version string (e.g. `"1.4.2"`); forwarded to the backend + client events so analytics can segment the funnel by app version. Auto-detected best-effort from `expo-constants`/`expo-application` (dependency-free) when omitted; pass it to override (yours wins). |
 
-## App events / analytics (root export)
+## App events (root export)
 
-The app-event / analytics API is exported from the ROOT (`@wireai/activation`), NOT a subpath.
+These device-only event helpers are exported from the ROOT (`@wireai/activation`). The analytics
+FACADE (`createAnalytics` and friends) is a different surface and lives on `@wireai/activation/analytics`.
 
 - `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.
@@ -105,8 +108,9 @@ The app-event / analytics API is exported from the ROOT (`@wireai/activation`),
 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.
+7. **Render + continuation**: drop `<WireOnboarding>` into the signup flow; `onComplete` → persist + navigate, `onSkip` → navigate. Pass the join key: `userContext={activationJoinContext(deviceKey)}`, or `activationJoinContext(resolveAutoDeviceKey({ appId, storage }))` when the app owns no device id. Skipping it leaves the `activated` funnel permanently empty and reports no error.
+8. **Lifecycle (do not skip)**: mount `useLifecycleEvents(config, { deviceKey?, sessionCount?, userId? })` ONCE at the app root, before anything else touches analytics. It is the only path that emits `app.first_open`, it registers the per-open session id that `createAnalytics` / `wire.track` / the gates all correlate to, and with `config.storage` it stamps the kit's persisted auto `device_key` on `app.session_started`, which is what the server's `min_sessions` rule counts. `useSessionStart` / `reportSessionStart` are the alternatives for a host that already owns an open counter; neither emits `first_open`.
+9. **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.
 
 ## Review firing (do not hand-roll the decision fetch)
 
@@ -131,6 +135,56 @@ write your own fetch.
   `createWireActivation(config)`. This is the kit-owned replacement for hand-rolling
   session-id + await-POST + revalidate.
 
+## RevenueCat (the purchase funnel)
+
+The app sells subscriptions through `react-native-purchases`? Wire the paywall to the same event
+stream as onboarding. The kit does NOT depend on `react-native-purchases` (it is a native module and
+the kit never forces a rebuild); the adapter types the RevenueCat objects structurally, so you pass
+the real ones you already have.
+
+```tsx
+import { createRevenueCatBridge, activationJoinContext } from "@wireai/activation";
+import { createAnalytics } from "@wireai/activation/analytics";
+
+const analytics = createAnalytics({ serverUrl, apiKey, storage, appId, userContext: { deviceKey } });
+const revenuecat = createRevenueCatBridge({ analytics, entitlementId: "pro" });
+
+revenuecat.paywallShown(offering, { source: variant });
+revenuecat.checkoutStarted(pkg, { source: variant });
+const entitled = revenuecat.purchaseCompleted(customerInfo, pkg, { source: variant });
+revenuecat.purchaseFailed(error, pkg, { source: variant });
+revenuecat.purchasesRestored(customerInfo);
+revenuecat.syncPlanTier(customerInfo);   // at launch, writes plan_tier with no event
+```
+
+Canonical names (they are also the `question_key` strings a firing trigger matches on):
+`wire_paywall_shown`, `wire_checkout_started`, `wire_purchase_completed`, `wire_purchase_failed`,
+`wire_purchase_restored`.
+
+**The join key is `user_context.device_key`, never `session_id`.** An onboarding session id is the
+A2A `contextId` and an app-event session id is the per-open id; the two live in separate spaces on
+purpose, so intersecting them returns nothing. Put the SAME device key on both sides: the analytics
+and activation surfaces auto-mint and stamp it on every event, and onboarding gets it from
+`<WireOnboarding userContext={activationJoinContext(deviceKey)} ... />`. Never hand-write
+`userContext={{ deviceKey }}`, because the server's device lookup reads `device_key` and a
+misspelled bucket produces an empty funnel instead of an error.
+
+**If the host owns no device id, read the kit's.** Do not leave the onboarding side blank.
+`resolveAutoDeviceKey({ appId, storage })` returns the exact id `createAnalytics` /
+`createWireActivation` auto-mint and persist for this install, so both halves of the join agree:
+
+```tsx
+import { resolveAutoDeviceKey, activationJoinContext } from "@wireai/activation";
+
+const deviceKey = resolveAutoDeviceKey({ appId, storage });   // the SAME id the analytics side stamps
+<WireOnboarding config={config} userContext={activationJoinContext(deviceKey)} ... />
+```
+
+Always pass `storage`. Without it the id is per-LAUNCH, not per-install, and a per-launch key makes
+every open look like a new device, which breaks `min_sessions` and A/B arm stickiness as surely as
+no key breaks the join. The same rule governs the lifecycle wiring: `useLifecycleEvents` falls back
+to this id for `app.session_started` / `app.first_open` ONLY when `config.storage` is present.
+
 ## 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).

package/CHANGELOG.md

@@ -3,10 +3,195 @@
 All notable changes to `@wireai/activation` (formerly `wireai-onboarding`).
 Historical entries below the rename keep the old package name on purpose.
 
-## [Unreleased]
+## [0.12.2] — Unreleased
+
+The auto-join patch. 0.12.1 taught the kit to complain about a missing join key; this one teaches it
+to supply the key. `user_context.device_key` is the only thing that stitches an onboarding session to
+everything the app reports later, the prop that carries it is optional, and two of three production
+integrations shipped without it and read `activated: 0`. A warning fixes that for the next host, not
+for the current one, so the default now produces a joined funnel.
+
+### Changed
+
+- **⚠️ BEHAVIOR CHANGE: `<WireOnboarding>` supplies its own join key when the host supplied none.**
+  With `storage` present and no `device_key` in `userContext`, the kit merges in its own per-install
+  key, and both the A2A session-start metadata and the onboarding client events carry it. That key is
+  the SAME id `createAnalytics` / `createWireActivation` mint and persist, resolved through
+  `hydrateAutoDeviceKey({ appId, storage })` rather than the synchronous
+  `resolveAutoDeviceKey({ appId, storage })`, so it is the persisted id, not a pre-hydration mint.
+  Three limits, all deliberate:
+  - **A host-supplied key always wins**, forwarded verbatim, nothing merged over it. An integration
+    that already passes `activationJoinContext(deviceKey)` sends a byte-identical payload.
+  - **No `storage`, no injection.** Without persistence the id is minted fresh every launch, and the
+    server counts `min_sessions` by distinct app-opens grouped on `device_key`: a per-launch key
+    corrupts that counter instead of merely leaving the join empty. The kit declines and warns in dev.
+  - **The key is resolved BEFORE the provider mounts**, behind the loader gate the persisted-session
+    read already holds. `userContext` feeds the A2A config, and swapping it after mount would rebuild
+    the adapter and drop the server-learned `contextId`. The read is timeout-capped, so a hung storage
+    adapter degrades to no key instead of a stuck loader.
+
+  Who this changes: a host that deliberately wanted an unlinked onboarding session. That host now
+  passes `autoJoinKey={false}`.
+- **The 0.12.1 missing-join-key dev warning is reconciled with the above.** It no longer fires when
+  auto-injection covered the gap. It still fires when the gap is genuinely open, and it now names
+  which of the three reasons applies: no `storage`, `autoJoinKey={false}`, or a storage adapter that
+  did not answer in time.
+- **A hand-written `userContext={{ deviceKey }}` still warns, even though the kit injected.** That
+  host demonstrably owns a device id, and their app-side events carry it, so the two families still
+  land in disjoint id spaces. Injection makes the onboarding side self-consistent; only the host can
+  make it join. Silencing this would have undone the 0.12.1 fix for the most common mis-wiring.
+
+### Added
+
+- **`autoJoinKey` prop on `<WireOnboarding>`,** the documented opt-out. Default `true`. Setting it to
+  `false` restores the pre-0.12.2 behavior exactly: nothing is injected and the dev warning fires.
+  Documented in the `userContext` JSDoc, the README props table, and the README join-key section.
+
+## [0.12.1] — 2026-07-27
+
+The integration-contract patch. 0.12.0's runtime worked; what did not work was everything the package
+let a host leave out. Two of three real integrations went wrong in ways the kit accepted without
+complaint, and the review that produced this release found a third: the ordered integration steps in
+every shipped doc never once said "mount `useLifecycleEvents`", while the kit's own runtime warning
+names that exact symbol as the fix. Nothing here tightens the wire; every new check is `__DEV__`-only
+or a client-side default.
+
+### Added
+
+- **`<WireOnboarding>` warns in dev when it got no join key.** `user_context.device_key` is the only
+  thing that joins an onboarding session to the app's later events, and the prop that carries it is
+  optional and named `userContext`, so forgetting it is the default and the failure is a silent zero
+  in the `activated` funnel. The warning names `activationJoinContext(deviceKey)` and, for a host that
+  owns no device id, `activationJoinContext(resolveAutoDeviceKey({ appId, storage }))`. The
+  `userContext` JSDoc + the README props row now lead with "this is where the join key goes" instead
+  of describing the prop as segmentation context. The prop is NOT renamed (breaking, for no gain), and
+  auto-injection is deliberately held for 0.13.0.
+- **`wireConfigFromEnv` says "Wire is off" out loud in dev.** A missing EAS env var made it return
+  `null`, and then the facade never constructed, `useLifecycleEvents` no-oped, and every gate returned
+  null: three independent silent no-ops from one missing var. It now warns once, naming WHICH var is
+  missing and that the kit is fully disabled. The `null` return is unchanged, and hosts still gate on
+  it. `WIRE_ENV_VARS` is exported so a host preflight can assert the three names itself.
+- **`hydrateAutoDeviceKey({ appId, storage })`,** the awaitable sibling of `resolveAutoDeviceKey`. It
+  joins the same single-flight storage read and resolves once the persisted id is in hand, for the one
+  caller that can afford to wait. Never rejects.
+- **The review / questionnaire gates warn in dev when they have no sync storage.** With no storage the
+  app-open counter is pinned at 1 forever, so the fail-closed `minSessions: 2` default is
+  unsatisfiable and the gate never fires, which is indistinguishable from "the rules said not yet".
+- **The lifecycle mount reached the docs.** `useLifecycleEvents` is now an ordered step in `AGENTS.md`
+  and `INTEGRATION_PROMPT.md`, a README section directly above "Session mapping", and a line in
+  `llms.txt`. `useSessionStart` / `reportSessionStart` are demoted to the "you already own a counter"
+  alternatives, with the fact that neither emits `app.first_open` stated where a reader will hit it.
+
+### Fixed
+
+- **`useLifecycleEvents` stamped a freshly minted `device_key`, not the persisted one.**
+  `resolveAutoDeviceKey` is synchronous by contract, so a mount-time caller got a brand-new `wdev_*`
+  and adopted the persisted id milliseconds later. On every launch, both lifecycle events therefore
+  rode a key nothing else shared. The server computes `min_sessions` by counting distinct
+  `app.session_started` grouped by `device_key`, so that counter could never exceed 1, and
+  `app.first_open` (once ever) landed under a key no later event shares, which broke `first_open` to
+  `activated` cohorting too. The mount fire now awaits `hydrateAutoDeviceKey` — but ONLY when the auto
+  fallback is actually in play. A host-supplied `deviceKey`, or no `storage`, still fires
+  synchronously at mount.
+- **The gate counter's unit could change mid-launch.** The gates call `bumpSessionCount` from a
+  `useState` initializer (render phase) while `useLifecycleEvents` registers the per-open id from a
+  root effect, and React runs every render before any effect. So a cold start counted a process id and
+  then a session id as TWO app-opens, which made `minSessions: 2` — the fail-closed default added
+  after the 2026-07-16 one-star incident — satisfiable inside a single launch. `currentOpenId()` now
+  pins whatever it first resolved for the whole launch. Behavioural, in the fail-closed direction: a
+  gate fires later, never earlier.
+- **The coachmark storage singleton was a plain module `let`, duplicated across four dist bundles.**
+  Under `dist` resolution (node `import`/`require`, SSR, jest, RN-web, anything that is not Metro) a
+  host that mounted `CoachmarkProvider` from `@wireai/activation/coachmarks` wrote the coachmarks copy
+  while `useReviewGate` from `@wireai/activation/reviews` read the reviews copy, which was still
+  `null` — so the gate never fired, the `seen` once-gate never persisted, and a tenant's coachmarks
+  kill switch never reached the reviews bundle. The storage, the QA replay flag and the kill switch now
+  live in one `globalThis` slot keyed by `Symbol.for("@wireai/activation:coachmarkRuntime")`, the same
+  remedy already applied to `currentSession`, the auto device-key registry and activation revalidation.
+- **The analytics facade read the session registry but never registered.** `resolveSessionId` was a
+  pure read with a per-instance fallback, so a `track` before the root lifecycle effect carried an id
+  the server had no `app.session_started` for and the server back-filled a phantom session, while a
+  `wire.track` moments later minted and registered a different one. It is now
+  `config.sessionId ?? ensureCurrentSessionId()`, a strict superset: when an open is registered this is
+  exactly `getCurrentSessionId()`, and the frozen-id opt-out is untouched.
+- **`wireConfigFromEnv` structurally could not carry `appVersion`,** so a host that built its config
+  the documented way forwarded `undefined` everywhere. The facade and lifecycle paths each auto-detect
+  their own fallback; `createWireActivation` did not, so EVERY `wire.track` event shipped with no
+  `app_version` at all. The helper now defaults it to `detectAppVersion()` (an explicit override still
+  wins) and `createWireActivation` gained the same fallback as the facade.
+- **`useSessionStart` had no auto `device_key` fallback,** while its sibling `useLifecycleEvents` did.
+  A host on the documented `useSessionStart` path emitted the very event `min_sessions` counts with no
+  device key while its other events carried an auto-minted one. Backported, storage-gated on the same
+  rule (no storage means no fallback, because a per-launch key corrupts the counter the other way).
+- **`AGENTS.md` shipped an import that cannot resolve, and denied a subpath that exists.**
+  `import { createAnalytics } from "@wireai/activation"` does not compile (it lives on
+  `@wireai/activation/analytics`), and the same file claimed "There is no `analytics` subpath" while
+  `package.json` exports it, `tsup` builds it and `llms.txt` documents it. `README.md` shipped the same
+  broken import. Both are fixed, and `src/docsContract.test.ts` now resolves every documented
+  specifier against the BUILT `dist` through the real `exports` map, so the drift cannot return quietly.
+- **`warnOnSkippedEvents` parsed the response body in release builds.** The `__DEV__` check sat inside
+  the `.then`, after `res.json()`, so every persistent-path POST paid a JSON parse to build a warning
+  nobody would read. The check is now the first statement in the function.
+
+## [0.12.0] — 2026-07-27
+
+The release Myelino 2.2.0 pins. Ships the RevenueCat path (#52), the identity/counting audit,
+the session-id fallback contract, and the transport/config fixes behind a silently dead lifecycle
+stream (a consumer's `first_open` read 6 all-time while the emitting code was deployed).
+
+### Added
+
+- **RevenueCat path (`createRevenueCatBridge`).** The purchase funnel is now a first-class, documented
+  path instead of glue every consumer writes itself. New ROOT exports: `createRevenueCatBridge`,
+  `WIRE_PURCHASE_EVENTS` (`wire_paywall_shown`, `wire_checkout_started`, `wire_purchase_completed`,
+  `wire_purchase_failed`, `wire_purchase_restored`), the pure mappers (`activeEntitlement`,
+  `resolvePlanTier`, `describePackage`, `describeEntitlement`, `isUserCancelled`, `describeFailure`),
+  `PLAN_TIER_CONTEXT_KEY`, and the structural RevenueCat types. The bridge reports through the
+  `createAnalytics` or `createWireActivation` instance the host already holds (a compile-time check in
+  `revenueCatBridge.ts` keeps both assignable), writes `plan_tier` (paid / trial / free) to the bound
+  user context, drops the store's localized error `message` and keeps only the stable RevenueCat
+  `code`, and reports a store-confirmed purchase that granted no entitlement as
+  `wire_purchase_failed` with `reason: "not_entitled"` rather than swallowing it. **No new dependency:
+  `react-native-purchases` is a native module and is never imported**, so the RevenueCat objects are
+  typed structurally and the host passes its real ones.
+- **`activationJoinContext(deviceKey)`.** The `userContext` value that joins an onboarding session to
+  the app's later events. The join key is `user_context.device_key` and NEVER `session_id`: an
+  onboarding session id is the A2A `contextId`, an app-event session id is the per-open id, and
+  intersecting the two id spaces returns zero rows every time. This helper exists so the wire spelling
+  (`device_key`) is decided in one place; a hand-written `userContext={{ deviceKey }}` builds a bucket
+  the server's device lookup does not read, which produces a silently empty funnel rather than an
+  error. `src/revenuecat/joinKey.test.ts` locks both sides against each other.
+- **One shared auto `device_key` per install.** `createAnalytics` and `createWireActivation` each
+  minted their OWN id and raced a storage read, so a host building both (the documented wiring)
+  stamped two different `device_key`s on one install — splitting the key that `min_sessions`, A/B arm
+  stickiness and the purchase-to-onboarding join all read. Now ONE id lives in a `globalThis` slot
+  keyed by `Symbol.for(...)` (the `currentSession` pattern). `useLifecycleEvents` now stamps the
+  shared key on lifecycle events too (storage-gated, so a per-launch id never corrupts the counter),
+  and `resolveAutoDeviceKey` is exported from the root and `./analytics` barrels.
+
+### Fixed
 
-Architecture-audit fixes. The next release that ships these MUST be at least **0.11.0** (0.10.0 is
-published and immutable). One BEHAVIOR CHANGE, called out below.
+- **Every event carries a `session_id`, or the server eats it.** `POST /v1/events` validates per
+  event inside a try/except that counts the failure as "skipped" and returns HTTP 200 anyway, so an
+  event without a session id was accepted by the wire and discarded. `ensureCurrentSessionId()`
+  returns the registered per-open id when there is one and otherwise mints one, REGISTERS it so later
+  events join the same session, and warns once per process in `__DEV__` (mount `useLifecycleEvents`
+  at the app root). Closes the `reportAppEvent(target, "screen", { deviceKey })` hole and
+  `wire.track()`'s refusal to send without a registered open.
+- **`config.sessionId` on `createAnalytics` now warns in dev.** Passing it pins EVERY event from the
+  instance to that one frozen id and opts out of the live per-open session — the exact footgun that
+  flatlined a consumer's lifecycle metrics. The JSDoc and README now state the freeze semantics
+  honestly; omitting it is the correct default.
+- **The persistent transport paths read the `/v1/events` ACK body.** A 200 was never a receipt: the
+  server reports discarded events only as `skipped` in the body. The event queue and
+  `reportSessionStart` now warn in dev with the skipped count. Log-only — retry/dequeue semantics
+  unchanged.
+- **`user_context.app_version` falls back to `detectAppVersion()`** when the host passes nothing, so
+  version attribution on the facade path no longer depends on the host forwarding its own version.
+
+## [0.11.0] — 2026-07-21
+
+Architecture-audit fixes (#50/#51). One BEHAVIOR CHANGE, called out below.
 
 ### Changed (BEHAVIOR) — review gate no longer fires on the first session
 

package/INTEGRATION_PROMPT.md

@@ -40,10 +40,21 @@ STEPS (do them in order, stop and ask if a convention is ambiguous):
    - `fallbackFlow` MUST be my existing static onboarding so a backend error/timeout degrades, never
      dead-ends.
    - Forward install attribution if I have it: `wireConfigFromEnv({ appId, metadata: attributionMetadata({...}) })`.
+   - THE JOIN KEY: pass `userContext={activationJoinContext(deviceKey)}`. If my app owns no stable
+     device id, use `activationJoinContext(resolveAutoDeviceKey({ appId, storage }))`, which returns
+     the same id the analytics side stamps. Leaving it out makes the `activated` funnel read zero
+     forever and reports no error.
    - 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. Event triggers (only if I asked to fire a review/questionnaire off an in-app action): pick the
+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
+   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.
+   `useSessionStart` / `reportSessionStart` are only for a host that already owns an open counter;
+   neither emits `first_open`.
+9. Event triggers (only if I asked to fire a review/questionnaire off an in-app action): pick the
    action that should trigger it (e.g. finishing a task, journaling a win) and its key, e.g.
    `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 })`
@@ -53,7 +64,19 @@ STEPS (do them in order, stop and ask if a convention is ambiguous):
    `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.
-9. Verify: type-check (and lint the changed files); test the flag-off + backend-error paths.
+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
+   `react-native-purchases` in the kit path; the adapter types the RevenueCat objects structurally,
+   so pass my real `PurchasesOffering` / `PurchasesPackage` / `CustomerInfo` straight in. Replace my
+   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
+   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.
 
 Report back: the files you changed (path:line), the typecheck result, and anything you couldn't
 infer about my conventions.

package/README.md

@@ -246,7 +246,8 @@ import { WireOnboarding } from "@wireai/activation";
 | `storage` | `WireOnboardingStorage` | Host-injected storage (AsyncStorage-compatible `getItem/setItem/removeItem`) for **session-id persistence**: an app KILL mid-onboarding resumes the SAME backend session instead of minting a new one, so the funnel's `started` count stays honest (no phantom drops). Pass AsyncStorage as-is, or a 3-line MMKV wrapper. Omit for the previous per-mount behavior. Persists the kit's own correlation seed only — answers stay the host's job via `onComplete`. |
 | `sessionTtlMs` | `number` | How long a persisted session id stays resumable. Default `3600000` (1h, the backend's session TTL). With `storage` only. |
 | `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. |
-| `userContext` | `Record<string, string \| number \| boolean>` | Host-injected, 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). |
+| `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)}` (or `activationJoinContext(resolveAutoDeviceKey({ appId, storage }))` if your app owns no device id). 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 `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)). |
 | `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)
@@ -370,6 +371,52 @@ 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.
 
+### Do not pass `sessionId` to `createAnalytics`
+
+`CreateAnalyticsConfig.sessionId` is an opt-out knob, not a default. Set it and **every** event that
+instance sends (including `identify`) is pinned to that one frozen id, and the instance stops
+following the live per-open session the kit registers from `app.session_started` (see
+[Session mapping](#session-mapping-know-when-a-user-opens-the-app-again)). Lifecycle analytics then
+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.
+
+```tsx
+const analytics = createAnalytics({ serverUrl, apiKey, storage, appId });  // ✅ follows each app-open
+const analytics = createAnalytics({ serverUrl, apiKey, sessionId: myId }); // ⚠️ frozen for good
+```
+
+Omit it. Pass one only if your host runs its own session lifecycle and owns the id the server should
+correlate on. This is a different field from the per-open `sessionId` that `useWireActivation` and
+`reportAppEvent` READ (that one is the live id, and reading it is always fine).
+
+## Lifecycle events (mount this once, before anything else touches analytics)
+
+One hook at your app root wires the whole top of the funnel: `app.first_open` once ever, and
+`app.session_started` on every real app-open, both offline-buffered.
+
+```tsx
+import { useLifecycleEvents } from "@wireai/activation";
+
+// At the app root, above your navigator:
+useLifecycleEvents(
+  { serverUrl, apiKey, appId, storage },      // same creds as onboarding
+  { deviceKey, sessionCount, userId },        // all optional
+);
+```
+
+Mount it first. Three other things read the per-open session it registers: `createAnalytics`,
+`wire.track`, and the review / questionnaire gates. Without it every one of them falls back to an id
+the server has no `app.session_started` for, so the session is thinner than a real open, and the kit
+warns about it once in dev.
+
+Pass `storage`. With it the hook falls back to the kit's persisted auto `device_key` when you supply
+none, and waits for that key to be read back before it fires, so the events the server counts
+`min_sessions` from carry the id this install keeps. Without storage the id would be per-launch, which
+would make every open look like a new device, so the fallback deliberately does not engage.
+
+The two alternatives below are for a host that already owns an open counter. Both emit
+`app.session_started` only, so `app.first_open` stays empty forever on those paths.
+
 ## Session mapping (know when a user opens the app again)
 
 Onboarding runs once, on the first launch. Session mapping is the other half: every time the
@@ -965,6 +1012,70 @@ If you are outside React (a service, a saga), `createWireActivation(config)` is
 factory. It returns `{ track, sessionId, subscribeRevalidation, getRevalidationVersion }`: the
 same `track`, plus the raw pub/sub the hook wraps for you.
 
+## RevenueCat (the purchase funnel)
+
+If you sell subscriptions with [RevenueCat](https://www.revenuecat.com/), the paywall is the other end of the funnel onboarding starts. `createRevenueCatBridge` wires the two together: one constructor, then your existing paywall call sites.
+
+The kit does **not** depend on `react-native-purchases`, and it never will. That package is a native module, and the kit's whole promise is that it never puts a native rebuild in your way. So the adapter types the RevenueCat objects structurally instead, which means you hand it the real `CustomerInfo` / `PurchasesPackage` / `PurchasesOffering` you already have. Nothing new gets installed.
+
+```tsx
+import { createRevenueCatBridge } from "@wireai/activation";
+import { createAnalytics } from "@wireai/activation/analytics";
+
+const analytics = createAnalytics({ serverUrl, apiKey, storage, appId, userContext: { deviceKey } });
+const revenuecat = createRevenueCatBridge({ analytics, entitlementId: "pro" });
+```
+
+Then five call sites, all fire-and-forget, none of which can throw at your paywall:
+
+```tsx
+revenuecat.paywallShown(offering, { source: variant });        // offering_id + packages_count
+revenuecat.checkoutStarted(pkg, { source: variant });          // package, product, price, currency
+
+const { customerInfo } = await Purchases.purchasePackage(pkg);
+if (revenuecat.purchaseCompleted(customerInfo, pkg, { source: variant })) navigateOn();
+
+revenuecat.purchaseFailed(error, pkg, { source: variant });    // reason: "cancelled" | "error"
+revenuecat.purchasesRestored(await Purchases.restorePurchases());
+revenuecat.syncPlanTier(await Purchases.getCustomerInfo());    // at launch, no event
+```
+
+**The names are canonical**, the same way `WIRE_ONBOARDING_EVENTS` standardizes the onboarding funnel: `wire_paywall_shown`, `wire_checkout_started`, `wire_purchase_completed`, `wire_purchase_failed`, `wire_purchase_restored`. They are `app_event` `question_key` values on the wire, so they are also the exact strings a review or questionnaire firing trigger matches on.
+
+**What the bridge decides for you.** The entitlement check lives in one place instead of being copy-pasted at the purchase site and the restore site. `plan_tier` (`paid` / `trial` / `free`) is written to the bound user context on every entitlement change, so the whole funnel can be sliced paid versus free. The store's error `message` is dropped and only the stable RevenueCat `code` rides the event, because that message is localized, unbounded, and occasionally names the account it failed for. And a purchase the store confirmed that granted **no** entitlement fires `wire_purchase_failed` with `reason: "not_entitled"` rather than returning quietly, which is the usual shape of a broken product-to-entitlement mapping.
+
+### The join key: `device_key`, never `session_id`
+
+A purchase event is worth nothing unless you can join it to the same user's onboarding. Get this wrong and you do not get a wrong number, you get a permanent zero, which is far harder to notice.
+
+`session_id` is not that key. The onboarding session id is the A2A `contextId`, the app-event session id gets minted per app-open, and the kit keeps those two id spaces apart on purpose. Intersect them and you get no rows. Ever.
+
+The key is **`user_context.device_key`**, and you have to put it on both sides:
+
+```tsx
+import { activationJoinContext } from "@wireai/activation";
+
+// Purchase side: createAnalytics / createWireActivation auto-mint and persist a device_key
+// and stamp it on every event. Supply your own to override it.
+const analytics = createAnalytics({ serverUrl, apiKey, storage, appId, userContext: { deviceKey } });
+
+// Onboarding side: forward the SAME key. The kit passes userContext verbatim into the A2A
+// session-start metadata, and the server records it on the session's session_started event.
+<WireOnboarding config={config} userContext={activationJoinContext(deviceKey)} onComplete={persist} />
+```
+
+`activationJoinContext(deviceKey)` exists because the wire key is `device_key` and the prop-facing name is `deviceKey`. Hand-writing `userContext={{ deviceKey }}` produces a bucket the server's device lookup does not read, and you get the silent-zero funnel instead of an error. This is the one place that spelling is decided.
+
+Skip the onboarding half and the purchase events are still valid on their own, they just cannot be attributed back to an onboarding.
+
+**Since 0.12.2 the kit fills the gap for you.** If `<WireOnboarding>` gets `storage` and a `userContext` with no `device_key`, it injects its own per-install key: the SAME id `createAnalytics` / `createWireActivation` mint and persist, read back from storage rather than minted fresh. So the default wiring joins, and the code block above is now about *overriding* the key rather than about remembering it.
+
+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.
+- **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.
+
 ## Feature controls (per-module kill switches)
 
 Every activation surface has a switch you can flip from the dashboard "in case of something":

package/dist/analytics/index.d.mts

@@ -1,6 +1,6 @@
-export { R as ReportAppEventOptions, r as reportAppEvent } from '../transport-BGW9uXZJ.mjs';
-import { W as WireUserContext, E as EventQueueOptions } from '../currentSession-C0_odnIW.mjs';
-export { A as AnalyticsEvent, C as ClearUserContextOptions, a as ClientEvent, b as ClientEventTarget, c as ClientEventType, d as ContextEnvelope, e as ContextEnvelopeInput, f as EnvelopeSource, g as EventQueue, h as WIRE_ONBOARDING_EVENTS, i as WireOnboardingEventName, j as analyticsUserIdStorageKey, k as buildContextEnvelope, l as clearPiiFromContext, m as clearUserContext, n as createEventQueue, o as getCurrentSessionId, p as looksLikeEmail, q as makeSessionId, r as reportClientEvent, s as reportClientEventAwait, t as reportClientEvents, u as reportClientEventsAwait, v as resetCurrentSessionId, w as setCurrentSessionId, x as toAnalyticsEvent } from '../currentSession-C0_odnIW.mjs';
+export { R as ReportAppEventOptions, r as reportAppEvent } from '../transport-CF_eHwzC.mjs';
+import { W as WireUserContext, E as EventQueueOptions } from '../currentSession-BlCeDP0f.mjs';
+export { A as AUTO_DEVICE_ID_PREFIX, a as AnalyticsEvent, C as ClearUserContextOptions, b as ClientEvent, c as ClientEventTarget, 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 resolveAutoDeviceKey, F as setCurrentSessionId, G as toAnalyticsEvent } from '../currentSession-BlCeDP0f.mjs';
 import '../types-CNUqMK0D.mjs';
 import '../types-BKfpdZzX.mjs';
 import '../types-BcmagF6K.mjs';
@@ -33,7 +33,12 @@ interface ScreenTrackerOptions {
         serverUrl: string;
         apiKey: string;
     };
-    /** The onboarding/session id to correlate screen views with, when known. */
+    /**
+     * The onboarding/session id to correlate screen views with, when known. Omitting it no longer
+     * means the view goes out WITHOUT a `session_id` (the server requires one and drops the event
+     * behind an HTTP 200 — that is why screen tracking silently produced nothing for a host that
+     * never mounted the lifecycle hook). `reportAppEvent` falls back to the current per-open id.
+     */
     sessionId?: string;
     /** A stable, non-PII device id — groups a device's sessions server-side. */
     deviceKey?: string;
@@ -103,8 +108,15 @@ type CreateAnalyticsConfig = {
     /** Tenant API key; sent as `Authorization: Bearer`. */
     apiKey: string;
     /**
-     * Correlation id shared by every event from this instance (and the `identify` event). Defaults
-     * to a fresh `makeSessionId()` at creation so all events agree on one id per analytics instance.
+     * ⚠️ OPT-OUT KNOB, not a default. Supplying a `sessionId` FREEZES the correlation id: every event
+     * this instance ever sends (including `identify`) is pinned to that one id, and the instance stops
+     * following the LIVE per-open session the server registered via `app.session_started`. Lifecycle
+     * analytics then collapse onto a single device-scoped session — one "first open", forever.
+     *
+     * OMIT IT — that is the correct default. Without it the kit reuses the live per-open session, and
+     * when no open has been registered yet it mints one AND registers it, so every later surface joins
+     * the same session instead of each inventing its own. Pass one ONLY if your host runs its own
+     * session lifecycle and owns the id the server should correlate on.
      */
     sessionId?: string;
     /** Tenant/app id used to namespace the queue's default storage key (`wireai:evtq:<appId>`). */

package/dist/analytics/index.d.ts

@@ -1,6 +1,6 @@
-export { R as ReportAppEventOptions, r as reportAppEvent } from '../transport-jUJd5kxu.js';
-import { W as WireUserContext, E as EventQueueOptions } from '../currentSession-DdnUq2HQ.js';
-export { A as AnalyticsEvent, C as ClearUserContextOptions, a as ClientEvent, b as ClientEventTarget, c as ClientEventType, d as ContextEnvelope, e as ContextEnvelopeInput, f as EnvelopeSource, g as EventQueue, h as WIRE_ONBOARDING_EVENTS, i as WireOnboardingEventName, j as analyticsUserIdStorageKey, k as buildContextEnvelope, l as clearPiiFromContext, m as clearUserContext, n as createEventQueue, o as getCurrentSessionId, p as looksLikeEmail, q as makeSessionId, r as reportClientEvent, s as reportClientEventAwait, t as reportClientEvents, u as reportClientEventsAwait, v as resetCurrentSessionId, w as setCurrentSessionId, x as toAnalyticsEvent } from '../currentSession-DdnUq2HQ.js';
+export { R as ReportAppEventOptions, r as reportAppEvent } from '../transport-DsRe4epC.js';
+import { W as WireUserContext, E as EventQueueOptions } from '../currentSession-BxEB37xt.js';
+export { A as AUTO_DEVICE_ID_PREFIX, a as AnalyticsEvent, C as ClearUserContextOptions, b as ClientEvent, c as ClientEventTarget, 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 resolveAutoDeviceKey, F as setCurrentSessionId, G as toAnalyticsEvent } from '../currentSession-BxEB37xt.js';
 import '../types-Buj9Lw9t.js';
 import '../types-BKfpdZzX.js';
 import '../types-BcmagF6K.js';
@@ -33,7 +33,12 @@ interface ScreenTrackerOptions {
         serverUrl: string;
         apiKey: string;
     };
-    /** The onboarding/session id to correlate screen views with, when known. */
+    /**
+     * The onboarding/session id to correlate screen views with, when known. Omitting it no longer
+     * means the view goes out WITHOUT a `session_id` (the server requires one and drops the event
+     * behind an HTTP 200 — that is why screen tracking silently produced nothing for a host that
+     * never mounted the lifecycle hook). `reportAppEvent` falls back to the current per-open id.
+     */
     sessionId?: string;
     /** A stable, non-PII device id — groups a device's sessions server-side. */
     deviceKey?: string;
@@ -103,8 +108,15 @@ type CreateAnalyticsConfig = {
     /** Tenant API key; sent as `Authorization: Bearer`. */
     apiKey: string;
     /**
-     * Correlation id shared by every event from this instance (and the `identify` event). Defaults
-     * to a fresh `makeSessionId()` at creation so all events agree on one id per analytics instance.
+     * ⚠️ OPT-OUT KNOB, not a default. Supplying a `sessionId` FREEZES the correlation id: every event
+     * this instance ever sends (including `identify`) is pinned to that one id, and the instance stops
+     * following the LIVE per-open session the server registered via `app.session_started`. Lifecycle
+     * analytics then collapse onto a single device-scoped session — one "first open", forever.
+     *
+     * OMIT IT — that is the correct default. Without it the kit reuses the live per-open session, and
+     * when no open has been registered yet it mints one AND registers it, so every later surface joins
+     * the same session instead of each inventing its own. Pass one ONLY if your host runs its own
+     * session lifecycle and owns the id the server should correlate on.
      */
     sessionId?: string;
     /** Tenant/app id used to namespace the queue's default storage key (`wireai:evtq:<appId>`). */