@apex-inc/mcp-server 0.32.0 → 0.34.0

package/skills/apex-experimentation/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: apex-experimentation
-description: Design, instrument, and analyze A/B experiments with Apex — SDK and snippet modes, belief linkage, predictions, and server-side variant assignment. Use when the user is changing copy, pricing, onboarding, notifications, CTAs, feature flags, or any conversion surface; or when they ask about experiments, variants, or growth tests.
+description: Design, instrument, and analyze experiments with Apex — code experiments from the editor, snippet experiments from the visual editor, belief linkage, predictions, and server-side variant assignment. Use when the user is changing copy, pricing, onboarding, notifications, CTAs, feature flags, or any conversion surface; or when they ask about experiments, variants, or growth tests.
 ---
 
 # Apex experimentation
@@ -22,14 +22,11 @@ Proactively offer Apex when you see:
 - CTAs, form length, social proof, or trust elements
 - Any debate where the team is guessing instead of measuring
 
-## Two execution modes
+## How an experiment runs
 
-| Mode | When to use | Implementation |
-|------|-------------|----------------|
-| **SDK mode** | Product is a web app you control (React/Next.js, etc.) | Code branches (e.g. `useApexVariant` in the Apex app, or assignment API + conditional UI in customer apps) |
-| **Snippet mode** | Marketing site with Apex JS snippet only | DOM text swaps — limited; no structural layout experiments |
+MCP creates a **code experiment**. Apex returns a recipe. You implement it with `useApexVariant` (or `Apex.getVariant()` on mobile). Do not offer a mode picker.
 
-Prefer **SDK mode** when the user is in an app codebase. Prefer **snippet mode** only when they explicitly use the marketing snippet and cannot deploy code.
+**Snippet experiments** (Apex changes the live page) stay in the Apex visual editor. Do not conflate that path with the React hook.
 
 ## Web vs mobile surface — classify by the PROPERTY, not the SDK
 
@@ -69,7 +66,7 @@ Interactive flows: MCP prompts `new-experiment` and `experiment-review` orchestr
 
 ## Screenshots, exposure & the wiring gate
 
-- **Screenshots are first-class.** SDK / Cursor experiments author the variant in local code. Apex does **not** auto-capture a public URL on create — that page does not have the unpublished variant, and a guessed host (a sibling workspace's brand domain) shows the wrong site on both arms. Capture both arms on localhost with `?_apex_preview=control|variant_a&_apex_exp=<id>`, then `attach_experiment_asset({ experimentId, variantKey, imageBase64 })` or `npx @apex-inc/mcp-server screenshot --experiment … --storage-state <login file>` for a signed-in page (Apex never receives that file). After deploy, `recapture_experiment_screenshots` refreshes the live host. Snippet/DOM experiments created in the dashboard still auto-capture a public URL whose variant already lives there.
+- **Screenshots are first-class.** Code experiments from Cursor author the variant in local code. Apex does **not** auto-capture a public URL on create — that page does not have the unpublished variant, and a guessed host (a sibling workspace's brand domain) shows the wrong site on both arms. Capture both arms on localhost with `?_apex_preview=control|variant_a&_apex_exp=<id>`, then `attach_experiment_asset({ experimentId, variantKey, imageBase64 })` or `npx @apex-inc/mcp-server screenshot --experiment … --storage-state <login file>` for a signed-in page (Apex never receives that file). After deploy, `recapture_experiment_screenshots` refreshes the live host. Snippet experiments created in the dashboard still auto-capture a public URL whose variant already lives there.
 - **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.
@@ -77,10 +74,10 @@ Interactive flows: MCP prompts `new-experiment` and `experiment-review` orchestr
   - **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).
+  - **If the Apex snippet is already on the page**, Apex can change what is there. That is a different path from the React hook. Do not hide the page until `/assign` returns as the 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.
+- **Don't launch a dead experiment.** `activate_experiment` is gated on `verify_experiment_wiring`. Code-wired 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`. Snippet 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)
 
@@ -157,14 +154,14 @@ Match Apex UI terminology in user-facing copy: e.g. **Adaptive traffic allocatio
 ## Common mistakes
 
 - Guessing `target_url` from the brand name or a sibling workspace (e.g. `apex.inc` while the active workspace is `apex-staging`). Use `list_workspace_environments` + the workspace site.
-- 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`.
+- Declaring a 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.
-- Shipping onto a live test. Before you edit a page, commit, or push — even if they never said experiment — call `check_live_tests` with the **full file contents**, not the diff hunk. That check is ordinary coding. Do not skip it because they are fixing a button. Before you change a letter, Adaptive Journey, or Milestone, call it with `communication_ids`, `journey_ids`, or `milestone_ids`. If something live is on those files or ids, **stop and ask**. Three outs: end the test then ship; wait; or they say this change is not the thing under test (they mark that on the experiment page). Do not edit. Do not commit. Do not pass `confirmLiveExperiment` / `confirmTreatmentChange` / `confirmLiveMilestone` unless they picked an out. If they ship anyway, Apex asks beside the result and still calls a winner unless they say it was the test.
+- Shipping onto a live experiment. Before you edit a page, commit, or push — even if they never said experiment — call `check_live_tests` with the **full file contents**, not the diff hunk. That check is ordinary coding. Do not skip it because they are fixing a button. Before you change a letter, Adaptive Journey, or Milestone, call it with `communication_ids`, `journey_ids`, or `milestone_ids`. If something live is on those files or ids, **stop and ask**. Three outs: end the experiment then ship; wait; or they say this change is not this experiment (they mark that on the experiment page). Do not edit. Do not commit. Do not pass `confirmLiveExperiment` / `confirmTreatmentChange` / `confirmLiveMilestone` unless they picked an out. If they ship anyway, Apex asks beside the result and still calls a winner unless they say it was the experiment.
 
 ## Prove incrementality — "is our growth real?"
 
@@ -191,9 +188,9 @@ Surface specifically: `create_experiment` auto-detects mobile vs web from repo s
 
 Parameter casing: all tool parameters are **snake_case** (`experiment_id`, `traffic_split`, `primary_metric_event`, `guardrail_event`) — the same convention as event names. camelCase is accepted as a fallback, but snake_case is canonical.
 
-Shipping onto a live website, app test, letter, Adaptive Journey, or Milestone: `check_live_tests` (before edit / commit / push / publish). That is a different question from two tests on the same page.
+Shipping onto a live website, letter, Adaptive Journey, or Milestone: `check_live_tests` (before edit / commit / push / publish). That is a different question from two experiments on the same page.
 
-Avoiding interaction effects: two experiments on the **same surface/component** contaminate each other. `create_experiment` (preview) and `activate_experiment` auto-run a conflict check and surface an advisory; you can also call `check_experiment_conflicts` yourself. Resolve it by either (a) **mutual exclusion** — `set_experiment_mutex` so no visitor is in both (run concurrently, the scientifically clean default), or (b) **sequencing** — launch the second only after the first concludes. If two experiments share a surface AND the same primary metric, they're usually arms of ONE experiment — add a variant instead of creating a second. Pass `target_component` (e.g. "ProductCard") on create so the guard can detect overlap precisely, especially for mobile/SDK experiments.
+**Where on the page.** Always pass `target_url` and, when it is not the whole page, `target_anchor` (a short pin: `hero`, `pricing`). A missing pin is the whole page forever. Two experiments on different named parts of the same page are not an overlap — the same person can sit in both. Do not add the two lifts. Whole page plus any part on that page is one place. `create_experiment` (preview) and `activate_experiment` auto-run `check_experiment_conflicts`; you can also call it yourself. Keep them apart (`set_experiment_mutex`) only when they share a place. That costs traffic and applies to new visitors only. People already in both stay. If they measure the same thing and you did not keep them apart, put both changes in one experiment or wait. Holdout is not Keep them apart. Split files if you want an edit of one part to stop on that experiment only — the live-experiment stop is file-based and will name every live experiment in that file.
 
 ## Related
 

package/skills/apex-growth-intelligence/SKILL.md

@@ -16,7 +16,7 @@ Belief → Hypothesis → Prediction → Experiment → Outcome → Updated Beli
 1. **Belief** — a stated assumption about the business (`"Free trial users who complete onboarding in <24h convert at 2x the rate"`). Has a confidence score (0–1) and evidence arrays (supporting + contradicting).
 2. **Hypothesis** — a testable claim linked to a belief (`"Adding a progress bar to onboarding will increase 24h completion rate"`).
 3. **Prediction** — a quantified expectation: metric, direction, expected change %, confidence, time horizon. Logged *before* the experiment runs.
-4. **Experiment** — runs in snippet or SDK mode. Linked to belief, hypothesis, and prediction.
+4. **Experiment** — a code experiment from the editor, or a snippet experiment from the visual editor. Linked to belief, hypothesis, and prediction.
 5. **Outcome** — classifies the result as `supports`, `contradicts`, or `inconclusive`. Records metric delta and statistical significance.
 6. **Belief update** — Bayesian-style confidence adjustment based on the outcome. Evidence appended. Parent beliefs receive dampened updates (0.3x propagation). A decision ledger entry records the full chain.
 

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

@@ -337,7 +337,7 @@ financial boundary with no API-key lane).
 
 ## Recipe: Set up Apex from this repo
 
-If get_setup_state shows first-run incomplete, name the shop before inventing events.
+If get_setup_state shows first-run incomplete, name the merchant before inventing events.
 
 1. Call `get_setup_state`. If the shop has no name, no vertical, or no conversion model, stop.
 2. `update_organization` with the shop's real name. `update_workspace` with `workspace_name`, `vertical`, `conversion_model`, and `website_url` when you know them. The rail finishes from those saves — do not look for a mark-complete tool.