@apex-inc/mcp-server 0.15.0 → 0.16.0

package/package.json

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

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

@@ -30,6 +30,8 @@ Belief → Hypothesis → Prediction → Experiment → Outcome → Updated Beli
 | `record_outcome` | After experiment completes — updates belief confidence, marks prediction evaluated |
 | `predict_impact` | Before building something — searches past experiments and beliefs for similar changes |
 | `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 |
 
 ## MCP resources
 
@@ -93,10 +95,39 @@ Use calibration to coach the user: "Your predictions at 80%+ confidence are only
 | `correlation_hint` | Detected relationship between metrics |
 | `metric_shift` | Significant change in a tracked metric |
 
+## Channel economics (where the next dollar goes)
+
+`get_channel_economics` is Layer 1 of Apex's cross-channel measurement stack
+(the established triangulation / Unified Marketing Measurement approach): cohort
+**LTV:CAC by acquisition channel** is the unit-economics foundation, with
+multi-touch attribution as a directional contrast lens layered on top.
+
+How to reason with it:
+
+- **Currency is gross-margin-adjusted LTV:CAC, not blended ROAS.** A 3:1 blended
+  ratio routinely hides organic at 6:1 subsidizing paid social below 1:1. Always
+  read it per channel.
+- **Acquisition vs leverage.** Paid channels (have spend) are where you "go get
+  users"; leverage channels (owned/organic, no spend) are where you "monetize the
+  base." Different plays — never average them together.
+- **Benchmarks for the verdict:** LTV:CAC 3-5x healthy, <3x investigate, >5x
+  likely underinvested; payback ≤12-18mo SaaS, 3-9mo ecommerce.
+- **Missing inputs read as "—", never a guess.** A channel with no connected
+  spend or revenue shows null, not a fabricated number.
+- **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.
+
+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.
+
 ## When to activate this skill
 
 - User says "what have we learned?" or "what do we know?" → surface beliefs + ledger
 - User asks "should we build X?" → use `evaluate_feature` or `predict_impact`
+- User asks "where should I spend?" / "which channel is best?" → `get_channel_economics`
 - User wants to review experiment results → connect outcome to belief update
 - User asks about prediction accuracy → surface calibration metrics
 - User is planning strategy → show Growth Intelligence Score and learning velocity
@@ -114,3 +145,25 @@ Use calibration to coach the user: "Your predictions at 80%+ confidence are only
 - Experiment design and instrumentation: see **apex-experimentation** skill
 - Event tracking and identity: see **apex-growth-tracking** skill
 - Communication experiments: see **apex-communications** skill
+
+## Vertical metrics → growth actions (Vertical Widget Packs)
+
+Apex ships vertical-specific read tools. Use them AMBIENTLY: when a
+metric implies a growth move, propose the belief/experiment — don't
+just report the number.
+
+| Signal (tool) | Growth action to propose |
+|---|---|
+| High zero-result-search rate (`get_marketplace_metrics`) | Supply-acquisition experiment for the missing categories — the queries name the gap |
+| Low search→transaction with healthy supply | Search-relevance or trust experiment (badges, reviews) |
+| Rising unfulfilled demand | Seller-activation journey (listing nudges) before paid demand spend |
+| Concentration: top 10% sellers > ~60% GMV | Long-tail seller enablement; the platform is one churn away from a revenue cliff |
+| NRR < 100% (`get_saas_recurring_revenue`) | Expansion journey + contraction interviews; churned-MRR column names the cohort |
+| Contraction MRR spike (`get_saas_expansion`) | Downgrade-reason capture (`subscription_event` action="downgrade" with reason) → pricing/packaging belief |
+| Rising return rate on one SKU (`get_dtc_returns` + `get_dtc_merchandising`) | Fix the PDP (size guide, photos) — reasons name the fix; returns are goods-back, refunds are money-back |
+| High views, low add-to-cart on a top SKU | Merchandising experiment (price anchor, social proof) on that product page |
+
+Honesty rules baked into every tool: metrics with unwired inputs come
+back as unwired hints (never zeros), rates follow small-n rules, low-
+volume slices are privacy-suppressed, and marketplace GMV never counts
+as the operator's revenue (the take — `fee_amount` — does).

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

@@ -249,3 +249,80 @@ Each producer that sends events into a workspace is a **Data Source** (Website,
 - Experiment design: see **apex-experimentation** skill
 - Communication setup: see **apex-communications** skill
 - Affiliate / partner programs: see **apex-partner-network** skill
+
+## Recipe: Vertical instrumentation (Vertical Widget Packs, 2026-07)
+
+Each launch vertical has a canonical event set that unlocks its
+industry-specific dashboard pack. Wire the vertical's set and the
+matching widgets + read APIs light up automatically.
+
+### B2B SaaS — recurring revenue
+
+```typescript
+// Subscription lifecycle (server transport — money truth). MRR-bearing
+// actions REQUIRE amount + period_type or the event is quarantined for
+// MRR purposes (an annual $299 sub must never read as $299 MRR).
+track("subscription_event", {
+  product_id: "pro_annual",
+  action: "start",           // start|renew|upgrade|downgrade|cancel|reactivate|trial_convert
+  amount: 299, period_type: "annual",   // → $24.92 MRR
+  seat_count: 25,
+});
+// Account economics via identify (typed: ApexAccountTraits)
+identify(user.id, { account_id: "acct_42", plan: "pro", mrr: 24.92, seat_count: 25 });
+```
+
+Unlocks: MRR waterfall, NRR/GRR, expansion & seats
+(`GET /api/saas/recurring-revenue`, `/api/saas/expansion` —
+`getSaasRecurringRevenue()` / `getSaasExpansion()` in the SDK,
+`get_saas_recurring_revenue` / `get_saas_expansion` via MCP).
+Connecting Stripe replaces manual events per account (Stripe wins).
+
+### E-commerce / DTC — merchandising + returns
+
+```typescript
+track("product_view", { product_id: "sku_a", product_name: "Trail Runner", category: "footwear", value: 129.99 });
+track("add_to_cart", { product_id: "sku_a", value: 129.99, quantity: 1 });
+// Money truth from the server:
+track("order_placed", { order_id: "o_1", value: 129.99, currency: "USD" });
+// Returns are GOODS BACK; refunds are MONEY BACK — separate events, separate rates:
+track("return_requested", { order_id: "o_1", product_id: "sku_a", reason: "wrong_size" });
+track("return_completed", { order_id: "o_1", product_id: "sku_a", reason: "wrong_size", refunded: true });
+track("purchase_refunded", { order_id: "o_1", value: 129.99, currency: "USD", reason: "wrong_size", product_id: "sku_a" });
+```
+
+Unlocks: per-product funnel, returns & reasons, AOV/repeat
+(`GET /api/dtc/merchandising`, `/api/dtc/returns`).
+
+### Marketplace — two-sided lifecycle
+
+```typescript
+// Supply side (server recommended):
+track("seller_signup", { seller_id: "sel_1", store_name: "Atlas Outfitters" });
+track("listing_created", { listing_id: "lst_9", price: 120, currency: "USD" });
+// Demand side:
+track("search", { query: "trail runner", results_count: 24 });  // results_count powers zero-result-search rate
+track("offer_submitted", { listing_id: "lst_9", amount: 110 });
+// The transaction (SERVER — carries BOTH parties + the take):
+track("transaction_completed", {
+  transaction_id: "txn_1",
+  amount: 120,          // GMV — NEVER credited as your revenue
+  fee_amount: 14.4,     // the take — THIS is your revenue (required for revenue credit)
+  buyer_id: "u_9", seller_id: "sel_1", listing_id: "lst_9",
+  category: "footwear", geo: "US", price_band: "100-250",
+});
+// Tag sides via identify so segments work: marketplace_side / is_seller / store_name / payout_method (enum: stripe|paypal|bank_transfer|other)
+identify(user.id, { marketplace_side: "seller", is_seller: true, store_name: "Atlas Outfitters", payout_method: "stripe" });
+```
+
+Unlocks: liquidity, supply & demand, economics (GMV vs take), trust,
+concentration (`GET /api/marketplace/metrics`, sliceable by
+category/geo/price_band).
+
+### Agency — client portfolio
+
+No new events: each client is a LINKED WORKSPACE. Connect the client's
+ad accounts + Stripe in their workspace; per-client spend/revenue/ROI
+and the transparent at-risk rule roll up on the agency org
+(`GET /api/agency/clients` — org owner/admin sessions only; it is a
+financial boundary with no API-key lane).

package/skills/apex-spec/SKILL.md

@@ -16,10 +16,11 @@ find where each business truth already lives and instrument it there.
 1. **Scan before asking.** Never ask the merchant to enumerate their
    events. Audit the codebase for Spec opportunities:
    - auth / signup flows → `apex.identify(email, first_name, last_name)` + `user_signed_up`
-   - login flows → `identify` (cross-device stitching)
-   - checkout / payment success paths → `purchase` / `checkout_started` / `order_placed` (server)
-   - in-app purchase / StoreKit / Play Billing → `in_app_purchase`
-   - subscription create / renew / cancel webhooks → `subscription_event`
+   - login flows → `identify` (cross-device stitching). If the auth provider exposes a profile photo (OIDC `picture` claim, Firebase `photoURL`), map it to the canonical `avatar_url` trait so the Customer gets a photo across Apex — Customers list, detail, Live Customers widget.
+   - checkout flow begun → `checkout_started` (client)
+   - checkout / payment success paths → `order_placed` (server, money-truth) and/or `checkout_completed` (client mirror)
+   - in-app purchase / StoreKit / Play Billing → `in_app_purchase` (store-verified)
+   - subscription create / renew / cancel webhooks → `subscription_started` / `subscription_renewed` / `subscription_canceled` (discrete) or `subscription_event` (action-driven)
    - lead/contact forms → `form_submit`
    - cart mutations → `add_to_cart`, `remove_from_cart`
    - search, share, content views → `search`, `share`, `content_view`
@@ -54,6 +55,17 @@ find where each business truth already lives and instrument it there.
    smallest change that works; never commit; never enable test mode in
    production paths.
 
+   **Transport is in the spec, not a guess.** Each event declares a
+   `recommendedTransport` (`server` | `client` | `either`) and revenue
+   events a `revenueRole` (`primary` | `client_mirror` | `iap`) — read
+   them from `get_event_spec`. The rule: fire money-truth events
+   (`order_placed` = primary, `in_app_purchase` = iap, all `payment_*` /
+   `invoice_*` / `subscription_*`) from the **server/store**; fire intent
+   and engagement events (`checkout_started`, `add_to_cart`, `page_view`,
+   `checkout_completed` = client_mirror) from the **client**. Never make
+   `checkout_completed` the dollar source of record when `order_placed`
+   exists — it's the client mirror and can duplicate.
+
 4. **Verify your own work.** Call `get_wiring_status` after wiring and
    iterate until every event you proposed reports `detected`. The
    merchant's page celebrates each first arrival — your verification
@@ -72,6 +84,42 @@ find where each business truth already lives and instrument it there.
 - Custom events are allowed (`apex.track` accepts any snake_case
   name) but prefer canonical Spec names — they unlock journeys,
   funnels, and metric chips automatically.
+- When a merchant's event has no canonical equivalent and matters to
+  their business, GOVERN it instead of leaving it loose: propose a
+  schema from the observed payloads (`get_schema`) + the codebase,
+  confirm with the merchant, then call `define_event` (snake_case name,
+  typed fields, scope). A governed event behaves like a canonical one —
+  trigger/goal-selectable, token-resolvable, validated, versioned
+  (SchemaVer). It can never shadow a canonical Spec name.
 - Revenue events MUST carry `value` + `currency`, and a stable
   external id when one exists (order id, invoice id) — dedupe depends
   on it.
+
+## Vertical event sets (Vertical Widget Packs, 2026-07)
+
+Scan-first additions per vertical — wire where the truth lives:
+
+- **SaaS**: subscription webhooks → `subscription_event` with a CLOSED
+  action enum (start/renew/upgrade/downgrade/cancel/reactivate/
+  trial_convert). MRR-bearing actions REQUIRE `amount` + `period_type`
+  (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).
+- **DTC**: 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.
+- **Marketplace**: supply (`seller_signup`, `listing_created`,
+  `payout_sent`), demand (`search` WITH `results_count`,
+  `listing_viewed`, `seller_viewed`, `item_saved`, `inquiry_started`,
+  `offer_submitted`, `match_created`), outcome
+  (`transaction_completed` — SERVER, with `amount` (GMV), `fee_amount`
+  (the take — the ONLY field credited as revenue), `buyer_id`,
+  `seller_id`, `listing_id`, and `category`/`geo`/`price_band` slices),
+  trust (`transaction_canceled`, `dispute_opened`, `review_submitted`
+  with `rating`). Legacy vocabularies (`supply_signup`,
+  `demand_signup`, `first_transaction`, `marketplace_*`) resolve via
+  built-in aliases — never wire them as new names.
+  Identify traits: `marketplace_side`, `is_buyer`, `is_seller`,
+  `store_name`, `seller_id`, `payout_method` (ENUM
+  stripe|paypal|bank_transfer|other — never instrument details).
+  Roles are event-derived and append-only; dual-hat users carry both.