@apex-inc/mcp-server 0.26.0 → 0.27.0

package/package.json

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

package/skills/apex-communications/SKILL.md

@@ -56,19 +56,19 @@ A comm that's live in a published journey also needs `intent`, whatever its
 
 ### The two intents
 
-- **`intent: "compete"`** — *Add as a variant.* Your edit runs as an experiment
-  against the current content. Nothing changes for recipients yet; Apex measures
-  which one is better and tells you.
-- **`intent: "replace"`** — *Update for everyone.* Your edit becomes what
-  everyone receives. Any prior win is superseded.
+- **`intent: "compete"`** — *Start an experiment.* What's sending now stays
+  live. Publish creates a filled-in draft. Then `activate_experiment` after
+  the user confirms.
+- **`intent: "replace"`** — *Replace what's sending.* Everyone gets this
+  version on the next send. No experiment row.
 
 ### When in doubt, compete
 
 This is the default, and it isn't a coin flip. The two mistakes are not
 symmetric:
 
-- Guessing `compete` when the user wanted `replace` costs **time** — they see
-  an experiment start and can promote the winner immediately.
+- Guessing `compete` when the user wanted `replace` costs **time** — they have
+  a draft to activate, or they can publish again with replace.
 - Guessing `replace` when the user wanted `compete` **destroys a measured
   result permanently**. There's no undo for evidence.
 
@@ -76,9 +76,9 @@ So: if the user explicitly said "just change it for everyone" / "replace the
 copy" / "roll this out," send `replace`. Otherwise send `compete`, and say what
 you did:
 
-> "That comm's control won an experiment, so I added your new copy as a variant
-> and started an experiment against it rather than overwriting the winner. Want
-> me to make it the control for everyone instead?"
+> "That comm's control won an experiment, so I published your copy as a
+> competing version and opened a filled-in draft. Want me to activate it, or
+> make this the letter everyone gets instead?"
 
 ### Don't force through a running experiment
 
@@ -97,9 +97,10 @@ re-issue. Do not retry the identical call.
 ### Running experiments
 
 1. **`list_communications`** — find the communication to test.
-2. **`create_comm_experiment`** — set up the A/B test with variants.
-3. The experiment runs automatically via Thompson Sampling.
-4. Check results via `list_communications` or the dashboard.
+2. **`edit_communication` / `add_communication_variant`** — write the versions.
+3. **`publish_communication`** with `intent: "compete"` — creates a prefilled draft. Does not start the test.
+4. **`activate_experiment`** — begins the test on the next send.
+5. Check results via `get_results` / `list_experiments`.
 
 ### Manual sends
 
@@ -157,15 +158,16 @@ hard-block**. For those journeys, filter to `pipeline="marketing"`.
 ```
 1. recommend_communications → look for retention/winback entries
 2. generate_communications for churn-related comms
-3. create_comm_experiment to A/B test the messaging
+3. add_communication_variant, publish_communication (compete), then activate_experiment
 4. get_event_taxonomy to see what churn signals to track
 ```
 
 ### "How do I A/B test my emails?"
 ```
 1. list_communications → find the target
-2. create_comm_experiment with subject or body split
-3. Explain Thompson Sampling: traffic shifts automatically toward the winner
+2. add_communication_variant (or edit the second column)
+3. publish_communication intent=compete → filled-in draft
+4. activate_experiment after the user confirms
 ```
 
 ### "Set up cart abandonment recovery"

package/skills/apex-experimentation/SKILL.md

@@ -72,7 +72,7 @@ Interactive flows: MCP prompts `new-experiment` and `experiment-review` orchestr
 - **Screenshots are first-class.** For public web URLs, `create_experiment` auto-captures control + variant screenshots and shows them on the dashboard experiment card + detail gallery. For localhost / auth-gated / mobile screens, capture the image yourself and call `attach_experiment_asset({ experimentId, variantKey, imageBase64 })`.
 - **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.
-- **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 **live customer** exposure — not merge, not activate, not TestFlight. Testers can still get an arm while waiting. 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 (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, not localhost. Testers on a named Beta site count in the winner. Localhost does not. 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)
 
@@ -95,18 +95,28 @@ Do NOT describe this as champion versus challenger, and do not try to run "the o
 
 ### Starting an experiment from the communication side
 
-`publish_communication` is the other way an experiment starts. Publishing a communication that has variants starts the experiment measuring them against the control, on the published journey that sends it. Preconditions, each reported rather than guessed:
+Write the letter with `edit_communication` / `add_communication_variant`. Then:
+
+1. `publish_communication` with `intent: "compete"` (or when variants already exist). This creates a **prefilled draft** on the same experiment page as web tests. It does **not** start the test.
+2. Show the user the draft. They can edit window, hypothesis, belief.
+3. `activate_experiment` starts it. People on that journey get control or the variant on the next send. Screenshots are captured on activate — do not call `attach_experiment_asset` for a letter unless capture failed.
+
+`intent: "replace"` publishes the letter for everyone. Leftover variant columns leave. No experiment row.
+
+Preconditions for a draft, each reported rather than guessed:
 
 - **A host** — some published journey must send the communication. `no_host` means there is no traffic to measure.
 - **A goal** — the host step's own goal event, or the journey's. `no_goal` means there is nothing to optimize toward; set the journey's goal event first.
 - **One host** — 409 `ambiguous_experiment_host` lists the candidates when several journeys send it. Ask the user which, then re-issue with `host_journey_id`.
 
+When in doubt, compete. The cheap mistake is now "they have a draft to activate," not "they already have a live test."
+
 ### Editing a control that won
 
 `edit_communication` and `publish_communication` both take `intent` when the control is protected (it won an experiment, or a published journey is sending it):
 
-- `"compete"` — the current content keeps sending and your change runs against it as an experiment. **This is the default when the user hasn't said otherwise**; it is recoverable.
-- `"replace"` — your change becomes what everyone receives, superseding the prior win. This permanently discards a measured result.
+- `"compete"` — the current content keeps sending. Publish opens a filled-in draft. Then `activate_experiment`. **This is the default when the user hasn't said otherwise**; it is recoverable.
+- `"replace"` — your change becomes what everyone receives, superseding the prior win. No experiment row.
 
 Omitting `intent` when it's required returns 409 `intent_required` naming both. Do not pick `replace` to clear the error.
 
@@ -160,7 +170,7 @@ Editability is gated by lifecycle, keyed to DATA:
 
 - **Draft, no exposures yet:** fully editable. Use `update_experiment({ experimentId, ... })` to fix a mislabeled surface, rename, or correct the hypothesis/metric/guardrail. This is where typo and surface fixes belong.
 - **Running, or any exposures recorded:** the pre-registration (hypothesis, metric, guardrails) and bucketing (surface, variants) FREEZE. `update_experiment` returns `experiment_locked` with the reason — that's intentional, so results stay valid. Do not fight it.
-- **After freeze:** call `fork_experiment({ experimentId })`. It duplicates the design into a fresh draft (no data carries over, lineage recorded), which you then edit and activate.
+- **After freeze:** call `fork_experiment({ experimentId })`. It duplicates the design into a fresh draft (no data carries over, lineage recorded). A copy gets a new id — replace `useApexVariant("<old id>")` with the new id, deploy, then activate. Preview still works via `_apex_exp`; a normal visit shows control until the new id is shipped.
 
 Surface specifically: `create_experiment` auto-detects mobile vs web from repo signals (capacitor.config.* / @apex-inc/capacitor-plugin) and the workspace's registered data sources when you omit `surface`; if a Capacitor app got mislabeled `web`, fix it on the draft with `update_experiment({ experiment_id, surface: "mobile" })` before the first exposure, or fork if it's already running.
 

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

@@ -20,7 +20,7 @@ Apex ingests **events** and **identities** so experiments, attribution, and inte
 ## Event naming
 
 - Use **snake_case** or **dot-separated** consistent verbs: `page_viewed`, `signup_started`, `trial_started`, `notification_clicked`.
-- Include **context** in properties, not in the event name explosion: `track("button_clicked", { surface: "pricing", label: "start_trial" })` vs dozens of `pricing_start_trial_clicked` events.
+- Include **context** in properties, not in the event name explosion: `track("ui_action", { action: "click", name: "Start trial", location: "pricing" })` vs dozens of `pricing_start_trial_clicked` events.
 - For experiments, include **`experimentId`** and **`variant`** when the event is relevant to that exposure.
 
 ## Canonical attributes (the Schema)

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

@@ -118,7 +118,7 @@ For agent-driven testing through MCP, use the **`send_server_event`** tool — s
 ## Event naming conventions
 
 - **snake_case**: `signup_completed`, `feature_used`, `invoice_paid`
-- Context in **properties**: `track("button_clicked", { surface: "pricing", label: "start_trial" })`
+- 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
 

package/skills/apex-spec/SKILL.md

@@ -94,6 +94,12 @@ find where each business truth already lives and instrument it there.
 - Revenue events MUST carry `value` + `currency`, and a stable
   external id when one exists (order id, invoice id) — dedupe depends
   on it.
+- Do **not** invent one event per button. In-product chrome (named
+  buttons, widget close/minimize/move, nav picks) is `ui_action` with
+  `action` + `name` + optional `location`. Outcomes stay semantic:
+  `integration_selected`, `setup_step_continued`, `integration_connected`.
+  `click` is the snippet's outbound-link auto-event; do not use it for
+  dashboard buttons.
 
 ## Vertical event sets (Vertical Widget Packs, 2026-07)