@avsbhq/vue 1.0.1 → 1.1.0

package/README.md

@@ -2,7 +2,7 @@
 
 Vue 3 SDK for the [A vs B](https://app.avsb.cloud) platform.
 
-Drop an `<AvsbProvider>` at the top of your component tree (or call `app.use(AvsbPlugin)`) and read feature flags from anywhere using composables. Built on `@avsbhq/browser`; components re-render automatically when flag values change.
+Mount one `<AvsbProvider>` (or install `AvsbPlugin`), then read feature flags anywhere with composables. Built on [`@avsbhq/browser`](https://www.npmjs.com/package/@avsbhq/browser): components update when a flag's value changes, and only the components reading that flag.
 
 ---
 
@@ -12,7 +12,7 @@ Drop an `<AvsbProvider>` at the top of your component tree (or call `app.use(Avs
 npm install @avsbhq/vue
 ```
 
-Vue 3.4 or later is required as a peer dependency. Pinia integration is optional: install `pinia` only if you use `useAvsbStore`.
+Vue 3.4 or later is required as a peer dependency. `pinia` is an optional peer: install it only if you import `@avsbhq/vue/pinia`.
 
 ---
 
@@ -21,11 +21,14 @@ Vue 3.4 or later is required as a peer dependency. Pinia integration is optional
 ```vue
 <!-- App.vue -->
 <script setup lang="ts">
-import { AvsbProvider } from '@avsbhq/vue'
+import { AvsbProvider } from '@avsbhq/vue';
+
+const sdkKey: string = import.meta.env['VITE_AVSB_SDK_KEY'] as string;
+const userId = 'u_123';
 </script>
 
 <template>
-  <AvsbProvider :sdk-key="sdkKey" :context="{ kind: 'user', key: userId }">
+  <AvsbProvider :sdk-key="sdkKey" :context="{ kind: 'user', key: userId, plan: 'pro' }">
     <RouterView />
   </AvsbProvider>
 </template>
@@ -34,330 +37,636 @@ import { AvsbProvider } from '@avsbhq/vue'
 ```vue
 <!-- CheckoutButton.vue -->
 <script setup lang="ts">
-import { useFlag, useTrack } from '@avsbhq/vue'
+import { useBoolFlag, useExposure, useTrack } from '@avsbhq/vue';
+import type { ComputedRef } from 'vue';
+import type { Flag } from '@avsbhq/vue';
+
+// Keep the ref: reading `.value` here instead would freeze the first value.
+const newCheckout: ComputedRef<Flag<boolean>> = useBoolFlag('new-checkout-flow', false);
+const track = useTrack();
 
-const newCheckout = useFlag('new-checkout-flow', false)
-const track = useTrack()
+// The visitor is about to see this decision, so record it once.
+useExposure('new-checkout-flow');
 </script>
 
 <template>
-  <button @click="track('checkout_clicked')">
+  <button @click="track('checkout_started', { value: 99 })">
     {{ newCheckout.value ? 'Start checkout (new)' : 'Buy now' }}
   </button>
 </template>
 ```
 
+Both props matter: without `context` the visitor gets a persisted anonymous id, which is fine for anonymous experiments but cannot target logged-in attributes.
+
 ---
 
 ## 3. SDK keys
 
-Get a client SDK key from your A vs B project's Environments page.
+Get the SDK key for the environment you want from your project: **app.avsb.cloud**, then **Settings**, then **Environments**. The format is `sdk_<environment>_<id>`, for example `sdk_production_ttqm0eaj4vth1krcb2xn`.
 
-Client SDK keys are safe to embed in browser bundles. Store them in your framework's public env variable:
+There is one SDK key per environment, and "SDK key" is its only name. There is no separate client key and server key to choose between.
+
+Your SDK key is a public identifier, not a secret: it is safe to ship in browser and mobile bundles, it can only fetch that environment's flag configuration and send events, and it can never read or change anything in your dashboard.
 
 ```
-VITE_AVSB_SDK_KEY=sdk-...
+VITE_AVSB_SDK_KEY=sdk_production_...
 ```
 
+The client checks the shape of the key when it is constructed. A key that does not look like an SDK key (a pasted dashboard URL, a truncated copy, a personal access token or a service token) logs one actionable error naming what it got and where the real key lives.
+
+---
+
+## 4. The whole type surface
+
+Every export, with its real signature. The signatures name the package's own types, and Vue's. Both come from here:
+
 ```ts
-// main.ts
-const key = import.meta.env.VITE_AVSB_SDK_KEY
+import type {
+  AvsbClientOptions,
+  AvsbContextValue,
+  AvsbPluginOptions,
+  AvsbProviderProps,
+  EvalContext,
+  Flag,
+  FlagDatafile,
+  FlagKeyInput,
+  TrackPayload,
+  UseAvsbStatusResult,
+  VueAvsbClient,
+} from '@avsbhq/vue';
+import type { ComputedRef, DefineComponent, InjectionKey, Plugin } from 'vue';
 ```
 
-Server SDK keys (used by `@avsbhq/node`) must never be exposed to the browser.
+```ts
+// Provider and plugin
+const AvsbProvider: DefineComponent<AvsbProviderProps>;
+const AvsbPlugin: Plugin<AvsbPluginOptions>;
+
+// Reading flags. `FlagKeyInput = string | Ref<string> | ComputedRef<string>`
+function useFlag<T>(flagKey: FlagKeyInput, defaultValue: T): ComputedRef<Flag<T>>;
+function useFlagValue<T>(flagKey: FlagKeyInput, defaultValue: T): ComputedRef<T>;
+function useBoolFlag(flagKey: FlagKeyInput, defaultValue: boolean): ComputedRef<Flag<boolean>>;
+function useStringFlag(flagKey: FlagKeyInput, defaultValue: string): ComputedRef<Flag<string>>;
+function useNumberFlag(flagKey: FlagKeyInput, defaultValue: number): ComputedRef<Flag<number>>;
+function useJsonFlag<T>(flagKey: FlagKeyInput, defaultValue: T): ComputedRef<Flag<T>>;
+function useAllFlags(): ComputedRef<Record<string, Flag>>;
+
+// Readiness and errors
+function useFlagReady(): ComputedRef<boolean>;
+function useAvsbStatus(): UseAvsbStatusResult;
+
+// Identity
+function useIdentify(): (context: EvalContext) => void;
+function useAlias(): (previousContext: EvalContext, newContext: EvalContext) => void;
+function useReset(): () => void;
+
+// Events
+function useTrack(): (eventKey: string, payload?: TrackPayload) => void;
+function useExposure(flagKey: FlagKeyInput): void;
+function useFlagSubscription(flagKey: FlagKeyInput, callback: (flag: Flag) => void): void;
+
+// The client itself
+function useAvsbClient(): VueAvsbClient;
+
+// Context, for custom providers
+const AvsbInjectionKey: InjectionKey<AvsbContextValue>;
+```
 
----
+### Provider props
 
-## 4. Identity (identify, updateAttributes, alias, reset)
+```ts
+type AvsbProviderProps = AvsbProviderModeAProps | AvsbProviderModeBProps;
+
+interface AvsbProviderModeAProps {
+  /** SDK key for the environment you are targeting. */
+  sdkKey: string;
+  /** Evaluation context. Omit for an anonymous, persisted visitor id. */
+  context?: EvalContext;
+  /** A datafile fetched on the server, so the first paint has real values. */
+  bootstrap?: FlagDatafile;
+  /** Everything else AvsbClient accepts (polling, logging, caching). */
+  options?: Omit<AvsbClientOptions, 'sdkKey' | 'context' | 'bootstrap'>;
+  client?: never;
+}
 
-### Provider-level context
+interface AvsbProviderModeBProps {
+  /** A client you built and own. The provider will not close it. */
+  client: VueAvsbClient;
+  sdkKey?: never;
+}
+```
 
-Pass a context object to `<AvsbProvider>` at bootstrap. This is the evaluation context used for all flag reads until you call `identify`.
+In templates the props are kebab-case and bound: `sdk-key`, `:context`, `:bootstrap`, `:options`, `:client`.
 
-```vue
-<AvsbProvider :sdk-key="key" :context="{ kind: 'user', key: userId, plan: 'pro' }">
+**Mode A** (an `sdk-key`) means the provider builds the client and closes it when it unmounts. **Mode B** (a `client`) means you own its lifetime and the provider never closes it. Passing neither throws at setup with a message naming both fixes, rather than rendering a tree where every flag is silently the default.
+
+### `Flag<T>`, the return type of every read
+
+```ts
+interface Flag<T = unknown> {
+  /** The variation value, typed against the default you passed. */
+  readonly value: T;
+  /** Variation key, null when the default was served or the flag is unknown. */
+  readonly variationKey: string | null;
+  /** Why this value was produced. */
+  readonly source: EvaluationSource;
+  /** Rule that matched, null when none did. */
+  readonly ruleId: string | null;
+  readonly ruleType: RuleType | null;
+  /** Structured reasons for this decision. Never null; may be empty. */
+  readonly reasons: string[];
+  /** ms-epoch when this was evaluated. */
+  readonly evaluatedAt: number;
+  /** Microseconds spent in the evaluator. */
+  readonly durationMicros: number;
+  /** A real decision produced a truthy value. */
+  isEnabled(): boolean;
+  /** False for 'not_found' and for 'not_ready'. */
+  exists(): boolean;
+}
+
+type RuleType = 'targeted_delivery' | 'ab_test' | 'holdout' | 'bandit';
+
+type EvaluationSource =
+  | 'datafileOverride'
+  | 'runtimeOverride'
+  | 'sticky'
+  | 'rule'
+  | 'holdout'
+  | 'bandit'
+  | 'default'
+  | 'not_found'
+  | 'disabled'
+  | 'not_ready';
 ```
 
-### useIdentify
+| `source`           | Meaning                                                       | `isEnabled()`   | `exists()` |
+| ------------------ | ------------------------------------------------------------- | --------------- | ---------- |
+| `datafileOverride` | A per-user override in the dashboard matched.                 | value-dependent | true       |
+| `runtimeOverride`  | `setOverrideForUser` or `setGlobalOverride` matched.          | value-dependent | true       |
+| `sticky`           | A previously stored assignment was reused.                    | value-dependent | true       |
+| `rule`             | A targeting rule or A/B rule matched.                         | value-dependent | true       |
+| `holdout`          | The visitor is held out, so the holdout variation was served. | value-dependent | true       |
+| `bandit`           | A bandit rule picked the variation.                           | value-dependent | true       |
+| `default`          | The flag exists, nothing matched, default variation served.   | false           | true       |
+| `disabled`         | The flag exists but is off in this environment.               | false           | true       |
+| `not_found`        | The datafile loaded and has no such key. Check the name.      | false           | false      |
+| `not_ready`        | No datafile yet. Gate on `useFlagReady()`.                    | false           | false      |
 
-Replace the current context at runtime (e.g. after sign-in):
+"value-dependent" means `isEnabled()` is `Boolean(flag.value)`.
+
+### `UseAvsbStatusResult`
 
 ```ts
-import { useIdentify } from '@avsbhq/vue'
+interface UseAvsbStatusResult {
+  status: ComputedRef<'loading' | 'ready' | 'error'>;
+  error: ComputedRef<Error | undefined>;
+  degraded: ComputedRef<boolean>;
+}
+```
 
-const identify = useIdentify()
+### Typed flag keys
 
-function onSignIn(user: User) {
-  identify({ kind: 'user', key: user.id, email: user.email, plan: user.plan })
-}
+`FlagKeyInput` is built from `string` until you generate your keys. Generate
+them and it is built from the union of this project's real flag keys, so a typo
+is a compile error and your editor completes the list:
+
+```bash
+npx avsb codegen --output src/generated/flags.ts
 ```
 
-The function is stable; it will not change reference between renders.
+The generated file declares your flags twice on purpose: an importable
+`FlagValues` interface for payload types, and a `declare global` block that
+teaches every composable in this package which keys exist. Its important parts:
 
-### useAlias
+```text
+// AUTO-GENERATED by @avsbhq/cli codegen. Do not edit by hand.
+
+export interface FlagValues {
+  'checkout-v2': boolean
+  'hero-copy': 'control' | 'variant-a'
+  'theme': { primary: string }
+}
 
-Record that an anonymous visitor and an identified user are the same person. Call this once at sign-in:
+declare global {
+  interface AvsbFlags {
+    'checkout-v2': boolean
+    'hero-copy': 'control' | 'variant-a'
+    'theme': { primary: string }
+  }
+}
+```
 
 ```ts
-import { useAlias } from '@avsbhq/vue'
+import { useBoolFlag, useJsonFlag } from '@avsbhq/vue';
+import type { FlagValues } from './generated/flags';
 
-const alias = useAlias()
+const checkout = useBoolFlag('checkout-v2', false);
 
-async function onSignIn(anonKey: string, userId: string) {
-  await alias(
-    { kind: 'user', key: anonKey },
-    { kind: 'user', key: userId }
-  )
-}
+// A JSON flag types its payload from the generated table:
+const theme = useJsonFlag<FlagValues['theme']>('theme', { primary: '#111' });
+
+// Once the generated file exists, this line stops compiling:
+// 'chekcout-v2' is not a flag key.
+const typo = useBoolFlag('chekcout-v2', false);
 ```
 
-### reset
+One real consequence for reactive keys: a `Ref<string>` no longer satisfies
+`FlagKeyInput` once your keys are generated, because that ref could hold any
+string. Declare it as `Ref<AvsbFlagKey>` (or `ComputedRef<AvsbFlagKey>`) and it
+fits again.
 
-Call `client.reset()` via `useAvsbClient()` to clear the current identity and return to the anonymous state.
+Nothing changes for a project that never runs `codegen`: with no generated file
+the table is empty, so `FlagKeyInput` accepts any string exactly as it does
+today, and every call you have already written compiles unchanged. For a key
+computed at runtime, widen deliberately with `key as AvsbFlagKey` (that type is
+exported from `@avsbhq/core`).
 
 ---
 
-## 5. Multi-context
+## 5. Why `.value.value`
 
-A vs B supports multi-context evaluation: evaluating a flag for both a user and an organisation simultaneously:
+`useFlag` returns a `ComputedRef<Flag<T>>`. Vue refs are unwrapped with `.value`, and the flag's own field is also called `value`, so in `<script setup>` you write:
 
 ```ts
-identify({
-  kind: 'multi',
-  user: { kind: 'user', key: 'u_123', plan: 'pro' },
-  organization: { kind: 'organization', key: 'org_456', tier: 'enterprise' },
-})
+const checkout = useFlag('new-checkout-flow', false);
+
+checkout.value.value; // boolean  (ref unwrap, then Flag.value)
+checkout.value.isEnabled(); // boolean
+checkout.value.variationKey; // string | null
 ```
 
----
+In a template Vue unwraps the ref for you, so it is one `.value`:
 
-## 6. Reading flags
+```vue
+<template>
+  <NewCheckout v-if="checkout.value" />
+</template>
+```
 
-### useFlag (full Flag object)
+This is a real papercut and we are not going to hide it behind a rename: `Flag.value` is the same field in seven SDKs, and renaming it here would make the Vue docs disagree with every other page and every code sample.
+
+Two ways to make it read better:
 
 ```ts
-import { useFlag } from '@avsbhq/vue'
+import { computed } from 'vue';
 
-const checkoutFlag = useFlag('new-checkout-flow', false)
-// checkoutFlag is ComputedRef<Flag<boolean>>
+// 1. Ask for the value instead of the Flag
+const showNewCheckout = useFlagValue('new-checkout-flow', false);
+showNewCheckout.value; // boolean, one .value everywhere
 
-// In template:
-// checkoutFlag.value.value        → the boolean value
-// checkoutFlag.value.isEnabled()  → true if rule-served AND truthy
-// checkoutFlag.value.variationKey → 'on' | 'off' | ...
-// checkoutFlag.value.source       → 'rule' | 'override' | 'not_found' | ...
+// 2. Destructure with toRefs-style naming at the top of setup
+const checkoutFlag = useFlag('new-checkout-flow', false);
+const isNewCheckout = computed(() => checkoutFlag.value.isEnabled());
 ```
 
-A default value is always required. It is returned until the SDK is ready and whenever the flag is not found.
+---
+
+## 6. Identity
+
+```vue
+<AvsbProvider :sdk-key="sdkKey" :context="{ kind: 'user', key: userId, plan: 'pro' }">
+```
 
-### useFlagValue (raw value shortcut)
+Anonymous visitors get a persisted id (localStorage, with a cookie fallback), so a returning visitor buckets into the same variation instead of being re-randomised on every load. If the A vs B web snippet is on the same page, the SDK adopts its visitor id so flag exposures and web experiment exposures join to one visitor.
 
 ```ts
-import { useFlagValue } from '@avsbhq/vue'
+import { useAvsbClient, useIdentify, useAlias, useReset } from '@avsbhq/vue';
 
-const showBanner = useFlagValue('promo-banner', false)
-// showBanner is ComputedRef<boolean>
+const client = useAvsbClient();
+const identify = useIdentify();
+const alias = useAlias();
+const reset = useReset();
+
+function onSignIn(user: { id: string; email: string; plan: string }): void {
+  const context = client.getContext();
+  const anonymousKey: string = 'key' in context ? String(context['key']) : '';
+
+  // Same person, two sessions: this is what lets results stitch them.
+  alias({ kind: 'user', key: anonymousKey }, { kind: 'user', key: user.id });
+
+  // From here on, flags evaluate for the signed-in user.
+  identify({ kind: 'user', key: user.id, email: user.email, plan: user.plan });
+}
+
+function onSignOut(): void {
+  reset(); // new anonymous identity, runtime overrides cleared
+}
 ```
 
-### Typed variants
+`alias` is synchronous: it queues one event and returns. There is nothing to await, and it does not rewrite assignments already made. To carry bucketing across a login, evaluate with the same context key on both sides.
 
-Use typed composables when you want a runtime type-safety check against the datafile's declared flag type:
+### Multi-context
 
 ```ts
-import { useBoolFlag, useStringFlag, useNumberFlag, useJsonFlag } from '@avsbhq/vue'
-
-const darkMode    = useBoolFlag('dark-mode', false)
-const theme       = useStringFlag('theme', 'light')
-const maxItems    = useNumberFlag('max-items', 10)
-const config      = useJsonFlag<{ timeout: number }>('api-config', { timeout: 5000 })
+identify({
+  kind: 'multi',
+  user: { kind: 'user', key: 'u_123', plan: 'pro' },
+  organization: { kind: 'organization', key: 'org_456', tier: 'enterprise' },
+});
 ```
 
-All return `ComputedRef<Flag<T>>`.
+A rule can bucket on `user.key` while matching an audience condition on `organization.tier`.
 
-### Reactive flag key
+---
 
-`useFlag` (and `useFlagValue`) accept a `Ref<string>` or `ComputedRef<string>` as the key, and the subscription updates automatically when the key changes:
+## 7. Reading flags
 
 ```ts
-const selectedFlag = ref('feature-a')
-const flag = useFlag(selectedFlag, false)
+import { useFlag, useBoolFlag, useJsonFlag } from '@avsbhq/vue';
+import type { Flag } from '@avsbhq/vue';
+
+const darkMode = useBoolFlag('dark-mode', false);
+
+interface ApiConfig {
+  timeout: number;
+  retries: number;
+}
+const config = useJsonFlag<ApiConfig>('api-config', { timeout: 5000, retries: 3 });
+const timeout: number = config.value.value.timeout;
 ```
 
-### useAllFlags (all evaluated flags)
+The typed reads check the value against the type the platform declared for that flag. **On a mismatch nothing throws**: the SDK logs one warning naming the flag and the getter, then returns your `defaultValue` with `source: 'not_found'`. `useJsonFlag<T>` does not validate the shape of `T` at runtime, only that the flag is declared as JSON; validate the payload yourself if it crosses a trust boundary.
+
+A default value is always required, and it is what you get before the SDK is ready or when the key is unknown.
+
+### Reactive keys
 
 ```ts
-import { useAllFlags } from '@avsbhq/vue'
+import { ref } from 'vue';
 
-const flags = useAllFlags()
-// flags is ComputedRef<Record<string, Flag>>
-// Re-computes on any flagChange event.
+const selected = ref('feature-a');
+const flag = useFlag(selected, false); // re-subscribes when `selected` changes
 ```
 
-Prefer individual `useFlag` composables in most components. `useAllFlags` triggers on any flag change and is best suited for debug panels.
+### Every flag at once
+
+```ts
+const flags = useAllFlags(); // ComputedRef<Record<string, Flag>>
+```
+
+Re-computes on any flag change, so prefer `useFlag` in normal components. Exposures are suppressed and the SDK returns the same object between changes, so this is cheap to read on every render.
 
 ---
 
-## 7. Tracking events
+## 8. Exposures: what lands in your results
 
-```ts
-import { useTrack } from '@avsbhq/vue'
+Reads during render never record an exposure. That is deliberate: an exposure means "this visitor saw this decision", and Vue can re-render a component any number of times for reasons that have nothing to do with the visitor.
 
-const track = useTrack()
+```ts
+import { useExposure } from '@avsbhq/vue';
 
-function onClick() {
-  track('button_clicked', { location: 'header', variant: 'A' })
-}
+// In the component that actually shows the variation:
+useExposure('new-checkout-flow');
 ```
 
-The function is defined once in setup, so it is safe to use as an event handler without wrapping in a closure.
+`useExposure` fires on mount, once, or as soon as the SDK becomes ready if it is not yet. It is also the piece that makes server-rendered variants visible in results: if a value arrived as a prop from the server, call `useExposure` where it is rendered.
 
----
+Only decisions that belong in an experiment (A/B rules, holdouts, bandits) produce an exposure event; a plain rollout has nothing to record.
 
-## 8. Error handling
+For side effects that are not rendering:
 
-### Provider-level error state
+```ts
+useFlagSubscription('new-checkout-flow', (flag) => {
+  analytics.track('checkout_variant_assigned', { variationKey: flag.variationKey });
+});
+```
+
+---
 
-`<AvsbProvider>` exposes a `status` that transitions to `'error'` if `onReady()` rejects or if the client emits an `'error'` event. Use `useFlagReady` to gate rendering:
+## 9. Readiness and failure
 
 ```vue
 <script setup lang="ts">
-import { useFlagReady } from '@avsbhq/vue'
-const ready = useFlagReady()
+import { useAvsbStatus } from '@avsbhq/vue';
+
+const { status, error, degraded } = useAvsbStatus();
 </script>
 
 <template>
-  <div v-if="!ready">Loading flags...</div>
-  <MyApp v-else />
+  <SkeletonApp v-if="status === 'loading'" />
+  <template v-else>
+    <StaleDataNotice v-if="degraded" :message="error?.message" />
+    <MyApp />
+  </template>
 </template>
 ```
 
-### Custom logger
+- `'loading'`: no datafile yet and nothing cached.
+- `'ready'`: flags answer. A **degraded** client is ready: a refresh failed while a cached datafile is being served, so values work and may be stale. `error` says why.
+- `'error'`: nothing could be loaded. Every flag returns the default you passed, and `error.message` names the HTTP status, the URL tried, and the fix.
 
-Pass a logger to suppress or redirect SDK output:
+The SDK's default logger writes to the console at `warn` level in development and is silent in production. Override it per client:
 
 ```ts
-app.use(AvsbPlugin, {
-  sdkKey: '...',
-  logger: {
-    debug: (msg, ...args) => myLogger.debug(msg, ...args),
-    warn:  (msg, ...args) => myLogger.warn(msg, ...args),
-    error: (msg, ...args) => myLogger.error(msg, ...args),
-  },
-})
+const options = { logLevel: 'silent' } as const;
+```
+
+```vue
+<AvsbProvider :sdk-key="sdkKey" :options="{ logLevel: 'debug' }">
 ```
 
 ---
 
-## 9. SSR / Nuxt
+## 10. Server rendering
 
-For SSR, pre-fetch the datafile server-side and pass it as the `bootstrap` option to skip the initial network round-trip on the client:
+Fetch the datafile on the server and hand it to the provider, so the first render has real values instead of defaults:
 
 ```ts
-// server.ts
-import { AvsbClient } from '@avsbhq/browser'
+// Server
+import { fetchDatafile } from '@avsbhq/browser/server';
+import type { FlagDatafile } from '@avsbhq/vue';
+
+const sdkKey: string = process.env['AVSB_SDK_KEY'] ?? '';
 
-const client = new AvsbClient({ sdkKey: '...', bootstrap: serverDatafile })
+const datafile: FlagDatafile | null = await fetchDatafile(sdkKey, { timeout: 2000 });
 ```
 
 ```vue
-<!-- App.vue, client side -->
-<AvsbProvider :sdk-key="sdkKey" :bootstrap="bootstrapDatafile">
-  <NuxtPage />
+<!-- Client -->
+<AvsbProvider :sdk-key="sdkKey" :bootstrap="datafileFromServer" :context="userContext">
+  <App />
 </AvsbProvider>
 ```
 
-Flag composables return a `not_found` sentinel during the hydration window so SSR output matches the client's initial render.
+With a bootstrap the client is ready on the first pass: `useFlagReady()` is already `true`, no loading state renders, and the values match what the server rendered. Serialise the datafile into the page the way your framework escapes JSON.
+
+For Nuxt apps, use the @avsbhq/nuxt module, which wires this plugin, SSR bootstrap, and auto-imports for you. Outside Nuxt, the pattern above is the whole SSR story for Vue, and it is honest: without a bootstrap the first render shows your defaults.
 
 ---
 
-## 10. Graceful shutdown
+## 11. Pinia (optional)
 
-When using `<AvsbProvider>` in Mode A (sdkKey prop), the client is closed automatically on component unmount. This flushes any queued events.
+```ts
+import { useAvsbStore } from '@avsbhq/vue/pinia';
 
-When using Mode B (passing a pre-built `client` prop), you own the lifecycle:
+const avsb = useAvsbStore();
+
+avsb.status; // 'loading' | 'ready' | 'error'
+avsb.degraded; // boolean
+avsb.flags; // Record<string, Flag>, refreshed on any flag change
+avsb.identify({ kind: 'user', key: 'u_1' });
+avsb.track('checkout_started', { value: 99 });
+avsb.reset();
+```
+
+The store reflects the provider; it never creates a client. The first component that calls `useAvsbStore()` binds it, so that call has to happen somewhere under `<AvsbProvider>` (or in an app that installed `AvsbPlugin`).
+
+This lives on its own entry point on purpose. Importing it from the main barrel used to pull `pinia` into every Vue app whether or not it used Pinia, which broke module resolution for everyone else.
+
+---
+
+## 12. Plugin form
 
 ```ts
-onUnmounted(async () => {
-  await client.flush()
-  await client.close()
-})
+import { createApp } from 'vue';
+import { AvsbPlugin } from '@avsbhq/vue';
+import App from './App.vue';
+
+declare const userId: string;
+
+const app = createApp(App);
+
+app.use(AvsbPlugin, {
+  sdkKey: import.meta.env['VITE_AVSB_SDK_KEY'] as string,
+  context: { kind: 'user', key: userId },
+});
+
+app.mount('#app');
 ```
 
-The `AvsbPlugin` (Mode A) proxies `app.unmount` to close the client when the Vue app tears down.
+Same semantics as the component, provided at app level. In Mode A the plugin closes the client when the app unmounts, which flushes whatever events are queued.
+
+### One provider, please
+
+Nesting a second `<AvsbProvider>` inside another shadows the outer one for everything below it: two clients, two visitor ids, two event queues, and identify calls that only reach one of them. The provider logs a warning in development when it detects this. Mount one provider at the root unless you deliberately want an isolated subtree.
 
 ---
 
-## 11. Testing
+## 13. Graceful shutdown
 
-Inject a mock context directly via `provide`; no need to mount the full provider:
+Mode A closes the client for you on unmount, which flushes queued events. In Mode B you own it:
 
 ```ts
-import { defineComponent, h, provide } from 'vue'
-import { mount } from '@vue/test-utils'
-import { vi } from 'vitest'
-import { AvsbInjectionKey } from '@avsbhq/vue'
-import { notFoundFlag, createFlag } from '@avsbhq/core'
-
-function makeMockClient() {
-  return {
-    subscribe: vi.fn((_key, cb) => { /* store cb */ return () => {} }),
-    getSnapshot: vi.fn((key, def) => notFoundFlag(def, 'no data')),
-    on: vi.fn(() => () => {}),
-    onReady: vi.fn(() => Promise.resolve()),
-    close: vi.fn(() => Promise.resolve()),
-    track: vi.fn(),
-    identify: vi.fn(),
-    alias: vi.fn(() => Promise.resolve()),
-    reset: vi.fn(),
-  }
-}
+import { onUnmounted } from 'vue';
 
-const Wrapper = defineComponent({
-  setup() {
-    provide(AvsbInjectionKey, {
-      client: makeMockClient(),
-      status: 'ready',
-    })
-  },
-  render() {
-    return h(MyComponent)
-  },
-})
+onUnmounted(async () => {
+  await client.close(); // flushes internally
+});
+```
 
-const wrapper = mount(Wrapper)
+---
+
+## 14. Testing
+
+```ts
+import { mount } from '@vue/test-utils';
+import { AvsbTestProvider } from '@avsbhq/vue/testing';
+import CheckoutButton from './CheckoutButton.vue';
+
+const wrapper = mount(AvsbTestProvider, {
+  props: { flags: { 'checkout-v2': true } },
+  slots: { default: CheckoutButton },
+});
 ```
 
-Use `createFlag()` from `@avsbhq/core` to build typed flag fixtures:
+`AvsbTestProvider` is the real `<AvsbProvider>` in Mode B around a real `AvsbClient` whose datafile is built from your flags map, with the network, the cache, and logging switched off. Your components use the same composables, the same evaluator, and the same exposure rules they use in production.
+
+Each entry in `flags` becomes a flag that is fully rolled out, so `isEnabled()` is true for truthy values and reads record exposures exactly as an A/B rule would.
+
+Drive the client directly when that is simpler:
+
+```ts
+import { createTestClient, createTestDatafile } from '@avsbhq/vue/testing';
+
+const client = createTestClient({
+  flags: { 'checkout-v2': true },
+  context: { kind: 'user', key: 'u_1' },
+});
+
+expect(client.getBoolFlag('checkout-v2', false).isEnabled()).toBe(true);
+
+// Publish a new datafile and watch subscribers wake up.
+client.applyDatafileBootstrap(
+  createTestDatafile({ 'checkout-v2': false }, { publishedAt: '2024-06-01T00:00:00.000Z' }),
+);
+```
 
 ```ts
-import { createFlag } from '@avsbhq/core'
+import type { AvsbClient } from '@avsbhq/browser';
+import type { FlagDatafileEntry } from '@avsbhq/vue';
 
-const FLAG_ON = createFlag<boolean>({
-  value: true,
-  variationKey: 'on',
-  source: 'rule',
-  ruleId: 'r1',
-  ruleType: 'ab_test',
-  reasons: ['matched rule'],
-})
+/** Flag key to the value it serves. */
+type TestFlags = Record<string, boolean | string | number | object | null>;
+
+interface TestClientOptions {
+  flags?: TestFlags;
+  context?: EvalContext;
+  /** A full datafile, for when a map of values is not expressive enough. */
+  datafile?: FlagDatafile;
+}
+
+function createTestClient(options?: TestClientOptions): AvsbClient;
+function createTestDatafile(
+  flags?: TestFlags,
+  options?: {
+    sdkKey?: string;
+    environmentKey?: string;
+    publishedAt?: string;
+    entries?: FlagDatafileEntry[];
+  },
+): FlagDatafile;
 ```
 
+Call `client.close()` at the end of a test that tracked events, so the flush timer does not outlive it.
+
 ---
 
-## 12. Migration from LaunchDarkly
+## 15. Migration from LaunchDarkly
+
+| LaunchDarkly                           | `@avsbhq/vue`                                      |
+| -------------------------------------- | -------------------------------------------------- |
+| `LDPlugin` / `asyncWithLDProvider`     | `<AvsbProvider sdk-key>` or `app.use(AvsbPlugin)`  |
+| `ldClient.waitForInitialization()`     | `useFlagReady()` or `useAvsbStatus()`              |
+| `useFlags()`                           | `useAllFlags()`                                    |
+| `ldClient.variation('key', false)`     | `useBoolFlag('key', false).value.value`            |
+| `ldClient.variationDetail('key', d)`   | `useFlag('key', d)`                                |
+| `ldClient.identify(context)`           | `useIdentify()(context)`                           |
+| `ldClient.track('event', data, value)` | `useTrack()('event', { value, properties: data })` |
+| `ldClient.on('change:key', cb)`        | `useFlagSubscription('key', cb)`                   |
 
-| LaunchDarkly (React SDK)              | @avsbhq/vue equivalent                            |
-|---------------------------------------|----------------------------------------------------|
-| `<LDProvider clientSideID="...">`     | `<AvsbProvider sdkKey="...">`                      |
-| `useLDClient()`                       | `useAvsbClient()`                                  |
-| `useFlags()`                          | `useAllFlags()`                                    |
-| `useLDFlag('key', default)`           | `useFlag('key', default).value`                    |
-| `ldClient.identify(context)`          | `useIdentify()(context)`                           |
-| `ldClient.track('event')`             | `useTrack()('event')`                              |
-| `ldClient.variation('key', default)`  | `useAvsbClient()?.getFlag('key', default)`         |
+Differences worth knowing:
 
-Key differences:
+- Every read returns a `Flag<T>` object, not a raw value, so you get the decision metadata without a second call.
+- Every read requires an explicit default. There is no untyped variation call.
+- Multi-context is first class: one `EvalContext` with kinds, no wrapper type.
+- Reads during render record no exposure. Call `useExposure` where the visitor actually sees the decision.
+
+---
+
+## 16. Set this up with your AI assistant
+
+Paste this into Claude Code, Cursor, or any coding assistant:
+
+```text
+Set up A vs B feature flags in this Vue project.
+
+1. Run: npx @avsbhq/cli init
+   Use my saved CLI login: do not ask me for a token and do not put one in any file.
+   It detects Vue, writes the SDK key into the environment file this project's
+   bundler reads (VITE_AVSB_SDK_KEY for Vite), and writes an example component.
+2. Install @avsbhq/vue with this project's package manager.
+3. Mount <AvsbProvider> once at the root with that key and a context of
+   { kind: 'user', key: <your user id> }, then read the flag the example names.
+4. Every getter returns a ref to a Flag object, so keep the ref and read
+   flag.value.value or call flag.value.isEnabled(), and always pass a fallback.
+   Reading a flag records nothing: call useExposure(key) where the variation is
+   shown.
+5. Then run: npx @avsbhq/cli codegen
+
+Done looks like: the app starts, the flag reads without throwing, and avsb init
+prints the line confirming it saw the first check-in.
+```
 
-- `useFlag` returns a `Flag<T>` object, not a raw `T`. Access `.value` for the primitive or `.isEnabled()` for a boolean gate. This gives you the evaluation metadata (source, variationKey, reasons) without a second call.
-- All `getFlag` variants require an explicit `defaultValue`. There is no untyped `.variation()`.
-- Multi-context is a first-class concept, with no adapter required.
+`avsb init` ends by waiting for your app's first check-in and printing what it
+saw, so the terminal tells you it works rather than the dashboard.