@apex-inc/sdk 0.20.2 → 0.25.0

package/skills/apex-adoption/SKILL.md

@@ -1,13 +1,19 @@
 ---
 name: apex-adoption
-description: Build on Apex's Adoption Engine from the SDK (createManagementClient) — define per-feature adoption milestones over your own events/traits, list/update them, and read aggregated metrics (funnel + lift vs holdout). Use when integrating adoption tracking or activation nudges programmatically. A milestone is NOT a goal.
+description: Build on Apex Adoption from the SDK (createManagementClient) — define Milestones, compose one Adaptive Journey (Nudge and/or Celebration), hours or days, unique Communications. A Milestone is NOT a Target.
 ---
 
 # Apex Adoption (SDK)
 
 Name live hosts with `apex.workspace.environments` (or Foundations) before you trust Production adoption numbers. Unmatched hosts stay Unclassified.
 
-The Adoption Engine tracks whether each end-user has adopted each feature, nudges the ones who haven't (one next-best nudge per user, through your journeys), and measures lift against a deterministic holdout.
+Adoption tracks whether each person has finished a Milestone. A Milestone is **This person** unless they set **Anyone here** (`finishWhen: "anyone_here"`). Anyone here = first person on the same Account (`identify({ account: { id } })`) finishes it for the company. Only that person gets the Celebration. Trait finishes stay This person. Company facts (snippet, SSO, billing) → Anyone here. Person skills (ran a report, invited a teammate) → This person. `apex.adoption.update(id, { finishWhen: "anyone_here" })` can flip a live event row; that backfills leftover Nudges.
+
+`compose` stamps **one Adaptive Journey** when they want letters — Trigger → Wait until they finish → Celebration and/or Nudge. Just-track is `scaffold: "none"`. Do not clone two templates.
+
+## Words
+
+Milestone, Nudge, Celebration, Adaptive Journey, Communication, Segment. A Milestone is not a Target.
 
 ## Bootstrap
 
@@ -20,137 +26,83 @@ const apex = createManagementClient({
 });
 ```
 
-## Define a milestone
-
-A milestone is "adopted feature X", defined by an event or a trait. It starts inactive.
+## Define a Milestone
 
 ```ts
 const milestone = await apex.adoption.create({
   name: "Ran first report",
   featureKey: "reporting",
   adoptedWhen: { kind: "event", eventName: "report_run" },
-  gapPolicy: { kind: "days_since_signup", days: 3 },
+  gapPolicy: { kind: "days_since_signup", days: 0, hours: 1 },
+  enrollMode: "future",
+  finishWhen: "this_person",
   priority: 10,
-  // active defaults to false — turn it on when you're ready to nudge.
 });
 
 await apex.adoption.update(milestone.id, { active: true });
 ```
 
-### Compose: milestone + celebration journey in one call
-
-A milestone has two possible journeys, and they're opposites: a **nudge**
-(fires when a user *hasn't* adopted) and a **celebration** (fires once the
-moment they *do* adopt — congratulate them + tell them what's next).
-`compose` creates the milestone and scaffolds its journey legs in a single
-call. Use `scaffold: "both"` to produce the whole milestone unit — exactly what
-the dashboard sentence on-ramp does:
+## Compose: one Adaptive Journey
 
 ```ts
-const { milestone, nudgeJourneyId, celebrationJourneyId } =
-  await apex.adoption.compose({
-    name: "Started first experiment",
-    featureKey: "experiments",
-    adoptedWhen: { kind: "event", eventName: "experiment_started" },
-    gapPolicy: { kind: "days_since_signup", days: 7 },
-    scaffold: "both", // nudge + celebration. Also: "celebration" (default), "nudge", "none".
-  });
-// Both ids are DRAFTS — edit copy in the canvas, then publish each.
-```
-
-For a single leg, pass `scaffold: "celebration"` (default) or `"nudge"` and an
-optional `journeyName`:
-
-```ts
-const { milestone, journeyId } = await apex.adoption.compose({
+const { milestone, journeyId, sends } = await apex.adoption.compose({
   name: "Started first experiment",
   featureKey: "experiments",
   adoptedWhen: { kind: "event", eventName: "experiment_started" },
-  scaffold: "celebration",
-  journeyName: "Congrats on your first experiment",
+  gapPolicy: { kind: "days_since_signup", days: 0, hours: 1 },
+  enrollMode: "future",
+  scaffold: "both", // also: "nudge" | "celebration" | "none"
 });
-// journeyId is a DRAFT — edit the congratulatory message in the canvas, then publish.
+// journeyId is a DRAFT. Preview each send's Communication, then publish.
 ```
 
-### Order milestones (unlocks the account-view Path funnel)
+`sends` is `{ role, stepId, commId }[]`. `nudgeJourneyId` is the same id. `celebrationJourneyId` is null on new rows.
 
-```ts
-await apex.adoption.reorder([
-  activationMilestone.id, // index 0 — reached first
-  depthMilestone.id,      // index 1
-]);
-```
+Each Send has its own Communication. Never reuse `comm-adoption-nudge` / `comm-adoption-celebration`.
+
+Extra Nudges: `nudgeClocks: [{ hours: 1 }, { hours: 3 }]`. First is the Wait deadline; later are more hours or days on that arm. One lift for the protocol.
 
-Ordering the full set turns on the "Path" funnel in the account view
-(step-by-step drop-off). Unordered milestones stay on the order-agnostic
-"Coverage" view — a funnel over an unordered set would imply a false sequence.
+Save as a Segment: `saveNotYetSegment` / `saveDoneSegment`.
 
-Trait-based milestone:
+## Order
 
 ```ts
-await apex.adoption.create({
-  name: "Upgraded to Pro",
-  featureKey: "pro_plan",
-  adoptedWhen: { kind: "trait", traitPath: "plan", traitOp: "equals", traitValue: "pro" },
-});
+await apex.adoption.reorder([
+  activationMilestone.id,
+  depthMilestone.id,
+]);
 ```
 
 ## List + read metrics
 
 ```ts
 const milestones = await apex.adoption.list();
-
 const { metrics, health } = await apex.adoption.metrics();
-// metrics: per-milestone { pending, nudged, adopted, holdout, liftPct, ... }
-// health:  { activeMilestones, totalTracked, totalStuck, totalAdopted, avgLiftPct, stuckByMilestone }
+const person = await apex.adoption.progress(endUserId);
+const company = await apex.adoption.accountProgress(accountId);
 ```
 
-`liftPct` is nudged-adoption-rate minus holdout-adoption-rate (percentage points) — the causal lift, not attribution. Treat it as directional until the holdout is large enough. **Trait (state) milestones don't report lift** (`liftMeasurable: false`) — a durable trait has no "became true after exposure" moment, so we show raw adoption until a baseline exists.
-
-## Feature groupings
-
-Milestones group under tenant-owned "features" (how the builder organizes your own events). Manage them from the IDE too:
-
-```ts
-await apex.adoption.features.create({ label: "Subscriptions", eventNames: ["subscription_started"] });
-const features = await apex.adoption.features.list();
-```
+Lift is one number for the protocol. Trait Milestones do not report lift (`liftMeasurable: false`).
 
-## Segments — one grammar for "people who…"
+## Stills
 
-A segment is a saved group of customers over your own events + traits. Author it with the SAME friendly grammar the dashboard chip builder uses (`conditions`), or drop to a raw `predicate`.
+If they already have the picture, `attach_adoption_milestone_still` (MCP) or `POST /api/adoption/milestones/:id/assets`.
 
-```ts
-// Friendly conditions (compiled + validated server-side):
-await apex.segments.create({
-  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" },
-      ] },
-    ],
-  },
-});
+Signed-in product pages: Playwright on their machine, then upload. Apex cannot sign in for them.
 
-const segments = await apex.segments.list();
+```
+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
 ```
 
-## Define an event before it fires (define ≠ fire)
-
-Built a feature but haven't wired Apex yet? Register the event's name so milestones/segments can reference it. **Defining doesn't make it happen** — a developer still calls `apex.track("...")` from the app.
+Save the login file with `npx playwright codegen --save-storage .apex/auth.json <url>` (or reuse their test login). Apex never receives that file.
 
-```ts
-await apex.events.define({ name: "report_exported", description: "User exported a report to CSV" });
-// then, in your app code: apex.track("report_exported");  // define → wire → verify
-```
+Public pages: Capture on the card / hosted recapture. A login wall writes nothing.
 
 ## Notes
 
-- Milestones are per-user, per-feature — not goals (which are workspace/experiment/journey success).
-- `adoptedWhen.eventName` / `traitPath` must match data you already send Apex (track/identify).
-- Nudges are marketing-class: they respect unsubscribe, opt-out, and frequency caps, and never target users in an active experiment.
-- A scaffolded celebration journey is a **draft**: publish it (and turn the milestone on) for the congratulation to actually send.
-- `order` is a display/sequence hint only — it never changes nudge ranking (that's `priority`).
+- A Milestone is per person, per feature — not a Target.
+- New rows default to `enrollMode: "future"`. Do not publish a short clock on `"all"`.
+- `gapPolicy.hours` wins over `days`. `0` is right away. 1 hour is not right away.
+- Nudge honors holdout, opt-out, and the Nudge cap. Celebration is holdout-exempt.
+- The Adaptive Journey is a draft until they publish it.

package/skills/apex-communications/SKILL.md

@@ -154,7 +154,7 @@ did: publish opened a filled-in draft; `activateExperiment` starts the test.
 
 `in_experiment` is a hard stop, not an intent question — the content is a
 treatment mid-measurement. `{ confirmLiveExperiment: true }` overrides it and
-**marks that experiment invalid, excluding its result from the belief graph**.
+**marks the numbers untrustworthy: Apex will not call a winner and will not learn from mixed counts**.
 Offer the alternatives first: wait for it to finish, or conclude it so the
 learning is captured.
 

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.
@@ -154,6 +154,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` (or `checkLiveTests` on the management client) with the **full file contents**, not the diff hunk. Before you change a letter, Adaptive Journey, or Milestone, pass those ids too. 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.
 
 ## Related