@apex-inc/mcp-server 0.22.1 → 0.23.0

package/package.json

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

package/skills/apex-communications/SKILL.md

@@ -25,11 +25,72 @@ Use these tools to help users build a communication program that sends the right
 
 ### Editing and testing
 
-1. **`list_communications`** — see what exists.
-2. **`edit_communication`** — update subject, body, CTA, channels, or status.
+1. **`list_communications`** — see what exists, and check `controlState` before you edit.
+2. **`edit_communication`** — update subject, body, CTA, channels, or status. Pass `intent` when the control is protected (see below).
 3. **`preview_communication`** — render the email with the user's brand.
 4. **`send_test_communication`** — send a test to verify it looks right.
 
+## Replace versus compete — the one rule that protects results
+
+A communication's **Control** is what everyone receives. It is often not just
+"the default copy": it can be the **winner** of an experiment Apex already ran,
+and it can be what a published journey is sending to real people right now.
+Overwriting it silently throws away either a measured result or a live
+experience, so Apex won't let you do it by accident.
+
+`list_communications` returns `controlState` for every comm:
+
+| `controlState` | What it means | Editing it |
+|---|---|---|
+| `none` | Never experimented on | Edit freely |
+| `no_winner` | An experiment ran and settled without a winner | Edit freely; worth re-testing |
+| `winner` | Won an experiment, unchanged since | Needs `intent` |
+| `winner_edited` | Won, then was changed | Needs `intent` |
+| `in_experiment` | Frozen — an experiment is measuring it right now | Blocked; see below |
+
+A comm that's live in a published journey also needs `intent`, whatever its
+`controlState`.
+
+### 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.
+
+### 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 `replace` when the user wanted `compete` **destroys a measured
+  result permanently**. There's no undo for evidence.
+
+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?"
+
+### Don't force through a running experiment
+
+`in_experiment` is a hard stop, not an intent question — the content is a
+treatment mid-measurement. `edit_communication` accepts
+`confirm_live_experiment: true` to override, and that **marks the experiment
+invalid and excludes its result from the belief graph**. Never pass it on your
+own initiative. Offer the alternatives first: wait for the experiment to
+finish, or end it with `conclude_experiment` / `promote_winner` so the learning
+is captured.
+
+If you omit `intent` when it's needed, the server returns a 409 that names both
+options. That's a fork in the road, not a failure — read it, ask the user, and
+re-issue. Do not retry the identical call.
+
 ### Running experiments
 
 1. **`list_communications`** — find the communication to test.

package/skills/apex-experimentation/SKILL.md

@@ -81,7 +81,34 @@ For experiments that run inside an Adaptive Journey (control vs variant email/co
 - `get_experiment_results` — computed results + the readiness verdict (`collecting | decisive | inconclusive | guardrail`). Check this before promoting: only `decisive` means a confident winner.
 - `promote_experiment_winner` — re-verifies the readiness gate server-side, writes the winning variant's content into the canonical communication as a new version, and archives the losers. Pass `force: true` only to override the gate deliberately.
 
-Journey-arm experiments are authored in the journey canvas (Experiment step) and launched on journey publish; the SDK/MCP surface is for reading results and promoting.
+Journey-arm experiments are authored in the journey canvas (Experiment step) and launched on journey publish. They can also start from the communication side — see below.
+
+## The winner is the control
+
+There is one control per communication, and it is the last thing that won. When you promote a winner, its content is merged into the communication itself; there is no separate "winning variant" living alongside the control afterwards. This matters for how you reason about a chain of experiments:
+
+- **An experiment always compares the current control against new variants**, never version 3 against version 5. Whatever won last time IS the control this time, so a chain of experiments reads as a chain of improvements against a moving, always-current baseline.
+- **`get_experiment_results` reports the previous baseline** alongside control and variant. For a chained experiment that number is the rate the predecessor's winner achieved — which is what stops "variant beat control by 8%" from hiding the fact that the control was already three rounds of improvement deep.
+- **A communication hosts one experiment at a time.** Starting a second returns 409 `comm_already_in_experiment`. That constraint is what lets "what won?" have exactly one answer.
+
+Do NOT describe this as champion versus challenger, and do not try to run "the old version versus the new version" as two concurrent experiments. Both were earlier models; neither is how Apex works now.
+
+### 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:
+
+- **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`.
+
+### 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.
+
+Omitting `intent` when it's required returns 409 `intent_required` naming both. Do not pick `replace` to clear the error.
 
 ## Server-side variant assignment (integrator apps)