codebyplan 1.13.48 → 1.13.50

package/templates/skills/cbp-clear-continue/SKILL.md

@@ -0,0 +1,86 @@
+---
+scope: org-shared
+name: cbp-clear-continue
+description: Resume work after /clear by reading .codebyplan/clear/handoff.md and re-invoking the previously-blocked heavy skill. Reports a friendly error if no handoff file exists.
+effort: xhigh
+---
+
+# cbp-clear-continue
+
+Resume a blocked heavy skill after a `/clear`. Reads `.codebyplan/clear/handoff.md`, restores
+task/round context into this fresh session, re-invokes the blocked skill, then deletes the
+handoff file so a stale snapshot never misleads a future session.
+
+## When Used
+
+- After running `/clear` following a `/cbp-clear-prep` capture
+- The user is ready to re-run the heavy skill (cbp-round-execute, cbp-task-testing,
+  cbp-standalone-task-testing, cbp-checkpoint-check, cbp-checkpoint-end) that was denied
+
+## Instructions
+
+### Step 1 — Read the handoff
+
+Read `.codebyplan/clear/handoff.md`.
+
+If the file is absent: output the following and STOP — do not attempt to infer state.
+
+```
+No handoff found at .codebyplan/clear/handoff.md — nothing to continue.
+Use /cbp-todo to find the next action.
+```
+
+### Step 2 — Restore context
+
+Parse the handoff fields:
+- `checkpoint_number`, `task_number`, `round_number`
+- `blocked_skill` — the skill that was denied
+- `next_action` — the exact skill invocation to re-run (with args)
+- `in_flight_notes` — any in-progress state worth restoring
+
+Output a brief context summary to orient the fresh session:
+
+```
+Resuming from handoff:
+  CHK-<N> TASK-<N> R<N>
+  Blocked skill:  /<blocked-skill>
+  Next action:    /<next-action>
+```
+
+### Step 3 — Delete the handoff BEFORE re-invoking
+
+Delete `.codebyplan/clear/handoff.md` once its contents have been read and displayed:
+
+```bash
+rm -f .codebyplan/clear/handoff.md
+```
+
+A stale handoff must not mislead a later session. Delete it here, before the skill runs,
+so even if the skill fails the handoff is gone and the user starts fresh next time.
+
+### Step 4 — Re-invoke the blocked skill
+
+Invoke the skill from `next_action` via the Skill tool, passing any recorded arguments.
+
+Example: if `next_action` is `/cbp-round-execute 217-2-1`, invoke `Skill(cbp-round-execute)`
+with args `217-2-1`.
+
+If the context window is STILL above threshold after `/clear` (unusual — compact may help),
+the guard will deny again. Follow the same cycle: `/cbp-clear-prep` → `/clear` →
+`/cbp-clear-continue`.
+
+## Key Rules
+
+- Delete `.codebyplan/clear/handoff.md` in Step 3 BEFORE invoking the next skill
+- If the handoff is absent, surface the friendly error and stop — never infer state from scratch
+- Re-invoke the EXACT skill and arguments from `next_action` — do not substitute or guess
+- `.codebyplan/clear/` is gitignored — never commit handoff.md
+
+## Integration
+
+- **Invoked by**: user after `/clear` following `/cbp-clear-prep`
+- **Reads**: `.codebyplan/clear/handoff.md`
+- **Deletes**: `.codebyplan/clear/handoff.md` (Step 3, before resuming)
+- **Then invokes**: the skill from `next_action` via Skill tool
+- **Companion**: `.claude/skills/cbp-clear-prep/SKILL.md` writes the handoff
+- **Guard hook**: `.claude/hooks/cbp-skill-context-guard.sh`

package/templates/skills/cbp-clear-prep/SKILL.md

@@ -0,0 +1,121 @@
+---
+scope: org-shared
+name: cbp-clear-prep
+description: Capture a clear-context handoff when the context window is too large to run a heavy skill. Reads active task/round state, writes .codebyplan/clear/handoff.md, then instructs the user to run /clear and /cbp-clear-continue to resume.
+argument-hint: "[blocked-skill]"
+effort: xhigh
+---
+
+# cbp-clear-prep
+
+Capture a handoff snapshot before clearing context. Invoked when the `cbp-skill-context-guard`
+PreToolUse hook denies a heavy skill (cbp-round-execute, cbp-task-testing,
+cbp-standalone-task-testing, cbp-checkpoint-check, cbp-checkpoint-end) because the context
+window exceeds the configured threshold.
+
+## When Used
+
+- The hook deny message says "Run /cbp-clear-prep now to capture a handoff"
+- A heavy skill was just blocked by the context guard
+- The user wants to preserve current task/round state before running `/clear`
+
+## Instructions
+
+### Step 1 — Identify the blocked skill
+
+Check `$ARGUMENTS` first. If empty, identify the blocked skill from the recent guard deny message
+in context — it will be one of: `cbp-round-execute`, `cbp-task-testing`,
+`cbp-standalone-task-testing`, `cbp-checkpoint-check`, `cbp-checkpoint-end`.
+
+### Step 2 — Resolve active task and round (local-first)
+
+1. Read `.codebyplan/state/session/current.json` to find the active task_id and checkpoint_id.
+2. Read `.codebyplan/state/checkpoints/<checkpoint_id>/tasks/<task_id>.json` for task details.
+3. Read the latest round file in `.codebyplan/state/checkpoints/<checkpoint_id>/tasks/<task_id>/rounds/`.
+4. On miss: run `npx codebyplan sync` once and re-read.
+5. Break-glass if state dir is absent: call `mcp__codebyplan__get_current_task` and
+   `mcp__codebyplan__get_rounds`.
+
+Capture: `checkpoint_id`, `checkpoint_number`, `task_id`, `task_number`, `round_id`,
+`round_number`. If no active task is found, set all to `unknown` and note the gap.
+
+### Step 3 — Identify the next action to resume
+
+From context, determine:
+- The exact skill the user was trying to invoke (blocked skill from Step 1)
+- Any arguments it was called with (e.g. `cbp-round-execute` args: `217-2-1`)
+- Any relevant in-flight state (round goal, step in progress, pending decisions)
+
+### Step 4 — Write the handoff file
+
+Create the directory and write `.codebyplan/clear/handoff.md`:
+
+```bash
+mkdir -p .codebyplan/clear
+```
+
+File content format:
+
+```
+# CBP Clear Handoff
+
+## Active Context
+
+checkpoint_id: <id or unknown>
+checkpoint_number: CHK-<N or unknown>
+task_id: <id or unknown>
+task_number: TASK-<N or unknown>
+round_id: <id or unknown>
+round_number: R<N or unknown>
+
+## Blocked Skill
+
+blocked_skill: <skill-name>
+
+## Next Action
+
+next_action: /<skill-name> <args if any>
+
+## In-Flight Notes
+
+<any relevant state — round goal, current step, pending decisions, uncommitted work>
+
+## Resume Instructions
+
+After /clear, run: /cbp-clear-continue
+```
+
+### Step 5 — Instruct the user
+
+Output exactly this summary (fill in the real values):
+
+```
+Handoff captured at .codebyplan/clear/handoff.md
+
+Active context:  CHK-<N> TASK-<N> R<N>
+Blocked skill:   /<blocked-skill>
+Resumes with:    /<next-action>
+
+Next steps:
+1. Run /clear to free context
+2. Run /cbp-clear-continue to resume
+```
+
+Do NOT auto-invoke `/clear` or `/cbp-clear-continue`. This is a directive-only stop.
+The user must run both commands manually.
+
+## Key Rules
+
+- Always write `.codebyplan/clear/handoff.md` BEFORE instructing `/clear`
+- Never auto-invoke the blocked skill — the guard denied it to protect context quality
+- If no active task resolves, still write the handoff with available context and note the gap
+- `.codebyplan/clear/` is gitignored — never commit handoff.md
+- Overwrite any existing handoff.md (each prep captures the freshest context)
+
+## Integration
+
+- **Invoked when**: `cbp-skill-context-guard` PreToolUse hook emits `permissionDecision: deny`
+- **Writes**: `.codebyplan/clear/handoff.md`
+- **Next**: user runs `/clear`, then `/cbp-clear-continue`
+- **Companion**: `.claude/skills/cbp-clear-continue/SKILL.md` reads `.codebyplan/clear/handoff.md`
+- **Guard hook**: `.claude/hooks/cbp-skill-context-guard.sh` — fires when context > CBP_CONTEXT_WARN_TOKENS (default 200000)

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-round-start/SKILL.md

@@ -216,7 +216,7 @@ Present the plan to user:
 ### Execution Waves
 | Wave | Agent type | Files | Depends on | Skill preloads |
 |------|-----------|-------|-----------|----------------|
-| web-ui | cbp-round-executor | 7 | — | cbp-frontend-design, cbp-frontend-a11y |
+| web-ui | cbp-round-executor | 7 | — | cbp-frontend-design |
 | backend-api | cbp-round-executor | 4 | — | — |
 ```
 

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).