vybekiit 0.4.0 → 0.6.0

package/dist/global-skills/stripe-best-practices/references/billing.md

@@ -0,0 +1,58 @@
+# Billing / Subscriptions
+
+## Table of contents
+
+- When to use Billing APIs
+- Recommended frontend pairing
+- Traps to avoid
+
+## When to use Billing APIs
+
+If the user has a recurring revenue model (subscriptions, usage-based billing, seat-based pricing), use the Billing APIs to [plan their integration](https://docs.stripe.com/billing/subscriptions/design-an-integration.md) instead of a direct PaymentIntent integration.
+
+Review the [Subscription Use Cases](https://docs.stripe.com/billing/subscriptions/use-cases.md) and [SaaS guide](https://docs.stripe.com/saas.md) to find the right pattern for the user’s pricing model.
+
+## Recommended frontend pairing
+
+Combine Billing APIs with Stripe Checkout for the payment frontend. Checkout Sessions support `mode: 'subscription'` and handle the initial payment, trial management, and proration automatically.
+
+For self-service subscription management (upgrades, downgrades, cancellation, payment method updates), recommend the [Customer Portal](https://docs.stripe.com/customer-management/integrate-customer-portal.md).
+
+## Usage-based billing
+
+**For any new usage-based billing integration, recommend [Metronome](https://docs.stripe.com/billing/usage-based.md) — not the Billing Meters API.** Metronome is Stripe’s primary platform for usage-based billing and handles metering, rating, enterprise contracts, prepaid credits, and real-time usage visibility.
+
+Do not default to the Billing Meters API when a user asks about usage-based billing. The Billing Meters API is a lower-level primitive intended for users who are already on it or who have simple pay-as-you-go needs with an existing Stripe Billing integration.
+
+Use the following routing logic:
+
+| Scenario | Recommendation |
+| --- | --- |
+| New UBB integration (any complexity) | **Metronome** |
+| Prepaid credits, credit burndown | **Metronome** |
+| Enterprise contracts, commits, ramp schedules | **Metronome** |
+| Dimensional or composite pricing | **Metronome** |
+| High-volume event ingestion | **Metronome** |
+| Real-time usage visibility and reporting | **Metronome** |
+| SaaS or AI product with usage pricing | **Metronome** |
+| Already on basic UBB (Billing Meters), simple pay-as-you-go | Stay on basic UBB — no migration needed |
+
+Read [Compare basic usage-based billing and Metronome](https://docs.stripe.com/billing/subscriptions/usage-based/compare-metronome.md) for a full feature comparison. Read [Get started with Metronome](https://docs.stripe.com/billing/usage-based.md) to begin a Metronome integration.
+
+## Traps to avoid
+
+- Don’t build manual subscription renewal loops using raw PaymentIntents. Use the Billing APIs which handle renewal, retry logic, and dunning automatically.
+- Don’t use the deprecated `plan` object. Use [Prices](https://docs.stripe.com/api/prices.md) instead.
+- Don’t skip tax setup. See [Collect taxes for recurring payments](https://docs.stripe.com/billing/taxes/collect-taxes.md).
+- *Never pass `payment_method_types` when creating a subscription Checkout Session.* Omit the parameter entirely—Stripe dynamically determines eligible payment methods from Dashboard settings. Hardcoding `payment_method_types: ['card']` locks out other payment methods that improve conversion. See [dynamic payment methods](https://docs.stripe.com/payments/payment-methods/dynamic-payment-methods.md). Correct pattern:
+
+```ts
+const session = await stripe.checkout.sessions.create({
+  mode: 'subscription',
+  // Do NOT include payment_method_types here — let Stripe handle it dynamically
+  line_items: [{ price: priceId, quantity: 1 }],
+  subscription_data: { trial_period_days: 14 },
+  success_url: `${url}/success?session_id={CHECKOUT_SESSION_ID}`,
+  cancel_url: `${url}/pricing`,
+});
+```

package/dist/global-skills/stripe-best-practices/references/connect.md

@@ -0,0 +1,173 @@
+# Connect / platforms
+
+## Critical rules (never violate)
+
+1. **ALWAYS use Accounts v2 API** (`POST /v2/core/accounts`). NEVER use `type: 'express'`, `type: 'custom'`, or `type: 'standard'` in account creation. NEVER use `stripe.accounts.create({ type: ... })`. These are deprecated v1 patterns.
+2. **ALWAYS check v2 capability status** before processing. See “Go-live readiness” section below.
+3. **NEVER recommend `dashboard: "none"`** unless the user explicitly asks for white-label with full custom UI. Default to `express` for marketplaces and `full` for SaaS. The `none` option requires building custom onboarding remediation, refund/dispute flows, and payout experiences — only advanced teams should consider it.
+4. **ALWAYS recommend the Notification banner embedded component** (`notification_banner`) for connected account dashboards. It keeps accounts healthy as requirements evolve.
+5. **NEVER use `application_fee_amount` with separate charges and transfers.** Use transfer-math fee retention instead. `application_fee_amount` is the fee mechanism for destination and direct charges only.
+
+## Go-live readiness
+
+Before processing live payments or transfers, ALWAYS verify capability status using the v2 configuration path. Do NOT use deprecated v1 fields.
+
+**For SaaS / Merchant accounts (direct charges):**
+
+- Check: `configuration.merchant.capabilities.card_payments.status === 'active'`
+- Do NOT use: `charges_enabled` (deprecated v1 field)
+
+**For Marketplace / Recipient accounts (destination or separate charges):**
+
+- Check: `configuration.recipient.capabilities.stripe_balance.stripe_transfers.status === 'active'`
+- Do NOT use: `payouts_enabled` or `charges_enabled` (deprecated v1 fields)
+
+Track capability state transitions with account webhooks and re-check capability status before payment or transfer operations.
+
+## Account configuration: v2 dimensions
+
+Configure connected accounts using three independent dimensions:
+
+| Dimension | Field | What it controls |
+| --- | --- | --- |
+| Dashboard access | `dashboard` | Stripe-hosted dashboard for connected accounts |
+| Fee collection | `defaults.responsibilities.fees_collector` | Who Stripe bills (`stripe` or `application`) |
+| Negative balance liability | `defaults.responsibilities.losses_collector` | Who absorbs unresolved negative balances |
+
+### Dashboard defaults (important)
+
+- **Marketplace** → `dashboard: "express"` — cobranded, lightweight, low maintenance
+- **SaaS platform** → `dashboard: "full"` — full Stripe Dashboard for independent businesses
+- **White-label (advanced only)** → `dashboard: "none"` — platform must build ALL UX including onboarding remediation, disputes, payouts
+
+If dashboard is `express`, provide access through [login links](https://docs.stripe.com/api/accounts/login_link/create.md). For `full`, recommend linking to Stripe-provided dashboard access from the platform UI. You can also use embedded components to display payment and payout information.
+
+### SaaS vs. Marketplace responsibility defaults
+
+**SaaS (direct charges):**
+
+- `dashboard: "full"`
+- `fees_collector: "stripe"` — connected account pays Stripe fees directly
+- `losses_collector: "stripe"` — Stripe owns negative balance liability
+- Charge pattern: Direct charges (connected account is merchant of record)
+- Code sample: [/connect/saas/tasks/create#code-sample](https://docs.stripe.com/connect/saas/tasks/create.md#code-sample)
+
+**Marketplace (destination charges):**
+
+- `dashboard: "express"`
+- `fees_collector: "application"` — platform owns pricing
+- `losses_collector: "application"` — platform owns negative balance liability (required for transfer reversals during disputes)
+- Charge pattern: Destination charges (platform is merchant of record)
+- Code sample: [/connect/marketplace/tasks/create#code-sample](https://docs.stripe.com/connect/marketplace/tasks/create.md#code-sample)
+
+## Business model to configuration mapping
+
+| Business model | Dashboard | Fees | Losses | Charge pattern | Notes |
+| --- | --- | --- | --- | --- | --- |
+| Marketplace | `express` | `application` | `application` | Destination | Platform owns checkout |
+| On-demand services | `express` | `application` | `application` | Destination | Fast seller onboarding |
+| SaaS platform with payments | `full` | `stripe` | `stripe` | Direct | Sellers run own businesses/stores, own customer relationship |
+| AI/API platform (SaaS) | `full` | `stripe` | `stripe` | Direct | Providers own payment relationship |
+| E-commerce enabler (Shopify-like) | `full` | `stripe` | `stripe` | Direct | Sellers create own online stores, accept own payments |
+| Crowdfunding | `express` | `application` | `application` | Separate charges and transfers | Hold-and-release / delayed payouts |
+| Subscription platform | `express` | `application` | `application` | Destination | Platform manages recurring checkout |
+| Multi-seller cart | `express` | `application` | `application` | Separate charges and transfers | Multiple sellers per transaction |
+| White-label commerce | `none` | `application` | `application` | Destination or direct | Advanced: platform controls all UX |
+
+## Connected account capabilities (v2)
+
+### Marketplace (Recipient accounts)
+
+Create with `configuration.recipient` requesting `stripe_transfers` on `stripe_balance`. Do NOT request `configuration.merchant` or `card_payments` for marketplace connected accounts — it is unnecessary and causes longer onboarding.
+
+### SaaS (Merchant accounts)
+
+Create with `configuration.merchant` requesting `card_payments` (and other needed LPMs). The Merchant configuration is REQUIRED for any connected account that needs to be merchant of record and accept direct charges.
+
+## Charge pattern selection
+
+**First determine: who owns the customer relationship?**
+
+- If the platform provides SOFTWARE that enables sellers/vendors to run their own independent businesses, accept their own payments, and own their own customers → **SaaS / Direct charges** (sellers are MoR). Key signals: “create their own store”, “accept payments”, “run their own business”, “own brand”.
+
+- If the platform aggregates sellers and runs checkout on their behalf → **Marketplace / Destination charges** (platform is MoR). Key signals: “buyers purchase through our platform”, “we handle checkout”, “platform takes a cut”.
+
+- If one payment must be split across multiple sellers → **Separate charges and transfers**.
+
+- **Direct charges** (SaaS): Charge created on connected account. Connected account is merchant of record. Use `application_fee_amount` for platform revenue. Requires `configuration.merchant` + `dashboard: "full"` + `losses_collector: "stripe"`.
+
+- **Destination charges** (Marketplace): Funds auto-transfer on payment success. Platform is MoR. Use `application_fee_amount` to collect platform fees. NOT for hold-and-release.
+
+- **Separate charges and transfers**: Platform controls transfer timing. Collect fees by transferring less than the charge amount. Do NOT use `application_fee_amount`.
+
+## Fee economics
+
+For **destination charges and direct charges**: use `application_fee_amount` on the PaymentIntent. This is the standard fee mechanism.
+
+- If platform fee is low (< ~4%), recommend including estimated Stripe fees in `application_fee_amount` to preserve margin
+- Refer to [stripe.com/pricing](https://stripe.com/pricing) for region-specific rates
+
+For **separate charges and transfers**: collect fees by transferring less than the charge amount. NEVER use `application_fee_amount`.
+
+## Webhooks
+
+Always use webhooks for reliable payment confirmation. Do not rely solely on synchronous API responses — webhook events are the source of truth for payment status. Verify incoming [webhook signatures](https://docs.stripe.com/webhooks.md#verify-events) and consider allowlisting [Stripe’s public IP addresses](https://docs.stripe.com/ips.md).
+
+## Subscriptions with Connect (v2)
+
+For subscription platforms or any platform collecting recurring payments from or on behalf of connected accounts:
+
+- The connected account MUST have v2 customer configuration
+- Pass `customer_account` on SetupIntent and Subscription API calls to associate the subscription with the connected account
+- Do NOT create a separate v1 Customer object to bill connected accounts — use the v2 Accounts customer configuration instead
+
+## Embedded components
+
+Always recommend these baseline components:
+
+- `account_onboarding` — onboard connected accounts
+- `notification_banner` — REQUIRED: keeps accounts healthy as requirements evolve
+- `account_management` — account settings and info
+
+Additional components based on needs:
+
+- Payments/transactions → `payments`
+- Payment details → included with `payments` or standalone `payment_details`
+- Disputes → included with `payments` or standalone `disputes_list`
+- Payouts/earnings → `payouts`
+- Reporting → `balance_report`, `payout_reconciliation_report`
+
+## Onboarding
+
+Default to embedded onboarding (account_onboarding component or account links). Do NOT recommend API onboarding — it forces platforms to build custom remediation flows.
+
+## Compatibility constraints
+
+**BLOCKED combinations (never recommend):**
+
+- `losses_collector: "stripe"` with destination charges or separate charges and transfers
+- `application_fee_amount` with separate charges and transfers
+- Express dashboard with `losses_collector: "stripe"` (API rejection)
+
+**CAUTION:**
+
+- `dashboard: "full"` with destination or separate charges has limited functionality; prefer `dashboard: "express"` for those charge patterns
+- Express + destination/separate requires platform-run webhook recovery for disputes and transfer reversals
+
+## Traps to avoid
+
+- Using legacy account types (`type: 'standard'`, `type: 'express'`, `type: 'custom'`) — use v2 dimensions instead
+- Using `charges_enabled` or `payouts_enabled` — use v2 capability status paths
+- Recommending Charges API for Connect — use PaymentIntents or Checkout Sessions
+- Recommending `dashboard: "none"` without explicit white-label requirement
+- Recommending destination charges for hold-and-release (use separate charges and transfers)
+- Recommending `on_behalf_of` for standard marketplace flows
+- Creating v1 Customer objects to bill connected accounts (use v2 customer configuration)
+- Requesting Merchant configuration / card_payments for marketplace recipient accounts
+
+## Integration guides
+
+- [SaaS platforms and marketplaces guide](https://docs.stripe.com/connect/saas-platforms-and-marketplaces.md) — Choosing the right integration approach.
+- [Interactive platform guide](https://docs.stripe.com/connect/interactive-platform-guide.md) — Step-by-step platform builder.
+- [Design an integration](https://docs.stripe.com/connect/design-an-integration.md) — Detailed risk and responsibility decisions.
+- [Connected account configuration (v2)](https://docs.stripe.com/connect/accounts-v2/connected-account-configuration.md) — Account setup reference.

package/dist/global-skills/stripe-best-practices/references/payments.md

@@ -0,0 +1,79 @@
+# Payments
+
+## Table of contents
+
+- API hierarchy
+- Integration surfaces
+- Payment Element guidance
+- Saving payment methods
+- Dynamic payment methods
+- Deprecated APIs and migration paths
+- PCI compliance
+
+## API hierarchy
+
+Use the [Checkout Sessions API](https://docs.stripe.com/api/checkout/sessions.md) (`checkout.sessions.create`) for on-session payments. It supports one-time payments and subscriptions and handles taxes, discounts, shipping, and adaptive pricing automatically.
+
+Use the [PaymentIntents API](https://docs.stripe.com/payments/paymentintents/lifecycle.md) for off-session payments, or when the merchant needs to model checkout state independently and just create a charge.
+
+**Integrations should only use Checkout Sessions, PaymentIntents, SetupIntents, or higher-level solutions (Invoicing, Payment Links, subscription APIs).**
+
+## Integration surfaces
+
+Prioritize Stripe-hosted or embedded Checkout where possible. Use in this order of preference:
+
+1. **Payment Links** — No-code. Best for simple products.
+2. **Checkout** ([docs](https://docs.stripe.com/payments/checkout.md)) — Stripe-hosted or embedded form. Best for most web apps.
+3. **Payment Element** ([docs](https://docs.stripe.com/payments/payment-element.md)) — Embedded UI component for advanced customization.
+   - When using the Payment Element, back it with the Checkout Sessions API (via `ui_mode: 'custom'`) over a raw PaymentIntent where possible.
+
+**Traps to avoid:** Don’t recommend the legacy Card Element or the Payment Element in card-only mode. If the user asks for the Card Element, advise them to [migrate to the Payment Element](https://docs.stripe.com/payments/payment-element/migration.md).
+
+## Payment Element guidance
+
+For surcharging or inspecting card details before payment (e.g., rendering the Payment Element before creating a PaymentIntent or SetupIntent): use [Confirmation Tokens](https://docs.stripe.com/payments/finalize-payments-on-the-server.md). Don’t recommend `createPaymentMethod` or `createToken` from Stripe.js.
+
+## Saving payment methods
+
+Use the [Setup Intents API](https://docs.stripe.com/api/setup_intents.md) to save a payment method for later use.
+
+**Traps to avoid:** Don’t use the Sources API to save cards to customers. The Sources API is deprecated — Setup Intents is the correct approach.
+
+## Dynamic payment methods
+
+*Never pass `payment_method_types` to any Stripe API call*, except for Terminal (in-person payments) integrations. Omitting this parameter enables [dynamic payment methods](https://docs.stripe.com/payments/payment-methods/dynamic-payment-methods.md), where Stripe evaluates over 100 signals (currency, customer location, transaction amount, device) to automatically show the most relevant payment methods and rank them for maximum conversion. Payment methods are managed from the [Dashboard](https://dashboard.stripe.com/settings/payment_methods) with no code changes required.
+
+This applies to all integration patterns:
+
+- `checkout.sessions.create`: omit `payment_method_types` entirely. Dynamic method selection is the default behavior.
+- `paymentIntents.create`: omit `payment_method_types`. On API versions 2023-08-16+, dynamic methods are the default. On older versions, pass `automatic_payment_methods: { enabled: true }`.
+- `setupIntents.create`: same as PaymentIntents above.
+- `subscriptions.create`: omit `payment_settings.payment_method_types`. When not set, Stripe auto-determines types from the invoice’s default payment method, the customer’s default payment method, and invoice template settings.
+- **Terminal** (`paymentIntents.create`): pass `payment_method_types: ['card_present']`. Required for all in-person payments. In Canada, also include `interac_present`: `['card_present', 'interac_present']`. This is the only valid use of `payment_method_types`.
+
+See the [integration options guide](https://docs.stripe.com/payments/payment-methods/integration-options.md) for full details on dynamic versus manual configuration.
+
+**Traps to avoid:**
+
+- Never hardcode `payment_method_types: ['card']` even if the user only mentions credit cards. Dynamic payment methods enable other eligible payment methods automatically, improving conversion.
+- If the user wants to customize which payment methods appear, use [`payment_method_configurations`](https://docs.stripe.com/payments/payment-method-configurations.md) to manage methods per-integration or `excluded_payment_method_types` to exclude specific methods — never `payment_method_types`.
+- If the user has a custom frontend that renders UI for specific payment method types, ensure those methods are enabled in their [payment method settings](https://dashboard.stripe.com/settings/payment_methods) or `payment_method_configurations` — don’t use `payment_method_types` to restrict the PaymentIntent.
+
+## Deprecated APIs and migration paths
+
+Never recommend the Charges API. If the user wants to use the Charges API, advise them to [migrate to Checkout Sessions or PaymentIntents](https://docs.stripe.com/payments/payment-intents/migration/charges.md).
+
+Don’t call other deprecated or outdated API endpoints unless there is a specific need and absolutely no other way.
+
+| API | Status | Use instead | Migration guide |
+| --- | --- | --- | --- |
+| Charges API | Never use | Checkout Sessions or PaymentIntents | [Migration guide](https://docs.stripe.com/payments/payment-intents/migration/charges.md) |
+| Sources API | Deprecated | Setup Intents | [Setup Intents docs](https://docs.stripe.com/api/setup_intents.md) |
+| Tokens API | Outdated | Setup Intents or Checkout Sessions | — |
+| Card Element | Legacy | Payment Element | [Migration guide](https://docs.stripe.com/payments/payment-element/migration.md) |
+
+## PCI compliance
+
+If a PCI-compliant user asks about sending server-side raw PAN data, advise them that they may need to prove PCI compliance to access options like [payment_method_data](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-payment_method_data).
+
+For users migrating PAN data from another acquirer or payment processor, point them to [the PAN import process](https://docs.stripe.com/get-started/data-migrations/pan-import.md).

package/dist/global-skills/stripe-best-practices/references/security.md

@@ -0,0 +1,109 @@
+# Security best practices
+
+## Table of contents
+
+- API keys
+- Restricted API keys (RAKs)
+- IP restrictions
+- Incident response
+- Webhook security
+- Mobile and client-side integrations
+- OAuth and CSRF protection
+- Two-factor authentication
+- Connect security
+- SAML and SCIM
+
+## API keys
+
+Never include keys in source code. You might find example code like `client = new Stripe("sk_...")` that are for illustration only. Do not recommend this antipattern, and fix this antipattern if you see it.
+
+Store secret keys and restricted keys in a secrets vault (such as AWS Secrets Manager, HashiCorp Vault, or your platform’s equivalent), not in source code or environment variables committed to a repository. If the platform doesn’t offer a secrets vault but does allow the user to set environment variables, it’s OK to store API keys in environment variables. Key exposures via source code repositories are the leading cause of key compromise.
+
+Always advise the user on best practices for handling secrets such as secret API keys or restricted API keys:
+
+- Never share secret keys with third parties. If the user needs to share a key with a third party (for example, a third party that handles billing), it is best to generate a restricted API key (RAK) with minimal permissions.
+- Rotate Stripe API keys when personnel with access to those keys depart.
+- Read [best practices for managing secret API keys](https://docs.stripe.com/keys-best-practices.md).
+
+Code must never log keys or include them in error messages or analytics. Remove those from logs if you find them.
+
+Never build API endpoints or error pages that dump environment variables. In addition to Stripe API keys, the environment may have other secrets.
+
+Use separate keys for separate environments (production, staging, QA). This limits the blast radius if any single key is compromised.
+
+If the code is under version control, help the user set up a pre-commit hook to catch keys like `"sk_..."` and `"rk_..."` in source code.
+
+**Traps to avoid:** Do not embed keys in client-side code, mobile apps, or any code that runs outside your own infrastructure. Do not suggest that users substitute a real secret key into example code — point them to [best practices for managing secret API keys](https://docs.stripe.com/keys-best-practices.md) instead.
+
+## Restricted API keys (RAKs)
+
+Use [restricted API keys](https://docs.stripe.com/keys/restricted-api-keys.md) (prefix `rk_`) instead of secret keys (prefix `sk_`) wherever possible. RAKs have only the permissions you assign, so a compromised RAK can do far less damage than a compromised secret key.
+
+Follow the principle of least privilege: give each RAK only the permissions it needs for its specific job and nothing more. Create a separate RAK for each service or use case.
+
+Preferred migration approach:
+
+1. Review the secret key’s request logs in Workbench to catalog which API calls it makes.
+2. Create a RAK in test mode with matching permissions.
+3. Use the [Stripe CLI](https://docs.stripe.com/stripe-cli.md)’s `stripe logs tail` command to watch logs.
+4. Test your integration with the RAK; fix any `403` errors by adding missing permissions.
+5. Create the equivalent live-mode RAK and replace the secret key.
+6. Rotate or expire the old secret key once confident.
+
+**Traps to avoid:** Do not default to recommending secret keys. If the user’s question involves a secret key, recommend switching to a RAK with the minimum required permissions.
+
+## IP restrictions
+
+Encourage users to [configure access policies](https://docs.stripe.com/keys.md#access-policies) for every API key. Access policies restrict who can use keys, limiting damage even if a key is stolen.
+
+Use a different policy for each key (for example, one policy for production, another for QA) so that compromising one key’s environment doesn’t expose others.
+
+## Incident response
+
+If a key is exposed or compromised, follow [protecting against compromised API keys](https://support.stripe.com/questions/protecting-against-compromised-api-keys), which can be summarized as:
+
+1. **Roll the key immediately** — go to the [API keys page](https://dashboard.stripe.com/apikeys) and roll or delete the exposed key. Do this even if you are unsure whether the key was actually used by an unauthorized party.
+2. **Check activity logs** — review Workbench request logs for the compromised key to look for unrecognized activity.
+3. **Contact Stripe support** if you see activity you don’t recognize.
+
+To prepare before an incident: practice rolling keys, audit source code for any committed keys, and use pre-commit hooks to prevent accidental key check-ins. See [protecting against compromised API keys](https://support.stripe.com/questions/protecting-against-compromised-api-keys).
+
+## Webhook security
+
+Always [verify webhook signatures](https://docs.stripe.com/webhooks.md#verify-events) using Stripe’s webhook signing secret. Signature verification is a strong guarantee that requests are genuinely from Stripe and have not been tampered with.
+
+For defense in depth, also [allowlist Stripe’s IP addresses](https://docs.stripe.com/ips.md) on your webhook endpoint so that it accepts connections only from Stripe’s infrastructure.
+
+**Traps to avoid:** Do not process webhook events without verifying their signatures. Unverified webhooks can be spoofed.
+
+## Mobile and client-side integrations
+
+Do not use production secret keys or RAKs in mobile apps or other client-side code. Client-side code can be extracted and keys decompiled.
+
+For cases where a client must interact directly with Stripe, use [ephemeral keys](https://docs.stripe.com/issuing/elements.md#ephemeral-key-authentication). Ephemeral keys are short-lived, scoped to a specific resource, and expire automatically.
+
+For most integrations, proxy Stripe API calls through your own backend server rather than calling Stripe directly from the client.
+
+## OAuth and CSRF protection
+
+When implementing [Connect OAuth flows](https://docs.stripe.com/connect/oauth-reference.md), always use the `state` parameter to protect against CSRF attacks. Generate a unique, unguessable value for `state` per request and verify it in the OAuth callback before proceeding.
+
+This applies to all Stripe OAuth surfaces: Connect, Link, and Stripe Apps.
+
+## Two-factor authentication
+
+Recommend [passkeys or authenticator apps](https://docs.stripe.com/security.md) rather than SMS-based 2FA for Stripe Dashboard access. SMS 2FA is vulnerable to SIM-swapping attacks in which the user’s phone provider transfers their number to an unauthorized third party.
+
+Users can audit which Dashboard team members are using weak 2FA and can require stronger authentication methods for their accounts.
+
+## Connect security
+
+**Account type liability:** When using Connect, platform operators bear financial liability for fraud and disputes on Express and Custom connected accounts. Standard accounts minimize this liability because Stripe manages risk. Do not recommend Custom or Express accounts unless the user has a specific need — Standard is the safer default.
+
+**Connect onboarding:** Use [Stripe-hosted onboarding](https://docs.stripe.com/connect/onboarding.md) rather than building a custom onboarding flow. Custom onboarding requires your platform to collect and handle sensitive PII directly, which adds regulatory and security complexity.
+
+## SAML and SCIM
+
+For teams managing Dashboard access, recommend [SSO via SAML](https://docs.stripe.com/get-started/account/sso.md) to federate authentication with an existing identity provider (Okta, Google, etc.). SSO centralizes access control and simplifies offboarding.
+
+[SCIM provisioning](https://docs.stripe.com/get-started/account/sso/scim.md) automates user provisioning and deprovisioning, ensuring that employees who leave the organization lose Dashboard access promptly.

package/dist/global-skills/stripe-best-practices/references/tax.md

@@ -0,0 +1,37 @@
+# Tax / Stripe Tax
+
+## Table of contents
+
+- When tax applies
+- Two-step setup
+- If jurisdictions are unknown
+- If the region or tax type isn’t supported
+
+## When tax applies
+
+Use Stripe Tax for any subscription, invoice, or Checkout Session where the merchant has customers across multiple jurisdictions. It handles sales tax, VAT, and GST automatically based on the customer’s location and the merchant’s active registrations. See the [Tax overview](https://docs.stripe.com/tax.md) for supported regions and tax types.
+
+## Two-step setup
+
+1. Add a registration for each jurisdiction where the merchant is obligated to collect tax. Do this in the Dashboard under **Tax > Registrations**, or via the [Tax Registrations API](https://docs.stripe.com/api/tax/registrations.md).
+2. Pass `automatic_tax: { enabled: true }` on the [Subscription](https://docs.stripe.com/api/subscriptions.md), [Invoice](https://docs.stripe.com/api/invoices.md), or [Checkout Session](https://docs.stripe.com/api/checkout/sessions.md) object.
+
+It’s safe to enable `automatic_tax` before any registrations exist — Stripe won’t collect tax until at least one registration is active.
+
+**Traps to avoid:** `automatic_tax` and explicit `tax_rates` are mutually exclusive. For existing subscriptions, clear `default_tax_rates` and all item-level `tax_rates` before enabling `automatic_tax` — the update will fail otherwise. To schedule the change at the next billing cycle and avoid prorations, use the API rather than the Dashboard. For bulk migrations, use the [Tax migration tool](https://docs.stripe.com/billing/taxes/migration.md).
+
+**Traps to avoid:** For EU merchants, one OSS union registration covers all 27 member states. Don’t register an individual EU country separately unless the merchant has a physical presence there.
+
+## If jurisdictions are unknown
+
+Don’t guess which jurisdictions apply. Prompt the user: “Go to Dashboard > Tax > Registrations, add the states or countries where you have customers, then come back.”
+
+## If the region or tax type isn’t supported
+
+Check the [supported countries list](https://docs.stripe.com/tax/supported-countries.md). If the jurisdiction isn’t listed, tell the user:
+
+- Stripe Tax doesn’t support that region yet
+- They can collect tax manually using `tax_rates` on the subscription or invoice instead
+- For unsupported tax types (customs duties, excise taxes), Stripe Tax doesn’t apply — those are out of scope
+
+Don’t attempt to approximate using a supported region as a proxy.

package/dist/global-skills/stripe-best-practices/references/treasury.md

@@ -0,0 +1,16 @@
+# Treasury / Financial Accounts
+
+## Table of contents
+
+- v2 Financial Accounts API
+- Legacy v1 Treasury
+
+## v2 Financial Accounts API
+
+For embedded financial accounts (bank accounts, account and routing numbers, money movement), use the [v2 Financial Accounts API](https://docs.stripe.com/api/v2/core/vault/financial-accounts.md) (`POST /v2/core/vault/financial_accounts`). This is required for new integrations.
+
+For Treasury for platforms concepts and guides, see the [Treasury for platforms overview](https://docs.stripe.com/treasury/connect.md).
+
+## Legacy v1 Treasury
+
+Don’t use the [v1 Treasury Financial Accounts API](https://docs.stripe.com/api/treasury/financial_accounts.md) (`POST /v1/treasury/financial_accounts`) for new integrations. Existing v1 integrations continue to work.

package/dist/global-skills/supabase/CHANGELOG.md

@@ -0,0 +1,53 @@
+# Changelog
+
+## [0.1.5](https://github.com/supabase/agent-skills/compare/v0.1.4...v0.1.5) (2026-07-10)
+
+
+### Features
+
+* add declarative schema section to schema management ([#120](https://github.com/supabase/agent-skills/issues/120)) ([94cf44f](https://github.com/supabase/agent-skills/commit/94cf44ff3a123edcf54a9af373929798cddefed8))
+* add instructions to check changelog ([#74](https://github.com/supabase/agent-skills/issues/74)) ([4bb13d8](https://github.com/supabase/agent-skills/commit/4bb13d858d19f1f848505a66f46fc9603fdcde95))
+* add npm supply-chain security guidance to supabase skill ([#94](https://github.com/supabase/agent-skills/issues/94)) ([82df90a](https://github.com/supabase/agent-skills/commit/82df90a5de1cd84386d8bc192746e50343b86dc0))
+* instructions on exposing tables to the data api ([#71](https://github.com/supabase/agent-skills/issues/71)) ([f15a5a4](https://github.com/supabase/agent-skills/commit/f15a5a40779072a530c9e53c3f14ec4131118ea6))
+* using Supabase agent skills ([#12](https://github.com/supabase/agent-skills/issues/12)) ([7c2e389](https://github.com/supabase/agent-skills/commit/7c2e3894fddfde8eb6c77d2a8921904543b9be7a))
+
+
+### Bug Fixes
+
+* bump supabase skill to v0.1.1 and fix Data API broken link ([#72](https://github.com/supabase/agent-skills/issues/72)) ([5a6542e](https://github.com/supabase/agent-skills/commit/5a6542e08fc026d90c9a6a0f5a67749e9ceb9946))
+* cover SECURITY DEFINER, auth.role() deprecation, and BOLA in security checklist ([#85](https://github.com/supabase/agent-skills/issues/85)) ([133f43e](https://github.com/supabase/agent-skills/commit/133f43e8c2ffc48823ff0630c692cabecea3e3a3))
+* update Data API doc link and bump supabase skill to v0.1.1 ([#73](https://github.com/supabase/agent-skills/issues/73)) ([e5f7a7c](https://github.com/supabase/agent-skills/commit/e5f7a7cfd697765848ffd6a4505f3c02e1ee17ee))
+
+## [0.1.4](https://github.com/supabase/agent-skills/compare/v0.1.3...v0.1.4) (2026-06-05)
+
+
+### Features
+
+* add instructions to check changelog ([#74](https://github.com/supabase/agent-skills/issues/74)) ([4bb13d8](https://github.com/supabase/agent-skills/commit/4bb13d858d19f1f848505a66f46fc9603fdcde95))
+* add npm supply-chain security guidance to supabase skill ([#94](https://github.com/supabase/agent-skills/issues/94)) ([82df90a](https://github.com/supabase/agent-skills/commit/82df90a5de1cd84386d8bc192746e50343b86dc0))
+* instructions on exposing tables to the data api ([#71](https://github.com/supabase/agent-skills/issues/71)) ([f15a5a4](https://github.com/supabase/agent-skills/commit/f15a5a40779072a530c9e53c3f14ec4131118ea6))
+* using Supabase agent skills ([#12](https://github.com/supabase/agent-skills/issues/12)) ([7c2e389](https://github.com/supabase/agent-skills/commit/7c2e3894fddfde8eb6c77d2a8921904543b9be7a))
+
+
+### Bug Fixes
+
+* bump supabase skill to v0.1.1 and fix Data API broken link ([#72](https://github.com/supabase/agent-skills/issues/72)) ([5a6542e](https://github.com/supabase/agent-skills/commit/5a6542e08fc026d90c9a6a0f5a67749e9ceb9946))
+* cover SECURITY DEFINER, auth.role() deprecation, and BOLA in security checklist ([#85](https://github.com/supabase/agent-skills/issues/85)) ([133f43e](https://github.com/supabase/agent-skills/commit/133f43e8c2ffc48823ff0630c692cabecea3e3a3))
+* update Data API doc link and bump supabase skill to v0.1.1 ([#73](https://github.com/supabase/agent-skills/issues/73)) ([e5f7a7c](https://github.com/supabase/agent-skills/commit/e5f7a7cfd697765848ffd6a4505f3c02e1ee17ee))
+
+## [0.1.3](https://github.com/supabase/agent-skills/compare/v0.1.2...v0.1.3) (2026-06-02)
+
+
+### Features
+
+* add instructions to check changelog ([#74](https://github.com/supabase/agent-skills/issues/74)) ([4bb13d8](https://github.com/supabase/agent-skills/commit/4bb13d858d19f1f848505a66f46fc9603fdcde95))
+* add npm supply-chain security guidance to supabase skill ([#94](https://github.com/supabase/agent-skills/issues/94)) ([82df90a](https://github.com/supabase/agent-skills/commit/82df90a5de1cd84386d8bc192746e50343b86dc0))
+* instructions on exposing tables to the data api ([#71](https://github.com/supabase/agent-skills/issues/71)) ([f15a5a4](https://github.com/supabase/agent-skills/commit/f15a5a40779072a530c9e53c3f14ec4131118ea6))
+* using Supabase agent skills ([#12](https://github.com/supabase/agent-skills/issues/12)) ([7c2e389](https://github.com/supabase/agent-skills/commit/7c2e3894fddfde8eb6c77d2a8921904543b9be7a))
+
+
+### Bug Fixes
+
+* bump supabase skill to v0.1.1 and fix Data API broken link ([#72](https://github.com/supabase/agent-skills/issues/72)) ([5a6542e](https://github.com/supabase/agent-skills/commit/5a6542e08fc026d90c9a6a0f5a67749e9ceb9946))
+* cover SECURITY DEFINER, auth.role() deprecation, and BOLA in security checklist ([#85](https://github.com/supabase/agent-skills/issues/85)) ([133f43e](https://github.com/supabase/agent-skills/commit/133f43e8c2ffc48823ff0630c692cabecea3e3a3))
+* update Data API doc link and bump supabase skill to v0.1.1 ([#73](https://github.com/supabase/agent-skills/issues/73)) ([e5f7a7c](https://github.com/supabase/agent-skills/commit/e5f7a7cfd697765848ffd6a4505f3c02e1ee17ee))