@apex-inc/mcp-server 0.25.0 → 0.27.0

package/package.json

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

package/skills/apex-adoption/SKILL.md

@@ -17,6 +17,8 @@ The Adoption Engine tracks whether each end-user has adopted each feature, nudge
   - **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).
 - Milestones can be given a sequence **order** (which one accounts reach first). Ordering the full set unlocks the account-view "Path" funnel (a step-by-step drop-off chart). Unordered milestones are treated as independent (order-agnostic coverage).
 
+Name live hosts (`list_workspace_environments` / `set_workspace_environments` or Foundations) before you trust Production adoption numbers. Unmatched hosts stay Unclassified.
+
 ## When to Activate
 
 - "Nudge users who signed up but never ran their first report."

package/skills/apex-communications/SKILL.md

@@ -7,6 +7,8 @@ description: Help users set up and manage lifecycle communications through Apex
 
 Use these tools to help users build a communication program that sends the right message at the right time — without building email infrastructure from scratch.
 
+One communication object. `audience_bucket` on create/edit is who gets it (`production` default, or `beta` / `dev`). Never All. Never Unclassified. Same email on TestFlight and the store is two contacts — a live send uses the live row only. Do not create a staging copy.
+
 ## When to Activate
 
 - User asks about setting up emails, notifications, or onboarding messages
@@ -54,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.
 
@@ -74,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
 
@@ -95,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
 
@@ -155,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"
@@ -180,6 +184,14 @@ Cart-recovery is a Journey (multi-step sequence with a wait) — not a single co
 
 The key is that the **journey** owns the wait, the branching on cart state, and the exit semantics. The **communications** are just the payloads the journey fires.
 
+## Writing copy
+
+When you draft or edit a letter:
+
+- Use contractions (we'll, it's, don't). People talk that way.
+- If the letter has pictures of variants, put them right after the title. Do not bury them under a wall of copy.
+- Write what the recipient needs: their experiment, their metric, their workspace. Do not write how the composer or a block works. The button label is enough.
+
 ## Theme vs Template
 
 **Template** is the job: event, attributes, slots, copy. Activate from the library. There is no extra theme step.

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") and starts them automatically at the first `experiment_exposure`. 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)
@@ -133,18 +133,18 @@ curl "https://app.apex.inc/api/v1/people/$(printf %s 'user@example.com' | jq -rR
 
 ## Environment separation — same key everywhere
 
-Apex auto-detects production / preview / localhost from the request hostname. **Use the same `workspaceKey` on staging and production.** Preview deploys and localhost are billed at $0 and hidden from the default dashboard.
+Use the **same `workspaceKey`** in Xcode, TestFlight, and the store. The phone files the build. Do not guess `staging.` / `qa.` / `dev.` hosts and do not set `environment` from `NODE_ENV`.
 
-Only pass the explicit `environment` override when your staging URL doesn't match the standard preview patterns (`*.vercel.app`, `*.netlify.app`, `staging.*`, `preview.*`, etc.):
+Four buckets:
 
-```typescript
-init({
-  workspaceKey: "apx_live_...",
-  environment: process.env.NODE_ENV === "production" ? "production" : "preview",
-});
-```
+- **Production** — hosts the merchant named live, plus App Store / Play production.
+- **Beta** — TestFlight, Play closed tracks, vendor preview hosts Apex can prove, plus hosts they named as Beta.
+- **Dev** — Xcode Run, Gradle DEBUG, sideloaded, localhost.
+- **Unclassified** — we could not prove a bucket. This is never Production.
+
+Every environment bills. Client-sent `environment` is dashboard slicing, never money truth. Do not create a second workspace. Name live hosts with `list_workspace_environments` / `set_workspace_environments` (or Foundations) before you trust the Production slice. Unmatched merchant hosts stay Unclassified. To clear the Unclassified Notice, name the host — do not add a second key and do not set `environment: production` on a server purchase to "fix" dollars. See `/docs/mobile/test-vs-production`.
 
-Do not recommend setting up a second workspace for staging. See `/docs/mobile/test-vs-production` for the full audience model.
+Server events may send `environment` / `release_channel`. Missing stays Unclassified. Required for honesty, not required to ingest.
 
 ## Data Sources & unified analytics
 

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
 
@@ -221,16 +221,17 @@ Use Gradle `buildConfigField` to inject the channel per build variant so the val
 
 ### Billing implications
 
-- **Dev** (Xcode-debug, Gradle-debug, sideloaded): always **free**.
-- **Beta** (TestFlight, Play internal/closed): always **free**.
-- **Production** (App Store, Play production): **billable**.
-- **Unknown** (older SDK without detection): billable, but the dashboard surfaces a fix-it nudge with an SDK upgrade prompt.
+Every environment bills — Dev, Beta, Production, and Unclassified. The monthly-reset free tier is the relief valve, not an environment exemption. `testMode` is a dry-run flag, not a free TestFlight bucket.
 
-No retroactive credits — if you misclassify a build, the fix takes effect for future events.
+Naming a site reclassifies events from that hostname immediately. Stored identity is not rewritten. Do not set `environment: production` to "fix" Unclassified money.
+
+### Name live sites before you trust Production
+
+Call `list_workspace_environments` (it also returns `unclassified_hosts_seen`) then `set_workspace_environments` with `production_hosts` and optional `beta_hosts`. Apex will not guess `staging.`. Naming reclassifies events from those sites at read time. Stripe / server purchase recipes must not set `environment: production` to "fix" Unclassified money.
 
 ### When NOT to recommend a separate workspace
 
-Some MMP vendors require two workspace keys (sandbox + live). Apex does not. If a merchant asks "should I use a different workspace for beta?" or "do I need a sandbox key?", the answer is **no**: point to `/docs/mobile/test-vs-production` and walk them through the **Build environments** card in Settings → Mobile apps.
+Some MMP vendors require two workspace keys (sandbox + live). Apex does not. If a merchant asks "should I use a different workspace for beta?" or "do I need a sandbox key?", the answer is **no**: point to `/docs/mobile/test-vs-production` and walk them through Foundations → Tell Apex which hosts are live.
 
 ## Related
 

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)