@apex-inc/mcp-server 0.28.0 → 0.29.0

package/package.json

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

package/skills/apex-adoption/SKILL.md

@@ -32,7 +32,11 @@ Do not say reminder, congratulations, clock, or watch list as names they see.
 
 ## Core idea
 
-- A Milestone is per person, per feature. Event (`report_run`) or trait (`plan = pro`).
+- A Milestone is **This person** unless they set **Anyone here**. Absent `finish_when` = This person. Existing rows stay This person until they flip them.
+- **This person** — only that person finishes. Their letters stay theirs.
+- **Anyone here** — first person on the same **Account** (`identify({ account: { id } })`) finishes it for the company. Leftover Nudges stop for the others. **Only the person who did it gets the Celebration.** Trait finishes stay This person.
+- Company facts (snippet live, SSO, billing) → Anyone here. Person skills (ran a report, invited a teammate) → This person.
+- `update_adoption_milestone` can flip a live event Milestone. Flipping to Anyone here backfills leftover Nudges for Accounts that already have a doer. A teammate who joins later inherits Done.
 - Hours or days from signup (or the anchor). `0` is right away. 1 hour is not right away.
 - New Milestones default to **from now on** (`enroll_mode: "future"`). Do not publish a short clock on everyone already here (`enroll_mode: "all"`).
 - Each Send gets its **own** Communication. Never reuse `comm-adoption-nudge` or `comm-adoption-celebration`.
@@ -57,10 +61,12 @@ Name live hosts (`list_workspace_environments` / `set_workspace_environments` or
 | `get_adoption_milestone` | Inspect one |
 | `create_adoption_milestone` | Define a Milestone (just-track unless they compose) |
 | `compose_adoption_milestone` | Create a Milestone and stamp **one** Adaptive Journey |
-| `update_adoption_milestone` | Change priority / order / hours or days / on-off |
+| `update_adoption_milestone` | Change priority / order / hours or days / on-off / `finish_when` |
 | `reorder_adoption_milestones` | Sequence for the Path funnel |
 | `delete_adoption_milestone` | Remove a Milestone |
 | `get_adoption_metrics` | Funnel + one lift number |
+| `get_adoption_user_progress` | One person's Path (Not yet / Started / Done) |
+| `get_adoption_account_progress` | One company's Path: who finished, how many are still Not yet |
 | `attach_adoption_milestone_still` | Attach Not yet or Done |
 | `list_adoption_milestone_stills` | List those two pictures |
 | `recapture_adoption_milestone_stills` | Capture from public pages on a named host |
@@ -81,7 +87,7 @@ Read-only summary: `apex://adoption`.
 
 Returns one `journey_id` (also `nudge_journey_id` for old callers) and each Send as `{ role, step_id, comm_id }`. `celebration_journey_id` is null on new rows.
 
-Params: `action_label`, `gap_hours` or `gap_days`, `nudge_clocks` (each hours or days), `save_not_yet_segment`, `save_done_segment`, `enroll_mode`.
+Params: `action_label`, `gap_hours` or `gap_days`, `nudge_clocks` (each hours or days), `save_not_yet_segment`, `save_done_segment`, `enroll_mode`, `finish_when` (`this_person` or `anyone_here`; event finishes only).
 
 Preview each Communication, then `publish_journey`. Leave the Milestone off until they confirm.
 
@@ -89,10 +95,26 @@ Do not `add_journey_step` send on a compose-built path. Point the existing Send
 
 ## Stills
 
-Two pictures: **Not yet** (empty screen) and **Done** (finished). Shop or agent attaches. No Apex default stills.
+Two pictures: **Not yet** (empty screen) and **Done** (finished). Shop or agent attaches. No Apex default stills. Apex cannot sign into their product.
 
-- `attach_adoption_milestone_still` — `image_base64` or a public image URL
-- `recapture_adoption_milestone_stills` — public https pages on a **named workspace host**. Not localhost. A login wall writes nothing.
+**Public page** (anyone can open it):
+
+- Capture on the card, or `recapture_adoption_milestone_stills` on a **named workspace host**. Not localhost. A login wall writes nothing.
+- Or the CLI without a login file.
+
+**Signed-in product** (almost every SaaS moment) — Playwright on THEIR machine:
+
+1. Save a login file they already have from their tests, or:
+   `npx playwright codegen --save-storage .apex/auth.json https://app.theirproduct.com`
+2. Sit both screens:
+   ```
+   npx @apex-inc/mcp-server screenshot --milestone <id> --state not_yet --url https://app.theirproduct.com/reports --storage-state .apex/auth.json
+   npx @apex-inc/mcp-server screenshot --milestone <id> --state done --url https://app.theirproduct.com/reports --storage-state .apex/auth.json
+   ```
+3. Do not send the login file to Apex. Only the picture uploads.
+4. If they already have a PNG, `attach_adoption_milestone_still`.
+
+Do not use hosted recapture for a login wall.
 
 ## Hand-built Adaptive Journey
 
@@ -117,9 +139,17 @@ Only when they are not using compose:
 ### "Just track — no letter"
 1. `compose_adoption_milestone` `scaffold: "none"`.
 
+### "First person at the company finishes it for everyone"
+1. Event finish only. Pass `finish_when: "anyone_here"` on compose, or `update_adoption_milestone` on a live row.
+2. Company facts (snippet, SSO, billing) — not person skills.
+3. A flip on a live row backfills leftover Nudges. Use `get_adoption_account_progress` for the company report.
+
 ### "Save not-yet as a Segment"
 Pass `save_not_yet_segment: true` (and/or `save_done_segment`) on compose. Names: `Not yet: {name}` / `Done: {name}`. Completing drops them from not-yet. The Adaptive Journey watch list stays private if they do not check this.
 
+### "Put pictures on a Milestone"
+Public page → `recapture_adoption_milestone_stills`. Signed-in page → CLI with `--storage-state` (recipe under Stills). Already have a PNG → `attach_adoption_milestone_still`.
+
 ## Guardrails
 
 - Milestones start OFF.

package/skills/apex-communications/SKILL.md

@@ -86,11 +86,10 @@ you did:
 
 `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.
+`confirm_live_experiment: true` to override, and that **marks the numbers
+untrustworthy: Apex will not call a winner and will not learn from mixed
+counts**. Never pass it on your own initiative. Offer the alternatives first:
+wait for the experiment to finish, or end it 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

package/skills/apex-experimentation/SKILL.md

@@ -69,7 +69,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 })`. 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.** 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.
 - **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.
@@ -164,6 +164,7 @@ Match Apex UI terminology in user-facing copy: e.g. **Adaptive traffic allocatio
 - 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. 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.
 
 ## Prove incrementality — "is our growth real?"
 
@@ -190,6 +191,8 @@ 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.
+
 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.
 
 ## Related