@apex-inc/sdk 0.20.1 → 0.21.0

package/skills/apex-experimentation/SKILL.md

@@ -73,7 +73,13 @@ Interactive flows: MCP prompts `new-experiment` and `experiment-review` orchestr
 - **Target URL is this workspace.** `target_url` must be a host named on the **active** workspace (`list_workspace_environments` + the workspace site). If the merchant already named a workspace, switch to it — do not ask which workspace again. If they have multiple hosts on that workspace, ask which URL. Never guess `apex.inc` or any other workspace's domain.
 - **Mobile/Capacitor experiments capture on-device.** When the experiment runs on an authed in-app screen (servers can't reach it), tell the dev to call `Apex.captureVariantScreenshot({ experimentId, variantKey })` on the variant's screen, keyed to the resolved variant in a `useEffect`, in a debug build (`Apex.initialize({ ..., debug: true })`). It no-ops in production and lands the shot on the dashboard card + gallery like web/agent captures.
 - **Exposure auto-fires.** When a variant resolves via `useApexVariant` (web) or `Apex.getVariant()` (mobile), the SDK fires the canonical `experiment_exposure` event — the denominator for results. You don't fire it manually.
-- **Preview on Next.js.** `useApexVariant` cannot read `window` during SSR. Pass the request search string (`useApexVariant(id, { search })` from `searchParams`, or `<ApexProvider search>`) so the first HTML matches `_apex_preview`. Without it the server renders control and the arm only appears after hydrate.
+- **First HTML / flicker.** Merchants still write `const variant = useApexVariant("exp_…")` and branch in React. That hook is not flicker-free by itself. First HTML is flicker-free only when it is already the assigned arm.
+  - **SSR (Next, Remix):** on the document request, mint or read the `apex_vid` cookie. Assign with the same rules as `GET /api/experiments/{id}/assign`. Pass that arm: `useApexVariant(id, { initialVariant, search })` or `<ApexProvider assignments={{ [id]: variant }}>`. `{ search }` also makes `_apex_preview` match on first HTML. Without the server arm, the first HTML is control; after `/assign` returns, React swaps. That swap is the flicker.
+  - **If you use Next.js:** `npm install @apex-inc/next` (visitor middleware + `assignExperiments`). Pass the result to `<ApexProvider assignments>`.
+  - **Client-only SPA:** the hook cannot know the arm before first HTML. Do not promise no flicker.
+  - **Snippet mode** (Apex mutates the DOM) is a different path. Do not conflate. Do not hide the page until `/assign` returns as the React-hook promise (worse LCP).
+  - Creating or activating an experiment (MCP or API) does not serve the visitor page and does not remove flicker. The merchant app must still pass the server arm.
+  - Pass the server arm into the hook or provider. `@apex-inc/react@0.4.3` accepts `initialVariant` and `ApexProvider assignments`.
 - **Don't launch a dead experiment.** `activate_experiment` is gated on `verify_experiment_wiring`. Code-wired (SDK-hook) web experiments are safe to activate before their code ships: the server holds them in `pending_deployment` ("Waiting on deploy"). The 14-day clock starts at the first **recorded** visit (a tester on a named Beta site, or a live visit) — not merge, not activate. Testers on a named Beta site count in the winner. Localhost/dev is recorded as Dev and does not start the window or decide the winner. Assign with no Origin is Unclassified (no enrollment). Backend assign must send `environment` or `x-apex-web-environment`. Non-SDK experiments with unwired arms are refused (pass `force: true` to override). Run `verify_experiment_wiring({ experimentId })` after the deploy lands to confirm both arms are live.
 
 ## The winner is the control
@@ -116,6 +122,8 @@ Omitting `intent` when it's required throws a 409 `intent_required` naming both
 
 `GET /api/experiments/{experimentId}/assign` returns `{ variant, experimentId, visitorId }`. Assignment is **deterministic** from a stable visitor id (cookie `apex_vid` in browsers).
 
+The same assign call is how a Next/Remix document request gets flicker-free first HTML: read or mint `apex_vid`, assign, pass the arm into `useApexVariant` / `ApexProvider`. If you use Next.js, `@apex-inc/next` does that. See First HTML / flicker above.
+
 For **server-side** sends (e.g. PLG email or API-triggered notifications):
 
 1. Use a **stable string per recipient** as the visitor id (e.g. hashed user id). Reuse the same id for every assignment call for that user for that experiment.
@@ -127,7 +135,7 @@ Then branch notification copy or UI on `variant` (`control` vs `variant_b`).
 ## Instrumentation checklist
 
 1. **Create and activate** the experiment in Apex (UI or MCP).
-2. **Assign variant** before rendering the experience.
+2. **Assign variant** before rendering the experience. On SSR, that means on the document request, then pass the arm into the hook or provider.
 3. **Track primary metric** events with consistent names (e.g. `notification_sent`, `notification_opened`, `goal_completed`) and include `experimentId` and `variant` in properties when possible.
 4. **Log a prediction** before launch when using the full intelligence loop (calibration).
 5. **Decide** with `get_results` / dashboard — avoid peeking without a rule (pre-registered sample size, Bayesian policy, or fixed run duration).
@@ -142,6 +150,8 @@ Match Apex UI terminology in user-facing copy: e.g. **Adaptive traffic allocatio
 - Declaring an SDK / Cursor draft ready from hosted screenshots of a public URL. The variant is local until deploy — attach localhost shots with `attach_experiment_asset`.
 - Starting an experiment without a **clear primary metric** tied to the belief.
 - Using different visitor ids for the same user across channels (breaks consistent assignment).
+- Promising no flicker from `useApexVariant` without passing a server arm. Creating the experiment does not remove flicker.
+- Hiding the page until `/assign` returns (worse LCP; not the React-hook promise).
 - Changing variant implementation mid-flight without versioning (invalidates analysis).
 - Only using p-values without effect size or business context.
 

package/skills/apex-integration-cookbook/SKILL.md

@@ -27,7 +27,7 @@ Events are batched and sent to `POST /api/events` automatically. Call `flush()`
 
 ```typescript
 // On signup
-track("signup_completed", { method: "email", plan: "free" });
+track("user_signed_up", { method: "email", plan: "free" });
 identify(user.id, {
   email: user.email,
   name: user.name,
@@ -210,7 +210,7 @@ still reduces revenue, but leaves the margin untouched.
 
 ## Event naming conventions
 
-- **snake_case**: `signup_completed`, `feature_used`, `invoice_paid`
+- **snake_case**: `user_signed_up`, `feature_used`, `invoice_paid`
 - Context in **properties**: `track("ui_action", { action: "click", name: "Start trial", location: "pricing" })`
 - For experiments, include `experimentId` and `variant` in properties
 - One primary metric per experiment; secondary metrics as properties
@@ -313,11 +313,11 @@ import { createManagementClient } from "@apex-inc/sdk";
 const apex = createManagementClient({ apiKey, workspaceKey, apiUrl });
 
 // Define the primary conversion — a custom_event matching the Apex Spec
-// event you send via apex.track("signup_completed", …)
+// event you send via apex.track("user_signed_up", …)
 const signup = await apex.conversions.create({
   name: "Signup",
   type: "custom_event",
-  eventName: "signup_completed",
+  eventName: "user_signed_up",
   isPrimary: true,
 });
 

package/skills/graduation-pipeline/SKILL.md

@@ -23,7 +23,11 @@ Call `check_workspace_readiness` (pass the current `owner/repo`). Resolve gaps:
    max duration, stopping rule) — all four are required to arm the gate.
 2. `create_experiment` → `exp_id`.
 3. Author the variant in the IDE: wrap the target with `useApexVariant("exp_id")`, add the
-   variant branch. Show the diff; let the developer tweak.
+   variant branch. On SSR, assign on the document request (mint or read `apex_vid`, same
+   rules as `GET /api/experiments/{id}/assign`) and pass that arm (`initialVariant` or
+   `<ApexProvider assignments>`). If you use Next.js, `npm install @apex-inc/next` and
+   pass `assignExperiments` into `<ApexProvider assignments>`. The hook alone is not flicker-free. A client-only SPA
+   cannot know the arm before first HTML. Show the diff; let the developer tweak.
 4. Commit with a Conventional Commit message that includes the id, e.g.
    `feat(apex): move pricing CTA above the fold for exp_482`. Add a
    `Co-Authored-By: Apex <apex@apex.inc>` trailer **unless** the workspace's "Apex