@apex-inc/mcp-server 0.34.0 → 0.35.0

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

@@ -32,6 +32,8 @@ Belief → Hypothesis → Prediction → Experiment → Outcome → Updated Beli
 | `evaluate_feature` | Pre-build decision: should we invest in this? Uses beliefs + experiment history |
 | `get_channel_economics` | "Where should my next dollar go?" — GM-adjusted LTV:CAC, payback, and CAC per acquisition channel, split acquisition vs leverage |
 | `get_growth_reality` | "Is our growth real?" — per-goal lift vs the do-nothing global holdout, with 95% CIs |
+| `create_experiment` (`surface: "paid_channel"`) + `attach_ad_exclusion` + `verify_ad_exclusion` | "Do these ads cause installs?" — an Ad holdout on one network's ad sets; the causal read for a paid channel. Apex puts the list on the Meta ad sets itself, after the shop has seen the before/after |
+| `list_belief_suggestions` + `accept_belief_suggestion` | "What did that test teach us?" — a settled experiment worth writing down as one belief. Statistical gate only; the shop edits the sentence, Apex keeps the numbers |
 
 ## MCP resources
 
@@ -42,6 +44,15 @@ Belief → Hypothesis → Prediction → Experiment → Outcome → Updated Beli
 | `apex://intelligence` | Growth Intelligence Score + Learning Velocity |
 | `apex://calibration` | Prediction accuracy metrics — Brier score, bias, reliability buckets |
 
+## Beliefs from outcomes — "worth writing down"
+
+A settled experiment is evidence, not yet a belief. Apex offers to write it down only when the result is clean: decisive; for an Ad holdout, the do-not-show list attached the whole window; no sample-ratio mismatch; no guardrail breached; both arms over the events floor. No model in the path — the sentence is a template filled from the numbers (audience, ad sets or page, metric, lift with its interval, window, people).
+
+- `list_belief_suggestions()` is the rail: every settled experiment not yet written down. `list_belief_suggestions({ experiment_id })` for one; when nothing is offered, `blocker` says why in one word and the tool says it in the shop's words. Repeat that reason; do not argue around it.
+- Show the shop the sentence. They may edit it. Then `accept_belief_suggestion({ experiment_id, statement? })` writes one Belief with the experiment as its evidence and `generatedFromExperimentId` set. Its evidence state is **one study** — one experiment, nothing against it, below the validated bar. A second test that agrees moves it to **validated**; one that disagrees makes it **contested**.
+- Writing it twice returns the existing belief. Do not `create_belief` the same verdict by hand — that loses the evidence link and the self-confirmation guard (a belief written from an experiment does not count that experiment again as fresh support).
+- Never phrase "one study" as settled truth. "One test says…" is the honest sentence until the second test lands.
+
 ## Two scoring systems
 
 Apex has two distinct scores. Don't conflate them.
@@ -123,12 +134,22 @@ How to reason with it:
 - **The verdict is free intelligence — never gate it.** Apex meters only when it
   *runs* something (a test, an optimizer, AI narration), not the measurement.
 - **Action boundary:** owned channels get an in-Apex action; paid channels get
-  advice the merchant applies in their ad platform. Apex never writes to Meta/Google.
+  advice the merchant applies in their ad platform. Apex does not change bids,
+  budgets, or creative on Meta/Google. The one thing it writes to an ad platform
+  is a **do-not-show list** for an Ad holdout — and only after the shop agreed
+  to hashed emails going there and (Meta) Apex proved its token can do it.
 
 For the causal ground truth behind a channel's number, pair it with
 `get_growth_reality` (holdout-based lift). Attribution is directional;
 incrementality is causal.
 
+For a *paid* channel specifically, the causal answer is an **Ad holdout**
+(`create_experiment` with `surface: "paid_channel"`, see apex-experimentation
+→ "Three holdouts, three questions"): Apex holds a share of the shop's known
+people back from the ad sets and counts installs in both lanes. Quote the two
+lane rates, not the network's claimed conversions; nothing counts until
+`verify_ad_exclusion` says the list is on every ad set.
+
 ## When to activate this skill
 
 - User says "what have we learned?" or "what do we know?" → surface beliefs + ledger

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

@@ -146,6 +146,15 @@ Every environment bills. Client-sent `environment` is dashboard slicing, never m
 
 Server events may send `environment` / `release_channel`. Missing stays Unclassified. Required for honesty, not required to ingest.
 
+## SKAN conversion values (iOS)
+
+Apple's SKAdNetwork postbacks carry a fine value 0–63 and a coarse value low / medium / high. Apex holds the shop's meaning for those numbers on the iOS app as a **SKAN schema**, and the Capacitor plugin reads it on the device (`/api/mobile/skan/schema/resolve`, cached a day) and sets the conversion value for you as events fire. The shop never types a 0–63 value in the normal path.
+
+- **Read** it with `get_skan_schema`. `schema: null` means the shop has not named its values; send them to Set up Apex → Mobile → "Say what Apple's numbers mean" (one question: which event means an install was worth it).
+- **Write** it with `set_skan_schema` only when the shop asked for specific values. Nested keys are snake_case: `windows[].values[].{event_name, fine_value, coarse_value, lock_window}`. Fine 0 is install and 1 is `app_open` — reserved. One value per event per window; Apex returns `problems` with a path per fault on a bad schema.
+- The setup step turns green when the schema maps the worth-it event. Do not mark it complete yourself.
+- The SKAN page headline (`/dashboard/mobile/skan`) reads the schema back in shop words: "<n> iPhone installs Apple told us about · <n> were worth it". Postbacks on values you have not named show as one amber sentence, not a to-do list.
+
 ## Data Sources & unified analytics
 
 Apex tags every event with the **producer** it came from — a **Data Source** — derived server-side from `platform` + `surface` + (mobile) `bundleId` + `hostname`. The kinds: **Website** (one source; subdomains are a `hostname` dimension), **iOS** / **Android** (one per app), **Backend** (the Server Events API). `dataSourceId` + `hostname` are **reporting-only** dimensions — filter by them, never gate on them.
@@ -163,4 +172,4 @@ The `apex://data-sources` resource exposes the same breakdown as a read-only sna
 ## Related
 
 - Experiments and variants: **apex-experimentation** skill.
-- Programmatic experiment management: `@apex-inc/sdk` management client (`createManagementClient`) where available.
+- Programmatic experiment management: `@apex-inc/sdk` management client (`createManagementClient`) where available. Grouped by surface: `apex.experiments.*`, `apex.links.*`, `apex.conversions.*`, `apex.adoption.*`, `apex.communications.*`, `apex.mobile.skan.*`.

package/skills/apex-integration-cookbook/SKILL.md

@@ -346,3 +346,26 @@ If get_setup_state shows first-run incomplete, name the merchant before inventin
 5. Finish writable setup with the matching tools (`claim_links_subdomain`, `set_consent_posture`, webhooks, scoring, invitations, engagement, app platforms, attribution, sender domain, push keys, protect auto-pause). Consent answers are not a live-site tap. Sender-domain records issued are not green — poll `get_sender_domain` until verified.
 6. Hop only when the next incomplete step is a hop: `start_integration_install` for GitHub, Stripe, Meta, Google, LinkedIn, or TikTok. Legal acknowledgements stay on the opened page. You cannot click the ad consoles or the DNS registrar for them.
 7. After ads are connected, make a paid Apex Link before inventing UTMs. Do not stamp conversion ack. `create_apex_link` writes the paid medium. `set_ad_measurement_events` chooses which sales to forward and returns a URL if the legal sentence is still open. `set_conversion_source_of_truth` picks who owns the sale. The rail finishes when those things exist — there is no mark-complete tool.
+
+## Recipe: Apex Links for app installs (Mobile Measurement)
+
+An Apex Link is a short URL that routes to the App Store / Play Store when the app is not installed and carries the click through to the first open (deferred deep link). Apex credits the install to the link's campaign and sends it back to the ad network the click came from.
+
+```typescript
+import { createManagementClient } from "@apex-inc/sdk";
+const apex = createManagementClient({ apiKey, workspaceKey, apiUrl });
+
+// One link per campaign. UTMs become the campaign on the Mobile home's table.
+const link = await apex.links.create({
+  slug: "spring-bows",
+  destinationUrl: "https://shop.example.com/spring",
+  utmSource: "meta",
+  utmMedium: "paid_social",
+  utmCampaign: "spring-bows",
+});
+// Put `https://<your-subdomain>.links.apex.inc/${link.slug}` in the ad.
+
+const live = await apex.links.list({ enabled: true });
+```
+
+Experiments live under `apex.experiments.*` (`list`, `get`, `getResults`, `activate`, `promote`, `assignVariant`, `checkConflicts`, `checkLiveTests`). `apex.mobile` is reserved for install attribution and SKAN values.

package/skills/apex-journeys/SKILL.md

@@ -92,6 +92,25 @@ This is the canonical journey-skill workflow. **Always involve apex-communicatio
 6. Walk the user through the apex.trackCart helpers their app needs to call (see apex-growth-tracking for the SDK shape)
 ```
 
+### "Send new installers a first letter" (mobile-install-nudge)
+
+The first install letter is a seeded template, not a journey to author from scratch. It starts on `app_install`, waits 24 hours, leaves the moment the person signs up, and sends one letter over push and email with an Apex Link back into the app.
+
+```
+1. get_setup_state → the Mobile Measurement step "first-letter" says whether the shop can reach installers at all
+   (push keys or a verified sender). If neither: stop and send them to Set up Apex. publish_journey refuses
+   a letter it cannot deliver; do not work around that.
+2. list_journeys → is a mobile-install-nudge journey already there? Turning it on twice sends two letters.
+3. create_journey_from_template({ template_id: "mobile-install-nudge" }) → a draft with the trigger, wait,
+   exit and send already in place. Do not add_journey_step; review with get_journey.
+4. Reach is honest by construction: push goes to the device token, so an installer with no account still gets
+   it; email only goes to people the shop already knows. Say that — "everyone who installs gets the push;
+   only known people also get the email."
+5. publish_journey (after check_live_tests). Sends bill the communications meter.
+```
+
+The setup step in the dashboard does steps 1–5 in one click with a reach preview; prefer sending the shop there when they are not in the editor.
+
 ### "Audit my journeys for missing exits"
 
 ```