@apex-inc/mcp-server 0.3.0 → 0.6.1

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

@@ -0,0 +1,240 @@
+---
+name: apex-integration-cookbook
+description: Recipes for integrating Apex into products — SDK wiring, form tracking, auth/signup events, Stripe lifecycle, communication triggers, and event naming conventions. Use when the user is adding Apex tracking to their product or wiring events to communications and experiments.
+---
+
+# Apex integration cookbook (SDK)
+
+Step-by-step recipes for integrating Apex via the `@apex-inc/sdk` package. For snippet-only sites or MCP-driven setup, see the full cookbook in `@apex-inc/mcp-server`.
+
+## SDK setup
+
+```typescript
+import { init, track, identify, trackForm, shutdown } from "@apex-inc/sdk";
+
+init({
+  projectKey: "YOUR_PROJECT_KEY",
+  apiUrl: "https://your-apex-url",  // optional, defaults to relative /api
+  flushInterval: 10000,              // ms between batch sends (default: 10s)
+  flushAt: 20,                       // batch size trigger (default: 20)
+  debug: false                       // log events to console
+});
+```
+
+Events are batched and sent to `POST /api/events` automatically. Call `flush()` before page unload if needed, or `shutdown()` to stop tracking.
+
+## Recipe 1: Signup and authentication
+
+```typescript
+// On signup
+track("signup_completed", { method: "email", plan: "free" });
+identify(user.id, {
+  email: user.email,
+  name: user.name,
+  visitorId: getCookie("apex_vid")  // stitch to pre-signup browsing
+});
+
+// On login
+track("login", { method: "google" });
+identify(user.id, { email: user.email });
+```
+
+The `visitorId` trait links the anonymous marketing session to the authenticated user. Without it, pre-signup attribution is lost.
+
+## Recipe 2: Onboarding funnel
+
+```typescript
+track("onboarding_step_completed", { step: "connect_data_source", stepNumber: 2, totalSteps: 5 });
+track("onboarding_completed", { timeToComplete: elapsedMs });
+```
+
+Events like `onboarding_completed` automatically match to active tenant communications when the trigger system is wired.
+
+## Recipe 3: Stripe subscription lifecycle
+
+```typescript
+// In your Stripe webhook handler
+track("subscription_created", { plan: "pro", amount: 9900, currency: "usd" });
+identify(userId, { plan: "pro", lifecycleStage: "paying" });
+
+// On cancellation
+track("subscription_cancelled", { reason: "too_expensive" });
+identify(userId, { lifecycleStage: "churned" });
+```
+
+## Recipe 4: Feature usage
+
+```typescript
+track("feature_used", { feature: "export_report", format: "csv" });
+track("milestone_reached", { milestone: "first_experiment_completed" });
+```
+
+Use one event name with a `feature` property — not dozens of unique event names.
+
+## Recipe 5: Form tracking (shortcut)
+
+```typescript
+trackForm({
+  email: formData.email,
+  formId: "contact-form",
+  action: "demo_request",
+  fields: { company: formData.company, role: formData.role }
+});
+```
+
+`trackForm` fires `form_submit` + `identify` in one call.
+
+## Recipe 6: Server-side events (Server Events API)
+
+For backend events (webhooks, cron jobs, CRM milestones), use the **Server Events API**: `sendServerEvent` / `sendServerEvents` from `@apex-inc/sdk`. This is the canonical replacement for raw `fetch()` calls to `/api/events`.
+
+```typescript
+import { sendServerEvent, newIdempotencyKey } from "@apex-inc/sdk";
+
+// Stripe webhook example
+await sendServerEvent(
+  { apiKey: process.env.APEX_API_KEY! }, // apex_sk_…
+  {
+    type: "purchase_completed",
+    email: customer.email,
+    visitorId: cookieJar.get("apex_vid"), // optional but improves stitching
+    data: { value: invoice.amount_paid / 100, currency: "USD", order_id: invoice.id },
+  },
+  { idempotencyKey: stripeEvent.id }, // dedupe on retry
+);
+```
+
+Why prefer the Server Events API over `fetch("/api/events")`:
+
+- **Idempotency-key** — retries don't double-count.
+- **clientType: "server"** — the Conversion Loop dashboard classifies events correctly.
+- **Single endpoint** — `/api/v1/events` is the documented, OpenAPI'd integration surface.
+- **Typed errors** — the wrapper throws on non-2xx with a clear `error.code` from the API.
+
+For batches > 1 event, use `sendServerEvents(config, events, { idempotencyKey })` (max 100 per call).
+
+For agent-driven testing through MCP, use the **`send_server_event`** tool — same endpoint, exposed as a single-call MCP tool with the idempotency key generated for you.
+
+## Event naming conventions
+
+- **snake_case**: `signup_completed`, `feature_used`, `invoice_paid`
+- Context in **properties**: `track("button_clicked", { surface: "pricing", label: "start_trial" })`
+- For experiments, include `experimentId` and `variant` in properties
+- One primary metric per experiment; secondary metrics as properties
+
+## Identity stitching checklist
+
+1. Call `identify(userId, { email, visitorId })` when the user becomes known
+2. `visitorId` = value of the browser `apex_vid` cookie
+3. Server-side: pass `traits.visitorId` to link to the browser session
+4. Without stitching, pre-signup attribution is lost
+
+## Partner Network patterns
+
+### Credit a partner for a self-serve signup
+
+When a visitor arrives from an affiliate link (`?utm_source=affiliate&utm_campaign=<handle>`) and signs up on your site, the Apex snippet automatically stitches the referral to the resulting Contact. The conversion auto-credits on the next purchase event (MMP-096 wiring).
+
+No SDK calls needed for basic attribution. Use `list_partner_program_members(programId)` to see who's actually earning.
+
+### Run a manual-approval program + vet applicants in a script
+
+```typescript
+import { createManagementClient } from "@apex-inc/sdk/management";
+const apex = createManagementClient({ projectKey, apiKey });
+
+// Create the program
+const program = await apex.createProgram({
+  name: "Vetted Partners",
+  vertical: "saas",
+  commissionStructure: { type: "revshare", percentage: 25, appliesTo: "subscription" },
+  visibility: "public",
+  approvalMode: "manual", // every applicant needs review
+});
+
+// ...applicants land in /admin/partners/applications for human review.
+// The SDK doesn't wrap the approval flow — that's an admin-auth path.
+// But merchants can monitor who's joined:
+const members = await apex.listProgramMembers(program.id);
+```
+
+### Batch-approve the weekly payout queue
+
+```typescript
+const queue = await apex.listPendingPayouts();
+const olderThanThirtyDays = queue.buckets["30_60"].concat(queue.buckets["60_plus"]);
+const result = await apex.approvePayouts(olderThanThirtyDays.map(c => c.id));
+console.log(`Approved ${result.approved.length}, skipped ${result.skipped.length}`);
+```
+
+**Approving does not fire Stripe transfers.** The next `run-payouts` cron cycle (per your `autoPayoutPolicy`) batches + fires. Design reason: reserve holdback window (90 days for NEW partners) has to elapse before transfer.
+
+### Give an enterprise partner a custom rate
+
+```typescript
+await apex.updateMembershipRate("prof_acme", {
+  commissionStructure: { type: "revshare", percentage: 35, appliesTo: "subscription" },
+  reason: "Enterprise negotiation - Q4 contract",
+});
+```
+
+Overrides are sticky. Updating the program default later won't overwrite this partner's rate (only `applyProgramDefaultToMembers` can mass-update, and it respects sticky overrides).
+
+### Disclose fees accurately in your UI
+
+```typescript
+const { fees } = await apex.getEffectiveFees();
+// Show merchants what they're charged per fee kind.
+// source: "merchant_override" means they have a custom (enterprise) rate.
+```
+
+## Recipe — Mobile build sources (TestFlight vs App Store)
+
+Apex auto-detects which build a mobile event came from and routes accordingly. Use the same `projectKey` everywhere — there's no separate sandbox key to provision.
+
+### Detection (no SDK code required)
+
+iOS uses StoreKit 2's `appStoreReceiptURL` to distinguish `app-store`, `testflight`, and `xcode-debug`. Android uses `PackageManager.getInstallSourceInfo()` (API 30+) to distinguish `play-production`, `play-internal`, and `sideloaded`, with `BuildConfig.DEBUG` overriding to `xcode-debug` for local builds.
+
+```typescript
+import { Apex } from "@apex-inc/capacitor-plugin";
+
+await Apex.initialize({ projectKey: "wsk_..." });
+// That's it. The next event includes `releaseChannel` + `releaseChannelSource`.
+```
+
+### Override for Android closed-test tracks
+
+iOS overrides are ignored (the receipt always wins). On Android, `getInstallerPackageName()` can't distinguish Play production from closed-test tracks, so you can supply a hint at init time:
+
+```typescript
+import { Apex } from "@apex-inc/capacitor-plugin";
+import { ApexChannel } from "./build-config"; // BuildConfig.APEX_CHANNEL
+
+await Apex.initialize({
+  projectKey: "wsk_...",
+  releaseChannel: ApexChannel, // "play-internal" for closed-test variant
+});
+```
+
+Use Gradle `buildConfigField` to inject the channel per build variant so the value is wired at compile time, not runtime.
+
+### Billing implications
+
+- **Dev** (Xcode-debug, Gradle-debug, sideloaded): always **free**.
+- **Beta** (TestFlight, Play internal/closed): always **free**.
+- **Production** (App Store, Play production): **billable**.
+- **Unknown** (older SDK without detection): billable, but the dashboard surfaces a fix-it nudge with an SDK upgrade prompt.
+
+No retroactive credits — if you misclassify a build, the fix takes effect for future events.
+
+### When NOT to recommend a separate project
+
+Some MMP vendors require two project keys (sandbox + live). Apex does not. If a merchant asks "should I use a different project for beta?" or "do I need a sandbox key?", the answer is **no**: point to `/docs/mobile/test-vs-production` and walk them through the **Build environments** card in Settings → Mobile apps.
+
+## Related
+
+- Event tracking fundamentals: see **apex-growth-tracking** skill
+- Experiment design: see **apex-experimentation** skill
+- Communication setup: see **apex-communications** skill
+- Affiliate / partner programs: see **apex-partner-network** skill

package/skills/apex-journeys/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: apex-journeys
+description: Help users design, audit, and ship Adaptive Journeys — multi-step lifecycle sequences with waits, branches, and exit rules. Use whenever the user mentions journeys, cart abandonment, onboarding sequences, drip campaigns, or asks to add/remove an exit rule. Always run alongside apex-communications for any cart-recovery, lifecycle, or sequence work.
+---
+
+# Apex Journeys (MCP)
+
+Journeys are multi-step communication sequences with waits, branches, and exit rules. A single `send_email` is a Communication; a `send_push → wait 1h → send_email → wait 24h → send_email` is a Journey.
+
+The single hardest thing about journeys is **knowing when to stop**. The vast majority of lifecycle programs that look broken to end users are journeys that fired a "you forgot something" message after the user already came back. This skill makes exit rules a first-class concern.
+
+## When to Activate
+
+- User says "journey", "sequence", "drip", "lifecycle program", "cart abandonment", "abandoned cart recovery"
+- User wants to chain multiple messages with delays between them
+- User is editing or auditing exit rules
+- User mentions branching on subject state (cart contents, plan tier, lifecycle stage)
+- User just created a marketing communication and you sense it should be part of a sequence
+
+## Tool Map
+
+| Tool | When to use |
+|---|---|
+| `list_journeys` | Browse all journeys with their exit-rule counts. Start here for any audit or "what do I have?" question. |
+| `get_journey` | Read full configuration for a specific journey (steps, exit rules, goal). |
+| `list_journey_exits` | Read only the exit rules for one journey. Use when the user asks "what triggers an exit for this?" |
+| `add_journey_exit` | Add an exit rule to a journey draft. Use when the user (or you proactively) decides a journey needs a new exit trigger. |
+| `remove_journey_exit` | Remove an exit rule from a journey draft. |
+| `audit_journey_exits` | Sweep across all published marketing journeys and find ones missing purchase exits. Run this proactively when a user mentions journeys, cart recovery, or marketing programs. |
+| `get_contact_cart` | Inspect a contact's current cart state to debug cart-recovery journeys or branch.condition evaluations. |
+
+## Core Concepts to Convey
+
+### A journey is just steps with edges
+
+Each step is one of: `send_email`, `send_push`, `send_sms`, `wait` (`fixed` or `until_event`), `branch.condition`, `goal`, or `exit`. Edges describe which step runs next. The runtime (a Step Functions state machine per execution) advances pointers and emits events.
+
+### Exit Events are journey-level, not step-level
+
+Exit rules are declared once at the journey level and apply to every in-flight execution. When a matching event fires for the executing subject, the matcher halts the execution **regardless of which step it was on**.
+
+```ts
+journey.exitEvents = [
+  {
+    id: "exit-cart-purchased",
+    eventName: "in_app_purchase",
+    description: "Stop messaging if the user completes a purchase",
+    enabled: true,
+  },
+  {
+    id: "exit-cart-cleared",
+    eventName: "cart_snapshot",
+    guard: { kind: "compare", path: "itemCount", op: "==", value: 0 },
+    description: "Stop messaging if the cart was emptied (not via purchase)",
+    enabled: true,
+  },
+];
+```
+
+When teaching users, this is the mental model:
+
+> "A journey starts because something happened. An exit fires when the reason for the journey no longer exists."
+
+### Send-time gate is authoritative
+
+Even if the stream-based exit matcher misses an event (race conditions are rare but possible), every `send_*` step re-checks exit rules immediately before firing. This is the guarantee Apex makes to its users: **if an exit event has fired by the moment we send, we will not send**.
+
+You can mention this to users; it removes a class of "what if the event arrived 2ms before send?" worries.
+
+### Counters that prove it works
+
+`/api/journeys/[id]/calibrated-impact` exposes:
+
+- `triggered_exposed_exited_before_send` — how many people exited before any message went out. **A healthy cart-recovery journey will have this > 0**: it's the number of customers Apex protected from a stale message.
+- `converted_exposed_messaged` — converted users who received at least one message. This is the honest "did the message contribute?" denominator.
+- `messagedLift` — calibrated lift restricted to messaged subjects.
+
+When discussing journey performance, lead with `messagedLift`, not raw conversion.
+
+## Tool Invocation Order
+
+### "Set up cart abandonment recovery"
+
+This is the canonical journey-skill workflow. **Always involve apex-communications** for the payloads.
+
+```
+1. list_journeys → check if a cart-recovery journey already exists
+2. If not, recommend the mobile-cart-recovery template (it's seeded in Apex)
+3. Ensure communications exist: hand off to apex-communications.recommend_communications + generate_communications for the cart-recovery push and email
+4. Confirm exit rules: add_journey_exit for in_app_purchase, cart_snapshot itemCount==0, and checkout_completed
+5. list_journey_exits to confirm
+6. Walk the user through the apex.trackCart helpers their app needs to call (see apex-growth-tracking for the SDK shape)
+```
+
+### "Audit my journeys for missing exits"
+
+```
+1. audit_journey_exits(active_only=true)
+2. For each missing_purchase_exit row: walk the user through add_journey_exit
+3. Re-run audit_journey_exits to confirm all journeys are green
+```
+
+### "Why didn't this user get my cart-recovery push?"
+
+```
+1. get_contact_cart(contact_id=...) → check current cart state (itemCount, lastEventId)
+2. If cart.itemCount === 0, the exit rule fired — that's correct behavior
+3. If cart still has items, get_journey(journey_id) and verify the wait duration + exit rules
+4. Check calibrated-impact for triggered_exposed_exited_before_send count
+```
+
+### "Add a new exit condition to onboarding"
+
+```
+1. list_journeys → find the onboarding journey id
+2. list_journey_exits(journey_id) → see what already exits
+3. add_journey_exit({journey_id, event_name: "onboarding_completed", description: "User finished setup before wait expired"})
+```
+
+## Proactive Behavior
+
+### When the user creates a marketing or lifecycle communication
+
+After helping a user generate a single communication, ask whether it's part of a sequence:
+
+> "This 'cart abandoned' push is a single send. Most cart-recovery programs are a sequence: push at 30 min → email at 2 hr → final reminder at 24 hr. Want me to wire this as a journey so it doesn't fire for users who already bought?"
+
+### When the user mentions a wait, delay, or "after X hours"
+
+Anything with a wait needs exit rules. Don't ship a journey without them.
+
+> "I set up the journey with a 1-hour wait before the next message. Before we publish, let me add exit rules so we stop messaging anyone whose cart is purchased or cleared during that hour."
+
+### When auditing existing programs
+
+Run `audit_journey_exits` proactively at the start of any conversation about journeys, marketing programs, or cart abandonment. If anything returns missing, surface it before doing anything else.
+
+### When the user asks "should I send this?"
+
+If the answer involves a wait, the real question is "what should stop this from sending?" Reframe the conversation toward exit rules.
+
+## Common Mistakes to Catch
+
+| Mistake | What to say |
+|---|---|
+| Cart-recovery journey with no exit on purchase | "Add an exit on `in_app_purchase`. Without it you'll message buyers after they bought." |
+| `wait.fixed` for cart abandonment | "Use `wait.until_event` with a deadline. That way the wait ends as soon as the user comes back, not on a fixed timer." |
+| Exit rule with no `guard` on `cart_snapshot` | "`cart_snapshot` fires whenever the cart changes, including adds. Add a guard like `itemCount == 0` so you only exit on a cleared cart." |
+| Same exit rule on multiple journeys, hand-managed | "Apex doesn't share exit rules across journeys, but the underlying event matches the same. Each journey gets its own copy — that's fine." |
+| Disabling all exit rules to "always send" | "If you want to always send, remove the wait. Don't disable exits and keep the wait — you'll re-create the original problem." |
+
+## Glossary
+
+- **AdaptiveJourney**: A draft/published journey with steps and exit rules.
+- **ExitEventRule**: One rule on `journey.exitEvents`. Has `eventName`, optional `guard` predicate, `description`, `enabled`.
+- **JourneyExecutionPointer**: Server-side record of an in-flight execution for one contact.
+- **wait.until_event**: A wait step that ends when a named event fires (or a deadline expires).
+- **branch.condition**: A step that routes execution based on a predicate over subject attributes (e.g., `cart.itemCount >= 2`).
+- **Send-time gate**: The authoritative re-check that runs immediately before any send step.
+
+## Resources
+
+- `apex://journeys` — current journeys list with exit-rule counts (if available as an MCP resource)
+
+## See Also
+
+- **apex-communications** — for the per-message payloads (subject, body, channel) the journey fires
+- **apex-growth-tracking** — for the `apex.trackCart` SDK helpers that emit the events journeys consume and exit on
+- **apex-experimentation** — to A/B test variants within a journey step

package/skills/apex-partner-network/SKILL.md

@@ -0,0 +1,191 @@
+---
+name: apex-partner-network
+description: Build, run, and grow an affiliate / referral program on the Apex Partner Network. Use when a merchant wants to pay partners a commission for driving installs / purchases / subscriptions, manage a roster of affiliates, or invite specific people to promote their product. The SDK wraps programs, memberships, invitations, payouts, fee disclosure, and merchant vouching.
+---
+
+# Apex Partner Network (SDK)
+
+The Apex Partner Network is a two-sided affiliate network: merchants own programs, partners join one or many programs across every merchant they work with, Apex facilitates the money rail between them via Stripe Connect.
+
+This skill covers the **merchant-facing management SDK** — programmatic access from a Node.js backend using an `apex_sk_*` service key. Partner-facing flows (self-signup, dashboard, Stripe Connect OAuth consent) happen in the hosted portal at `partners.apex.inc`.
+
+## Core mental model
+
+| Concept | What it is |
+|---|---|
+| **Program** | A merchant-owned commission offer (CPA or RevShare). Merchants can run multiple. |
+| **Membership** | One partner × one program. Carries the partner's current commission (and its audit history). |
+| **Conversion** | A tracked install/purchase/subscription credited to a partner via their Apex link. |
+| **HoldbackEntry** | One per approved conversion. Splits commission into available + held portions per the partner's trust tier. |
+| **MerchantPayoutBatch** | A settled cycle of all released-available commissions for one partner, fired per the merchant's `autoPayoutPolicy`. |
+
+## SDK bootstrap
+
+```typescript
+import { createManagementClient } from "@apex-inc/sdk/management";
+
+const apex = createManagementClient({
+  projectKey: "your-project-key",
+  apiKey: process.env.APEX_API_KEY!,
+  apiUrl: "https://app.apex.inc", // omit for local dev
+});
+```
+
+All calls below go through this client. Under the hood, requests attach `x-api-key` + `x-apex-project` headers to every `/api/mobile/affiliates/*` route.
+
+## Creating your first program
+
+```typescript
+const program = await apex.createProgram({
+  name: "Partner Program",
+  description: "Refer a customer, earn 20% for 12 months.",
+  vertical: "saas",
+  commissionStructure: {
+    type: "revshare",
+    percentage: 20,
+    appliesTo: "subscription",
+  },
+  visibility: "public",   // shows in /marketplace for partner discovery
+  approvalMode: "manual", // review each applicant
+});
+```
+
+Programs can be `paused`/`archived` later via `updateProgram(id, { status: "paused" })`. Pausing freezes new applications + new conversions but keeps existing memberships alive.
+
+## Inviting a partner
+
+```typescript
+await apex.invitePartner({
+  email: "sarah@example.com",
+  programId: program.id,
+  inviterName: "Alice from Acme",
+  inviterMessage: "I'd love to partner with you — here's a special rate.",
+  customRate: {
+    commissionStructure: {
+      type: "revshare",
+      percentage: 30, // negotiated higher rate
+      appliesTo: "subscription",
+    },
+  },
+});
+```
+
+Sarah gets a magic-link email. If she's already a partner on Apex, the invite creates a new `AffiliateMembership` bound to this program. If she's new, she claims a handle + completes onboarding at the portal.
+
+**Handle rule**: one `@sarah` works across every merchant program she joins. She doesn't need a separate account per merchant.
+
+## Adjusting commission rates
+
+Three commission sources are possible:
+- `program_default` — set by the program; member has never been individually adjusted
+- `membership_override` — explicit override set on this membership (sticky; survives program default updates)
+- `invite_override` — set at invite time (sticky same as membership_override)
+
+```typescript
+// Bump this specific partner to 35%
+await apex.updateMembershipRate("prof_sarah", {
+  commissionStructure: {
+    type: "revshare",
+    percentage: 35,
+    appliesTo: "subscription",
+  },
+  reason: "Volume performer — Q3 bump",
+});
+
+// ...later, reset them back to program default
+await apex.resetMembershipRate("prof_sarah", "Q3 promo ended");
+```
+
+Updating a program's default does NOT retroactively change existing memberships — call `applyProgramDefaultToMembers(programId)` to fan it out (skips overrides).
+
+## Approving payouts
+
+Commissions sit as `pending` until approved. The full batch flow:
+
+```typescript
+// 1. What's owed
+const queue = await apex.listPendingPayouts();
+// {
+//   buckets: { "0_30": [...], "30_60": [...], "60_plus": [...] },
+//   totals: { "0_30": 1450.00, ... },
+//   effectivePolicy: { policy: "manual", source: "project", capUsd: undefined },
+//   caps: { daily: undefined }
+// }
+
+// 2. Approve (creates HoldbackEntry + transitions to "approved")
+const result = await apex.approvePayouts(
+  queue.buckets["0_30"].map(c => c.id),
+);
+// { approved: [{ id, heldbackAmountUsd }], skipped: [...], failed: [...] }
+```
+
+**Approving does NOT fire the Stripe transfer**. The transfer happens at the merchant's `autoPayoutPolicy` cycle (daily / weekly / manual). This decoupling:
+
+- lets the merchant review multiple conversions before committing
+- lets the platform batch per (merchant, partner) to minimize Stripe fees
+- gives the holdback release window (90d for NEW partners, 30d for VERIFIED) time to run
+
+## Fee disclosure
+
+Merchants should always know what Apex charges them:
+
+```typescript
+const { fees } = await apex.getEffectiveFees();
+// fees: {
+//   facilitation_payout: { bps: 25, flatUsd: 0.5, source: "platform_default", isCustom: false },
+//   identity_verification: { flatUsd: 2.5, source: "platform_default", isCustom: false },
+//   instant_payout: { bps: 100, flatUsd: 0.5, source: "platform_default", isCustom: false },
+// }
+```
+
+Enterprise deals show `isCustom: true` with `source: "merchant_override"`. Admin edits propagate within 60 seconds (cache TTL).
+
+## Vouching for a partner
+
+A merchant who knows a partner outside Apex can vouch for them — bumping their trust tier one level for 60 days. This unlocks higher payout caps for the partner immediately. It's NOT free: the merchant takes on indemnity.
+
+```typescript
+await apex.vouchForPartner("prof_sarah", {
+  indemnityAcknowledged: true, // MUST be literally true
+  reason: "10-year professional relationship, verified off-platform",
+});
+```
+
+**Important**: if the partner commits fraud during the 60-day vouched window, the merchant's account is liable for clawbacks the reserve can't cover. Use sparingly.
+
+## What happens when things fail
+
+**Partner reaches a cap**: the batch surfaces a tier-aware message. NEW-tier partners see "processing" (masked); TRUSTED/VERIFIED partners see the reason.
+
+**Merchant's Stripe balance is short**: retry fires in 24h. After 48h (2nd fail), the merchant gets an email. After 72h (3rd fail), a dashboard card appears + partner messaging flips. After 7 days (7th fail), Apex opens a support case — **not labeled as fraud** — for human triage.
+
+Automation never freezes a merchant's `autoPayoutPolicy`. That's always a human decision.
+
+## Reading auto-payout policy
+
+Set per-project or per-program:
+
+```typescript
+await apex.updateProgram(programId, {
+  autoPayoutPolicy: "auto_under_cap", // auto-pay up to cap, manual above
+  autoPayoutCapUsd: 1000,
+});
+```
+
+Policies:
+- `"manual"` — every payout needs merchant click-to-approve (default)
+- `"auto"` — approved conversions auto-queue for the next payout cycle
+- `"auto_under_cap"` — auto under `autoPayoutCapUsd`, queue above
+
+## What this SDK does NOT cover
+
+- **Partner-facing flows** (self-signup at `/apply`, portal dashboard, Stripe Connect Express onboarding) — these happen in the hosted portal + require Cognito auth, not API key auth.
+- **Admin / Fraud Ops** (case queue, appeal decisions, ban list, fee policy edits) — admin Cognito flow, different tooling.
+- **Webhooks** (Stripe Connect events, identity verification status) — those are inbound from Stripe, not outbound from the SDK.
+- **Real-time Stripe transfers** — transfers fire on the merchant's schedule via the platform's payout orchestrator, not synchronously from the SDK.
+
+## See also
+
+- `apex-integration-cookbook` — end-to-end patterns combining partner network + communications + experiments
+- MCP tools: `list_partner_programs`, `create_partner_program`, `invite_partner`, `approve_payouts`, `vouch_for_partner`, `get_effective_fees`
+- Docs: `/docs/partner-network/` for concept walkthroughs + integration guides