@wireai/activation 0.8.0 → 0.9.0

package/AGENTS.md

@@ -12,10 +12,17 @@ A **drop-in mobile-app onboarding kit** over the OSS `wireai-rn` SDK. One compon
 themed native cards (chosen by an LLM, one per turn over A2A), a progress bar, a mid-flow
 value screen, per-step validation, and a completion recap, ending with the user's
 structured answers for the app to persist. The host supplies a tenant config, a theme,
-and brand artwork; the kit owns the flow. **Nearly pure JS (no reanimated, no SVG/icon
-deps).** Peers: `react`, `react-native`, `wireai-rn`, `zod`, and `react-native-safe-area-context`
-(>=4.0.0, for safe-area insets; the host must render a `SafeAreaProvider` ancestor, which
-every Expo/RN app already ships).
+and brand artwork; the kit owns the flow. **Nearly pure JS: no REQUIRED reanimated, SVG, or
+icon dependency.** Required peers: `react`, `react-native`, `wireai-rn`, `zod`, and
+`react-native-safe-area-context` (>=4.0.0, for safe-area insets; the host must render a
+`SafeAreaProvider` ancestor, which every Expo/RN app already ships).
+
+**Optional peers** are never installed for you and never trigger a native rebuild. Each is
+lazily resolved and degrades to a defined no-op when absent: `@expo/vector-icons` (>=14, real
+icons on the choice cards; absent → those cards simply render without icons),
+`expo-store-review`, `expo-haptics`, `expo-blur`, `react-native-reanimated`,
+`@blazejkustra/react-native-onboarding`. You can also skip `@expo/vector-icons` entirely and
+pass your own brand nodes via the `icons` prop.
 
 Use it whenever someone wants "AI / dynamic / personalized onboarding" in a React Native / Expo app.
 
@@ -27,7 +34,7 @@ subpaths are optional secondary feature modules; import one only if you use it.
 - `@wireai/activation` (root): `WireOnboarding`, the helpers/types below, and the app-event/analytics reporters.
 - `@wireai/activation/coachmarks`: in-app coachmark tour (`CoachmarkProvider`, `useCoachmarkTour`).
 - `@wireai/activation/showcase`: post-onboarding feature showcase (`FeatureShowcase`).
-- `@wireai/activation/reviews`: store-review gating (`ReviewGate`, `ReviewModal`).
+- `@wireai/activation/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).
 
@@ -54,6 +61,7 @@ There is no `analytics` subpath: the app-event / analytics API is exported from
 | `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 }`. |
+| `icons` | `Record<string, ReactNode>` | no | Host icon nodes keyed by the semantic vocabulary name the AI emits (`{ instagram: <BrandIg/> }`). Checked FIRST: use it to brand an icon, to add names of your own, or to supply icons without installing `@expo/vector-icons`. Unlisted names fall back to that optional peer, then to no icon. |
 | `validators` | `Record<string, StepValidator>` | no | Per base-question key (e.g. `username`). Blocks advance + inline error. |
 | `onSkip` | `() => void` | no | Retained for back-compat. Per-question Skip is now internal (the kit advances one question on `skippable` screens), so this is no longer wired to that control. |
 | `onError` | `(err) => void` | no | Backend error/timeout after retries. Host recovery (e.g. static onboarding). `fallbackFlow` takes precedence over it. |
@@ -100,6 +108,22 @@ The app-event / analytics API is exported from the ROOT (`@wireai/activation`),
 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.
 
+## Review firing (do not hand-roll the decision fetch)
+
+If you gate the review prompt on the server, call **`fetchReviewDecision(target, { deviceKey })`**
+from `@wireai/activation/reviews` and pass the result to `useReviewGate({ decision })`. Never
+write your own fetch.
+
+- It returns the FULL `{ fire, reason, arm }` on 2xx, and `null` ONLY when the server is
+  unreachable / non-2xx / sends bad JSON. It never throws.
+- **Never collapse `{fire:false}` into null/undefined.** The seam is `decision ?? local`, so a
+  collapsed `false` reads as "no server opinion" and your LOCAL timer fires. A host did exactly
+  this and prompted a real user for a review 3 minutes into their first session (1 star).
+- `sessionId` is OPTIONAL: the gate usually lives on the home feed, where there is no onboarding
+  session. `deviceKey` is the identity that matters. Pass `sessionId` only when you have one.
+- Running a firing experiment? Echo the returned `arm` back as `meta.firing_arm` on the review
+  submission so per-arm attribution survives a reweighting.
+
 ## 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

@@ -20,6 +20,163 @@ Historical entries below the rename keep the old package name on purpose.
 
 ## [Unreleased]
 
+### Added: `fetchReviewDecision` — the kit now owns the review firing decision (live user harm)
+
+- **A real user was prompted for a review ~3 minutes into their FIRST session**, having seen
+  nothing, and left 1 star. It is still happening in prod; only an app release stops it.
+- **Root cause was an asymmetry in this kit.** `src/questionnaire/transport.ts` has
+  `fetchQuestionnaireDecision`; `src/reviews/transport.ts` had **no decision fetch at all**. So
+  the host hand-rolled one, and its helper collapsed an explicit `{fire:false}` into `undefined`.
+  The seam is `decideReview = (local, decision) => decision ?? local`, so `undefined` means "the
+  server has no opinion, use local rules" and the local 30s timer fired. **The server could turn
+  review prompts ON but never OFF.**
+- **The fix lives in the kit, not the host** (Malik: *"the idea is not to comment in the
+  organism, the idea is to change wire activation, to fix this errors"*). Hosts now keep a thin
+  call site. `decideReview` itself was already correct and is unchanged; the missing piece was a
+  faithful producer of `{fire:false}`.
+- `fetchReviewDecision(target, { deviceKey, sessionId? })` returns the FULL `{fire, reason, arm}`
+  on 2xx, and `null` **only** on unreachable / non-2xx / bad JSON, so fail-open to local rules is
+  preserved exactly where it belongs. A body without a boolean `fire` is not a decision → null.
+- **`sessionId` stays OPTIONAL, deliberately.** The gate lives on the home feed, where there is
+  no onboarding session; `deviceKey` is the real identity. Today's prod still requires
+  `session_id` on the decision route and answers **422** without it (the server relaxation is
+  unmerged), and a 422 is just a non-2xx → `null` → local rules. Tightening `sessionId` here
+  would break the very hosts this unblocks. Permissive wire, strict client.
+- `arm` is carried through so a host can echo it back as `meta.firing_arm` (the server keeps an
+  echoed arm verbatim, else recomputes from the sticky hash).
+
+### Fixed: the 5-star review never reached the server (live data loss)
+
+- **Every promoter was being dropped.** `ReviewGate`'s 5-star branch called
+  `requestStoreReview` and nothing else: `submitReview` was reachable ONLY from the feedback
+  phase, which only a 1-4 rating enters. So server-side `by_stars["5"]` and `store_routed` sat
+  at **0 forever** and `avg` averaged detractors only — the firing experiment could never
+  attribute a promoter to an arm. The four gate events go to the HOST's `onEvent`, never to
+  Wire, so nothing surfaced it. Tapping 5 now POSTs a text-less `stars=5` row.
+- **`meta.store_route` records which route we took** (`native` / `store_url` / `none`) — the
+  return value of `requestStoreReview`, which was previously computed and thrown away.
+  **Honest ceiling:** `requestReview` is OS-quota'd and reports NOTHING about whether the user
+  actually left a review. This only ever means *we asked*. Never read it as a review count.
+- No server change needed: the body is exactly the shape `CreateReviewRequest` already
+  documents as the store route, and the shape its `store_routed` aggregate already counts
+  (`stars == 5 and not feedback_text`).
+
+### Changed: a 1-4 rating must now leave feedback — and can no longer take its rating with it
+
+- **The opinion box is MANDATORY** (Malik, 2026-07-16), mirroring the questionnaire's forced
+  last step. Send stays disabled until it holds non-whitespace text, and the feedback step's
+  Skip link is gone. The suggestion box stays optional. Enforced **client-side only**:
+  `feedback_text` stays optional on the wire, because every already-shipped client still posts
+  text-less rows and the transport is fire-and-forget — tightening the server would silently
+  422 them into oblivion. Permissive wire, strict client.
+- **Forcing the text does NOT cost us the rating.** Naively, blocking Send would lose the
+  ratings of exactly the detractors who bail rather than type. So a rating that is still
+  unposted when the gate goes away is now posted anyway, with whatever text was typed, flagged
+  `meta.abandoned`. The user is pushed to explain; the rating is never the price. We do not
+  trap the user in the modal — backdrop / Android back still work.
+- **Exactly ONE row per gate, ever** (`postOnce`). We deliberately did NOT post at star-tap and
+  again on submit: the server mints its own id (`_new_id()`) and `CreateReviewRequest` has no id
+  field, so two posts = two rows = a double-counted `count` and a corrupted `avg` — the same
+  class of corruption this change exists to fix. Revisit only once the server accepts a
+  client-supplied idempotency id.
+
+### Added: an icon vocabulary the AI emits, and `CardGridSelectCard`
+
+- **`icon` on choice options.** `SelectionCard` options may now carry an optional `icon`, so
+  "Where did you hear about us?" can put a real Instagram mark next to the Instagram row.
+  Bare-string options and bare `{value,label}` options are unchanged.
+- **A named semantic vocabulary is the contract, not raw library glyph names.** The AI emits
+  `"instagram"` / `"friend"` / `"wedding"`; `src/icons/vocabulary.ts` maps that to a concrete
+  glyph. The model is never coupled to a library version. `WIRE_ICON_NAMES` is exported for
+  pasting into the server prompt.
+- **`CardGridSelectCard`** — the 2-column grid of small icon cards Malik asked for (icon on
+  top, short label beneath, selection on the card). It is its OWN card, not a `display` mode on
+  `SelectionCard`, because a card's `description` IS the LLM's router and cannot honestly carry
+  three modes; `ChipSelectCard` sets the precedent that a presentation difference earns a name.
+- **`@expo/vector-icons` is an OPTIONAL peer**, lazily required. A host without it installs,
+  bundles, and renders fine (icons simply absent) — **no native rebuild is forced on anyone**,
+  which is what the no-native-dependency policy actually forbids. Both live hosts already ship
+  `^15.0.3`. A new `icons` prop overrides any name with host artwork, so the library is never
+  the only path.
+- **Every icon miss is a no-op.** Unknown / hallucinated / newer-than-this-client name, or a
+  missing peer → no icon, no crash, no tofu box, and no layout shift (a garbage icon renders a
+  tree identical to no icon — asserted in `test/canary/icons.test.tsx`).
+- **Back-compat:** an old kit receiving `{value,label,icon}` STRIPS the unknown key (zod strips
+  by default and the SDK renderer mounts `parsed.data`), so it renders its plain row — the wire
+  stays additive. `CardGridSelectCard` is invisible to shipped clients until they re-pin, by
+  construction: they never advertise it in `supportedComponents`, so the server intersects it
+  away. ⚠️ **It cannot be emitted until the server adds it to `KNOWN_COMPONENTS` +
+  `COMPONENT_DOCS` + the tenant's `allowed_components`** — a two-sided change, still open.
+
+### Changed: the questionnaire is multi-step, the FORCED answer moved to the last step; both gates animate
+
+- **The mandatory-opinion gate is GONE.** `QuestionnaireGate` was one screen with three
+  stacked boxes and a Send disabled until the "what do you think" box had text. It is now a
+  MULTI-STEP popup: ONE question per step, and the first two steps are skippable.
+- **The LAST step is REQUIRED instead** (Malik, on device: "i want at least something
+  forced"). `suggestions` — "Any improvements or feedback?" — renders no Skip control and
+  keeps Send disabled until the box holds non-whitespace text. So the forced answer moved
+  from step 1 to step 3: the user picks WHICH thing they say, not WHETHER they say anything.
+  Requiredness is per-step data (`steps.ts` → `REQUIRED_STEPS`), enforced in `commitStep`,
+  which `skipStep` (defined as committing `""`) inherits for free.
+- ⚠️ **This client now REQUIRES the server to accept an empty `answers.opinion`.** Step 1 is
+  skippable, so a skipped step 1 posts `opinion: ""`; the live endpoint validates `opinion`
+  with minLength=1 and rejects that body with a 422 — **silently**, because the transport is
+  fire-and-forget, taking the user's forced step-3 answer down with it. The client is
+  deliberately NOT worked around (no placeholder opinion, no field reordering): the server
+  schema is the fix.
+- **The wire shape is UNCHANGED.** `buildQuestionnaireSubmission` still builds the same
+  `POST /v1/questionnaires/{id}/responses` body from the same three answers; a skipped step is
+  simply an empty answer.
+- **The step logic is pure and tested.** `questionnaire/steps.ts` owns advance / skip / back /
+  the required gate as pure functions, covered by `questionnaire/steps.test.ts` under node:test.
+
+### Changed: questionnaire chrome — dots, a back icon, no "Not now", no repeated title
+
+All four from Malik's on-device test, 2026-07-16. The **review** gate's chrome is untouched.
+
+- **Step DOTS replace the "Question 2 of 3" counter.** New `components/StepDots` — a filled
+  `colors.primary` layer crossfades over a `colors.border` base at the design system's
+  `SELECT_FILL_MS`, opacity-only on the native driver, snapping under reduce motion. The row
+  is one `progressbar` node labelled "Step 2 of 3" with a numeric `accessibilityValue`, so
+  screen readers keep the count sighted users now read from the dots. (Distinct from
+  `StepProgress`, which serves the onboarding flow and deliberately shows no count.)
+- **Back is a top-left icon**, not a text link in the button stack — a `‹` Text glyph, no
+  vector dependency (the `DoneCheck` ✓ / review-star idiom). It is **absent** on step 1
+  rather than present-and-dead, and keeps its "Back to the previous question" label.
+- **"Not now" is gone.** Per-step "Skip step" is the only in-card opt-out.
+  **`questionnaire_dismissed` moved to the modal's dismiss path** rather than dying with the
+  link: dismissal is still reachable (backdrop tap, Android hardware back) and now fires the
+  event from there. This also FIXES a hole — those two paths never fired it before, so the
+  metric only ever counted users who found the link. Expect the number to legitimately RISE.
+  Submitting still does not fire it.
+- **The repeated title is gone.** The gate drew `questionnaire.title` as a heading on EVERY
+  step, directly above that step's own question — two asking-texts stacked, the same string
+  three times, and mid-slide the outgoing and incoming panes each drew their own copy, so it
+  was briefly on screen twice. The step's question is the heading now and renders once.
+  `QuestionnaireDefinition.title` is **deprecated and no longer rendered**; it stays in the
+  type because tenants still send it and the server contract is unchanged.
+- `components/ModalPaneHost` gained a `header` slot: chrome measured with the pane but
+  outside the `CardHandoff`, so it never slides, never doubles mid-handoff, and its removal
+  (form → thanks) rides the eased card resize instead of snapping.
+- **Motion.** Both gates now transition between panes instead of swapping in place, via the new
+  shared `components/ModalPaneHost` (it delegates the slide to the existing `CardHandoff` and
+  eases the modal card's height). `CardHandoff` gained `direction` (mirrors the slide for Back)
+  and `layout` (`"auto"` for panes inside an auto-height card). The thank-you plays the new
+  shared `components/DoneCheck` before the existing 1500ms auto-close. Every new animation
+  honors reduce motion, and no new motion values were invented — all come from `motionSpec`.
+- **Haptics (new OPTIONAL peer `expo-haptics`).** A star tap, a step change, and a submit now
+  fire a haptic through `haptics/haptics.ts`, loaded lazily via a guarded dynamic import —
+  the same contract `expo-store-review` uses. A host that has not installed it feels nothing
+  and nothing throws. Install with `npx expo install expo-haptics` to enable.
+- **Copy.** The default `improve`/`suggestions` labels dropped their "(optional)" tags.
+  Skippability is carried by the CONTROLS (Skip present or absent, Send live or disabled),
+  never by label text — labels are tenant-configurable and would drift out of sync.
+- **A11y.** The in-card questionnaire controls are real labelled buttons instead of bare
+  text, the dots carry a `progressbar` role + "Step X of N", and the back icon is a labelled
+  button. The 5-star → native store review route (`routeRating`) is untouched.
+- `theme/mergeThemeOver` extracts the helper both gates had copy-pasted.
+
 ### 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`
@@ -87,7 +244,7 @@ Historical entries below the rename keep the old package name on purpose.
 - The façade's `identify` (and `track`/`screen` app-events) now source their `session_id` from
   `config.sessionId ?? getCurrentSessionId() ?? <stable per-instance id>` — so identity binds to the
   session the server ALREADY saw (via `app.session_started`) instead of minting a fresh id the server
-  back-fills into a synthetic session. This is what inflated the Morrow/Myelino session counts. An
+  back-fills into a synthetic session. This is what inflated the Morrow/a host app session counts. An
   explicit `config.sessionId` still freezes the id (opt-out). This is also the kit half of the #205
   "align all app-events to the per-open session" follow-up. **No server change required** for the
   normal flow (session-start fires on mount, identify at login); the only residual is an `identify`
@@ -130,7 +287,7 @@ Historical entries below the rename keep the old package name on purpose.
   user once `userId` arrives (here or via `identifyOnboarding`).
 - Convenience hook `useSessionStart(config, {userId, sessionCount, deviceKey})` fires on mount and
   on foreground-after-30-min-background (a real new open, not a quick app-switch), collecting the
-  device snapshot for you. Optional: a host with its own session counter (Myelino/Morrow) can call
+  device snapshot for you. Optional: a host with its own session counter (a host app/Morrow) can call
   the plain `reportSessionStart` directly instead. Both paths are first-class.
 - Exports added to the core barrel: `reportSessionStart`, `useSessionStart`, `SESSION_STARTED_EVENT`,
   `BACKGROUND_SESSION_MS`, and the `ReportSessionStartOptions` / `SessionStartConfig` /
@@ -362,7 +519,7 @@ Historical entries below the rename keep the old package name on purpose.
   (`OnboardingIntroPanel.tsx`), and the full-bleed image hero panel
   (`OnboardingImageContainer.tsx`'s `colorBg`). So the button fix also painted the
   whole hero panel in the accent, which dominated the first slide and "hid" the
-  app (reported in Myelino on 0.3.1). The package exposes no per-surface color key
+  app (reported in a host app on 0.3.1). The package exposes no per-surface color key
   to split them, but it does accept a `background?: () => ReactNode` render prop
   that REPLACES that panel fill outright. `FeatureShowcase` now passes one: a calm
   theme `surface` base with a faint accent tint (~10% opacity) on top. Result: the
@@ -400,7 +557,7 @@ Historical entries below the rename keep the old package name on purpose.
 ### Changed: the in-app review prompt is now a centered popup by default
 - **`ReviewGate` renders as a centered modal** (dimmed backdrop, card in the middle of the
   screen, spring/fade entrance) instead of the bare host-positioned card, which rendered
-  bottom-anchored and half-hidden on device (reported in Myelino on 0.3.0). The entrance
+  bottom-anchored and half-hidden on device (reported in a host app on 0.3.0). The entrance
   uses RN's built-in `Animated` on the native driver (the same idiom as `CompletionView` /
   `AnimatedCard`), so the reviews module stays dependency-free (no reanimated). The card
   surface, radius, spacing, and text all come from the active theme, so it is theme-aware in
@@ -410,7 +567,7 @@ Historical entries below the rename keep the old package name on purpose.
   (transparent RN `Modal` + centered container + backdrop-tap dismiss + content
   stop-propagation + springy zoom-in), reimplemented on RN core primitives.
 - **Additive API, no app change needed.** New optional `presentation?: "modal" | "inline"`
-  prop on `ReviewGate`, defaulting to `"modal"`. Apps like Myelino's `HomeReviewGate` pick up
+  prop on `ReviewGate`, defaulting to `"modal"`. Apps like a host app's `HomeReviewGate` pick up
   the centered popup automatically when they bump to 0.3.1, with zero code changes. Pass
   `presentation="inline"` to keep the legacy bare card. New exports: `ReviewModal`,
   `ReviewModalHandle`, `ReviewModalProps`, `ReviewPresentation`, `resolvePresentation`,
@@ -426,7 +583,7 @@ Historical entries below the rename keep the old package name on purpose.
   `background.primary` — its BRAND/action color, despite the "primary" name. The kit
   was mapping `background.primary` to the theme's `background`, so every consuming app
   rendered the "Next/Get Started" CTA in its own screen background color: white-on-white
-  in light mode, dark-on-dark in dark mode (reported in Morrow Self + Myelino, both on
+  in light mode, dark-on-dark in dark mode (reported in Morrow Self + a host app, both on
   0.3.0). The CTA now maps to the theme's `primary` (or the `accentColor` override), and
   the screen/panel background maps to `background`. No app change is required to pick up
   the fix — apps already pass their theme/`accentColor` correctly.

package/README.md

@@ -28,10 +28,16 @@ Sponsored by [AI Mobile Launcher](https://aimobilelauncher.com?utm_source=github
 | **Backend** | `wire-rn/examples/dynamic-onboarding/server` | Multi-tenant LangGraph engine. Per-app `product_context` + `allowed_components`; validates every emission against `KNOWN_COMPONENTS`. Live on fly dev. |
 | **Consumers** | Production B2C mobile apps | Each hosts `<WireOnboarding>` with its own theme + illustration registry. |
 
-The kit's peers are `react`, `react-native`, `wireai-rn`, and
-`react-native-safe-area-context` (>=4.0.0, for safe-area insets — the host must render a
-`SafeAreaProvider` ancestor, standard in every Expo/RN app) — **no reanimated, no SVG, no
-icon font.** Brand artwork is supplied by the host (see [Illustrations](#illustrations)).
+The kit's required peers are `react`, `react-native`, `wireai-rn`, `zod`, and
+`react-native-safe-area-context` (>=4.0.0, for safe-area insets, so the host must render a
+`SafeAreaProvider` ancestor, standard in every Expo/RN app). **Nothing in the kit forces you into
+a native rebuild.** Brand artwork is supplied by the host (see [Illustrations](#illustrations)).
+
+Everything else is an **optional peer**: `@expo/vector-icons` (icons on the choice cards, see
+[Icons](#icons)), `expo-store-review`, `expo-haptics`, `expo-blur`, `react-native-reanimated`, and
+`@blazejkustra/react-native-onboarding`. npm never installs them for you. Each one sits behind a
+guarded lazy require and falls back to a defined no-op when it is missing. Don't want the icon
+library? Pass your own nodes through the `icons` prop.
 
 ## How to include it in an app (end-to-end)
 
@@ -380,7 +386,7 @@ carries both ids.)
 
 **Two ways to wire it. Both are first-class.**
 
-If your app already keeps a session counter (Myelino and Morrow do), call the plain function
+If your app already keeps a session counter (most host apps do), call the plain function
 from your own "app opened" path and pass the counter value:
 
 ```tsx
@@ -450,11 +456,18 @@ to use your own button.
 ## Cards
 
 `onboardingComponents` registers: `TextInputCard`, `SelectionCard`,
-`ChipSelectCard`, `NumberStepperCard`, `StatusCard` (terminal recap), and
-**`InterstitialCard`** — a mid-flow momentum/value screen (Duolingo/Cal-AI style):
+`ChipSelectCard`, **`CardGridSelectCard`**, `NumberStepperCard`, `StatusCard` (terminal recap),
+and **`InterstitialCard`** — a mid-flow momentum/value screen (Duolingo/Cal-AI style):
 an illustration + a line that reflects the user's answers back + a Continue tap.
 It is not a question; the backend emits it once mid-flow.
 
+The three choice cards differ only in presentation, and each card's `description` is what the
+model routes on. `SelectionCard` is a vertical list, for options wordy enough that someone has to
+read them. `ChipSelectCard` packs 4 to 12 short tags into compact pills. `CardGridSelectCard` puts
+2 to 6 visual choices in a two-column grid, icon on top, short label under it ("What brings you
+here?"). All three accept an option as a bare string, a `{value, label}`, or a
+`{value, label, icon}`.
+
 ### Illustrations
 
 A tenant can configure **multiple** growth images per app (name + description +
@@ -472,6 +485,51 @@ illustrations={{
 }}
 ```
 
+### Icons
+
+Options on `SelectionCard` and `CardGridSelectCard` can carry an `icon`, so "Where did you hear
+about us?" puts a real Instagram mark next to the Instagram row. The AI emits a **semantic name
+from a fixed vocabulary**, never a raw glyph name from an icon library:
+
+```jsonc
+// what the backend emits
+{ "component": "CardGridSelectCard", "props": { "title": "What brings you here?", "options": [
+  { "value": "wedding", "label": "Wedding day", "icon": "wedding" },
+  { "value": "travel",  "label": "Travelling",  "icon": "travel"  }
+]}}
+```
+
+That indirection is the whole point. The model never learns a library's glyph names, so swapping
+or upgrading the icon set is a one-file change in `src/icons/vocabulary.ts`. Import
+`WIRE_ICON_NAMES` to get the list to paste into your prompt as the allowed values.
+
+Resolution runs in three steps, and every miss is silent:
+
+| Step | Source | When it applies |
+|---|---|---|
+| 1 | your `icons` prop | Always checked first. Overrides any name, and accepts names of your own. |
+| 2 | `@expo/vector-icons` | If that optional peer resolves. |
+| 3 | nothing | Renders `null`. |
+
+Step 3 is a feature, not a gap. An icon name that is unknown, misspelled, or simply newer than the
+installed build renders nothing at all: no crash, no tofu box, no layout shift, because the row
+lays out exactly as it would with no icon. That is what lets the vocabulary keep growing without
+waiting on every shipped app to update.
+
+`@expo/vector-icons` sits behind a guarded lazy require. Install it and the icons work with no
+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:
+
+```tsx
+icons={{
+  instagram: <BrandInstagram />,   // override one name with your own mark
+  "my-custom-thing": <MyGlyph />,  // or add a name the AI can emit
+}}
+```
+
+Icons are decorative: the label carries the meaning, so an icon stays hidden from screen readers
+and never becomes an option's accessible name.
+
 ## Backend coupling
 
 The backend (`wire-rn/examples/dynamic-onboarding/server`) is the source of truth
@@ -480,9 +538,19 @@ for what the agent may emit. 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),
 
-then `fly deploy`. Registering the card in this kit alone is **not** enough — the
-server validates every emission and replaces unknown components with a safe
-`StatusCard`. (`InterstitialCard` is already wired on both sides.)
+then `fly deploy`. Registering the card in this kit alone is **not** enough: the server validates
+every emission against `KNOWN_COMPONENTS` and the tenant's `allowed_components`, so a card it does
+not know is simply never emitted. (`InterstitialCard` is already wired on both sides.
+`CardGridSelectCard` is registered here but **not yet on the server**, so it cannot be emitted
+until the two steps above are done.)
+
+Old app versions are protected by a handshake, not by luck: the kit advertises the exact set it
+can render (`supportedComponents`, sent in the reserved A2A `metadata`), and the server narrows
+each turn to that intersection. That is why adding a card here cannot break an app already in the
+stores. It never advertises the new name, so the server never sends it one. Do not bypass that
+check, because a component name a device cannot render does **not** degrade gracefully. It throws
+`COMPONENT_NOT_FOUND` inside `wireai-rn` before the renderer ever sees it, and the user loses the
+turn to the retry/fallback path.
 
 ## Consuming from source (Metro + tsconfig)
 
@@ -749,6 +817,33 @@ per-app trigger rules against the app's event stream, and later a learnings-driv
 replaces the internals behind the same contract. Building the seam now is the whole cost of
 being AI-ready.
 
+**Use `fetchReviewDecision`. Do not hand-roll the fetch.**
+
+```tsx
+import { fetchReviewDecision, useReviewGate } from "@wireai/activation/reviews";
+
+// The review gate usually lives on the home feed, where there is no onboarding session,
+// so deviceKey is the identity that matters. sessionId is optional.
+const decision = await fetchReviewDecision(target, { deviceKey });
+
+const gate = useReviewGate({ config, decision: decision ?? undefined, storage });
+```
+
+It returns the full `{ fire, reason, arm }` on a 2xx and `null` on anything else. That
+distinction is the whole contract, and it is worth being blunt about why.
+
+A host wrote its own version of this and collapsed an explicit `{fire: false}` into
+`undefined`. Since the seam is `decision ?? local`, `undefined` means "the server has no
+opinion, use my local rules", so the server could turn prompts **on** but never **off**. The
+local timer then asked a real user to rate the app about three minutes into their first
+session, before they had seen anything. They left one star.
+
+So: `fire: false` must reach the gate as `false`. `null` must mean only that the server was
+unreachable or answered badly, which is the one case where local rules should take over. A 422,
+a 500, a 404, or bad JSON all return `null` and never throw. If the app runs a firing
+experiment, echo the returned `arm` back as `meta.firing_arm` on the submission so per-arm
+attribution survives a later reweighting.
+
 The firing chain, in order: a server `decision` wins immediately, then after
 `timeoutFallbackMs` the local rules take over (the timeout is a fallback only), and the
 once-per-version gate (`wire_review_<id>_seen`) always applies locally so a server bug can

package/dist/analytics/index.d.mts

@@ -1,10 +1,10 @@
-export { R as ReportAppEventOptions, r as reportAppEvent } from '../transport-BeO_Brcu.mjs';
-import { W as WireUserContext, E as EventQueueOptions } from '../currentSession-d9CrBxwe.mjs';
-export { A as AnalyticsEvent, C as ClientEvent, a as ClientEventTarget, b as ClientEventType, c as ContextEnvelope, d as ContextEnvelopeInput, e as EnvelopeSource, f as EventQueue, g as WIRE_ONBOARDING_EVENTS, h as WireOnboardingEventName, i as buildContextEnvelope, j as createEventQueue, k as getCurrentSessionId, m as makeSessionId, r as reportClientEvent, l as reportClientEvents, n as resetCurrentSessionId, s as setCurrentSessionId, t as toAnalyticsEvent } from '../currentSession-d9CrBxwe.mjs';
-import '../types-A6pTxIZV.mjs';
+export { R as ReportAppEventOptions, r as reportAppEvent } from '../transport-f5VVB5hH.mjs';
+import { W as WireUserContext, E as EventQueueOptions } from '../currentSession-Bs2JfTJ8.mjs';
+export { A as AnalyticsEvent, C as ClientEvent, a as ClientEventTarget, b as ClientEventType, c as ContextEnvelope, d as ContextEnvelopeInput, e as EnvelopeSource, f as EventQueue, g as WIRE_ONBOARDING_EVENTS, h as WireOnboardingEventName, i as buildContextEnvelope, j as createEventQueue, k as getCurrentSessionId, m as makeSessionId, r as reportClientEvent, l as reportClientEvents, n as resetCurrentSessionId, s as setCurrentSessionId, t as toAnalyticsEvent } from '../currentSession-Bs2JfTJ8.mjs';
+import '../types-CNUqMK0D.mjs';
 import '../types-BKfpdZzX.mjs';
-import '../types-GL_hQ0TN.mjs';
-import '../types-CMuOexw0.mjs';
+import '../types-BcmagF6K.mjs';
+import '../types-CKFhyrMu.mjs';
 import 'react';
 import 'wireai-rn';
 import 'react-native';

package/dist/analytics/index.d.ts

@@ -1,10 +1,10 @@
-export { R as ReportAppEventOptions, r as reportAppEvent } from '../transport-DLpd1v5_.js';
-import { W as WireUserContext, E as EventQueueOptions } from '../currentSession-f7LWcdWG.js';
-export { A as AnalyticsEvent, C as ClientEvent, a as ClientEventTarget, b as ClientEventType, c as ContextEnvelope, d as ContextEnvelopeInput, e as EnvelopeSource, f as EventQueue, g as WIRE_ONBOARDING_EVENTS, h as WireOnboardingEventName, i as buildContextEnvelope, j as createEventQueue, k as getCurrentSessionId, m as makeSessionId, r as reportClientEvent, l as reportClientEvents, n as resetCurrentSessionId, s as setCurrentSessionId, t as toAnalyticsEvent } from '../currentSession-f7LWcdWG.js';
-import '../types-BhpXJGlg.js';
+export { R as ReportAppEventOptions, r as reportAppEvent } from '../transport-DzU-TqZz.js';
+import { W as WireUserContext, E as EventQueueOptions } from '../currentSession-61dcm3V-.js';
+export { A as AnalyticsEvent, C as ClientEvent, a as ClientEventTarget, b as ClientEventType, c as ContextEnvelope, d as ContextEnvelopeInput, e as EnvelopeSource, f as EventQueue, g as WIRE_ONBOARDING_EVENTS, h as WireOnboardingEventName, i as buildContextEnvelope, j as createEventQueue, k as getCurrentSessionId, m as makeSessionId, r as reportClientEvent, l as reportClientEvents, n as resetCurrentSessionId, s as setCurrentSessionId, t as toAnalyticsEvent } from '../currentSession-61dcm3V-.js';
+import '../types-Buj9Lw9t.js';
 import '../types-BKfpdZzX.js';
-import '../types-GL_hQ0TN.js';
-import '../types-CMuOexw0.js';
+import '../types-BcmagF6K.js';
+import '../types-CKFhyrMu.js';
 import 'react';
 import 'wireai-rn';
 import 'react-native';