@wireai/activation 0.13.6-next.0 → 0.13.6

package/AGENTS.md

@@ -60,7 +60,7 @@ subpaths are optional secondary feature modules; import one only if you use it.
 | Prop | Type | Required | Notes |
 |---|---|---|---|
 | `config` | `WireOnboardingConfig` | yes | A2A transport + tenant. See the `config` fields table below. |
-| `onComplete` | `(result: { answers, raw }) => void` | yes | Terminal recap CTA tapped. Persist `answers` via your profile-update path, then navigate on. |
+| `onComplete` | `(result: OnboardingResult) => void` | yes | Terminal recap CTA tapped. Persist `answers` via your profile-update path, then navigate on. `result` always has `answers` + `raw`; since 0.13.6 it also carries `plan` (the backend's onboarding plan, AI path only) and `variant` (the assigned experiment arm) when the backend sent them. Both keys are ABSENT otherwise, so an integration written before 0.13.6 sees no change. The kit does not interpret either one: validate `plan` before applying it. |
 | `theme` | `Partial<OnboardingTheme>` | no | Colors + font family names + radius/spacing, deep-merged over a neutral default. For dark/light, pass a different theme per app theme-state. |
 | `components` | `WireAIComponent[]` | no | Override registered cards (default `onboardingComponents`). |
 | `illustrations` | `Record<string, ReactNode>` | no | Host artwork for `InterstitialCard`, keyed by name. `{ ...defaultIllustrations, ...myArt }`. |

package/CHANGELOG.md

@@ -3,6 +3,81 @@
 All notable changes to `@wireai/activation` (formerly `wireai-onboarding`).
 Historical entries below the rename keep the old package name on purpose.
 
+## [0.13.6] - 2026-08-09
+
+Two things the backend already decides, handed to the host instead of guessed at. Both ride the
+same boundary: the kit reads a payload the server sent, carries it out through `onComplete`, and
+stops. It does not interpret either one, does not validate their contents, does not log them and
+never attaches them to an analytics event.
+
+The `plan` half of this release was published as `0.13.6-next.0` on 2026-08-08 with no changelog
+entry. This entry is that debt paid, plus the `variant` half, released together as 0.13.6.
+
+### Added
+
+- **`OnboardingResult.plan`, the backend's onboarding plan reaching the host uninterpreted.**
+  On the AI path the server appends a SECOND A2A DataPart to the turn it finishes on,
+  `{ kind: "onboarding_plan", plan: {...} }`, alongside the component envelope the renderer already
+  consumes. A new pure reader, `src/utils/readPlan.ts`, lifts it off the thread and `handleFinish`
+  puts it on the result. The static (non-AI) flow carries no plan and is unchanged.
+
+  The one thing the reader is allowed to reject is a structural fact: a plan is an object. A scalar,
+  an array, a misspelled marker or a missing payload yields `undefined` and the host falls back to
+  exactly its pre-plan behaviour. No field is required and no unknown field is stripped, because a
+  kit-side schema would make the kit the thing that rejects a plan the host could have used, and the
+  server's lenient path adds markers the kit must neither read nor strip. **The host must validate
+  the payload before applying it.**
+
+  **It finds the plan by MARKER, never by position**, and that is the load-bearing part of the read.
+  The kit walks the thread newest turn first and, inside a turn, returns the first part whose `kind`
+  is `onboarding_plan` and whose payload is an object. Anything else is skipped rather than treated
+  as a terminator, so a thread carrying two plans resolves to the last one, the turn the flow
+  completes on, and a malformed part can never shadow a good one. Position would be the wrong tool
+  here: the SDK collects a task's parts across agent messages LATEST-FIRST, so on a task that
+  carries history a previous turn's envelope can sit in the same array as this turn's plan. The
+  marker makes that harmless, and it is also why nothing in this pipe promises wire order.
+
+  It needs an SDK that surfaces the DataParts PAST the first one. The first DataPart is the
+  component envelope the renderer already consumes, and it is the one the SDK turns into the string
+  it returns for the turn, so the plan is one of the parts left behind after it.
+  `wireai-rn@0.2.5-next.1` hands those over on `Message.dataParts`, and a turn that carried nothing
+  but the envelope leaves the member ABSENT rather than an empty array (checked against the
+  published tarball, not against a paraphrase of it). The peer range here is unchanged at `>=0.2.3`,
+  so this degrades rather than breaks: an older SDK, `0.2.4` included, sets no `dataParts`, the kit
+  reads no plan, and the host lands on exactly the path a tenant that sends none already takes.
+
+- **`OnboardingResult.variant`, the experiment arm the backend assigned, surfaced to the host.**
+  The server rides the arm key on the render envelope at `props.progress.variant`, a sibling of
+  `step` / `total` / `key` / `slot_id`. The kit had no way to hand it over, so a host that wanted to
+  branch on the arm had to INFER it from the shape of the flow (counting answers against a
+  hard-coded maximum), an inference that goes silently wrong the day the server changes a flow
+  length.
+
+  `readProgress` whitelists `variant` exactly the way it already whitelists `slot_id`: a non-string
+  or absent key reads as "no experiment", never as an error. `OnboardingFlow` latches the arm at
+  first sight into a ref that is never cleared, because the assignment is sticky per session but
+  only rides the render envelope, and a later card that omits it must not un-assign it.
+
+  It is also available DURING the flow: the `turn` event carries `variant` from the first card that
+  declares one onwards, reusing an event hosts already subscribe to instead of adding a prop for a
+  scalar. What an arm key MEANS is the host's decision; the kit does not map it to a name, brand it,
+  default it or log it. **It is deliberately never attached to an analytics event either**, on
+  either surface, so a host that wants arm-segmented funnels has to put the arm on its own events.
+
+### Unchanged
+
+- **Both keys are byte-identical no-ops when the backend sends nothing.** `plan` and `variant` are
+  each set on the result ONLY when one was actually seen, so a run without them leaves
+  `Object.keys(result)` as `["answers", "raw"]` and `"plan" in result` / `"variant" in result`
+  false. Setting a key to `undefined` would pass an `=== undefined` check while breaking every host
+  deep-equality assertion, so the canaries assert the KEY SET, not the value. The same rule governs
+  the `turn` event.
+- **Neither read can throw.** Both sit on the single code path to `onComplete`, where a throw would
+  cost the user the completion of an onboarding they already finished. Every read is runtime-guarded
+  and `readPlan` declares its own structural type rather than casting: an `as` cast silences the
+  compiler in both directions, including the day the published SDK type disagrees.
+- No new runtime dependency, no export renamed or removed, no change to the exports map.
+
 ## [0.13.5] - 2026-08-03
 
 Two halves of one idea: stop finding out about a broken events integration from a funnel report.
@@ -866,7 +941,11 @@ true, and pins the wire with tests.
 - Version reset to `0.1.0` to mark the start of the new package line. The GitHub repository
   stays `chohra-med/wireai-onboarding`.
 
-## [Unreleased]
+## [0.9.0] — 2026-07-17
+
+*This section carried the title `[Unreleased]` until 2026-08-09, long after it shipped. Everything
+below went out in 0.9.0; the three analytics/device items it also held belong to 0.8.0 and have been
+moved to their own section under this one.*
 
 ### Added: `fetchReviewDecision` — the kit now owns the review firing decision (live user harm)
 
@@ -1025,6 +1104,11 @@ All four from Malik's on-device test, 2026-07-16. The **review** gate's chrome i
   button. The 5-star → native store review route (`routeRating`) is untouched.
 - `theme/mergeThemeOver` extracts the helper both gates had copy-pasted.
 
+## [0.8.0] — 2026-07-15
+
+*Also mis-filed under `[Unreleased]` until 2026-08-09. These three items shipped in 0.8.0, one
+release before everything in the section above.*
+
 ### Added: "device" is now fully automatic — auto-minted, persisted per-install `device_key`
 
 - The analytics façade (`createAnalytics`) now auto-mints a stable, NON-PII per-install `device_key`
@@ -1058,7 +1142,7 @@ All four from Malik's on-device test, 2026-07-16. The **review** gate's chrome i
 - Backward compatible: no existing export renamed or removed; zero new dependencies. The one
   behavior change is intentional — events now carry an auto `device_key` when the host omits one.
 
-## [0.7.0] — Unreleased
+## [0.7.0] — 2026-07-15
 
 ### Added: `WireUserContext` — one rich user-context object → every event's `user_context`
 
@@ -1439,7 +1523,7 @@ All four from Malik's on-device test, 2026-07-16. The **review** gate's chrome i
   `showcaseColorsFromTheme(theme, accent)` (new `src/showcase/showcaseColors.ts`) with a
   regression test asserting the primary button is the accent and never the background.
 
-## [0.3.0] — Unreleased
+## [0.3.0] — 2026-07-12
 
 > Pending release. `0.2.1` is already published on npm (coachmarks + showcase, no
 > identity API), so this identity surface — alongside the unpublished `/reviews`

package/README.md

@@ -231,7 +231,7 @@ import { WireOnboarding } from "@wireai/activation";
 | Prop | Type | Notes |
 |---|---|---|
 | `config` | `{ apiKey, serverUrl, appId, metadata?, appVersion? }` | A2A transport; the key resolves the tenant server-side. `appVersion` is host-injected (e.g. `Constants.expoConfig?.version`) and forwarded for analytics segmentation. **Required.** |
-| `onComplete` | `(result: { answers, raw }) => void` | Fires when the user taps the terminal recap's CTA. **Required.** |
+| `onComplete` | `(result: OnboardingResult) => void` | Fires when the user taps the terminal recap's CTA. `result` always carries `answers` and `raw`. Since 0.13.6 it may also carry `plan` (the backend's onboarding plan, AI path only) and `variant` (the experiment arm the backend assigned, when the tenant runs one). Each of those two keys is set ONLY when the backend actually sent one, so a run without them returns exactly the object earlier versions returned: `"plan" in result` and `"variant" in result` both stay false. The kit does not interpret either: **validate `plan` before you apply it.** **Required.** |
 | `theme` | `Partial<OnboardingTheme>` | Brand colors/fonts/radius/spacing, deep-merged over a neutral default. |
 | `illustrations` | `Record<string, ReactNode>` | App artwork for `InterstitialCard`, keyed by name. |
 | `icons` | `Record<string, ReactNode>` | Your own icon nodes, keyed by the semantic name the AI emits (`{ instagram: <BrandIg/> }`). Checked first, so use it to put your brand mark on a choice card, to add names the vocabulary does not carry, or to get icons at all without installing `@expo/vector-icons`. Anything you leave out falls back to that optional peer, then to no icon. Never a crash. See [Icons](#icons). |
@@ -241,7 +241,7 @@ import { WireOnboarding } from "@wireai/activation";
 | `onError` | `(err) => void` | Backend error or first-card timeout, fired **after retries are exhausted**, not on the first failure. When `fallbackFlow` is not supplied, the host owns recovery (e.g. route to a static flow). With neither, the kit shows an inline retry. `fallbackFlow` takes precedence over this. |
 | `fallbackFlow` | `ReactNode` | Your predefined STATIC onboarding, rendered in place once the AI flow fails and retries are exhausted. **Takes precedence over `onError`.** This is the "it can never break your onboarding" guarantee: pass the same flow you shipped before adding Wire AI and the user always keeps moving. |
 | `maxRetries` | `number` | Consecutive failures to auto-retry before degrading to `fallbackFlow`/`onError`. Default `1` (one silent retry, then degrade). `0` degrades on the first failure. Budget it deliberately: each retry restarts the flow, so with `startTimeoutMs` at its `15000` default the default `maxRetries` puts 30s of loader in front of a user before they see the fallback. A retry also sends a skip sentinel, so the user loses one question and a retry is never recorded as their first answer. |
-| `onEvent` | `(e: OnboardingEvent) => void` | `started` / `turn` / `error` — recover per-turn analytics since the kit owns the loop. |
+| `onEvent` | `(e: OnboardingEvent) => void` | `started` / `resumed` / `turn` / `error` / `retry` / `fallback` / `permission`, the full union in `OnboardingEvent`. Recover per-turn analytics since the kit owns the loop. See the note under the helpers table. |
 | `copy` | `Partial<OnboardingCopy>` | Localize the kit's built-in English loader/completion strings. |
 | `approxScreens` | `number` | Approx total screens — paces the bar as `step/total` (capped, never shown). A backend `progress.total` (the screen budget, sent every turn incl. init) wins, so usually unnecessary. |
 | `components` | `WireAIComponent[]` | Override the registered cards (defaults to `onboardingComponents`). |
@@ -271,7 +271,7 @@ You rarely hand-roll config, gating, analytics, or attribution — the kit ships
 | `themeFromBrand({ primary })` · `defaultIllustrations` | One-color theme; dependency-free fallback artwork. |
 | `motionSpec` | The motion constants behind every kit animation (durations, springs, the design ease). Read-only for hosts. `setMotionDurationScale` / `getMotionDurationScale` are QA tools for the playground's animation-speed knob: never call them in production code. |
 
-> **`onEvent`** fires `started` / `resumed` / `turn` / `error` / `retry` / `fallback` (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. 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)).
+> **`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.
 
@@ -1310,49 +1310,47 @@ then *improve* Wire AI, not just eyeball it.
 
 ### MCP server (`mcp/`)
 
-A local Model Context Protocol server (`@wireai/mcp`, stdio, TypeScript). It is a
-repo-local dev tool — **not** published to npm (excluded from the package `files`
-allowlist). Build it in place:
+A Model Context Protocol server (`@wireai/mcp`, TypeScript) that exposes the whole
+onboarding control plane as agent tools. It runs two ways, same tools either way:
 
-```bash
-cd mcp && npm install && npm run build
-```
-
-Then add it to your agent client's MCP config:
+1. **Hosted, and this is the default.** `https://wireai-mcp.fly.dev/mcp` over Streamable
+   HTTP. You authenticate per request with an `Authorization: Bearer` header, so there is
+   no build step, no login step, and nothing on disk.
+2. **Local stdio.** `cd mcp && npm install && npm run build`, then point your client at
+   `mcp/dist/index.js`. Auth is a one-time `node dist/index.js login`, or raw keys via
+   `WIREAI_SERVER_URL` / `WIREAI_API_KEY` / `WIREAI_ADMIN_KEY`. This package is repo-local
+   and **not** published to npm (it is excluded from the kit's `files` allowlist).
 
 ```json
 {
   "mcpServers": {
     "wireai": {
-      "command": "node",
-      "args": ["<abs-path>/@wireai/activation/mcp/dist/index.js"],
-      "env": {
-        "WIREAI_SERVER_URL": "https://<your-backend>.fly.dev",
-        "WIREAI_API_KEY": "wai_<tenant-key>",
-        "WIREAI_ADMIN_KEY": "wai_admin_<operator-key>"
-      }
+      "type": "http",
+      "url": "https://wireai-mcp.fly.dev/mcp",
+      "headers": { "Authorization": "Bearer <your-token>" }
     }
   }
 }
 ```
 
-Tools (P1 is read-biased; the only writes are the existing register/update):
+**Three credential classes, and you probably want the third.** A tenant `wai_` key reads
+your own app's funnel and files learning reports. The operator admin key reaches the
+cross-tenant management surface. A **client console token** (minted from a Wire console
+session) drives your own apps over the `/v1/me/*` console routes, which means a customer
+runs the full management surface from an agent *without* holding the platform admin key.
 
-| Tool | Auth key | Does |
-|---|---|---|
-| `wireai_get_integration_guide` | none | the current integration recipe |
-| `wireai_list_components` | none | the card vocabulary |
-| `wireai_get_insights` | tenant `WIREAI_API_KEY` | **read** the funnel brief (`/v1/insights.md`), app resolved from the key; a valid "no data yet" brief when empty |
-| `wireai_get_onboarding_config` | admin `WIREAI_ADMIN_KEY` | **read** the live generation config (context, first question, allowed components) |
-| `wireai_register_onboarding_app` | admin `WIREAI_ADMIN_KEY` | create an app + get its key |
-| `wireai_list_onboarding_apps` | admin `WIREAI_ADMIN_KEY` | list apps |
-| `wireai_get_onboarding_app` | admin `WIREAI_ADMIN_KEY` | one app's raw record |
-| `wireai_update_onboarding_app` | admin `WIREAI_ADMIN_KEY` | patch config, no release |
-| `wireai_get_onboarding_analytics` | admin `WIREAI_ADMIN_KEY` | funnel JSON |
-| `wireai_list_reviews` | admin `WIREAI_ADMIN_KEY` | **read** in-app reviews across tenants (stars, feedback, contact) |
-
-Least privilege: for the read-only loop, hand the agent just `WIREAI_SERVER_URL` +
-`WIREAI_API_KEY` (tenant) and skip the admin key. Full detail: [`mcp/README.md`](./mcp/README.md).
+**Where the tool list lives.** Ask the server: a connected client's `tools/list` is the
+only copy that is current by construction, and it is already scoped to the credential you
+presented. `wireai_get_integration_guide` needs no auth at all and returns the recipe.
+Inside the repo the written table is `mcp/README.md`, and `mcp/src/toolAccess.test.ts`
+re-derives it from the handlers and goes red when the two disagree.
+
+This section deliberately does not restate that table. It used to, and the copy drifted to
+10 tools of 21 with a "the only writes are register/update" line the code had stopped
+honouring, because nothing gated it. A duplicated list with no test on it goes stale.
+
+Least privilege still applies: for the read-only improve loop, hand the agent a tenant
+credential and skip the admin key entirely.
 
 ### `wire-ai` skill (`.claude/skills/wire-ai`)
 

package/dist/analytics/index.d.mts

@@ -1,6 +1,6 @@
 export { R as ReportAppEventOptions, r as reportAppEvent } from '../transport-j5gFfJhK.mjs';
-import { C as ClientEventTarget, W as WireUserContext, E as EventQueueOptions } from '../currentSession-Cs3lweFZ.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-Cs3lweFZ.mjs';
+import { C as ClientEventTarget, W as WireUserContext, E as EventQueueOptions } from '../currentSession-DngW-QoD.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-DngW-QoD.mjs';
 import { W as WireOnboardingStorage } from '../types-BpwiRpA8.mjs';
 import '../types-Cju-1_jT.mjs';
 import '../types-BKfpdZzX.mjs';

package/dist/analytics/index.d.ts

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

package/dist/{currentSession-DD6dKB0i.d.ts → currentSession-C5976akx.d.ts}

@@ -484,6 +484,16 @@ type OnboardingResult = {
      * the host's decision, not the kit's.
      */
     plan?: unknown;
+    /**
+     * The experiment ARM the backend assigned this session, when it is running one. Absent when
+     * the tenant runs no experiment, which is the common case, and absent is NOT an error.
+     * The kit does NOT interpret it, does not log it, does not brand it and never attaches it
+     * to an analytics event. What an arm key MEANS is the host's decision.
+     *
+     * Like {@link plan}, the KEY is set only when an arm was actually seen, so a run with no
+     * experiment leaves the result byte-identical to what every host already reads.
+     */
+    variant?: string;
 };
 /**
  * Lifecycle events emitted as the flow runs, for host-side analytics. The kit owns
@@ -495,7 +505,11 @@ type OnboardingResult = {
  *  - `resumed`: a persisted session was restored after an app kill (fires INSTEAD of
  *               `started`, so host funnels don't double-count the same session). Also carries
  *               `contextId`. Requires the `storage` prop.
- *  - `turn`: a new assistant card arrived (`step` = 1-based index of cards seen).
+ *  - `turn`: a new assistant card arrived (`step` = 1-based index of cards seen). Carries
+ *               `variant`, the backend's experiment arm for this session, from the first card that
+ *               declared one onwards — this is how the arm is available DURING the flow rather than
+ *               only at completion. The key is absent whenever no arm has been seen, which is every
+ *               turn of every tenant running no experiment.
  *  - `error`: the backend errored or the first-card watchdog timed out.
  *  - `retry`: a transient failure is being auto-retried (`attempt` = 1-based).
  *  - `fallback`: retries are exhausted; the kit degraded to the static `fallbackFlow`
@@ -516,6 +530,7 @@ type OnboardingEvent = {
     type: "turn";
     step: number;
     component?: string;
+    variant?: string;
 } | {
     type: "error";
     reason: "backend" | "timeout";
@@ -790,6 +805,17 @@ type OnboardingProgress = {
     slot_id?: string;
     /** Whether the CURRENT screen may be skipped (backend-marked; default false → no Skip shown). */
     skippable?: boolean;
+    /**
+     * The EXPERIMENT ARM the backend assigned this session, when the tenant is running one. Rides the
+     * render envelope as a sibling of {@link step}/{@link total}/{@link key}/{@link slot_id}, and is
+     * OMITTED entirely for a tenant running no experiment — which is the common case, and is not an
+     * error. The assignment is sticky for the session, so a later card that omits it does not
+     * un-assign it.
+     *
+     * The kit does NOT interpret this. It is whitelisted, latched and handed to the host exactly as
+     * received; what an arm key MEANS is the host's decision. See {@link OnboardingResult.variant}.
+     */
+    variant?: string;
 };
 
 /**

package/dist/{currentSession-Cs3lweFZ.d.mts → currentSession-DngW-QoD.d.mts}

@@ -484,6 +484,16 @@ type OnboardingResult = {
      * the host's decision, not the kit's.
      */
     plan?: unknown;
+    /**
+     * The experiment ARM the backend assigned this session, when it is running one. Absent when
+     * the tenant runs no experiment, which is the common case, and absent is NOT an error.
+     * The kit does NOT interpret it, does not log it, does not brand it and never attaches it
+     * to an analytics event. What an arm key MEANS is the host's decision.
+     *
+     * Like {@link plan}, the KEY is set only when an arm was actually seen, so a run with no
+     * experiment leaves the result byte-identical to what every host already reads.
+     */
+    variant?: string;
 };
 /**
  * Lifecycle events emitted as the flow runs, for host-side analytics. The kit owns
@@ -495,7 +505,11 @@ type OnboardingResult = {
  *  - `resumed`: a persisted session was restored after an app kill (fires INSTEAD of
  *               `started`, so host funnels don't double-count the same session). Also carries
  *               `contextId`. Requires the `storage` prop.
- *  - `turn`: a new assistant card arrived (`step` = 1-based index of cards seen).
+ *  - `turn`: a new assistant card arrived (`step` = 1-based index of cards seen). Carries
+ *               `variant`, the backend's experiment arm for this session, from the first card that
+ *               declared one onwards — this is how the arm is available DURING the flow rather than
+ *               only at completion. The key is absent whenever no arm has been seen, which is every
+ *               turn of every tenant running no experiment.
  *  - `error`: the backend errored or the first-card watchdog timed out.
  *  - `retry`: a transient failure is being auto-retried (`attempt` = 1-based).
  *  - `fallback`: retries are exhausted; the kit degraded to the static `fallbackFlow`
@@ -516,6 +530,7 @@ type OnboardingEvent = {
     type: "turn";
     step: number;
     component?: string;
+    variant?: string;
 } | {
     type: "error";
     reason: "backend" | "timeout";
@@ -790,6 +805,17 @@ type OnboardingProgress = {
     slot_id?: string;
     /** Whether the CURRENT screen may be skipped (backend-marked; default false → no Skip shown). */
     skippable?: boolean;
+    /**
+     * The EXPERIMENT ARM the backend assigned this session, when the tenant is running one. Rides the
+     * render envelope as a sibling of {@link step}/{@link total}/{@link key}/{@link slot_id}, and is
+     * OMITTED entirely for a tenant running no experiment — which is the common case, and is not an
+     * error. The assignment is sticky for the session, so a later card that omits it does not
+     * un-assign it.
+     *
+     * The kit does NOT interpret this. It is whitelisted, latched and handed to the host exactly as
+     * received; what an arm key MEANS is the host's decision. See {@link OnboardingResult.variant}.
+     */
+    variant?: string;
 };
 
 /**

package/dist/index.d.mts

@@ -1,7 +1,7 @@
 import * as React from 'react';
 import React__default, { ReactNode } from 'react';
-import { I as WireOnboardingProps, J as WireOnboardingConfig, O as OnboardingResult, K as WirePermissionStatus, P as PermissionStage, L as WirePermissionOutcome, S as StepValidator, M as OnboardingEvent, N as OnboardingCopy, C as ClientEventTarget, Q as DeviceContext, T as PermissionScreenConfig, W as WireUserContext, U as PermissionPlacement, c as ClientEvent, g as EnvelopeSource } from './currentSession-Cs3lweFZ.mjs';
-export { A as AUTO_DEVICE_ID_PREFIX, a as AnalyticsEvent, b as ClearUserContextOptions, d as ClientEventType, V as DEFAULT_PERMISSION_COPY, X as DeviceFormFactor, D as DeviceKeyStorage, Y as EXTRA_KEY_PREFIX, Z as GENERIC_PERMISSION_COPY, _ as IdentifyOnboardingBinding, $ as IdentifyOnboardingOptions, a0 as IdentityRecord, a1 as IdentitySource, a2 as IdentitySpace, a3 as NOTIFICATIONS_PERMISSION_COPY, a4 as OnboardingProgress, a5 as PermissionScreenCopy, R as ResolveAutoDeviceKeyOptions, a6 as ResolveUserContextOptions, a7 as ResolvedUserContext, a8 as USER_ID_MAX_LENGTH, i as WIRE_ONBOARDING_EVENTS, a9 as WIRE_PERMISSION_EVENTS, j as WireOnboardingEventName, aa as WirePermissionEventName, ab as WirePermissionKind, ac as activationJoinContext, k as analyticsUserIdStorageKey, m as clearPiiFromContext, n as clearUserContext, ad as collectDeviceContext, p as deviceIdStorageKey, q as ensureCurrentSessionId, r as getCurrentSessionId, ae as hashEmailFnv1a, af as hostIdentity, ag as hydrateAutoDeviceKey, ah as hydrateDeviceIdentity, ai as identifyOnboarding, aj as isWireScalar, s as looksLikeEmail, t as makeSessionId, ak as mintDeviceId, al as namespaceExtra, am as normalizePermissionStatus, an as permissionEventName, ao as permissionEventProps, u as reportClientEvent, v as reportClientEventAwait, w as reportClientEvents, x as reportClientEventsAwait, y as resetAutoDeviceKeys, z as resetCurrentSessionId, ap as resetIdentityProvenance, F as resolveAutoDeviceKey, aq as resolveIdentity, ar as resolvePermissionCopy, as as resolveUserContext, at as sanitizeUserId, G as setCurrentSessionId, H as toAnalyticsEvent } from './currentSession-Cs3lweFZ.mjs';
+import { I as WireOnboardingProps, J as WireOnboardingConfig, O as OnboardingResult, K as WirePermissionStatus, P as PermissionStage, L as WirePermissionOutcome, S as StepValidator, M as OnboardingEvent, N as OnboardingCopy, C as ClientEventTarget, Q as DeviceContext, T as PermissionScreenConfig, W as WireUserContext, U as PermissionPlacement, c as ClientEvent, g as EnvelopeSource } from './currentSession-DngW-QoD.mjs';
+export { A as AUTO_DEVICE_ID_PREFIX, a as AnalyticsEvent, b as ClearUserContextOptions, d as ClientEventType, V as DEFAULT_PERMISSION_COPY, X as DeviceFormFactor, D as DeviceKeyStorage, Y as EXTRA_KEY_PREFIX, Z as GENERIC_PERMISSION_COPY, _ as IdentifyOnboardingBinding, $ as IdentifyOnboardingOptions, a0 as IdentityRecord, a1 as IdentitySource, a2 as IdentitySpace, a3 as NOTIFICATIONS_PERMISSION_COPY, a4 as OnboardingProgress, a5 as PermissionScreenCopy, R as ResolveAutoDeviceKeyOptions, a6 as ResolveUserContextOptions, a7 as ResolvedUserContext, a8 as USER_ID_MAX_LENGTH, i as WIRE_ONBOARDING_EVENTS, a9 as WIRE_PERMISSION_EVENTS, j as WireOnboardingEventName, aa as WirePermissionEventName, ab as WirePermissionKind, ac as activationJoinContext, k as analyticsUserIdStorageKey, m as clearPiiFromContext, n as clearUserContext, ad as collectDeviceContext, p as deviceIdStorageKey, q as ensureCurrentSessionId, r as getCurrentSessionId, ae as hashEmailFnv1a, af as hostIdentity, ag as hydrateAutoDeviceKey, ah as hydrateDeviceIdentity, ai as identifyOnboarding, aj as isWireScalar, s as looksLikeEmail, t as makeSessionId, ak as mintDeviceId, al as namespaceExtra, am as normalizePermissionStatus, an as permissionEventName, ao as permissionEventProps, u as reportClientEvent, v as reportClientEventAwait, w as reportClientEvents, x as reportClientEventsAwait, y as resetAutoDeviceKeys, z as resetCurrentSessionId, ap as resetIdentityProvenance, F as resolveAutoDeviceKey, aq as resolveIdentity, ar as resolvePermissionCopy, as as resolveUserContext, at as sanitizeUserId, G as setCurrentSessionId, H as toAnalyticsEvent } from './currentSession-DngW-QoD.mjs';
 import { O as OnboardingTheme } from './types-BKfpdZzX.mjs';
 export { a as OnboardingButtonStyle, b as OnboardingColors, c as OnboardingFonts, d as OnboardingRadius, e as OnboardingSpacing } from './types-BKfpdZzX.mjs';
 export { C as CenteredModal, a as CenteredModalHandle, b as CenteredModalProps } from './CenteredModal-C3qQBHsA.mjs';
@@ -1286,6 +1286,8 @@ type PartialProgress = {
     /** The stable per-slot identity, when the backend sends one. See `OnboardingProgress.slot_id`. */
     slot_id?: string;
     skippable?: boolean;
+    /** The experiment arm assigned to this session, when the tenant runs one. See `OnboardingProgress.variant`. */
+    variant?: string;
 };
 declare const readProgress: (response?: WireAIResponse) => PartialProgress;
 

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import * as React from 'react';
 import React__default, { ReactNode } from 'react';
-import { I as WireOnboardingProps, J as WireOnboardingConfig, O as OnboardingResult, K as WirePermissionStatus, P as PermissionStage, L as WirePermissionOutcome, S as StepValidator, M as OnboardingEvent, N as OnboardingCopy, C as ClientEventTarget, Q as DeviceContext, T as PermissionScreenConfig, W as WireUserContext, U as PermissionPlacement, c as ClientEvent, g as EnvelopeSource } from './currentSession-DD6dKB0i.js';
-export { A as AUTO_DEVICE_ID_PREFIX, a as AnalyticsEvent, b as ClearUserContextOptions, d as ClientEventType, V as DEFAULT_PERMISSION_COPY, X as DeviceFormFactor, D as DeviceKeyStorage, Y as EXTRA_KEY_PREFIX, Z as GENERIC_PERMISSION_COPY, _ as IdentifyOnboardingBinding, $ as IdentifyOnboardingOptions, a0 as IdentityRecord, a1 as IdentitySource, a2 as IdentitySpace, a3 as NOTIFICATIONS_PERMISSION_COPY, a4 as OnboardingProgress, a5 as PermissionScreenCopy, R as ResolveAutoDeviceKeyOptions, a6 as ResolveUserContextOptions, a7 as ResolvedUserContext, a8 as USER_ID_MAX_LENGTH, i as WIRE_ONBOARDING_EVENTS, a9 as WIRE_PERMISSION_EVENTS, j as WireOnboardingEventName, aa as WirePermissionEventName, ab as WirePermissionKind, ac as activationJoinContext, k as analyticsUserIdStorageKey, m as clearPiiFromContext, n as clearUserContext, ad as collectDeviceContext, p as deviceIdStorageKey, q as ensureCurrentSessionId, r as getCurrentSessionId, ae as hashEmailFnv1a, af as hostIdentity, ag as hydrateAutoDeviceKey, ah as hydrateDeviceIdentity, ai as identifyOnboarding, aj as isWireScalar, s as looksLikeEmail, t as makeSessionId, ak as mintDeviceId, al as namespaceExtra, am as normalizePermissionStatus, an as permissionEventName, ao as permissionEventProps, u as reportClientEvent, v as reportClientEventAwait, w as reportClientEvents, x as reportClientEventsAwait, y as resetAutoDeviceKeys, z as resetCurrentSessionId, ap as resetIdentityProvenance, F as resolveAutoDeviceKey, aq as resolveIdentity, ar as resolvePermissionCopy, as as resolveUserContext, at as sanitizeUserId, G as setCurrentSessionId, H as toAnalyticsEvent } from './currentSession-DD6dKB0i.js';
+import { I as WireOnboardingProps, J as WireOnboardingConfig, O as OnboardingResult, K as WirePermissionStatus, P as PermissionStage, L as WirePermissionOutcome, S as StepValidator, M as OnboardingEvent, N as OnboardingCopy, C as ClientEventTarget, Q as DeviceContext, T as PermissionScreenConfig, W as WireUserContext, U as PermissionPlacement, c as ClientEvent, g as EnvelopeSource } from './currentSession-C5976akx.js';
+export { A as AUTO_DEVICE_ID_PREFIX, a as AnalyticsEvent, b as ClearUserContextOptions, d as ClientEventType, V as DEFAULT_PERMISSION_COPY, X as DeviceFormFactor, D as DeviceKeyStorage, Y as EXTRA_KEY_PREFIX, Z as GENERIC_PERMISSION_COPY, _ as IdentifyOnboardingBinding, $ as IdentifyOnboardingOptions, a0 as IdentityRecord, a1 as IdentitySource, a2 as IdentitySpace, a3 as NOTIFICATIONS_PERMISSION_COPY, a4 as OnboardingProgress, a5 as PermissionScreenCopy, R as ResolveAutoDeviceKeyOptions, a6 as ResolveUserContextOptions, a7 as ResolvedUserContext, a8 as USER_ID_MAX_LENGTH, i as WIRE_ONBOARDING_EVENTS, a9 as WIRE_PERMISSION_EVENTS, j as WireOnboardingEventName, aa as WirePermissionEventName, ab as WirePermissionKind, ac as activationJoinContext, k as analyticsUserIdStorageKey, m as clearPiiFromContext, n as clearUserContext, ad as collectDeviceContext, p as deviceIdStorageKey, q as ensureCurrentSessionId, r as getCurrentSessionId, ae as hashEmailFnv1a, af as hostIdentity, ag as hydrateAutoDeviceKey, ah as hydrateDeviceIdentity, ai as identifyOnboarding, aj as isWireScalar, s as looksLikeEmail, t as makeSessionId, ak as mintDeviceId, al as namespaceExtra, am as normalizePermissionStatus, an as permissionEventName, ao as permissionEventProps, u as reportClientEvent, v as reportClientEventAwait, w as reportClientEvents, x as reportClientEventsAwait, y as resetAutoDeviceKeys, z as resetCurrentSessionId, ap as resetIdentityProvenance, F as resolveAutoDeviceKey, aq as resolveIdentity, ar as resolvePermissionCopy, as as resolveUserContext, at as sanitizeUserId, G as setCurrentSessionId, H as toAnalyticsEvent } from './currentSession-C5976akx.js';
 import { O as OnboardingTheme } from './types-BKfpdZzX.js';
 export { a as OnboardingButtonStyle, b as OnboardingColors, c as OnboardingFonts, d as OnboardingRadius, e as OnboardingSpacing } from './types-BKfpdZzX.js';
 export { C as CenteredModal, a as CenteredModalHandle, b as CenteredModalProps } from './CenteredModal-Cdgns6--.js';
@@ -1286,6 +1286,8 @@ type PartialProgress = {
     /** The stable per-slot identity, when the backend sends one. See `OnboardingProgress.slot_id`. */
     slot_id?: string;
     skippable?: boolean;
+    /** The experiment arm assigned to this session, when the tenant runs one. See `OnboardingProgress.variant`. */
+    variant?: string;
 };
 declare const readProgress: (response?: WireAIResponse) => PartialProgress;
 

package/dist/index.js

@@ -1161,7 +1161,10 @@ var readProgress = (response) => {
     key: typeof p.key === "string" ? p.key : void 0,
     // Whitelisted the same way as every other field: an old backend simply omits it.
     slot_id: typeof p.slot_id === "string" ? p.slot_id : void 0,
-    skippable: typeof p.skippable === "boolean" ? p.skippable : void 0
+    skippable: typeof p.skippable === "boolean" ? p.skippable : void 0,
+    // Whitelisted like the rest: a non-string (or absent) arm key reads as "no experiment", never
+    // as an error. The kit does not interpret the value — see `OnboardingProgress.variant`.
+    variant: typeof p.variant === "string" ? p.variant : void 0
   };
 };
 
@@ -1703,6 +1706,7 @@ var OnboardingFlow = ({
   const clientContextRef = React19.useRef(clientContext);
   clientContextRef.current = clientContext;
   const lastScreenIndexRef = React19.useRef(-1);
+  const variantRef = React19.useRef(void 0);
   const previewTimer = React19.useRef(null);
   const [runId, setRunId] = React19.useState(0);
   const startedRunRef = React19.useRef(-1);
@@ -1752,14 +1756,17 @@ var OnboardingFlow = ({
   React19.useEffect(() => {
     var _a2, _b2, _c2, _d2;
     setValidationError(void 0);
+    if (variantRef.current === void 0 && progress.variant) variantRef.current = progress.variant;
     if (!(lastCard == null ? void 0 : lastCard.id)) return;
     const step2 = (_a2 = progress.step) != null ? _a2 : renderedCount;
     lastScreenIndexRef.current = Math.max(0, step2 - 1);
-    (_c2 = onEventRef.current) == null ? void 0 : _c2.call(onEventRef, {
+    const turn = {
       type: "turn",
       step: step2,
       component: (_b2 = lastCard.response) == null ? void 0 : _b2.component
-    });
+    };
+    if (variantRef.current !== void 0) turn.variant = variantRef.current;
+    (_c2 = onEventRef.current) == null ? void 0 : _c2.call(onEventRef, turn);
     if (((_d2 = lastCard.response) == null ? void 0 : _d2.component) === "InterstitialCard") {
       sendPreview(reportTargetRef.current, {
         sessionId: sessionIdRef.current,
@@ -1820,6 +1827,7 @@ var OnboardingFlow = ({
     const result = { answers: deriveAnswers(messages), raw: messages };
     const plan = readPlan(messages);
     if (plan !== void 0) result.plan = plan;
+    if (variantRef.current !== void 0) result.variant = variantRef.current;
     onCompleteRef.current(result);
   }, [messages]);
   const handleRetry = React19.useCallback(() => {