ani-skills 1.0.0

package/skills/connect-recommend/references/compatibility-matrix.md

@@ -0,0 +1,194 @@
+# Connect integration compatibility reference
+
+This document encodes known Connect integration incompatibilities — combinations of account controller properties and charge types that cause serious issues for platforms. Use this as a validation checklist when recommending or reviewing any Connect configuration.
+
+---
+
+## 1. Controller Property + Charge Type Compatibility Matrix
+
+Significant compatibility issues arise when account controller properties (dashboard, fees_collector, losses_collector) are paired with incompatible charge types. Each combination below is rated:
+
+- **BLOCKED** — Incompatible combination. Never recommend. Can cause liability-model mismatch, fee-model mismatch, or inability to manage key payment operations.
+- **CAUTION** — Technically functional but has significant drawbacks. Present with explicit warnings.
+- **ALLOWED** — Supported combination. Proceed normally.
+- **OUT OF SCOPE** — Not supported by this guide. Redirect to Stripe docs or sales.
+- **Reasoning depth vs output brevity** — This reference is intentionally detailed so the assistant can reason about liability and transfer mechanics. User-facing warnings should stay concise and action-oriented.
+- **Output guardrail** — Keep recommendation warnings concise (typically one to two sentences). Use the mechanism details in this document to choose the right warning and alternative path, not to dump every detail verbatim.
+
+### Core Rule
+
+> **For GA configurations with `losses_collector: "stripe"`, ONLY direct charges are safe.**
+>
+> For destination charges and separate charges and transfers, use `losses_collector: "application"` so responsibility aligns with dispute and transfer-reversal flows. In this guide, combinations that pair these charge patterns with `losses_collector: "stripe"` are marked BLOCKED.
+>
+> **Exception:** Express dashboard with `losses_collector: "stripe"` (regardless of fees_collector) is blocked for ALL charge types including direct — these configs are still in beta. Do not recommend them.
+
+> **Note:** `on_behalf_of` configurations are not supported by this guide. `on_behalf_of` columns are retained in the matrix for compatibility detection only — if the assistant encounters `on_behalf_of` requirements, it should redirect to Stripe docs or sales.
+
+### Full Matrix (v2 field names)
+
+| Dashboard | Fees Collector | Losses Collector | Direct | Destination | Destination `on_behalf_of` | Separate charges and transfers | Separate charges and transfers `on_behalf_of` |
+|-----------|---------------|-----------------|--------|-------------|----------|------|----------|
+| `full` | `stripe` | `stripe` | ALLOWED | BLOCKED | OUT OF SCOPE | BLOCKED | OUT OF SCOPE |
+| `express` | `application` | `application` | ALLOWED | CAUTION | OUT OF SCOPE | CAUTION | OUT OF SCOPE |
+| `express` | `stripe` | `stripe` | BLOCKED* | BLOCKED | OUT OF SCOPE | BLOCKED | OUT OF SCOPE |
+| `express` | `application` | `stripe` | BLOCKED* | BLOCKED | OUT OF SCOPE | BLOCKED | OUT OF SCOPE |
+| `none` | `stripe` | `stripe` | ALLOWED | BLOCKED | OUT OF SCOPE | BLOCKED | OUT OF SCOPE |
+| `none` | `application` | `stripe` | ALLOWED | BLOCKED | OUT OF SCOPE | BLOCKED | OUT OF SCOPE |
+| `none` | `application` | `application` | ALLOWED | ALLOWED | OUT OF SCOPE | ALLOWED | OUT OF SCOPE |
+
+*Express dashboard with `losses_collector: "stripe"` configs are still in beta. Even when GA, destination charges and separate charges and transfers still require platform-run dispute/refund recovery (including transfer reversals), which aligns with `losses_collector: "application"` instead.
+
+### CAUTION Details
+
+**express/application/application + destination charges (without `on_behalf_of`) and separate charges and transfers:**
+- Connected accounts cannot manage refunds, disputes, or Radar rules from their Express dashboard for these charge types (see [Express dashboard payments docs](https://docs.stripe.com/connect/express-dashboard/payments))
+- Stripe debits disputes to the platform first for these charge patterns; recovery depends on reversing prior transfers back from connected accounts
+- This pattern is only viable when the platform owns losses (`losses_collector: "application"`) and runs webhook-driven refund/dispute recovery workflows
+- Platform must handle failure modes (for example, insufficient connected-account balance) and negative-balance remediation
+- `on_behalf_of` is out of scope for this guide. Redirect to Stripe docs or sales instead of recommending it.
+
+### Blessed Paths (Safe Defaults)
+
+| Business Model | Dashboard | Fees | Losses | Charge Type | Why Safe |
+|---------------|-----------|------|--------|-------------|----------|
+| **Marketplace** | `express` | `application` | `application` | Destination | Platform-owned fees/losses with Express visibility for sellers; keeps refund/dispute transfer-recovery accountability with the platform |
+| **SaaS** | `full` | `stripe` | `stripe` | Direct | Stripe-managed fee/loss defaults for direct charges; connected accounts are independent merchants |
+| **Enterprise/White-label** | `none` | `application` | `application` | Destination or Direct | Full platform control, compatible with all charge types |
+
+---
+
+## 2. Why Blocked Combos Fail
+
+When `losses_collector: "stripe"` is combined with non-direct charges (destination or separate charges and transfers), this guide marks the combination as BLOCKED for three documented reasons:
+
+1. **Liability settings should align with where disputes are debited.** For destination charges and separate charges and transfers, disputes are debited from the platform balance. Use `losses_collector: "application"` so the liability model matches this funds flow.
+
+2. **Payment fees for these charge types are assessed on the platform.** For destination charges or separate charges and transfers, Stripe collects payment fees from the platform account regardless of `fees_collector`. (Rates vary by region — see [stripe.com/pricing](https://stripe.com/pricing).) Note: Legacy types behave differently, see [Fee behavior](https://docs.stripe.com/connect/direct-charges-fee-payer-behavior).
+
+3. **Recovery from connected accounts requires explicit transfer-reversal handling.** For destination/separate disputes, Stripe debits the platform first; the platform then recovers funds by reversing transfers via API or Dashboard. Refunds can auto-reverse transfers when `reverse_transfer: true`, but dispute recovery is not automatic and requires explicit logic.
+
+---
+
+## 3. Merchant of record enforcement gap
+
+Whoever provides the good or service at the transaction level should be the merchant of record. The charge type dictates who the merchant of record is:
+- **Direct charges** → Connected account is merchant of record (their name on bank statements)
+- **Destination charges / separate charges and transfers** → Platform is merchant of record
+- **`on_behalf_of` variants** → Connected account is merchant of record (despite charge living on platform account)
+
+**CRITICAL:** Platforms declare their intended merchant-of-record setup during platform onboarding, but can then create charges with any pattern regardless. Stripe will NOT enforce this selection at the API level. The recommendation must ensure the charge type matches the user's actual business relationship (who provides the goods/services).
+
+---
+
+## 4. Additional compatibility risks
+
+### 4a. OAuth / Connecting Existing Stripe Accounts
+
+**Risk level:** OUT OF SCOPE
+
+Connecting existing Stripe accounts via OAuth is a v1-only pattern primarily used in sales-assisted integrations. This guide does not support OAuth-based onboarding.
+
+**Why OAuth is problematic:**
+- Connected accounts can disconnect at any time, severing the platform's ability to process payments
+- Platform loses visibility into the connected account's state and requirements
+- Less platform control over onboarding flow and requirement collection
+- Not compatible with all embedded components
+
+**If the user mentions OAuth, "connect existing Stripe accounts," or "link existing accounts":**
+Direct them to the [Connect documentation](https://docs.stripe.com/connect) and recommend [contacting Stripe sales](https://stripe.com/contact/sales). This guidance only supports creating new connected accounts with embedded onboarding.
+
+### 4b. Custom Onboarding Complexity
+
+**Risk level:** CAUTION
+
+Platforms that choose `dashboard: "none"` and build custom onboarding underestimate the ongoing burden:
+- **KYC lifecycle ownership** shifts fully to the platform: initial collection, ongoing requirement monitoring, and remediation when verification fails.
+- **Country-specific legal entity requirements** change frequently. What works for US entities does not work for EU, and new countries add new requirements.
+- **Ongoing requirement collection** is required, not one-time. When regulatory and compliance requirements change (updated KYC rules, etc.), the platform must update collection flows and prompt existing accounts.
+- **Invalid information** from connected accounts leads to accounts stuck in restricted states. Without Stripe's built-in validation, platforms end up manually remediating stuck accounts.
+- **Higher remediation and maintenance burden** compared to embedded/hosted onboarding, because API-based onboarding requires custom collection logic and ongoing updates as requirements evolve.
+
+**Recommendation:** Use embedded onboarding components or Stripe-hosted onboarding unless the platform has dedicated compliance engineering resources AND a specific branding requirement that embedded components cannot meet. This reduces compliance and maintenance burden (see [Onboard your connected account](https://docs.stripe.com/connect/marketplace/tasks/onboard)).
+
+### 4c. Dashboard DIY (Missing Refund/Dispute Flows)
+
+**Risk level:** CAUTION
+
+Platforms that build their own dashboard experience (`dashboard: "none"`) commonly build earnings and payout views but **neglect refund and dispute management flows**. Without these:
+- Connected accounts cannot initiate refunds, leading to customer complaints escalating to chargebacks
+- Connected accounts cannot respond to disputes, causing auto-losses
+- Connected accounts cannot easily identify or remediate KYC requirement failures, causing prolonged restrictions
+
+**Recommendation:** If building a custom dashboard, day-one scope should include refund initiation, dispute response, and KYC requirement status/remediation with country-aware requirement handling. Strongly recommend using embedded components for these. If the platform cannot commit to this, use `dashboard: "express"` instead.
+
+### 4d. Product Compatibility by Integration Shape
+
+**Risk level:** INFO (long-term gap)
+
+Not all Stripe products work with all Connect integration shapes.
+
+**Recommendation:** If the platform plans to use Billing, Invoicing, or Payment Links, recommend direct charges.
+
+For other charge types, when encountering Billing (Subscriptions, Invoicing), Tax, Payment Links, or Checkout Sessions, proceed with caution and look things up in the Stripe docs or recommend contacting sales.
+
+### 4e. Geo Expansion Limitations
+
+**Risk level:** INFO (long-term gap)
+
+Certain integration paths have geographic restrictions:
+- **Cross-border payouts** have currency and timing limitations that vary by connected account country.
+- **Instant payouts** are only available in select countries and may require specific account configurations.
+
+**Recommendation:** If the user mentions international expansion plans, note that their integration shape may need adjustment for new countries and recommend checking Stripe's country availability documentation.
+
+### 4f. Taking on Pricing Without Expertise
+
+**Risk level:** CAUTION
+
+Platforms that choose `fees_collector: "application"` (platform owns pricing) should model Stripe processing fees explicitly, because unmodeled fees can reduce margins.
+
+**Recommendation:** This is already well-covered by the skill's mandatory fee economics breakdowns. Reinforce during discovery: if the platform does not have dedicated pricing expertise, recommend `fees_collector: "stripe"` and use `application_fee_amount` for platform revenue.
+
+### 4g. Destination Charges + Disputes: Missing Transfer Reversals
+
+**Risk level:** CAUTION
+
+When a dispute occurs on a destination charge:
+1. The charge lives on the **platform's** account (platform is merchant of record)
+2. Stripe debits the **platform's** balance for the disputed amount
+3. However, the platform has already transferred funds to the connected account via `transfer_data`
+
+The platform's balance is reduced but the connected account still has the funds. **A common implementation issue:** platforms fail to initiate a **transfer reversal** to recover the disputed amount from the connected account.
+
+**What should happen:**
+- Platform listens for `charge.dispute.created` webhook
+- Platform creates a transfer reversal to pull funds back from the connected account
+- If the connected account's Stripe balance is insufficient, the reversal creates a negative balance on the connected account (requires `losses_collector: "application"`)
+
+**What commonly goes wrong:**
+- Platform does not listen for dispute webhooks at all
+- Platform processes disputes manually but forgets the transfer reversal step
+- Platform assumes Stripe automatically reverses the transfer (it does NOT — `reverse_transfer` defaults to `false` on both refunds and disputes)
+- Connected account balance is zero, and without `losses_collector: "application"`, there's no mechanism to recover
+
+**Recommendation:**
+- Always implement a `charge.dispute.created` webhook handler that automatically reverses the associated transfer
+- Use `reverse_transfer: true` on refunds to make transfer reversal automatic for voluntary refunds
+- For disputes, build explicit transfer reversal logic — automatic reversal only happens for refunds, not disputes
+- Ensure `losses_collector: "application"` is set so the connected account balance can go negative, enabling recovery
+- Consider alerting on unrecovered dispute amounts where transfer reversal failed (e.g., connected account already withdrew funds)
+
+---
+
+## 5. Compatibility checks during discovery
+
+When generating a recommendation in the discovery flow, validate the final configuration against this checklist:
+
+1. **Compatibility matrix check:** Look up `(dashboard, fees_collector, losses_collector)` + `chargePattern` in the matrix above. If BLOCKED, do not present. Explain why and recommend the nearest allowed alternative.
+2. **Merchant-of-record consistency check:** Verify the recommended charge type matches who actually provides goods/services. Direct charges = connected account is merchant of record. Destination/separate charges and transfers = platform is merchant of record.
+3. **OAuth check:** If the user mentions OAuth for connecting accounts, warn about tradeoffs and recommend Account Links.
+4. **Custom onboarding check:** If `dashboard: "none"` and the user plans custom onboarding, warn about ongoing KYC collection/remediation burden and country-specific requirement drift.
+5. **Dashboard scope check:** If `dashboard: "none"`, confirm the platform plans to build refund/dispute operations, not just earnings views.
+6. **Fee expertise check:** If `fees_collector: "application"`, ensure the fee economics section includes explicit breakeven analysis.
+7. **Warning brevity check:** Keep user-facing warnings concise (typically one to two sentences), using this document as reasoning context.

package/skills/connect-recommend/references/decision-matrix.md

@@ -0,0 +1,367 @@
+# Connect Integration Decision Matrix
+
+## IMPORTANT: Use Accounts v2 API
+
+**ALWAYS use the Accounts v2 API (`/v2/core/accounts`) for new integrations.** Do NOT use the legacy v1 API with `type: 'express'`, `type: 'standard'`, or `type: 'custom'`. These are legacy categories that bundle together responsibility, dashboard, and requirement decisions into opaque labels.
+
+Instead, configure accounts using three independent dimensions:
+- **Dashboard access**: `express` (lightweight), `full` (independent businesses), `none` (white-label)
+- **Fee collection**: `stripe` (Stripe bills connected accounts) or `application` (platform manages billing)
+- **Loss liability**: `stripe` (Stripe bears unresolved negative balances) or `application` (platform bears negative balances)
+
+## Business Model → Recommendation Mapping
+
+| Business Model | Dashboard | Fees | Losses | Charge Pattern | Onboarding | Reasoning |
+|---|---|---|---|---|---|---|
+| **Marketplace** | `express` | `application` | `application` | Destination | Embedded | Platform owns customer relationship; platform-owned pricing + loss liability required for Express dashboard today |
+| **On-demand services** | `express` | `application` | `application` | Destination | Embedded | Fast onboarding for drivers/providers; platform-owned pricing + loss liability required for Express |
+| **Professional services** | `express` | `application` | `application` | Destination | Embedded | Similar to marketplace; platform-owned pricing + loss liability required for Express |
+| **SaaS with payments** | `full` | `stripe` | `stripe` | Direct | Embedded | Sellers want independence, own Stripe accounts, own branding |
+| **Crowdfunding** | `express` | `application` | `application` | Separate | Embedded | Multi-party splits and delayed release. Use transfer math (not `application_fee_amount`) and platform-owned loss liability for transfer reversals |
+| **Subscription platforms** | `express` | `application` | `application` | Destination | Embedded | Recurring billing, platform manages subscriptions; platform-owned pricing + loss liability required for Express |
+| **E-commerce (white-label)** | `none` | `application` | `application` | Destination or Direct | Embedded | Full branding control. Use embedded components for white-label feel. Going fully custom (no embedded components) adds significant complexity — the platform must build and maintain all connected account UX including onboarding remediation, refund/dispute flows, and ongoing requirement collection. |
+| **Rental marketplace** | `express` | `application` | `application` | Destination | Embedded | Platform owns booking flow; platform-owned pricing + loss liability required for Express |
+| **Event ticketing** | `express` | `application` | `application` | Destination | Embedded | Platform manages event/ticket flow; platform-owned pricing + loss liability required for Express |
+| **B2B platforms** | `none` | `application` | `application` | Separate | Embedded | For complex enterprise multi-party flows, prefer Separate charges and transfers with transfer math. Do not default to Destination in these scenarios. Often requires sales engagement for billing complexity — [Stripe sales](https://stripe.com/contact/sales). |
+
+**Note:** `fees` and `losses` columns refer to `defaults.responsibilities.fees_collector` and `defaults.responsibilities.losses_collector` in the v2 API. Values are `"stripe"` or `"application"` (your platform).
+
+---
+
+## Decision Tree Logic
+
+### Account Configuration Selection (Accounts v2)
+
+Rather than choosing a legacy "account type", configure three independent dimensions:
+
+**If the user asks "what account type should I use?" (or similar):**
+Reframe explicitly before giving settings: "In Accounts v2, avoid the legacy `type` parameter and configure behavior with explicit fields: `dashboard`, `defaults.responsibilities.fees_collector`, `defaults.responsibilities.losses_collector`, and the appropriate account configuration (`merchant` for direct charges or `recipient` for destination/separate flows)." Then provide the recommended field values.
+
+**Dashboard access:**
+```
+What dashboard should connected accounts see?
+├── No dashboard needed (fully embedded/white-label) → dashboard: "none"
+├── Independent businesses needing full Stripe access → dashboard: "full"
+└── Lightweight dashboard for sellers/providers → dashboard: "express" ← DEFAULT
+```
+
+**Responsibilities:**
+```
+Who collects fees and bears losses?
+├── Marketplace (destination/separate charges) → fees_collector: "application", losses_collector: "application"
+│   Platform is merchant of record and should be responsible for paying Stripe fees
+│   Platform-owned pricing + loss liability is REQUIRED for Express dashboard today
+│   Platform-owned loss liability enables connected account negative balances for transfer reversals
+├── SaaS (direct charges) → fees_collector: "stripe", losses_collector: "stripe" ← DEFAULT
+└── White-label/enterprise → fees_collector: "application", losses_collector: "application" (use embedded components; fully custom adds significant complexity)
+```
+
+**Detailed rules:**
+- If sellers are independent businesses wanting their own Stripe access → `dashboard: "full"`
+- If sellers need lightweight access (common for marketplaces) → `dashboard: "express"` (typical default)
+- If fully white-labeled, sellers never see Stripe → `dashboard: "none"`
+- Marketplace defaults: `dashboard: "express"` + `fees_collector: "application"` + `losses_collector: "application"`
+- SaaS defaults: `dashboard: "full"` + `fees_collector: "stripe"` + `losses_collector: "stripe"`
+- Hybrid Express defaults (same accounts used for direct + destination/separate): keep `dashboard: "express"` + `fees_collector: "application"` + `losses_collector: "application"` for both sides
+
+### Charge Pattern Selection
+
+```
+How many sellers per transaction?
+├── Multiple sellers → Separate charges & transfers
+└── One seller
+    └── Who should the customer pay at checkout?
+        ├── Seller runs checkout (seller name on receipt/statement) → Direct charges
+        └── Platform runs checkout (platform name on receipt/statement) → Destination charges ← DEFAULT
+```
+
+**Detailed rules:**
+- If platform owns customer relationship → **Destination** (most marketplaces)
+- If seller owns customer relationship → **Direct** (SaaS model)
+- If customers discover services on your platform and complete checkout in your platform flow (you own checkout UX, order confirmation, and payment operations) → **Destination**
+- Language saying payments should "belong to" or be "associated with" sellers, or that sellers should "run their own account," is usually a payout expectation (who receives proceeds) or a dashboard-access preference, not a checkout-ownership signal. Destination charges satisfy payout expectations through automatic transfers and Express dashboard satisfies "own account" expectations. Only choose Direct when sellers independently own the checkout experience (their own payment page, their branding on statements, they handle refunds/disputes).
+- Choose **Direct** when the behavior is SaaS enablement: each seller runs their own payment relationship, customers pay the seller directly, seller branding appears on receipts/statements, and seller-side operations handle payment support/refunds/disputes.
+- If multi-party splits needed → **Separate** (carts, one payment split across multiple parties)
+- If "platform collects then pays out" → **Destination**
+- If "buyers pay sellers directly" → **Direct**
+- If one payment maps to one connected account and funds transfer immediately (payout timing to bank is controlled by payout schedule, not release logic) → **Destination**
+- If the platform needs to hold funds and only transfer to the connected account after a trigger (delivery, job completion, approval, campaign end) → **Separate** (use transfer math; do not use `application_fee_amount`)
+- If one payment must be split across multiple connected accounts (e.g., multi-vendor cart) → **Separate**
+- For B2B enterprise flows with multi-party allocation, approval gates, or staged release, prefer **Separate** and do NOT default to **Destination**
+- If unsure and the flow is single-recipient, immediate-transfer marketplace behavior → **Destination** (safest default)
+
+### Hybrid model guidance
+
+Some platforms run two sides of business with the same connected accounts. This is supported, but every transaction must be explicitly classified to the correct side:
+- **Connected account is merchant of record** → **Direct** charges
+- **Platform is merchant of record** → **Destination** or **Separate** charges and transfers
+
+When both sides share Express connected accounts, keep controller settings aligned with the allowed path in this guide: `dashboard: "express"` + `fees_collector: "application"` + `losses_collector: "application"` for both direct and destination/separate contexts.
+
+Hybrid models add material complexity:
+- Two payment flows to build and maintain (direct + destination/separate)
+- Webhook handling across both payment lifecycle and transfer/reversal lifecycle
+- Expanded end-to-end testing matrix (refunds, disputes, transfer reversals, negative balance behavior)
+
+Launch the most business-critical side first, stabilize webhook/reconciliation behavior, then add the second side.
+
+### Onboarding Method Selection
+
+```
+How much control over onboarding UX?
+├── "Stripe handles everything" → Embedded components (recommended default)
+├── "Some customization" → Embedded components with [appearance options API](https://docs.stripe.com/connect/embedded-appearance-options)
+└── "Fully custom" → API-based — NOT RECOMMENDED for platforms integrating without dedicated Stripe guidance.
+    Requires building custom remediation flows. Direct to [Stripe sales](https://stripe.com/contact/sales).
+```
+
+**Detailed rules:**
+- `dashboard: "express"` → **Embedded components** (recommended, keeps users in-app) or Stripe-hosted redirect (fallback)
+- `dashboard: "full"` → **Embedded components** or Stripe-hosted redirect
+- `dashboard: "none"` + want embedded → **[Embedded components](https://docs.stripe.com/connect/embedded-onboarding)**
+- If unsure → **Embedded components** (Stripe handles requirement collection and ongoing compliance updates)
+- Do NOT recommend API onboarding. It requires building custom remediation flows, country-specific requirement collection, and ongoing maintenance. If a user insists on fully custom onboarding, direct them to [Stripe sales](https://stripe.com/contact/sales).
+
+### Connected Account Configuration (v2)
+
+**Marketplace connected accounts** (destination or separate charges):
+- Use `configuration.recipient` (v2) — the connected account receives transfers from the platform, not direct payments
+- Request `stripe_transfers` on `stripe_balance` so the account has a balance for receiving transfers
+- Do **NOT** request `configuration.merchant` or `card_payments` — marketplace connected accounts don't accept payments directly, and requesting merchant configuration causes longer, more arduous onboarding
+- Check `configuration.recipient.capabilities.stripe_balance.stripe_transfers.status === 'active'` before initiating transfers
+
+**SaaS connected accounts** (direct charges):
+- Use `configuration.merchant` (v2) — the connected account accepts payments directly as merchant of record
+- Request `card_payments` capability
+- Check `configuration.merchant.capabilities.card_payments.status === 'active'` before processing charges
+
+**SaaS recurring fees (service fees / SaaS fees):**
+- If the platform charges a recurring SaaS fee (subscription), the connected account needs both `merchant` and `customer` configurations in v2
+- Pass the account as `customer_account` on SetupIntent and Subscription API calls — do NOT create a separate v1 Customer object (the customer configuration replaces it)
+
+---
+
+## Combining Answers
+
+### Answer Combination → Recommendation
+
+| Q1: Model | Q3: Flow | Q4: Control | → Dashboard | → Fees/Losses | → Charges | → Onboarding |
+|-----------|----------|-------------|-------------|---------------|-----------|--------------|
+| Marketplace | Platform collects | Stripe handles | `express` | `application`/`application` | Destination | Embedded |
+| Marketplace | Platform collects | Some custom | `express` | `application`/`application` | Destination | Embedded |
+| Marketplace | Platform collects | Fully custom | `none` | `application`/`application` | Destination | API |
+| Marketplace | Direct to seller | Stripe handles | `full` | `stripe`/`stripe` | Direct | Embedded |
+| SaaS | Direct to seller | Stripe handles | `full` | `stripe`/`stripe` | Direct | Embedded |
+| SaaS | Platform collects | Stripe handles | `express` | `application`/`application` | Destination | Embedded |
+| On-demand | Platform collects | Stripe handles | `express` | `application`/`application` | Destination | Embedded |
+| Crowdfunding | Platform collects | Stripe handles | `express` | `application`/`application` | Separate | Embedded |
+| Platform + contractors | Platform collects | Stripe handles | `express` | `application`/`application` | Destination | Embedded |
+
+### Risk Management by Business Model
+
+> **Note:** This section is directional guidance only. For detailed risk and Radar configuration, refer to the [Stripe Radar for Platforms documentation](https://docs.stripe.com/radar/radar-for-platforms).
+
+**Default recommendation: Let Stripe manage risk.** This usually reduces operational overhead for launch. Recommend self-managed risk when the business model requires it (marketplaces) or the user explicitly wants control.
+
+| Business Model | Risk Owner | Radar | Stripe-Managed OK? | Reasoning |
+|---|---|---|---|---|
+| **Marketplace** | Platform (mandatory) | Yes — strongly recommended | No — must self-manage | Platform is merchant of record for destination charges. Liable for fraud/disputes. Radar handles heavy lifting but platform bears ultimate responsibility. |
+| **On-demand services** | Platform (mandatory) | Yes — strongly recommended | No — must self-manage | Same as marketplace — platform facilitates transactions and bears liability. |
+| **Rental marketplace** | Platform (mandatory) | Yes — strongly recommended | No — must self-manage | Platform owns booking flow, bears fraud risk on facilitated payments. |
+| **SaaS with payments** | Stripe (recommended) | Optional | **Yes — recommended** | Stripe's built-in protection handles most fraud. Platform can upgrade to Radar later if needed. |
+| **Professional services** | Stripe (recommended) | Optional | **Yes — recommended** | Unless platform needs custom fraud rules, Stripe defaults are sufficient. |
+| **Crowdfunding** | Stripe (recommended) | Optional | **Yes — recommended** | Stripe-managed defaults are often sufficient for launch; reassess based on dispute/fraud patterns. |
+| **Subscription platforms** | Stripe (recommended) | Optional | **Yes — recommended** | Recurring billing has different risk profile — churn > fraud. Stripe's defaults usually sufficient. |
+| **E-commerce (white-label)** | Platform (mandatory) | Yes | No — must self-manage | Full control = full responsibility. Dashboard-none configurations need platform-managed risk. |
+
+**Key rules:**
+- If `chargePattern` is `destination` or `separate`, the platform is the merchant of record and MUST manage risk — but Radar does the heavy lifting.
+- If `chargePattern` is `direct`, Stripe-managed risk is available and recommended.
+- Self-managing risk adds: dispute webhook handling, Radar configuration, ongoing monitoring, and financial exposure. Always warn the user about this added complexity.
+- Stripe Radar is a tool platforms use to manage risk — it is NOT the same as "Stripe manages risk for you." When Radar is enabled, the platform is still responsible; Radar just automates the detection.
+
+### Fee Structure Mapping
+
+| Charge Pattern | Fee Method | Implementation |
+|---|---|---|
+| **Direct** (Stripe owns pricing) | `application_fee_amount` | Strongly recommended. Charged in addition to Stripe fees that the connected account pays. The platform retains the full application fee amount. |
+| **Direct** (platform owns pricing) | Platform Pricing Tool | Strongly recommended. Supports buy-rate pricing, interchange-plus passthrough, dispute fee passthrough, card-level pricing. |
+| **Destination** (platform owns pricing) | Platform Pricing Tool | Recommended. Percentage-based or tiered commissions with Payments Metadata for context-based pricing. |
+| **Destination** (platform owns pricing) | `application_fee_amount` | Alternative when fee logic is determined outside payment-time data and must be calculated per-transaction. |
+| **Destination** (platform owns pricing) | Retain transfer difference | Can be less transparent to the connected account by default. Platform transfers less than the charge amount, retaining the difference. |
+| **Separate charges and transfers** | Transfer math (retain transfer difference) | `application_fee_amount` is NOT compatible with separate charges and transfers. Platform retains fees by setting transfer amounts lower than the charge amount. |
+
+**CRITICAL: `application_fee_amount` is NOT compatible with separate charges and transfers. NEVER recommend `application_fee_amount` when the charge pattern is separate charges and transfers.** Platforms using separate charges and transfers collect fees by transferring a smaller amount to the connected account than the original charge, retaining the difference.
+
+For separate charges and transfers, frame fee guidance as transfer math:
+`platform_margin = charge_amount − total_transfers_to_connected_accounts − Stripe_fees`
+
+### Fee Calculation & Fee Economics
+
+**Who pays Stripe's processing fees is one of the determining factors in whether your platform is profitable.**
+
+Stripe charges processing fees on every transaction. Rates vary by region, card type, payment method, and negotiated terms — see [stripe.com/pricing](https://stripe.com/pricing) for current rates. Who actually pays these fees depends on the charge pattern:
+
+| Charge Pattern | Who Pays Stripe Fees | Platform Net per Transaction |
+|---|---|---|
+| **Destination charges** | **Platform** pays Stripe fees | `application_fee_amount − Stripe_fees` |
+| **Destination charges + on_behalf_of** | **Platform** still pays (changes statement descriptor, merchant of record, and dispute management — see `charge-patterns.md`) | Same as above |
+| **Direct charges** (`fees_collector: "stripe"`) | **Connected account** pays Stripe fees | `application_fee_amount` (platform retains full fee — Stripe fees paid by connected account) |
+| **Direct charges** (`fees_collector: "application"`) | **Platform** pays Stripe fees | `application_fee_amount − Stripe_fees` |
+| **Separate charges & transfers** | **Platform** pays Stripe fees | Must account for fees in transfer math |
+
+> **Note:** Who pays Stripe fees on direct charges depends on the [`fees_collector` responsibility setting](https://docs.stripe.com/connect/direct-charges-fee-payer-behavior). When `fees_collector: "stripe"` (the default for SaaS), the connected account pays Stripe fees and the platform retains their full `application_fee_amount`. With `fees_collector: "application"` (used with Platform Pricing Tool and platform-owned pricing), the platform pays Stripe fees instead.
+
+**Profitability warning:** If the platform's desired fee margin is low relative to Stripe's processing fees for their region, destination charges may cause per-transaction losses unless the `application_fee_amount` is set high enough to cover Stripe fees + the platform's margin. DO NOT make definitive profit/loss claims with specific dollar amounts — pricing is situation-dependent.
+
+Strongly recommend:
+- The [Platform Pricing Tool](https://dashboard.stripe.com/settings/connect/platform_pricing) to configure pricing rules without code (requires platform-owned pricing, i.e. `fees_collector: "application"`; supports direct and destination charges, NOT separate charges and transfers)
+- Monitoring the margin report in the Stripe Dashboard
+- Checking [stripe.com/pricing](https://stripe.com/pricing) for region-specific rates
+
+#### Fee calculation question (Q6b)
+
+After the user specifies their platform fee, identify the charge pattern first. This question applies to **destination charges** only. For **separate charges and transfers**, do not ask how to set `application_fee_amount` — use transfer math instead. For direct charges with Stripe-owned pricing (`fees_collector: "stripe"`), the connected account pays Stripe fees and this question is moot. For direct charges with platform-owned pricing (`fees_collector: "application"`), the platform pays Stripe fees — use the Platform Pricing Tool.
+
+**IMPORTANT: With destination charges, the platform ALWAYS pays Stripe's processing fees.** They are deducted from the platform's balance, not the connected account's. The platform cannot make connected accounts pay Stripe fees directly. The choice is how to calculate `application_fee_amount`.
+
+Use Option A and Option B below as reference material for destination charges.
+
+**Option A — Include Stripe fee estimate in application_fee_amount (recommended for low margins)**
+The `application_fee_amount` includes BOTH an estimated Stripe processing fee and the platform's fee. The platform takes a larger cut to cover both its margin and Stripe's fee. The platform's fee percentage is preserved as net margin.
+
+```
+Concept: application_fee_amount = estimated Stripe processing fee + platform margin
+Platform NET = the platform's full fee percentage (margin preserved — Stripe fee covered by the higher application_fee_amount)
+Connected account receives = charge amount − application_fee_amount
+```
+
+**Option B — Platform fee only (platform absorbs Stripe fees)**
+The `application_fee_amount` is only the platform's cut. Stripe processing fees reduce the platform's net. Only viable when the platform fee is substantially higher than Stripe's processing fees.
+
+```
+Concept: application_fee_amount = platform fee only
+Platform NET = platform fee − Stripe processing fee
+Connected account receives = charge amount − application_fee_amount
+```
+
+**Recommendation output rule:** choose the single most appropriate option for the specific scenario instead of always presenting both. Keep the other option as reference material and surface it only when the user asks for alternatives/tradeoffs.
+
+**Decision guidance:** If the platform fee appears low or uncertain relative to processing fees (check [stripe.com/pricing](https://stripe.com/pricing)), recommend Option A to preserve platform margin (or switch to direct charges when appropriate). Use Option B only when fee headroom is clearly high and the platform explicitly accepts absorbing fee variance.
+
+**For destination charges, NEVER say "seller pays Stripe fees" or "connected account pays Stripe fees."** The platform always pays. The choice is whether to set a higher `application_fee_amount` to preserve the platform's margin.
+
+**Minimum charge amounts:** Stripe enforces minimum charge amounts by currency. For micro-payment platforms with very small transaction amounts, warn the user that:
+- Stripe enforces minimum charge amounts that vary by currency
+- On very small charges, the fixed fee component becomes a large percentage of the transaction
+- Micro-payments may need batching or alternative approaches to be economically viable
+
+#### Fee guidance principles
+
+When presenting fee recommendations:
+- DO NOT hardcode specific processing fee amounts (e.g., "2.9% + $0.30") — these are US-only and vary by region, card type, and payment method
+- DO NOT make definitive profit/loss claims (e.g., "you WILL lose money") — say "you may lose money at standard rates"
+- DO link to [stripe.com/pricing](https://stripe.com/pricing) for region-specific rates
+- DO strongly recommend the [Platform Pricing Tool](https://dashboard.stripe.com/settings/connect/platform_pricing)
+- DO recommend monitoring the margin report in the Stripe Dashboard
+- DO explain the concept of `application_fee_amount` and what it should include based on the calculation choice
+- DO return one recommended fee option for the scenario (do not always present both Option A and Option B)
+- DO prefer margin-preserving recommendations in low-margin or uncertain-margin scenarios
+- DO use transfer-math framing for separate charges and transfers (never `application_fee_amount`)
+- NEVER say "seller pays Stripe fees" or "connected account pays Stripe fees" for destination charges — the platform always pays
+
+#### Fee sanity checks
+
+- If the Platform Pricing Tool is used, ensure `application_fee_amount` is NOT set on the PaymentIntent — explicit `application_fee_amount` overrides the Platform Pricing Tool.
+- `application_fee_amount` is NOT compatible with separate charges and transfers. NEVER recommend it for separate charges and transfers.
+- For separate charges and transfers, validate the transfer-math model (`charge_amount − total_transfers − Stripe_fees`) to ensure expected platform margin.
+- Platforms based outside Brazil cannot collect application fees from Brazilian connected accounts due to regulatory requirements. Same restriction applies to Malaysia.
+- Use `amount` on the ApplicationFee object, not the charge field, for accurate fee reporting.
+- For small transactions (e.g., $1–$5), fees may be large relative to proceeds. Consider creative ways to combine transactions.
+- **Low-complexity margin path:** Direct charges with Stripe-owned pricing. Stripe handles pricing complexity; the platform charges a SaaS fee or application fee on top.
+- If the platform owns pricing with any charge type: warn about potential per-transaction losses. Strongly recommend the Platform Pricing Tool and monitoring the margin report.
+
+---
+
+### Loss Liability (Negative Balance Liability)
+
+**Loss liability and risk management are TWO SEPARATE decisions.** The current skill MUST NOT conflate them.
+
+| Concept | What it means | Where configured |
+|---------|--------------|-----------------|
+| **Negative balance liability** | Who is financially LIABLE when disputes/chargebacks create negative balances on connected accounts | Configured when creating the connected account; may require visiting the Stripe Dashboard → Connect platform profile to acknowledge understanding of how negative balance liability works |
+| **Risk management** | Who DETECTS and PREVENTS fraud (Radar, rules, monitoring) | Code + Dashboard (Radar settings) |
+
+You can have Stripe own loss liability while still using Radar for fraud detection. Radar is available regardless of loss liability setting.
+
+#### Loss Liability Recommendations by Business Model
+
+**Recommendation depends on charge pattern:**
+- **Marketplaces (destination/separate charges):** Platform-owned loss liability. This is **required** for destination charges — it enables connected account balances to go negative, which the platform needs to reverse transfers (e.g., for refunds or disputes). Also required for Express dashboard today.
+- **SaaS (direct charges):** Stripe-owned loss liability. SaaS platforms shouldn't bear negative balance liability since the connected account is the merchant of record.
+- **Enterprise/white-label:** Platform-owned. Full control = full responsibility.
+
+| Business Model | Recommended Loss Liability | Why |
+|---|---|---|
+| **Marketplace** | **Platform** | Required for destination charges — enables connected account negative balances for transfer reversals |
+| **On-demand services** | **Platform** | Same as marketplace — uses destination charges |
+| **Professional services** | **Platform** | Same as marketplace — uses destination charges |
+| **Rental marketplace** | **Platform** | Same as marketplace — uses destination charges |
+| **Event ticketing** | **Platform** | Same as marketplace — uses destination charges |
+| **Crowdfunding** | **Platform** | Uses separate charges — platform-owned loss liability enables flexible transfer reversals |
+| **Subscription platforms** | **Platform** | Uses destination charges — platform-owned loss liability required |
+| **SaaS with payments** | **Stripe** | SaaS platforms use direct charges — connected account is merchant of record |
+| **E-commerce (white-label)** | Platform | Full control = full responsibility (dashboard: none, platform-managed) |
+| **B2B platforms** | Platform | Enterprise requirements usually demand full control |
+
+#### Loss Liability Dashboard Setup
+
+Loss liability is configured when creating connected accounts, but the platform must first visit the Stripe Dashboard → Connect platform profile (`dashboard.stripe.com/settings/connect/platform-profile`) to acknowledge understanding of how negative balance liability works.
+
+The platform profile page asks about "Negative balance liability" (formerly called "loss liability"). The choice determines which account configuration combinations are available:
+
+- **Stripe manages losses** → Set `defaults.responsibilities.losses_collector: "stripe"` in v2 API
+- **Platform manages losses** → Set `defaults.responsibilities.losses_collector: "application"` in v2 API
+
+When guiding users through this page, always:
+1. Explain what loss liability means in plain language with a concrete example
+2. Recommend platform-owned for marketplaces using destination/separate charges — required for transfer reversals and Express dashboard
+3. Recommend Stripe-owned for SaaS platforms using direct charges
+4. Note that this is separate from Radar/fraud detection
+
+---
+
+## Integration Antipattern Warnings
+
+> **Read the full compatibility matrix in `compatibility-matrix.md`.** This section is a quick reference.
+
+### Common Blocked Combinations
+
+These combinations are true antipatterns that Stripe will never support. Do NOT recommend them:
+
+1. **`losses_collector: "stripe"` + destination charges** — Liability and fee behavior do not align with this charge pattern. Treat as BLOCKED when `losses_collector: "stripe"` is selected.
+2. **`losses_collector: "stripe"` + separate charges and transfers (including `on_behalf_of`)** — Same negative balance mechanism as destination charges. Platform cannot recover funds from connected accounts that only receive transfers.
+3. **Express dashboard + `losses_collector: "stripe"` + `fees_collector: "stripe"`** — Express dashboard requires platform to own both fees and losses (`application`/`application`). This is a hard API constraint — setting Express with Stripe-owned pricing produces an API rejection.
+4. **`dashboard: "full"` + destination charges or separate charges and transfers** — Full dashboard has reduced payment-management capabilities with these charge types and is not recommended. Full dsahboard supports applications using destination charges with `on_behalf_of`, but full dashboard is generally designed for direct charges.
+5. **`losses_collector: "application"` + `fees_collector: "stripe"` (platform-owned losses + Stripe-owned pricing)** — This combination is NOT supported.
+6. **(`on_behalf_of` is out of scope for this guide — redirect to docs/sales if encountered.)** **`on_behalf_of` with destination charges for marketplace use cases** — Do NOT use `on_behalf_of` for marketplaces. `on_behalf_of` makes the connected account the merchant of record, but in a marketplace the platform should be merchant of record. If a user requires `on_behalf_of`, direct them to [Stripe Connect docs](https://docs.stripe.com/connect/charges) or [Stripe sales](https://stripe.com/contact/sales).
+7. **`application_fee_amount` with separate charges and transfers** — NOT compatible. Platforms using separate charges and transfers collect fees by transferring less than the charge amount.
+
+### Blessed Paths (Safe Defaults)
+
+| Business Model | Dashboard | Fees | Losses | Charge Type | Status |
+|---|---|---|---|---|---|
+| **Marketplace** | `express` | `application` | `application` | Destination | ALLOWED — baseline path in this guide |
+| **SaaS** | `full` | `stripe` | `stripe` | Direct | ALLOWED — connected accounts are independent merchants |
+| **Enterprise** | `none` | `application` | `application` | Any | ALLOWED — full platform control |
+
+**Any deviation from these blessed paths should trigger a compatibility check against `compatibility-matrix.md`.** If the user's choices lead to a BLOCKED combination, do not present it. Explain why it fails and recommend the nearest allowed alternative.
+
+> **Scope boundary:** This guide supports the blessed paths above. Configurations outside these paths (full+application, none+stripe+stripe, `on_behalf_of`, OAuth, non-payments products like Issuing/Treasury/Capital/Tax/Terminal) should trigger sales-led detection and redirect to docs/sales.
+
+### Additional Antipatterns to Watch For
+
+- **OAuth instead of Account Links** — Developers think OAuth is simpler but lose platform control (connected account can disconnect at any time). Recommend Account Links or embedded components.
+- **Custom onboarding** (`dashboard: "none"` + API-based) — Ongoing requirement collection burden and country-specific complexity. Only for platforms with dedicated compliance engineering.
+- **Dashboard DIY without refund/dispute flows** — Platforms build earnings views but skip refund and dispute management. Connected accounts cannot respond to disputes, leading to auto-losses.
+- **Stripe does NOT enforce merchant of record at API level** — Platforms can create charges with any pattern regardless of their onboarding declaration. Code must consistently use the correct charge type for the actual business relationship.