@apex-inc/mcp-server 0.25.0 → 0.26.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apex-inc/mcp-server",
-  "version": "0.25.0",
+  "version": "0.26.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
@@ -180,6 +182,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 **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.
 
 ### Journey-arm experiments (any surface)
 

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

@@ -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

@@ -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