@wireai/activation 0.15.0 → 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.15.0.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}
     />
   );
 }
@@ -205,20 +245,22 @@ returns the same config. `options.appRoot` defaults to `process.cwd()`.
 
 `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
+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()}
@@ -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}
@@ -389,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
@@ -571,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
@@ -613,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
@@ -682,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" }
 ```
@@ -707,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),
@@ -745,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 |
 |---|---|
@@ -758,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
@@ -861,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",
@@ -955,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)));
@@ -1033,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";
 
@@ -1074,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
@@ -1170,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

package/dist/analytics/index.d.mts

@@ -1,6 +1,6 @@
 export { R as ReportAppEventOptions, r as reportAppEvent } from '../transport-s5QxA-ci.mjs';
-import { C as ClientEventTarget, W as WireUserContext, E as EventQueueOptions } from '../currentSession-orZy5p1e.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-orZy5p1e.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-Byx306Kv.mjs';
 import '../types-BKfpdZzX.mjs';
@@ -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 };

package/dist/analytics/index.d.ts

@@ -1,6 +1,6 @@
 export { R as ReportAppEventOptions, r as reportAppEvent } from '../transport-xqqSFqxs.js';
-import { C as ClientEventTarget, W as WireUserContext, E as EventQueueOptions } from '../currentSession-CFSRZ2wg.js';
-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-CFSRZ2wg.js';
+import { C as ClientEventTarget, W as WireUserContext, E as EventQueueOptions } from '../currentSession-z-CZ55ad.js';
+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-z-CZ55ad.js';
 import { W as WireOnboardingStorage } from '../types-BpwiRpA8.js';
 import '../types-tdATL5z0.js';
 import '../types-BKfpdZzX.js';
@@ -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 };