@apex-inc/mcp-server 0.27.2 → 0.27.4

package/guardrails/experiment-rules.md

@@ -13,6 +13,17 @@
 ## Implementation
 - Resolve the variant with the canonical Apex resolver (`useApexVariant` on web,
   `Apex.getVariant()` on mobile). Both fire the `experiment_exposure` event.
+- Merchants still write `const variant = useApexVariant("exp_…")` and branch.
+  First HTML is flicker-free only when the server already assigned the visitor
+  and passed that arm (`initialVariant` or `<ApexProvider assignments>`).
+  Mint or read `apex_vid` on the document request and assign with the same
+  rules as `GET /api/experiments/{id}/assign`. If you use Next.js,
+  `npm install @apex-inc/next @apex-inc/react`, then
+  `apexVisitorMiddleware`, `assignExperiments`,
+  `<ApexProvider assignments>`. The hook alone is not flicker-free. A
+  client-only SPA cannot know the arm before first HTML; do not promise
+  no flicker there. Do not hide the page until assign (worse LCP).
+  Creating the experiment via MCP does not remove flicker.
 - The variant must fall back to control on ineligible / error.
 - For VISUAL changes, confirm the arms actually differ — screenshot both. Class
   overrides can silently no-op (e.g. when the codebase doesn't tailwind-merge),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apex-inc/mcp-server",
-  "version": "0.27.2",
+  "version": "0.27.4",
   "description": "MCP server for Apex \u2014 currently in private beta.",
   "type": "module",
   "main": "dist/index.js",

package/skills/apex-adoption/SKILL.md

@@ -11,7 +11,9 @@ The Adoption Engine tracks whether each end-user has adopted each feature, nudge
 
 - A **milestone** = "has this end-user adopted feature X?" — defined by an event they fire (`report_run`) or a trait (`plan = pro`). It is per-user and per-feature. It is **not** a goal (goals are workspace/experiment/journey success).
 - Apex ranks a user's unmet milestones by priority and sends the single top nudge per cadence — so nobody gets spammed.
-- A ~10% deterministic holdout is kept automatically; the report shows lift vs that holdout, not last-touch attribution. Users in an active experiment are never nudged.
+- A deterministic holdout is kept automatically (~5–10%); the report shows lift vs that holdout. Users in an active experiment are never nudged.
+- New milestones default to **future-only** (`enroll_mode: "future"`): only people who sign up after the milestone is created can enter the nudge. Pass `enroll_mode: "all"` to include the historical roster. Existing milestones without `enrollMode` stay "all" so live lists do not shrink.
+- `gap_hours` wins over `gap_days`. `0` hours or days means right away. Do not assume a 1-day floor.
 - A milestone has **two possible journeys**, and they are opposites:
   - **Nudge** (audience-entry): fires when a user *hasn't* adopted within the gap window. Drives them toward the feature.
   - **Celebration** (fires once on adoption): congratulates the user the moment they *do* reach the milestone, and tells them what's next. Scaffold both legs in one call with `compose_adoption_milestone` + `scaffold: "both"` (this mirrors the dashboard sentence on-ramp).
@@ -79,19 +81,20 @@ raw `predicate`:
 
 ### "Nudge users who haven't run their first report"
 1. `list_adoption_milestones` → check it doesn't already exist.
-2. `create_adoption_milestone` with `name: "Ran first report"`, `featureKey: "reporting"`, `adoptedWhenKind: "event"`, `eventName: "report_run"`, `gapDays: 3`. Leave `active` off first.
+2. `create_adoption_milestone` with `name: "Ran first report"`, `feature_key: "reporting"`, `adopted_when_kind: "event"`, `event_name: "report_run"`, `gap_days: 3` (or `gap_hours` for a same-day clock). Defaults to future-only. Leave `active` off first. Read the `warnings` in the response — a duplicate event or an event never seen on an identified person is a hard honesty problem.
 3. Tell the user it's created as a draft, and that turning it on (`update_adoption_milestone` with `active: true`) starts nudging through their journeys (opt-out + caps respected).
 4. Later: `get_adoption_metrics` → report the lift-vs-holdout so they know whether it worked.
 
 ### "Congratulate users when they start their first experiment"
 1. `compose_adoption_milestone` with `name: "Started first experiment"`, `featureKey: "experiments"`, `adoptedWhenKind: "event"`, `eventName: "experiment_started"`, `scaffold: "celebration"`. This creates the milestone AND a draft celebration journey wired to fire once, the moment the user reaches it.
-2. Tell the user the celebration journey is a **draft** — they edit the congratulatory message in the canvas (Communications composer), then publish it.
+2. Tell the user the celebration journey is a **draft**. Preview with `preview_communication`, then `publish_journey` (dry-run first).
 3. Turning the milestone on is separate from publishing the journey; both must be live for the celebration to send.
 
 ### "Set up a full milestone — nudge the ones who don't, celebrate the ones who do"
-1. `compose_adoption_milestone` with `scaffold: "both"` (e.g. `name: "Started first experiment"`, `featureKey: "experiments"`, `adoptedWhenKind: "event"`, `eventName: "experiment_started"`, `gapDays: 7`). One call creates the milestone plus BOTH draft journeys: the nudge (for users who haven't started an experiment within 7 days) and the celebration (for the moment they do). This is exactly what the dashboard sentence on-ramp produces.
-2. The response carries `nudgeJourneyId` and `celebrationJourneyId` — both are **drafts**. Edit copy in the canvas and publish each.
-3. Turn the milestone on (`update_adoption_milestone` `active: true`) once its nudge is published, so it can measure lift vs the holdout.
+1. `compose_adoption_milestone` with `scaffold: "both"` (default). Example: `name: "Started first experiment"`, `feature_key: "experiments"`, `adopted_when_kind: "event"`, `event_name: "experiment_started"`, `gap_hours: 1` (or `gap_days: 7` in production). One call creates the milestone plus BOTH draft journeys.
+2. The response carries `nudge_journey_id`, `celebration_journey_id`, and `warnings`. Preview the letter with `preview_communication`, then `publish_journey` (dry-run first). Do not activate until the letter is previewed and the journey is published.
+3. Do not scaffold a celebration on an event that already has a published operator letter (experiment started, domain verified, etc.) — pass `scaffold: "nudge"`.
+4. Turn the milestone on (`update_adoption_milestone` `active: true`) once its nudge is published, so it can measure lift vs the holdout.
 
 ### "Put my milestones in the order accounts should hit them"
 1. `list_adoption_milestones` → get the ids.

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).
+  - **MCP does not serve the visitor page.** `create_experiment` / `activate_experiment` do 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.
 
 ### Journey-arm experiments (any surface)
@@ -126,6 +132,8 @@ Omitting `intent` when it's required returns 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.
@@ -137,7 +145,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).
@@ -152,6 +160,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 via MCP 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.