@apex-inc/mcp-server 0.19.0 → 0.21.0

package/package.json

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

package/skills/apex-adoption/SKILL.md

@@ -12,6 +12,10 @@ The Adoption Engine tracks whether each end-user has adopted each feature, nudge
 - 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 ~10% deterministic holdout is kept automatically; the report shows lift vs that holdout, not last-touch attribution. Users in an active experiment are never nudged.
+- 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).
 
 ## When to Activate
 
@@ -26,7 +30,9 @@ The Adoption Engine tracks whether each end-user has adopted each feature, nudge
 | `list_adoption_milestones` | See the workspace's current milestones |
 | `get_adoption_milestone` | Inspect one milestone |
 | `create_adoption_milestone` | Define a new "adopted feature" milestone |
-| `update_adoption_milestone` | Change priority / gap window / turn on/off |
+| `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) |
@@ -75,6 +81,21 @@ raw `predicate`:
 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.
 
+### "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** — they edit the congratulatory message in the canvas (Communications composer), then publish it.
+3. Turning the milestone on is separate from publishing the journey; both must be live for the celebration to send.
+
+### "Set up a full milestone — nudge the ones who don't, celebrate the ones who do"
+1. `compose_adoption_milestone` with `scaffold: "both"` (e.g. `name: "Started first experiment"`, `featureKey: "experiments"`, `adoptedWhenKind: "event"`, `eventName: "experiment_started"`, `gapDays: 7`). One call creates the milestone plus BOTH draft journeys: the nudge (for users who haven't started an experiment within 7 days) and the celebration (for the moment they do). This is exactly what the dashboard sentence on-ramp produces.
+2. The response carries `nudgeJourneyId` and `celebrationJourneyId` — both are **drafts**. Edit copy in the canvas and publish each.
+3. Turn the milestone on (`update_adoption_milestone` `active: true`) once its nudge is published, so it can measure lift vs the holdout.
+
+### "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.
+
 ## Guardrails
 
 - Milestones start OFF. Only set `active: true` when the user confirms they want to start sending.

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

@@ -39,6 +39,33 @@ When a user was anonymous and then becomes known (signup, login, checkout email)
 - Call **`identify`** with a stable `userId` and pass **`traits.email`** when applicable.
 - **Server-side** `identify` (webhooks, API routes): pass **`traits.visitorId`** = value of the browser **`apex_vid`** cookie so the stitch links to the real marketing session. Without it, Apex may create a synthetic visitor disconnected from prior events.
 
+## B2B accounts + groups (model the company, not just the seat)
+
+For B2B, revenue belongs to the **account** (company), not the individual. Add a nested `account` object to the SAME `identify` you already call at login/signup:
+
+```ts
+identify(user.id, {
+  email: user.email,
+  account: { id: "acct_acme", name: "Acme Inc", plan: "enterprise", seat_count: 25 },
+});
+```
+
+Apex upserts the Account, links the user as a member, and rolls every member's revenue into one account LTV (no double counting). `account.id` is required — Apex never infers the company from a shared email domain.
+
+If your product has an intermediate org-unit layer (workspaces / teams / projects), assert it with `groups[]` on the same identify — the "model a team/workspace layer" recipe:
+
+```ts
+identify(user.id, {
+  account: { id: "acct_acme", name: "Acme Inc" },
+  groups: [
+    { id: "ws_prod", name: "Production", kind: "workspace", role: "admin" },
+    { id: "team_growth", name: "Growth Team", kind: "team", parent_id: "acct_acme" },
+  ],
+});
+```
+
+Each group becomes a sub-account of `parent_id` (defaults to `account.id`) and the user is linked to it. Read it back with `apex.accounts.list()` / `.subaccounts(id)` / `.people(id)` / `.contactGroups(contactId)` (SDK) or `list_accounts` / `list_sub_accounts` / `get_contact_groups` (MCP). Revenue lands on the billed account; a parent's LTV is its own counters, not the sum of children.
+
 ## What to measure by loop phase
 
 - **Acquisition**: landing views, campaign params (UTM already captured by snippet where configured), signup started.

package/skills/apex-spec/SKILL.md

@@ -105,6 +105,16 @@ Scan-first additions per vertical — wire where the truth lives:
   (monthly|annual|quarterly|weekly) — quarantined for MRR otherwise.
   `seat_count` unlocks seat growth. Account traits: `account_id`,
   `plan`, `mrr`, `arr`, `seat_count` (typed via ApexAccountTraits).
+  For account-level rollup (B2B): send a nested `account` object on
+  `identify` — `identify(user.id, { account: { id, name, plan,
+  seat_count } })` — so revenue rolls up to the company, not the seat.
+  For an intermediate org-unit layer (workspaces / teams / projects),
+  add `groups[]` on the SAME identify: `groups: [{ id, name, kind,
+  parent_id?, role? }]`. Each group becomes a sub-account of `parent_id`
+  (defaults to `account.id`) and the user is linked to it. snake_case
+  sub-keys; a group only attaches under an account the user is already
+  anchored to. Read back via MCP `list_accounts` / `list_sub_accounts`
+  / `get_contact_groups`.
 - **E-commerce**: returns pipeline → `return_requested` / `return_completed`
   (goods back) alongside `purchase_refunded` (money back — now carries
   optional `product_id` for per-SKU attribution). Never conflate the two.