@apex-inc/mcp-server 0.27.5 → 0.28.1

package/package.json

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

package/skills/apex-adoption/SKILL.md

@@ -1,108 +1,149 @@
 ---
 name: apex-adoption
-description: Help users set up and run Apex's Adoption Engine — per-feature adoption milestones defined over their own events/traits, automatic nudges to users who haven't adopted, and lift-vs-holdout measurement. Use whenever the user mentions product adoption, activation nudges, "users who haven't tried X", feature adoption, onboarding nudges, or wants to drive users to a feature. A milestone is NOT a goal.
+description: Help users set up Apex Adoption — one Milestone per feature, one Adaptive Journey when they want letters (Nudge and/or Celebration), hours or days, unique Communications, and two stills. Use when they mention product adoption, activation letters, "people who haven't tried X", or feature adoption. A Milestone is NOT a Target.
 ---
 
 # Apex Adoption (MCP)
 
-The Adoption Engine tracks whether each end-user has adopted each feature, nudges the ones who haven't (one next-best nudge per user), and measures the lift against a holdout.
+Adoption tracks whether each person has finished a Milestone. If they want letters, Apex stamps **one Adaptive Journey**:
+
+```
+Trigger: signed up (or the anchor)
+  Wait until they finish
+    on event    → Celebration Send → Exit   (or Exit if no letter)
+    on deadline → Nudge Send → Exit         (or Exit if just-track)
+```
+
+Just-track is a Milestone only. No Adaptive Journey. `scaffold: "none"`.
+
+Do **not** clone two templates. Do **not** create a second live Adaptive Journey for the same Milestone.
+
+## Words
+
+- **Milestone** — they finished one thing. Not a Target (that is an aggregate number by a date).
+- **Nudge** — the letter when they have not finished yet.
+- **Celebration** — the letter when they finish.
+- **Adaptive Journey** — the graph those letters ride.
+- **Communication** — the letter on a Send.
+- **Segment** — a saved Customers rule, only if they check save.
+- **Not yet / Done** — picture labels, not objects.
+
+Do not say reminder, congratulations, clock, or watch list as names they see.
 
 ## Core idea
 
-- A **milestone** = "has this end-user adopted feature X?" — defined by an event they fire (`report_run`) or a trait (`plan = pro`). It is per-user and per-feature. It is **not** a goal (goals are workspace/experiment/journey success).
-- Apex ranks a user's unmet milestones by priority and sends the single top nudge per cadence — so nobody gets spammed.
-- A deterministic holdout is kept automatically (~5–10%); the report shows lift vs that holdout. Users in an active experiment are never nudged.
-- New milestones default to **future-only** (`enroll_mode: "future"`): only people who sign up after the milestone is created can enter the nudge. Pass `enroll_mode: "all"` to include the historical roster. Existing milestones without `enrollMode` stay "all" so live lists do not shrink.
-- `gap_hours` wins over `gap_days`. `0` hours or days means right away. Do not assume a 1-day floor.
-- A milestone has **two possible journeys**, and they are opposites:
-  - **Nudge** (audience-entry): fires when a user *hasn't* adopted within the gap window. Drives them toward the feature.
-  - **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).
+- A Milestone is per person, per feature. Event (`report_run`) or trait (`plan = pro`).
+- 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`.
+- Extra Nudges are more hours or days on the deadline arm (duration Wait + Send). One lift for the protocol.
+- Completing the Milestone stops leftover Nudges (exit rule on the done event).
+- Celebration Send is holdout-exempt. Nudge honors holdout, opt-out, and the Nudge cap.
+- Already finished when the Wait starts → event arm. Do not sit to the deadline and Nudge.
 
-Name live hosts (`list_workspace_environments` / `set_workspace_environments` or Foundations) before you trust Production adoption numbers. Unmatched hosts stay Unclassified.
+Name live hosts (`list_workspace_environments` / `set_workspace_environments` or Foundations) before you trust Production numbers. Unmatched hosts stay Unclassified.
 
 ## When to Activate
 
-- "Nudge users who signed up but never ran their first report."
-- "Which features are people not adopting?"
-- "Set up an activation program / onboarding nudges."
+- "Nudge people who signed up but never ran their first report."
+- "Which features are people not finishing?"
+- "Set up activation letters."
 
 ## Tool Map
 
 | Tool | When to use |
 |---|---|
-| `list_adoption_milestones` | See the workspace's current milestones |
-| `get_adoption_milestone` | Inspect one milestone |
-| `create_adoption_milestone` | Define a new "adopted feature" milestone |
-| `compose_adoption_milestone` | Create a milestone AND scaffold its journey legs (`scaffold: "both" \| "celebration" \| "nudge" \| "none"`) in one call |
-| `update_adoption_milestone` | Change priority / order / gap window / turn on/off |
-| `reorder_adoption_milestones` | Set the sequence order of the whole set (unlocks the Path funnel) |
-| `delete_adoption_milestone` | Remove a milestone |
-| `get_adoption_metrics` | Per-milestone funnel + lift-vs-holdout + workspace health |
-| `list_adoption_features` / `create_adoption_feature` | Tenant-owned feature groupings (group your own events) |
-| `list_segments` / `get_segment` / `create_segment` | Saved groups of customers — same grammar as milestones |
-| `define_event` | Register an event's NAME before it fires (define ≠ fire) |
-
-Read-only summary resource: `apex://adoption`.
-
-## One grammar: define → wire → verify
-
-Milestones and segments both describe "people who…" over the workspace's own
-events + traits. The methodology is the same everywhere (dashboard, SDK, MCP):
-
-1. **Define** — name the signal. If the event doesn't exist yet, `define_event`
-   registers it. Defining does NOT make it fire.
-2. **Wire** — a developer calls `apex.track("your_event")` from the app (or
-   sends the trait via `apex.identify`). Until then it shows a "not seen yet"
-   dot.
-3. **Verify** — once real events arrive, milestone lift / segment counts fill in.
-
-### Segments — `create_segment`
-
-Author with the friendly `conditions` grammar (snake_case sub-keys), or pass a
-raw `predicate`:
-
-```json
-{
-  "name": "Power users who haven't upgraded",
-  "conditions": {
-    "match": "all",
-    "groups": [
-      { "match": "all", "conditions": [
-        { "verb": "has", "event": "report_run", "window_days": 30 },
-        { "attribute": "plan", "op": "is_not", "value": "pro" }
-      ] }
-    ]
-  }
-}
-```
+| `list_adoption_milestones` | See the current Milestones |
+| `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 |
+| `reorder_adoption_milestones` | Sequence for the Path funnel |
+| `delete_adoption_milestone` | Remove a Milestone |
+| `get_adoption_metrics` | Funnel + one lift number |
+| `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 |
+| `edit_communication` / `set_journey_send` | Write the letter on an existing Send |
+| `publish_journey` | Go live after preview |
+| `add_journey_step` | Hand-built Adaptive Journey only. Prefer compose. |
+
+Read-only summary: `apex://adoption`.
+
+## Compose
+
+`compose_adoption_milestone` with `scaffold`:
+
+- `both` (default) — Nudge + Celebration
+- `nudge` — deadline letter only
+- `celebration` — finish letter only
+- `none` — just-track
+
+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`.
+
+Preview each Communication, then `publish_journey`. Leave the Milestone off until they confirm.
+
+Do not `add_journey_step` send on a compose-built path. Point the existing Send with `set_journey_send`.
+
+## Stills
+
+Two pictures: **Not yet** (empty screen) and **Done** (finished). Shop or agent attaches. No Apex default stills. Apex cannot sign into their product.
+
+**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
+
+Only when they are not using compose:
+
+1. `create_journey` → `set_journey_trigger`
+2. `add_journey_step` `kind=wait` `mode=until_event` `trigger_contract_id` `deadline_iso`
+3. `add_journey_step` `kind=send` `arm=event` or `arm=deadline`
+4. `set_journey_send` if the Send already exists
 
 ## Tool Invocation Order
 
-### "Nudge users who haven't run their first report"
-1. `list_adoption_milestones` → check it doesn't already exist.
-2. `create_adoption_milestone` with `name: "Ran first report"`, `feature_key: "reporting"`, `adopted_when_kind: "event"`, `event_name: "report_run"`, `gap_days: 3` (or `gap_hours` for a same-day clock). Defaults to future-only. Leave `active` off first. Read the `warnings` in the response — a duplicate event or an event never seen on an identified person is a hard honesty problem.
-3. Tell the user it's created as a draft, and that turning it on (`update_adoption_milestone` with `active: true`) starts nudging through their journeys (opt-out + caps respected).
-4. Later: `get_adoption_metrics` → report the lift-vs-holdout so they know whether it worked.
+### "Nudge people who haven't run their first report"
+1. `list_adoption_milestones`
+2. `compose_adoption_milestone` with `scaffold: "nudge"`, `enroll_mode: "future"`, hours or days. Leave `active` off.
+3. Preview the Communication. `publish_journey`. Then turn the Milestone on.
+
+### "Celebrate when they start their first experiment"
+1. `compose_adoption_milestone` `scaffold: "celebration"` (or `both` if they also want a Nudge).
+2. Preview. Publish. Do not scaffold a Celebration on an event that already has a published operator letter — pass `scaffold: "nudge"`.
 
-### "Congratulate users when they start their first experiment"
-1. `compose_adoption_milestone` with `name: "Started first experiment"`, `featureKey: "experiments"`, `adoptedWhenKind: "event"`, `eventName: "experiment_started"`, `scaffold: "celebration"`. This creates the milestone AND a draft celebration journey wired to fire once, the moment the user reaches it.
-2. Tell the user the celebration journey is a **draft**. Preview with `preview_communication`, then `publish_journey` (dry-run first).
-3. Turning the milestone on is separate from publishing the journey; both must be live for the celebration to send.
+### "Just track — no letter"
+1. `compose_adoption_milestone` `scaffold: "none"`.
 
-### "Set up a full milestone — nudge the ones who don't, celebrate the ones who do"
-1. `compose_adoption_milestone` with `scaffold: "both"` (default). Example: `name: "Started first experiment"`, `feature_key: "experiments"`, `adopted_when_kind: "event"`, `event_name: "experiment_started"`, `gap_hours: 1` (or `gap_days: 7` in production). One call creates the milestone plus BOTH draft journeys.
-2. The response carries `nudge_journey_id`, `celebration_journey_id`, and `warnings`. Preview the letter with `preview_communication`, then `publish_journey` (dry-run first). Do not activate until the letter is previewed and the journey is published.
-3. Do not scaffold a celebration on an event that already has a published operator letter (experiment started, domain verified, etc.) — pass `scaffold: "nudge"`.
-4. Turn the milestone on (`update_adoption_milestone` `active: true`) once its nudge is published, so it can measure lift vs the holdout.
+### "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 my milestones in the order accounts should hit them"
-1. `list_adoption_milestones` → get the ids.
-2. `reorder_adoption_milestones` with `orderedIds` in the intended sequence (activation before depth).
-3. Tell the user the account view's "Path" funnel is now unlocked — it shows drop-off between consecutive milestones. Without a full order it stays on the order-agnostic "Coverage" view.
+### "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. Only set `active: true` when the user confirms they want to start sending.
-- Never call it a "goal" in user-facing text.
-- The `eventName`/`traitPath` must be an event/trait the workspace actually sends — confirm with the user if unsure.
+- Milestones start OFF.
+- Never call a Milestone a Target or a goal.
+- Unique Communications. Never reuse the shared catalog letter ids.
+- Do not publish a short clock on everyone already here.
+- Do not publish Website is talking / Send from your own domain / Started your first experiment / Connected your first integration unless they ask — those are Apex's own product drafts.
+- Capture fail never writes a still.

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.