codebyplan 1.13.48 → 1.13.49

package/dist/cli.js

@@ -39,7 +39,7 @@ var VERSION, PACKAGE_NAME;
 var init_version = __esm({
   "src/lib/version.ts"() {
     "use strict";
-    VERSION = "1.13.48";
+    VERSION = "1.13.49";
     PACKAGE_NAME = "codebyplan";
   }
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codebyplan",
-  "version": "1.13.48",
+  "version": "1.13.49",
   "description": "CLI for CodeByPlan — AI-powered development planning and tracking",
   "type": "module",
   "bin": {

package/templates/agents/cbp-round-executor.md

@@ -315,6 +315,7 @@ When the approved plan includes specialized work, delegate to sub-executor agent
 | Work Type | Agent | When to Delegate |
 |-----------|-------|-----------------|
 | Supabase migrations, RLS, types | `cbp-database-agent` | Plan includes DB schema changes, RLS policies, or type generation |
+| Stripe integration (Checkout, webhooks, subscriptions, customer portal) | `cbp-stripe-agent` | Plan includes Stripe work (files under `stripe/`, or steps referencing `payment`, `checkout`, `webhook`, `subscription`, or `approved_plan.stripe_work === true`) |
 | Batch identical-structure file writes (≥4 files) | `general-purpose` (background) | Plan has 4+ independent files, no shared state, no ordered dependency |
 | `.claude/` infrastructure deliverables | `cbp-cc-executor` | `files_to_modify[]` includes **≥2** `.claude/` files (rules, skills, agents, context, hooks, settings, CLAUDE.md). A single `.claude/` file edit stays on Step 0 Skill-tool routing |
 
@@ -324,6 +325,12 @@ When the approved plan includes specialized work, delegate to sub-executor agent
 3. Wait for completion, merge files_changed into executor output
 4. Continue with remaining non-DB steps
 
+**How to delegate to `cbp-stripe-agent`:**
+1. Collect all Stripe-related steps from the plan
+2. Spawn `cbp-stripe-agent` via Agent tool with those steps and `files_changed_scope` set to the executor's current `files_to_modify[]` paths
+3. Wait for completion, merge files_changed into executor output
+4. Continue with remaining non-Stripe steps
+
 **When NOT to delegate:**
 - Simple Supabase queries in application code (executor handles these)
 - Only delegate schema/migration/RLS/type generation work

package/templates/agents/cbp-stripe-agent.md

@@ -0,0 +1,173 @@
+---
+scope: org-shared
+name: cbp-stripe-agent
+description: Stripe integration specialist. Writes Stripe code (Checkout, webhooks, subscriptions, customer portal) in the consuming app and optionally drives live Stripe via MCP. Spawned as sub-executor by round-executor when the plan includes Stripe work.
+tools: Read, Write, Edit, Glob, Grep, Bash, AskUserQuestion
+model: sonnet
+effort: xhigh
+---
+
+# Stripe Agent
+
+Stripe integration specialist for payments, billing, webhooks, Connect, Tax, and Treasury.
+
+## Purpose
+
+Handles Stripe integration work when a round's plan includes payment code. Spawned by
+round-executor as a sub-executor, not directly by `/cbp-round-start`. Two operating modes:
+
+- **Primary (always)** — writes/modifies Stripe integration code in the consuming app using
+  the current Stripe Node SDK, guided by the `cbp-stripe` skill's API-selection routing.
+- **Optional (opt-in)** — when a Stripe MCP server is configured AND a restricted/test key is
+  present, scaffolds live test data (products, prices, payment links) via that server. Absent
+  either, it degrades silently to code-only — never a hard failure.
+
+## Input Contract
+
+```yaml
+input:
+  stripe_tasks: [{step_number, description, type}]  # Stripe-related plan steps
+  files_changed_scope: string[]                     # paths the round is allowed to touch
+  repo_id: string
+  context:
+    checkpoint_goal: string
+    task_requirements: string
+```
+
+## Output Contract
+
+```yaml
+output:
+  status: 'completed' | 'blocked' | 'failed'
+  live_path_used: boolean                # true only when the optional MCP path ran
+  files_changed:
+    - path: string
+      action: 'created' | 'modified' | 'deleted'
+  stripe_resources_created:              # populated only when live_path_used === true
+    - type: string                       # e.g. 'product' | 'price' | 'payment_link'
+      id: string
+      mode: 'test'                       # ALWAYS test — live mode is never scaffolded here
+  issues_encountered: string[]
+```
+
+## Workflow
+
+### Pre-flight: Load Guidance + Resolve Live-Path Availability
+
+Run both checks before writing any code:
+
+1. **Load the `cbp-stripe` skill** for API-selection routing and security rules. Invoke the
+   `cbp-stripe` Skill (or Read `.claude/skills/cbp-stripe/SKILL.md` and the relevant
+   `reference/*.md` when Skill dispatch is unavailable). This is the source of truth for
+   which Stripe API to use per intent — do not select APIs from memory.
+
+2. **Resolve live-path availability.** The optional MCP path runs ONLY when ALL hold:
+   - `STRIPE_SECRET_KEY` (or an equivalent restricted-key env var) is present AND is a
+     **test-mode** key. Check presence + prefix WITHOUT printing the secret (never `echo` or
+     `printenv` the raw value):
+
+     ```bash
+     case "${STRIPE_SECRET_KEY:-}" in
+       sk_test_*|rk_test_*) echo "live path: eligible (test key)" ;;
+       sk_live_*|rk_live_*) echo "live path: refused (live-mode key)" ;;
+       "")                  echo "live path: skipped (no key)" ;;
+       *)                   echo "live path: refused (unknown prefix ${STRIPE_SECRET_KEY:0:8})" ;;
+     esac
+     ```
+
+     Only `sk_test_`/`rk_test_` enable the live path; live-mode keys (`sk_live_`, `rk_live_`)
+     are refused so a dev round never scaffolds real Stripe data.
+   - A Stripe MCP server is reachable. Stripe MCP tools (`mcp__stripe__*`) are NOT listed in
+     this agent's frontmatter because the server is optional and absent by default; discover
+     them at runtime via `ToolSearch` (query `mcp__stripe`). Setup is documented in
+     `.claude/skills/cbp-stripe/reference/stripe-mcp-setup.md`.
+
+   If any condition fails, set `live_path_used = false` and proceed code-only. Record the
+   reason in `issues_encountered[]` (e.g. `live path skipped: no STRIPE_SECRET_KEY`). This is
+   a normal outcome, NOT a block.
+
+### Step 1: Analyze Stripe Tasks
+
+Read `stripe_tasks` and categorize by type, mapping each to the `cbp-stripe` routing table:
+
+- **One-time payments** → Checkout Sessions (`reference/payments.md`)
+- **Custom payment UI** → Checkout Sessions + Payment Element (`reference/payments.md`)
+- **Saving a payment method** → Setup Intents (`reference/payments.md`)
+- **Subscriptions / recurring billing** → Billing APIs + Checkout Sessions, Customer Portal
+  (`reference/billing.md`)
+- **Webhooks** → signed event handler (`reference/security.md`)
+- **Marketplace / platform** → Connect Accounts v2 (`reference/connect.md`)
+- **Tax** → Stripe Tax (`reference/tax.md`); **embedded finance** → Treasury
+  (`reference/treasury.md`)
+
+### Step 2: Write Stripe Integration Code (PRIMARY)
+
+For each task, write or modify code in `files_changed_scope` using the current Stripe Node SDK:
+
+1. **Honor the critical rules from the skill**: never pass `payment_method_types` except for
+   the documented Terminal and Treasury-bank-account exceptions; prefer dynamic payment
+   methods.
+2. **Server-side key handling**: read the key from `process.env` only; never hardcode or log
+   it. Prefer a restricted key (`rk_`) over a secret key.
+3. **Next.js API routes that import `stripe` MUST export `export const dynamic =
+   'force-dynamic'`** at the top of the file (the SDK reads a runtime env var; static analysis
+   at build time fails without it). Source: `.claude/skills/cbp-frontend-design/reference/nextjs-scss.md`
+   Rule 6.
+4. **Webhook routes** must verify the signature with `stripe.webhooks.constructEvent(rawBody,
+   sig, secret)` against the raw (unparsed) body, and guard the `stripe-signature` header
+   (it is typed `string | string[] | undefined`) before use.
+5. Match the consuming app's existing conventions (error handling, response shape, file
+   layout). Verify the installed `stripe` major version (`grep '"stripe"' package.json`) and
+   write code for that version — the skill notes the latest API version, but consumer repos
+   may pin an older SDK.
+
+### Step 3: Scaffold Live Test Data (OPTIONAL — only when Pre-flight enabled the live path)
+
+When `live_path_used` is eligible AND a task explicitly needs live test data (e.g. "create a
+test product + price for the checkout demo"):
+
+1. Re-confirm the key prefix is `sk_test_` or `rk_test_` immediately before the first call.
+   Abort the live path on any live-mode key (`sk_live_` or `rk_live_`).
+2. Use the discovered Stripe MCP tools to create only what the task requires (products,
+   prices, payment links, test customers). Record each in `stripe_resources_created[]`.
+3. On ANY MCP error (server unreachable, auth rejected, rate limit), fall back to code-only:
+   set `live_path_used = false`, record the error in `issues_encountered[]`, and continue —
+   never block the round on the optional path.
+
+### Step 4: Verify
+
+1. For each changed `.ts`/`.tsx` file, run a scoped `npx tsc --noEmit` (or the app's
+   typecheck) on the changed set and confirm no new type errors.
+2. Confirm every API route importing `stripe` exports `dynamic = 'force-dynamic'`
+   (`grep -L "force-dynamic"` across the changed route files).
+3. Confirm no secret was committed: `grep -rE 'sk_live_|rk_live_|sk_test_[A-Za-z0-9]{16,}|rk_test_[A-Za-z0-9]{16,}'`
+   over the changed files returns nothing real. Live-key prefixes (`sk_live_`, `rk_live_`)
+   match with no length floor — a committed live key is never acceptable; test-key prefixes
+   carry a `{16,}` floor so doc placeholders like `sk_test_…` don't false-positive.
+
+### Step 5: Return Output
+
+Populate all output-contract fields. Include every file changed. Report the live-path outcome
+(used / skipped + reason) in `issues_encountered[]` for the audit trail.
+
+## When NOT to Use This Agent
+
+- Non-payment application code (round-executor handles these).
+- Reading Stripe data for display only with no integration change.
+- Designing the payment UX/visual layer — that is the frontend skills' job; this agent writes
+  the Stripe wiring beneath it.
+- Production / live-mode Stripe operations (`sk_live_`, `rk_live_`) — this agent refuses
+  live-mode keys by design; only test-mode keys enable the optional live path.
+
+## Integration
+
+- **Spawned by**: `round-executor` (as sub-executor when the plan includes Stripe work — see
+  `cbp-round-executor` Step 3.5 and `/cbp-round-execute` Step 3b-stripe dispatch).
+- **Returns to**: `round-executor` (merges `files_changed[]` into the round output).
+- **Loads**: the `cbp-stripe` skill (`.claude/skills/cbp-stripe/SKILL.md` + `reference/*.md`)
+  for API selection and security rules.
+- **Optional tools**: Stripe MCP (`mcp__stripe__*`) discovered at runtime via `ToolSearch`
+  when a server is configured per `.claude/skills/cbp-stripe/reference/stripe-mcp-setup.md` —
+  intentionally absent from frontmatter because the server is opt-in.
+- **Rule**: never commit Stripe secrets; restricted/test keys only; degrade to code-only when
+  the live path is unavailable.

package/templates/settings.project.base.json

@@ -68,6 +68,18 @@
       "mcp__codebyplan__delete_session_log",
       "mcp__codebyplan__delete_worktree",
       "mcp__codebyplan__release_assignment",
+      "mcp__stripe__create_customer",
+      "mcp__stripe__create_product",
+      "mcp__stripe__create_price",
+      "mcp__stripe__create_payment_link",
+      "mcp__stripe__create_invoice",
+      "mcp__stripe__create_subscription",
+      "mcp__stripe__update_subscription",
+      "mcp__stripe__create_refund",
+      "mcp__stripe__list_customers",
+      "mcp__stripe__list_products",
+      "mcp__stripe__list_prices",
+      "mcp__stripe__list_invoices",
       "Bash(codebyplan setup:*)",
       "Bash(npx codebyplan setup:*)",
       "Bash(codebyplan create-org:*)",
@@ -127,6 +139,7 @@
       "Skill(cbp-ship-configure)",
       "Skill(cbp-standalone-task-check)",
       "Skill(cbp-standalone-task-testing)",
+      "Skill(cbp-stripe)",
       "Skill(cbp-supabase-branch-check)",
       "Skill(cbp-supabase-migrate)",
       "Skill(cbp-supabase-setup)",

package/templates/skills/cbp-round-execute/SKILL.md

@@ -118,6 +118,14 @@ If the approved plan includes database schema changes, RLS policies, or type gen
 2. Wait for completion
 3. Merge `files_changed` into executor output
 
+### Step 3b-stripe: Stripe Work (if plan includes Stripe integration)
+
+If the approved plan includes Stripe integration work (files under `stripe/`, or plan steps referencing `payment`, `checkout`, `webhook`, `subscription`, or an explicit `stripe_work: true` flag from the planner):
+
+1. Spawn `cbp-stripe-agent` with Stripe-related steps from the plan and `files_changed_scope` from the executor output
+2. Wait for completion
+3. Merge `files_changed` into executor output
+
 ### Step 3c: Completion Check
 
 - `status: 'completed'` and all deliverables done → proceed to Step 4
@@ -228,7 +236,7 @@ Trigger `/cbp-round-end`.
 
 - **Reads**: `.codebyplan/state/checkpoints/<id>/tasks/<id>.json`, `checkpoints/<id>/tasks/<id>/rounds/<id>.json` (local-first; `npx codebyplan sync` on miss; MCP `get_current_task` / `get_rounds` as break-glass)
 - **Writes**: `codebyplan round update --id <uuid> --task-id <uuid> --checkpoint-id <uuid>` (Steps 6+7 — context with executor_output + testing_qa_output + e2e_eligible + e2e_outputs + frontend_ui_review; break-glass: MCP `update_round`)
-- **Spawns**: `cbp-round-executor` (per wave or single), `cbp-testing-qa-agent` (per wave, parallel sibling of the `cbp-e2e-*` specialists), the `cbp-e2e-*` specialists (config-driven dispatch per `context/testing/e2e.md`, one per eligible framework in `.codebyplan/e2e.json`), `cbp-database-agent` (if DB work), `cbp-security-agent` (if security review needed)
+- **Spawns**: `cbp-round-executor` (per wave or single), `cbp-testing-qa-agent` (per wave, parallel sibling of the `cbp-e2e-*` specialists), the `cbp-e2e-*` specialists (config-driven dispatch per `context/testing/e2e.md`, one per eligible framework in `.codebyplan/e2e.json`), `cbp-database-agent` (if DB work), `cbp-stripe-agent` (if Stripe work), `cbp-security-agent` (if security review needed)
 - **Skill invocations**: `cbp-frontend-ui` at Step 5b with `phase: 'screenshot_review'` (post-e2e)
 - **Triggers**: `/cbp-round-end` (auto)
 - **Triggered by**: `/cbp-round-start` (auto, after plan approval)

package/templates/skills/cbp-stripe/SKILL.md

@@ -0,0 +1,116 @@
+---
+scope: org-shared
+name: cbp-stripe
+description: "Stripe integration guidance — load when implementing or reviewing payments, Checkout, subscriptions/billing, webhooks, Connect, Tax, or Treasury. Encodes the API-selection routing table, the no-payment_method_types rule, restricted-key security, and Stripe SDK conventions."
+effort: xhigh
+---
+
+# Stripe Integration (CBP)
+
+Load this skill before writing or reviewing any Stripe integration code — accepting payments,
+Checkout Sessions, subscriptions, webhooks, marketplaces (Connect), tax compliance, or
+embedded financial accounts (Treasury). It encodes Stripe's current recommended API surface,
+the critical `payment_method_types` prohibition, and CBP-specific conventions.
+
+## Integration routing table
+
+| Building…                                     | Recommended API                     | Reference                         |
+| --------------------------------------------- | ----------------------------------- | --------------------------------- |
+| One-time payments                             | Checkout Sessions                   | [reference/payments.md](reference/payments.md) |
+| Custom payment form with embedded UI          | Checkout Sessions + Payment Element | [reference/payments.md](reference/payments.md) |
+| Saving a payment method for later             | Setup Intents                       | [reference/payments.md](reference/payments.md) |
+| Connect platform or marketplace               | Accounts v2 (`/v2/core/accounts`)   | [reference/connect.md](reference/connect.md)   |
+| Subscriptions or recurring billing            | Billing APIs + Checkout Sessions    | [reference/billing.md](reference/billing.md)   |
+| Sales tax, VAT, or GST compliance             | Stripe Tax + Registrations API      | [reference/tax.md](reference/tax.md)           |
+| Embedded financial accounts / banking         | v2 Financial Accounts               | [reference/treasury.md](reference/treasury.md) |
+| Security (keys, webhooks, OAuth, Connect risk)| Restricted keys + sig verification  | [reference/security.md](reference/security.md) |
+
+Read the relevant reference file before answering any integration question or writing code.
+
+## Critical rules
+
+### Never include `payment_method_types` (except Terminal)
+
+Never pass `payment_method_types` in any Stripe API call. There are two narrow exceptions:
+- **Terminal** (in-person): `payment_method_types: ['card_present']` (Canada: add `'interac_present'`).
+- **Treasury bank-account Setup Intents**: `payment_method_types: ['us_bank_account']` with
+  `flow_directions: ['outbound']` (see [reference/treasury.md](reference/treasury.md)).
+
+Outside those, omit the parameter to enable dynamic payment methods — Stripe evaluates
+100+ signals to surface the most relevant methods and manage them from the Dashboard
+without code changes.
+
+This applies to ALL call sites:
+- `checkout.sessions.create` — omit entirely
+- `paymentIntents.create` — omit; on API versions before 2023-08-16 pass
+  `automatic_payment_methods: { enabled: true }` instead
+- `setupIntents.create` — same as PaymentIntents
+- `subscriptions.create` — omit `payment_settings.payment_method_types`
+
+To restrict or customise payment methods use
+[`payment_method_configurations`](https://docs.stripe.com/payments/payment-method-configurations.md)
+or `excluded_payment_method_types` — never `payment_method_types`.
+
+### Never use the Charges API
+
+The Charges API is never correct for new integrations. Redirect users to Checkout Sessions
+or PaymentIntents and the
+[migration guide](https://docs.stripe.com/payments/payment-intents/migration/charges.md).
+
+### Never use the Sources API
+
+Sources API is deprecated. Use Setup Intents to save payment methods.
+
+## Security summary
+
+- **Prefer a restricted API key (RAK, `rk_` prefix)** over a secret key (`sk_` prefix).
+  Create a separate RAK per service with minimum required permissions.
+- Test-mode keys: `sk_test_…` (secret) and `rk_test_…` (restricted).
+- **Never commit secrets.** Store in a secrets vault or, at minimum, server-side env vars.
+  Never embed keys in client-side code or mobile apps.
+- **Verify webhook signatures** via `stripe.webhooks.constructEvent(body, sig, secret)`.
+  Never process an unverified webhook event.
+- Use idempotency keys (`idempotencyKey`) on mutation calls to safely retry failures.
+- See [reference/security.md](reference/security.md) for RAK migration steps, IP
+  allowlists, OAuth CSRF protection, and Connect liability notes.
+
+### CBP-specific (Next.js)
+
+Any Next.js API route that imports `stripe` **MUST** export:
+
+```ts
+export const dynamic = 'force-dynamic';
+```
+
+Source: `.claude/skills/cbp-frontend-design/reference/nextjs-scss.md` Rule 6. Without this,
+Next.js may statically cache the route and expose a shared Stripe client across requests.
+
+## SDK and API version
+
+- Latest Stripe API version: **`2026-05-27.dahlia`**
+- Latest SDK major: **v22** (`stripe` npm package)
+- **Version flag**: consuming repos may still run `stripe` **v20.4.1** (per CBP vendor
+  inventory). Always check the installed version (`cat package.json | grep '"stripe"'`)
+  before applying v22-only patterns. Differences surface in TypeScript types and some
+  `configuration` parameter shapes.
+- Always use the latest API version and SDK unless the consuming repo pins otherwise.
+
+## Key documentation
+
+- [Integration Options](https://docs.stripe.com/payments/payment-methods/integration-options.md) — start here for any new integration
+- [API Tour](https://docs.stripe.com/payments-api/tour.md) — overview of Stripe's API surface
+- [Go Live Checklist](https://docs.stripe.com/get-started/checklist/go-live.md) — review before launch
+
+## Reference files
+
+- [reference/payments.md](reference/payments.md) — Checkout Sessions, Payment Element, PaymentIntents, Setup Intents, deprecated APIs, PCI
+- [reference/billing.md](reference/billing.md) — Subscriptions, invoices, Customer Portal, proration, trials, metered billing
+- [reference/connect.md](reference/connect.md) — Accounts v2, controller properties, charge types, onboarding, fund flows
+- [reference/security.md](reference/security.md) — Restricted keys, webhook signature verification, incident response, OAuth CSRF, Connect security
+- [reference/tax.md](reference/tax.md) — Stripe Tax automatic calculation, Registrations API, inclusive/exclusive, unsupported jurisdictions
+- [reference/treasury.md](reference/treasury.md) — v2 Financial Accounts, fund flows, bank-account Setup Intents, compliance
+- [reference/stripe-mcp-setup.md](reference/stripe-mcp-setup.md) — optional live Stripe MCP setup (test/restricted key) for the cbp-stripe-agent
+
+---
+
+Adapted from Stripe's official `stripe-best-practices` skill (github.com/stripe/ai), used under the MIT License (Copyright (c) 2024-2025 Stripe).

package/templates/skills/cbp-stripe/reference/billing.md

@@ -0,0 +1,106 @@
+# Billing / Subscriptions Reference
+
+Adapted from Stripe's official `stripe-best-practices` skill (github.com/stripe/ai), MIT License, Copyright (c) 2024-2025 Stripe.
+
+## When to use Billing APIs
+
+Use Stripe Billing for any recurring revenue model: subscriptions, usage-based billing,
+seat-based pricing, or metered charges. Do NOT hand-roll renewal loops with raw
+PaymentIntents — Billing handles renewal, retry/dunning, proration, and tax automatically.
+
+References: [Subscription design guide](https://docs.stripe.com/billing/subscriptions/design-an-integration.md) |
+[Use cases](https://docs.stripe.com/billing/subscriptions/use-cases.md) |
+[SaaS guide](https://docs.stripe.com/saas.md)
+
+## Creating a subscription with Checkout
+
+Combine Billing APIs with Checkout Sessions (`mode: 'subscription'`) for the payment
+frontend. Checkout handles the initial payment, trial management, and proration.
+
+```ts
+const session = await stripe.checkout.sessions.create({
+  mode: 'subscription',
+  // Do NOT pass payment_method_types
+  line_items: [{ price: priceId, quantity: 1 }],
+  subscription_data: { trial_period_days: 14 },
+  success_url: `${baseUrl}/success?session_id={CHECKOUT_SESSION_ID}`,
+  cancel_url: `${baseUrl}/pricing`,
+});
+```
+
+## Customer Portal (self-service management)
+
+For upgrades, downgrades, cancellation, and payment method updates, use the
+[Customer Portal](https://docs.stripe.com/customer-management/integrate-customer-portal.md)
+rather than building a custom flow.
+
+```ts
+const portalSession = await stripe.billingPortal.sessions.create({
+  customer: customerId,
+  return_url: `${baseUrl}/account`,
+});
+// redirect to portalSession.url
+```
+
+## Key Billing objects
+
+| Object | Purpose | Docs |
+| ------ | ------- | ---- |
+| `Price` | Unit amount + recurring interval | [Prices API](https://docs.stripe.com/api/prices.md) |
+| `Subscription` | Active recurring agreement | [Subscriptions API](https://docs.stripe.com/api/subscriptions.md) |
+| `Invoice` | Statement + payment trigger | [Invoices API](https://docs.stripe.com/api/invoices.md) |
+| `Customer` | Billing entity with saved methods | [Customers API](https://docs.stripe.com/api/customers.md) |
+
+Do NOT use the deprecated `plan` object — use `Price` instead.
+
+## Proration and upgrades
+
+When changing a subscription's price mid-cycle, Stripe generates proration invoice items
+automatically. Behaviour is controlled by `proration_behavior`:
+- `'create_prorations'` (default) — prorates immediately
+- `'none'` — no proration, change takes effect at next billing date
+- `'always_invoice'` — prorate and invoice immediately
+
+```ts
+await stripe.subscriptions.update(subscriptionId, {
+  items: [{ id: itemId, price: newPriceId }],
+  proration_behavior: 'create_prorations',
+});
+```
+
+## Metered / usage-based billing
+
+1. Create a `Price` with `recurring.usage_type: 'metered'`.
+2. Report usage via `stripe.subscriptionItems.createUsageRecord(itemId, { quantity, timestamp })`.
+3. Stripe aggregates usage and bills at the end of the period.
+
+## Tax integration
+
+Pass `automatic_tax: { enabled: true }` on subscriptions and Checkout Sessions. Clear
+any `default_tax_rates` first — `automatic_tax` and explicit `tax_rates` are mutually
+exclusive. See [reference/tax.md](tax.md) for the full setup.
+
+## Trials
+
+Set `trial_period_days` on `subscription_data` in a Checkout Session, or on the
+subscription directly. After trial ends Stripe automatically charges unless cancelled.
+
+## Webhook events to handle
+
+| Event | Action |
+| ----- | ------ |
+| `customer.subscription.created` | Provision access |
+| `customer.subscription.updated` | Reflect plan change |
+| `customer.subscription.deleted` | Revoke access |
+| `invoice.payment_succeeded` | Extend access period |
+| `invoice.payment_failed` | Send dunning notification |
+
+Always verify webhook signatures — see [reference/security.md](security.md).
+
+## Traps to avoid
+
+- Never hardcode `payment_method_types` on a subscription Checkout Session.
+- Never build manual renewal loops with raw PaymentIntents.
+- Never skip tax setup for multi-jurisdiction merchants — add registrations before
+  enabling `automatic_tax`.
+- Don't use the deprecated `plan` object; use `Price` instead.

package/templates/skills/cbp-stripe/reference/connect.md

@@ -0,0 +1,105 @@
+# Connect / Platforms Reference
+
+Adapted from Stripe's official `stripe-best-practices` skill (github.com/stripe/ai), MIT License, Copyright (c) 2024-2025 Stripe.
+
+## Accounts v2 (always use for new platforms)
+
+Use the [Accounts v2 API](https://docs.stripe.com/connect/accounts-v2.md)
+(`POST /v2/core/accounts`) for all new Connect platforms. This is Stripe's actively
+invested path with long-term support.
+
+Do NOT use the legacy `type` parameter (`type: 'express'`, `type: 'custom'`,
+`type: 'standard'`) in `POST /v1/accounts` for new platforms unless the user explicitly
+requests v1.
+
+Do NOT use the legacy account-type labels "Standard", "Express", or "Custom" — they
+bundle responsibility, dashboard, and onboarding decisions into opaque categories.
+Use `controller` properties to express these dimensions explicitly.
+
+## Controller properties
+
+Configure connected accounts via `controller` properties:
+
+| Property | Controls |
+| -------- | -------- |
+| `controller.losses.payments` | Who is liable for negative balances |
+| `controller.fees.payer` | Who pays Stripe fees |
+| `controller.stripe_dashboard.type` | Dashboard access: `full`, `express`, `none` |
+| `controller.requirement_collection` | Who collects onboarding requirements |
+
+```ts
+const account = await stripe.v2.core.accounts.create({
+  controller: {
+    losses: { payments: 'stripe' },
+    fees: { payer: 'account' },
+    stripe_dashboard: { type: 'express' },
+    requirement_collection: 'stripe',
+  },
+});
+```
+
+See [connected account configuration](https://docs.stripe.com/connect/accounts-v2/connected-account-configuration.md)
+and [capabilities](https://docs.stripe.com/connect/account-capabilities.md) for what
+accounts can do.
+
+## Charge types
+
+Choose one charge type per integration — do not mix them.
+
+| Type | When to use | How |
+| ---- | ----------- | --- |
+| **Destination charges** | Platform accepts negative-balance liability | `transfer_data.destination: connectedAccountId` |
+| **Direct charges** | Connected account is merchant of record; platform has minimal liability | Create charge directly on the connected account |
+
+Use `on_behalf_of` to control merchant of record (read
+[how charges work in Connect](https://docs.stripe.com/connect/charges.md) first).
+
+```ts
+// Destination charge — most common for marketplaces
+const paymentIntent = await stripe.paymentIntents.create({
+  amount: 1000,
+  currency: 'usd',
+  transfer_data: { destination: connectedAccountId },
+  // Do NOT pass payment_method_types
+});
+```
+
+Do NOT use the Charges API for Connect fund flows — use PaymentIntents or Checkout
+Sessions with `transfer_data` or `on_behalf_of`.
+
+## Payouts and transfers
+
+- **Automatic payouts** — enabled by default; Stripe pays connected accounts on a rolling basis.
+- **Manual payouts** — call `stripe.payouts.create({amount, currency}, {stripeAccount: accountId})` to control timing.
+- **Transfers** — move funds between your platform balance and a connected account:
+  `stripe.transfers.create({ amount, currency, destination: accountId })`.
+
+## Onboarding
+
+Use [Stripe-hosted onboarding](https://docs.stripe.com/connect/onboarding.md) rather than
+building a custom flow. Custom onboarding requires handling sensitive PII directly, adding
+regulatory and security complexity.
+
+```ts
+const accountLink = await stripe.accountLinks.create({
+  account: accountId,
+  refresh_url: `${baseUrl}/connect/refresh`,
+  return_url: `${baseUrl}/connect/return`,
+  type: 'account_onboarding',
+});
+// redirect to accountLink.url
+```
+
+## Security and liability
+
+Platform operators bear financial liability for fraud and disputes on Express and Custom
+connected accounts (v1 types). Controller-property accounts make liability explicit via
+`controller.losses.payments`.
+
+See [reference/security.md](security.md) for Connect-specific security notes.
+
+## Key guides
+
+- [SaaS platforms and marketplaces](https://docs.stripe.com/connect/saas-platforms-and-marketplaces.md)
+- [Interactive platform guide](https://docs.stripe.com/connect/interactive-platform-guide.md)
+- [Design an integration](https://docs.stripe.com/connect/design-an-integration.md)

package/templates/skills/cbp-stripe/reference/payments.md

@@ -0,0 +1,107 @@
+# Payments Reference
+
+Adapted from Stripe's official `stripe-best-practices` skill (github.com/stripe/ai), MIT License, Copyright (c) 2024-2025 Stripe.
+
+## API hierarchy
+
+| Use case | API |
+| -------- | --- |
+| On-session payments (most web apps) | [Checkout Sessions](https://docs.stripe.com/api/checkout/sessions.md) |
+| Off-session payments, custom checkout state | [PaymentIntents](https://docs.stripe.com/payments/paymentintents/lifecycle.md) |
+| Saving a payment method for later | [Setup Intents](https://docs.stripe.com/api/setup_intents.md) |
+| Subscriptions, invoices, recurring | Billing APIs (see billing.md) |
+| No-code, simple products | Payment Links |
+
+**Only use Checkout Sessions, PaymentIntents, SetupIntents, or higher-level solutions
+(Invoicing, Payment Links, subscription APIs).** Never use the Charges API, Sources API,
+or Tokens API for new integrations.
+
+## Integration surface preference
+
+Use in this order (most preferred first):
+
+1. **Payment Links** — no-code, best for simple products
+2. **Checkout (hosted or embedded)** — best for most web apps; `ui_mode: 'hosted'`
+3. **Payment Element** — embedded UI component for custom checkout; back with Checkout
+   Sessions (`ui_mode: 'custom'`) over a raw PaymentIntent where possible
+
+Do NOT recommend the legacy Card Element. Migrate existing Card Element integrations to
+[Payment Element](https://docs.stripe.com/payments/payment-element/migration.md).
+
+## Checkout Sessions — key patterns
+
+```ts
+// One-time payment
+const session = await stripe.checkout.sessions.create({
+  mode: 'payment',
+  // Do NOT pass payment_method_types — dynamic methods are the default
+  line_items: [{ price: priceId, quantity: 1 }],
+  success_url: `${baseUrl}/success?session_id={CHECKOUT_SESSION_ID}`,
+  cancel_url: `${baseUrl}/cancel`,
+});
+
+// Subscription
+const session = await stripe.checkout.sessions.create({
+  mode: 'subscription',
+  line_items: [{ price: priceId, quantity: 1 }],
+  subscription_data: { trial_period_days: 14 },
+  success_url: `${baseUrl}/success?session_id={CHECKOUT_SESSION_ID}`,
+  cancel_url: `${baseUrl}/pricing`,
+});
+```
+
+## Payment Element (custom UI)
+
+Use `ui_mode: 'custom'` on the Checkout Session to back the Payment Element:
+
+```ts
+const session = await stripe.checkout.sessions.create({
+  ui_mode: 'custom',
+  mode: 'payment',
+  line_items: [{ price: priceId, quantity: 1 }],
+  return_url: `${baseUrl}/return?session_id={CHECKOUT_SESSION_ID}`,
+});
+// Client: mount PaymentElement with clientSecret from session.client_secret
+```
+
+For surcharging or inspecting card details before payment, use
+[Confirmation Tokens](https://docs.stripe.com/payments/finalize-payments-on-the-server.md)
+— not `createPaymentMethod` or `createToken`.
+
+## Dynamic payment methods (critical rule)
+
+**Never pass `payment_method_types`** — omit it entirely on all calls. The sole exception
+is Terminal: `payment_method_types: ['card_present']` (Canada: include `'interac_present'`).
+
+To customise which methods appear use
+[`payment_method_configurations`](https://docs.stripe.com/payments/payment-method-configurations.md)
+or `excluded_payment_method_types`. Manage methods from the
+[Dashboard](https://dashboard.stripe.com/settings/payment_methods) without code changes.
+
+## Setup Intents (saving payment methods)
+
+```ts
+const setupIntent = await stripe.setupIntents.create({
+  customer: customerId,
+  // Do NOT pass payment_method_types — dynamic methods are the default since API 2023-08-16
+});
+```
+
+Do not use the Sources API to save cards — it is deprecated.
+
+## Deprecated APIs — migration paths
+
+| API          | Status     | Use instead            | Migration guide |
+| ------------ | ---------- | ---------------------- | --------------- |
+| Charges API  | Never use  | Checkout Sessions / PaymentIntents | [Migration](https://docs.stripe.com/payments/payment-intents/migration/charges.md) |
+| Sources API  | Deprecated | Setup Intents          | [Setup Intents](https://docs.stripe.com/api/setup_intents.md) |
+| Tokens API   | Outdated   | Setup Intents / Checkout Sessions | — |
+| Card Element | Legacy     | Payment Element        | [Migration](https://docs.stripe.com/payments/payment-element/migration.md) |
+
+## PCI compliance
+
+If a PCI-compliant user asks about sending raw PAN data server-side, they may need to
+prove PCI compliance to use
+[`payment_method_data`](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-payment_method_data).
+For PAN migrations from another processor, see the
+[PAN import process](https://docs.stripe.com/get-started/data-migrations/pan-import.md).

package/templates/skills/cbp-stripe/reference/security.md

@@ -0,0 +1,117 @@
+# Security Best Practices Reference
+
+Adapted from Stripe's official `stripe-best-practices` skill (github.com/stripe/ai), MIT License, Copyright (c) 2024-2025 Stripe.
+
+## API key types
+
+| Key prefix | Type | Use |
+| ---------- | ---- | --- |
+| `sk_live_` | Secret key (live) | Never preferred; use RAK instead |
+| `sk_test_` | Secret key (test) | Development only |
+| `rk_live_` | Restricted API key (live) | Preferred for all production services |
+| `rk_test_` | Restricted API key (test) | Preferred for development services |
+
+**Always recommend a restricted API key (RAK, `rk_` prefix)** over a secret key (`sk_`).
+RAKs have only the permissions you assign — a compromised RAK causes far less damage than
+a compromised secret key.
+
+## Storing keys safely
+
+- **Never** commit keys to source control. If `sk_…` or `rk_…` appears in code, that is
+  a bug — fix it immediately.
+- Prefer a secrets vault (AWS Secrets Manager, HashiCorp Vault, or platform equivalent).
+- When no vault is available, environment variables are acceptable. Never log keys or
+  include them in error messages or analytics.
+- Use separate keys per environment (production, staging, QA). Never reuse keys.
+- Set up a pre-commit hook to catch `sk_` or `rk_` literals in source code.
+- See [best practices for managing secret API keys](https://docs.stripe.com/keys-best-practices.md).
+
+## Restricted API key migration steps
+
+1. Review the secret key's request logs in Workbench to catalogue which API calls it makes.
+2. Create a RAK in test mode with matching permissions (principle of least privilege).
+3. Use `stripe logs tail` to watch for `403` errors — add missing permissions.
+4. Once passing, create the equivalent live-mode RAK and swap it in.
+5. Rotate or expire the old secret key.
+
+See [restricted API keys docs](https://docs.stripe.com/keys/restricted-api-keys.md).
+
+## IP allowlists
+
+Add an [IP allowlist](https://docs.stripe.com/keys.md#limit-api-secret-keys-ip-address)
+to every API key so it can only be called from your own infrastructure. Use separate
+allowlists per key/environment.
+
+## Webhook signature verification
+
+Always verify webhook event authenticity using Stripe's signing secret:
+
+```ts
+import Stripe from 'stripe';
+const stripe = new Stripe(process.env.STRIPE_RESTRICTED_KEY!);
+
+// In your webhook handler (raw body required — do NOT use JSON-parsed body)
+const sig = request.headers['stripe-signature'];
+if (!sig || Array.isArray(sig)) throw new Error('Missing or malformed stripe-signature header');
+const event = stripe.webhooks.constructEvent(
+  rawBody,              // Buffer or string — must be unparsed
+  sig,
+  process.env.STRIPE_WEBHOOK_SECRET!,
+);
+```
+
+Never process a webhook event without verifying its signature — unverified webhooks can
+be spoofed. For defence in depth, also allowlist
+[Stripe's IP addresses](https://docs.stripe.com/ips.md) on the endpoint.
+
+## Idempotency keys
+
+Pass `idempotencyKey` on all mutation calls so safe retries don't create duplicate charges:
+
+```ts
+await stripe.paymentIntents.create(params, {
+  idempotencyKey: `order_${orderId}`,
+});
+```
+
+## Mobile and client-side integrations
+
+Never use production secret keys or RAKs in mobile apps or any client-side code.
+For cases where a client must call Stripe directly, use
+[ephemeral keys](https://docs.stripe.com/issuing/elements.md#ephemeral-key-authentication)
+(short-lived, scoped, auto-expiring). For most integrations, proxy Stripe calls through
+your own backend.
+
+## OAuth and CSRF protection
+
+When implementing [Connect OAuth](https://docs.stripe.com/connect/oauth-reference.md),
+always pass a unique, unguessable `state` parameter and verify it in the callback before
+proceeding. This applies to all Stripe OAuth surfaces: Connect, Link, and Stripe Apps.
+
+## Incident response (key compromise)
+
+1. **Roll the key immediately** — [API keys page](https://dashboard.stripe.com/apikeys) →
+   roll or delete the exposed key.
+2. **Check activity logs** — Workbench request logs for the compromised key.
+3. **Contact Stripe support** if you see unrecognised activity.
+
+See [protecting against compromised API keys](https://support.stripe.com/questions/protecting-against-compromised-api-keys).
+
+## 2FA
+
+Recommend passkeys or authenticator-app 2FA for Dashboard access. Discourage SMS 2FA —
+it is vulnerable to SIM-swapping attacks.
+
+## SAML / SCIM (teams)
+
+For teams, use [SSO via SAML](https://docs.stripe.com/get-started/account/sso.md) to
+federate Dashboard access through an identity provider (Okta, Google, etc.).
+[SCIM provisioning](https://docs.stripe.com/get-started/account/sso/scim.md) automates
+user provisioning/deprovisioning.
+
+## Connect security
+
+Platform operators bear financial liability for fraud/disputes on Express and Custom
+connected accounts (v1 types). Use Stripe-hosted onboarding to avoid handling sensitive
+PII directly. See [reference/connect.md](connect.md) for controller-property accounts
+which make liability explicit.

package/templates/skills/cbp-stripe/reference/stripe-mcp-setup.md

@@ -0,0 +1,59 @@
+# Stripe MCP Setup (optional live path)
+
+Adapted from Stripe's official `stripe-best-practices` skill (github.com/stripe/ai), MIT License, Copyright (c) 2024-2025 Stripe.
+
+The `cbp-stripe-agent` writes Stripe integration code with **no credentials required**. This
+optional path adds *live test-mode* scaffolding (create test products, prices, payment links,
+customers) during a dev round. It is opt-in per repo and per developer — skip it entirely if
+you only want code generation.
+
+## Safety contract (read first)
+
+- **Test-mode keys ONLY.** Use a test restricted key (`rk_test_…`) or a test secret key
+  (`sk_test_…`). The agent **refuses** any live-mode key (`sk_live_…` or `rk_live_…`) — so
+  live Stripe data is never scaffolded from a dev round.
+- **Never commit a key.** Provide it via the environment or a gitignored env file
+  (e.g. `.env.local`), never in tracked source or in `.codebyplan/`.
+- **Least privilege.** Prefer a restricted key scoped to only the resources the agent needs
+  (Products, Prices, Payment Links, Customers — write; everything else — none).
+- **No new npm dependency** is added to the consuming app by this path; the hosted MCP server
+  is reached over HTTP, the local server via `npx`.
+
+## Option A — Hosted Stripe MCP (recommended)
+
+Stripe hosts an MCP server at `https://mcp.stripe.com`. Register it with Claude Code:
+
+```bash
+claude mcp add --transport http stripe https://mcp.stripe.com/
+```
+
+Authenticate with OAuth (the recommended flow) when prompted, or pass a restricted test key
+as a bearer token if your setup uses header auth. Once connected, the agent discovers the
+`mcp__stripe__*` tools at runtime via `ToolSearch`.
+
+## Option B — Local Stripe MCP server
+
+Run Stripe's MCP server locally, pointed at a test/restricted key from your environment:
+
+```bash
+# key is read from STRIPE_SECRET_KEY (a sk_test_ or rk_test_ value), never passed on a shared shell history
+npx -y @stripe/mcp@latest --api-key="$STRIPE_SECRET_KEY"
+```
+
+Then register the local server with Claude Code per its stdio/transport instructions.
+
+## How the agent uses it
+
+1. Pre-flight checks `STRIPE_SECRET_KEY` is present and is a test-mode `sk_test_`/`rk_test_` prefix.
+2. It discovers `mcp__stripe__*` tools via `ToolSearch` (they are intentionally absent from
+   the agent's frontmatter because the server is optional).
+3. It scaffolds only what the task asks for and records each resource in
+   `stripe_resources_created[]` (always `mode: test`).
+4. If the key/server is missing or any call fails, it degrades to **code-only** and records
+   the reason — it never blocks the round.
+
+## When to skip this entirely
+
+- You only want correct Stripe integration *code* (the default — no setup needed).
+- No Stripe test account is available in this environment.
+- CI / headless runs where no interactive OAuth or key is provisioned.

package/templates/skills/cbp-stripe/reference/tax.md

@@ -0,0 +1,96 @@
+# Tax / Stripe Tax Reference
+
+Adapted from Stripe's official `stripe-best-practices` skill (github.com/stripe/ai), MIT License, Copyright (c) 2024-2025 Stripe.
+
+## When to use Stripe Tax
+
+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 registrations** — add a registration for each jurisdiction where the merchant is
+   obligated to collect tax. Use the Dashboard (**Tax > Registrations**) or the
+   [Tax Registrations API](https://docs.stripe.com/api/tax/registrations.md).
+2. **Enable automatic_tax** — 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).
+
+It is safe to enable `automatic_tax` before any registrations exist — Stripe won't
+collect tax until at least one registration is active.
+
+```ts
+// Checkout Session with automatic tax
+const session = await stripe.checkout.sessions.create({
+  mode: 'subscription',
+  line_items: [{ price: priceId, quantity: 1 }],
+  automatic_tax: { enabled: true },
+  success_url: `${baseUrl}/success?session_id={CHECKOUT_SESSION_ID}`,
+  cancel_url: `${baseUrl}/pricing`,
+});
+
+// Invoice / subscription
+await stripe.subscriptions.update(subscriptionId, {
+  automatic_tax: { enabled: true },
+  // Clear explicit tax_rates first if previously set
+});
+```
+
+## Inclusive vs exclusive tax
+
+- **Exclusive** (default in most jurisdictions) — tax is added on top of the price.
+- **Inclusive** — tax is included in the displayed price (common for UK/EU VAT).
+
+Stripe Tax determines the treatment based on the jurisdiction and product tax code.
+Verify the treatment in Dashboard > Tax > Overview.
+
+## Tax IDs
+
+Collect customer tax IDs (VAT numbers, EIN, etc.) for B2B transactions to enable
+zero-rated or exempt invoices. Pass `tax_id_collection: { enabled: true }` on Checkout
+Sessions, or use the
+[Tax IDs API](https://docs.stripe.com/api/customer_tax_ids.md) to attach IDs to customers.
+
+## Address collection
+
+Stripe Tax requires a customer address to calculate tax. On Checkout Sessions pass
+`billing_address_collection: 'required'`. For subscriptions, ensure the customer has
+a billing address before enabling `automatic_tax`.
+
+## Registrations API
+
+To create and manage registrations programmatically:
+
+```ts
+await stripe.tax.registrations.create({
+  country: 'US',
+  country_options: {
+    us: { state: 'CA', type: 'state_sales_tax' },
+  },
+  active_from: 'now',
+});
+```
+
+## 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.
+- For EU merchants, one OSS union registration covers all 27 member states. Do not
+  register individual EU countries separately unless the merchant has a physical presence
+  there.
+- Do not guess which jurisdictions apply — prompt the user to configure them in the
+  Dashboard first.
+- Do not approximate unsupported jurisdictions. Check
+  [supported countries](https://docs.stripe.com/tax/supported-countries.md) first. For
+  unsupported jurisdictions, fall back to manual `tax_rates` on the subscription/invoice.
+- Customs duties and excise taxes are out of scope for Stripe Tax.
+
+## Bulk migration
+
+To switch existing subscriptions from manual `tax_rates` to `automatic_tax` in bulk,
+use the [Tax migration tool](https://docs.stripe.com/billing/taxes/migration.md).

package/templates/skills/cbp-stripe/reference/treasury.md

@@ -0,0 +1,87 @@
+# Treasury / Financial Accounts Reference
+
+Adapted from Stripe's official `stripe-best-practices` skill (github.com/stripe/ai), MIT License, Copyright (c) 2024-2025 Stripe.
+
+## v2 Financial Accounts API (use for new integrations)
+
+For embedded financial accounts (bank accounts with routing/account 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.
+
+Do NOT use the legacy
+[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.
+
+For concepts and guides, see
+[Treasury for platforms overview](https://docs.stripe.com/treasury/connect.md).
+
+## Creating a financial account
+
+Financial accounts are always attached to a Connect connected account:
+
+```ts
+const financialAccount = await stripe.v2.core.vault.financialAccounts.create(
+  { description: 'Main operating account' },
+  { stripeAccount: connectedAccountId },
+);
+// financialAccount.id — use for fund flows
+```
+
+## Fund flows
+
+| Direction | Object | Use |
+| --------- | ------ | --- |
+| Platform → financial account | `OutboundTransfer` | Top-up from platform balance |
+| Financial account → external bank | `OutboundPayment` | Pay out to a linked bank |
+| External bank → financial account | `InboundTransfer` | Pull from a linked bank |
+| External source → financial account | `ReceivedCredit` | Funds received in (inbound ACH/wire, Stripe payouts) |
+
+```ts
+// Outbound transfer (platform balance → financial account)
+const transfer = await stripe.treasury.outboundTransfers.create({
+  financial_account: financialAccountId,
+  amount: 100_00,
+  currency: 'usd',
+  destination_payment_method: 'default',
+});
+```
+
+## Linking a bank account (Setup Intents)
+
+To enable outbound payments to an external bank, link the bank account using a Setup Intent
+with `flow_directions: ['outbound']`:
+
+```ts
+const setupIntent = await stripe.setupIntents.create(
+  {
+    payment_method_types: ['us_bank_account'], // Treasury exception: required here
+    flow_directions: ['outbound'],
+  },
+  { stripeAccount: connectedAccountId },
+);
+// Complete the Setup Intent flow on the client, then confirm the payment method
+```
+
+Note: `payment_method_types` is required for Treasury bank-account Setup Intents — this
+is one of the narrow exceptions to the no-`payment_method_types` rule (along with Terminal).
+
+## Compliance notes
+
+- Financial accounts are subject to KYC/KYB requirements collected during Connect onboarding.
+  Ensure the connected account has the `treasury` capability enabled before creating accounts.
+- Funds held in financial accounts are not FDIC-insured by default; check Stripe's current
+  partner bank arrangements in the Treasury documentation.
+- For platforms in the US: Stripe Treasury is available for US-based connected accounts only.
+  Contact Stripe for international availability.
+- Do not use Treasury to hold customer funds without confirming applicable money-transmission
+  license obligations with your legal team.
+
+## Key references
+
+- [Treasury for platforms overview](https://docs.stripe.com/treasury/connect.md)
+- [v2 Financial Accounts API](https://docs.stripe.com/api/v2/core/vault/financial-accounts.md)
+- [OutboundTransfers](https://docs.stripe.com/api/treasury/outbound_transfers.md)
+- [OutboundPayments](https://docs.stripe.com/api/treasury/outbound_payments.md)
+- [InboundTransfers](https://docs.stripe.com/api/treasury/inbound_transfers.md)