cue-ai 0.3.0

package/resources/skills/skills/review/security-review/SKILL.md

@@ -0,0 +1,301 @@
+---
+name: security-review
+description: >-
+  Use when user says "security review", "security audit", "check for vulnerabilities", "OWASP review", or "/security-review". Audits for OWASP Top 10, secrets, injection, auth flaws. NOT for general code quality — use code-review.
+---
+
+# Security Review Skill
+
+Conduct a thorough security audit checking for OWASP Top 10 vulnerabilities, hardcoded secrets, and unsafe patterns.
+
+## When to Use
+
+This skill activates when:
+- User requests "security review", "security audit"
+- After writing code that handles user input
+- After adding new API endpoints
+- After modifying authentication/authorization logic
+- Before deploying to production
+- After adding external dependencies
+
+## What It Does
+
+## GPT-5.5 Guidance Alignment
+
+- Default to outcome-first progress and completion reporting: state the target result, evidence, validation status, and stop condition before adding process detail.
+- Treat newer user task updates as local overrides for the active workflow branch while preserving earlier non-conflicting constraints.
+- If correctness depends on additional inspection, retrieval, execution, or verification, keep using the relevant tools until the security review is grounded; stop once enough evidence exists.
+- Continue through clear, low-risk, reversible next steps automatically; ask only when the next step is materially branching, destructive, credentialed, external-production, or preference-dependent.
+
+Delegates to the `security-reviewer` agent (THOROUGH tier) for deep security analysis:
+
+1. **OWASP Top 10 Scan**
+   - A01: Broken Access Control
+   - A02: Cryptographic Failures
+   - A03: Injection (SQL, NoSQL, Command, XSS)
+   - A04: Insecure Design
+   - A05: Security Misconfiguration
+   - A06: Vulnerable and Outdated Components
+   - A07: Identification and Authentication Failures
+   - A08: Software and Data Integrity Failures
+   - A09: Security Logging and Monitoring Failures
+   - A10: Server-Side Request Forgery (SSRF)
+
+2. **Secrets Detection**
+   - Hardcoded API keys
+   - Passwords in source code
+   - Private keys in repo
+   - Tokens and credentials
+   - Connection strings with secrets
+
+3. **Input Validation**
+   - All user inputs sanitized
+   - SQL/NoSQL injection prevention
+   - Command injection prevention
+   - XSS prevention (output escaping)
+   - Path traversal prevention
+
+4. **Authentication/Authorization**
+   - Proper password hashing (bcrypt, argon2)
+   - Session management security
+   - Access control enforcement
+   - JWT implementation security
+
+5. **Dependency Security**
+   - Run `npm audit` for known vulnerabilities
+   - Check for outdated dependencies
+   - Identify high-severity CVEs
+
+## Agent Delegation
+
+```
+delegate(
+  role="security-reviewer",
+  tier="THOROUGH",
+  prompt="SECURITY REVIEW TASK
+
+Conduct comprehensive security audit of codebase.
+
+Scope: [specific files or entire codebase]
+
+Security Checklist:
+1. OWASP Top 10 scan
+2. Hardcoded secrets detection
+3. Input validation review
+4. Authentication/authorization review
+5. Dependency vulnerability scan (npm audit)
+
+Output: Security review report with:
+- Summary of findings by severity (CRITICAL, HIGH, MEDIUM, LOW)
+- Specific file:line locations
+- CVE references where applicable
+- Remediation guidance for each issue
+- Overall security posture assessment"
+)
+```
+
+## External Model Consultation (Preferred)
+
+The security-reviewer agent SHOULD consult Codex for cross-validation.
+
+### Protocol
+1. **Form your OWN security analysis FIRST** - Complete the review independently
+2. **Consult for validation** - Cross-check findings with Codex
+3. **Critically evaluate** - Never blindly adopt external findings
+4. **Graceful fallback** - Never block if tools unavailable
+
+### When to Consult
+- Authentication/authorization code
+- Cryptographic implementations
+- Input validation for untrusted data
+- High-risk vulnerability patterns
+- Production deployment code
+
+### When to Skip
+- Low-risk utility code
+- Well-audited patterns
+- Time-critical security assessments
+- Code with existing security tests
+
+### Tool Usage
+Before first MCP tool use, call `ToolSearch("mcp")` to discover deferred MCP tools.
+Use `mcp__x__ask_codex` with `agent_role: "security-reviewer"`.
+If ToolSearch finds no MCP tools, fall back to the `security-reviewer` agent.
+
+**Note:** Security second opinions are high-value. Consider consulting for CRITICAL/HIGH findings.
+
+## Output Format
+
+```
+SECURITY REVIEW REPORT
+======================
+
+Scope: Entire codebase (42 files scanned)
+Scan Date: 2026-01-24T14:30:00Z
+
+CRITICAL (2)
+------------
+1. src/api/auth.ts:89 - Hardcoded API Key
+   Finding: AWS API key hardcoded in source code
+   Impact: Credential exposure if code is public or leaked
+   Remediation: Move to environment variables, rotate key immediately
+   Reference: OWASP A02:2021 – Cryptographic Failures
+
+2. src/db/query.ts:45 - SQL Injection Vulnerability
+   Finding: User input concatenated directly into SQL query
+   Impact: Attacker can execute arbitrary SQL commands
+   Remediation: Use parameterized queries or ORM
+   Reference: OWASP A03:2021 – Injection
+
+HIGH (5)
+--------
+3. src/auth/password.ts:22 - Weak Password Hashing
+   Finding: Passwords hashed with MD5 (cryptographically broken)
+   Impact: Passwords can be reversed via rainbow tables
+   Remediation: Use bcrypt or argon2 with appropriate work factor
+   Reference: OWASP A02:2021 – Cryptographic Failures
+
+4. src/components/UserInput.tsx:67 - XSS Vulnerability
+   Finding: User input rendered with dangerouslySetInnerHTML
+   Impact: Cross-site scripting attack vector
+   Remediation: Sanitize HTML or use safe rendering
+   Reference: OWASP A03:2021 – Injection (XSS)
+
+5. src/api/upload.ts:34 - Path Traversal Vulnerability
+   Finding: User-controlled filename used without validation
+   Impact: Attacker can read/write arbitrary files
+   Remediation: Validate and sanitize filenames, use allowlist
+   Reference: OWASP A01:2021 – Broken Access Control
+
+...
+
+MEDIUM (8)
+----------
+...
+
+LOW (12)
+--------
+...
+
+DEPENDENCY VULNERABILITIES
+--------------------------
+Found 3 vulnerabilities via npm audit:
+
+CRITICAL: axios@0.21.0 - Server-Side Request Forgery (CVE-2021-3749)
+  Installed: axios@0.21.0
+  Fix: npm install axios@0.21.2
+
+HIGH: lodash@4.17.19 - Prototype Pollution (CVE-2020-8203)
+  Installed: lodash@4.17.19
+  Fix: npm install lodash@4.17.21
+
+...
+
+OVERALL ASSESSMENT
+------------------
+Security Posture: POOR (2 CRITICAL, 5 HIGH issues)
+
+Immediate Actions Required:
+1. Rotate exposed AWS API key
+2. Fix SQL injection in db/query.ts
+3. Upgrade password hashing to bcrypt
+4. Update vulnerable dependencies
+
+Recommendation: DO NOT DEPLOY until CRITICAL and HIGH issues resolved.
+```
+
+## Security Checklist
+
+The security-reviewer agent verifies:
+
+### Authentication & Authorization
+- [ ] Passwords hashed with strong algorithm (bcrypt/argon2)
+- [ ] Session tokens cryptographically random
+- [ ] JWT tokens properly signed and validated
+- [ ] Access control enforced on all protected resources
+- [ ] No authentication bypass vulnerabilities
+
+### Input Validation
+- [ ] All user inputs validated and sanitized
+- [ ] SQL queries use parameterization (no string concatenation)
+- [ ] NoSQL queries prevent injection
+- [ ] File uploads validated (type, size, content)
+- [ ] URLs validated to prevent SSRF
+
+### Output Encoding
+- [ ] HTML output escaped to prevent XSS
+- [ ] JSON responses properly encoded
+- [ ] No user data in error messages
+- [ ] Content-Security-Policy headers set
+
+### Secrets Management
+- [ ] No hardcoded API keys
+- [ ] No passwords in source code
+- [ ] No private keys in repo
+- [ ] Environment variables used for secrets
+- [ ] Secrets not logged or exposed in errors
+
+### Cryptography
+- [ ] Strong algorithms used (AES-256, RSA-2048+)
+- [ ] Proper key management
+- [ ] Random number generation cryptographically secure
+- [ ] TLS/HTTPS enforced for sensitive data
+
+### Dependencies
+- [ ] No known vulnerabilities in dependencies
+- [ ] Dependencies up to date
+- [ ] No CRITICAL or HIGH CVEs
+- [ ] Dependency sources verified
+
+## Severity Definitions
+
+**CRITICAL** - Exploitable vulnerability with severe impact (data breach, RCE, credential theft)
+**HIGH** - Vulnerability requiring specific conditions but serious impact
+**MEDIUM** - Security weakness with limited impact or difficult exploitation
+**LOW** - Best practice violation or minor security concern
+
+## Remediation Priority
+
+1. **Rotate exposed secrets** - Immediate (within 1 hour)
+2. **Fix CRITICAL** - Urgent (within 24 hours)
+3. **Fix HIGH** - Important (within 1 week)
+4. **Fix MEDIUM** - Planned (within 1 month)
+5. **Fix LOW** - Backlog (when convenient)
+
+
+## Scenario Examples
+
+**Good:** The user says `continue` after the workflow already has a clear next step. Continue the current branch of work instead of restarting or re-asking the same question.
+
+**Good:** The user changes only the output shape or downstream delivery step (for example `make a PR`). Preserve earlier non-conflicting workflow constraints and apply the update locally.
+
+**Bad:** The user says `continue`, and the workflow restarts discovery or stops before the missing verification/evidence is gathered.
+
+## Use with Other Skills
+
+**With Team:**
+```
+/team "run security review on authentication module"
+```
+Uses: explore → security-reviewer → executor → security-reviewer (re-verify)
+
+**With Swarm:**
+```
+/swarm 4:security-reviewer "audit all API endpoints"
+```
+Parallel security review across multiple endpoints.
+
+**With Ralph:**
+```
+/ralph security-review then fix all issues
+```
+Review, fix, re-review until all issues resolved.
+
+## Best Practices
+
+- **Review early** - Security by design, not afterthought
+- **Review often** - Every major feature or API change
+- **Automate** - Run security scans in CI/CD pipeline
+- **Fix immediately** - Don't accumulate security debt
+- **Educate** - Learn from findings to prevent future issues
+- **Verify fixes** - Re-run security review after remediation

package/resources/skills/skills/review/wtf/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: wtf
+description: >-
+  Pre-launch and pre-commit audit for vibe coding projects. Use when asked to check whether a project is ready to ship, deploy, merge, or commit, especially for common AI-built app mistakes: broken project structure, committed secrets or cache files, environment variable hygiene, database migrations, ORM/schema drift, unsafe raw SQL, unused legacy code, dead routes/components, weak auth, missing tests, build failures, and deployment footguns.
+---
+
+# WTF
+
+Use this skill as a hard-nosed pre-launch or pre-commit audit for fast-moving "vibe coded" projects. The goal is to find concrete blockers before code is shipped, not to produce a generic best-practices essay.
+
+## Operating Mode
+
+- Inspect the actual repository before judging it. Start with `git status --short`, project docs, file tree, package manifests, framework config, CI config, and deployment config.
+- Keep the audit scoped to the user's target: current branch, staged changes, a PR diff, or the whole project. If unclear, default to the current worktree plus files likely to affect deploy/runtime.
+- Prefer evidence over guesses. Tie every finding to a file, command output, or missing expected artifact.
+- Do not print secret values. If a secret is committed or exposed, name the file and variable/key shape, but redact the value.
+- If the user asks to fix issues, implement the fixes after the audit and verify them. Otherwise, remain in review/audit mode.
+
+## Audit Workflow
+
+1. **Map the project**
+   - Identify app type, framework, package manager, runtime, deployment target, database, ORM, auth provider, and build/test commands.
+   - Check whether the root is clean or dirty. Preserve unrelated user changes.
+   - Find likely entrypoints: app routes, API routes, workers, server actions, CLI commands, cron jobs, migrations, schemas, and config files.
+
+2. **Check repository hygiene**
+   - Look for committed `.env*` files other than safe examples, local database files, logs, cache directories, build outputs, generated artifacts, coverage, temporary uploads, screenshots, and tool caches.
+   - Verify `.gitignore` covers framework/runtime artifacts such as `.next`, `dist`, `build`, `.turbo`, `.vercel`, `.wrangler`, `.parcel-cache`, `coverage`, `node_modules`, local SQLite files, logs, and upload/cache folders.
+   - Use `git ls-files` to distinguish ignored local junk from files already tracked by Git.
+
+3. **Check secrets and environment variables**
+   - Search for tokens, private keys, API keys, JWT secrets, database URLs, webhook secrets, cloud credentials, and hardcoded production URLs.
+   - Verify required env vars are documented in `.env.example`, deployment docs, or typed config. Flag required envs that are used in code but undocumented.
+   - Check for accidental logging of secrets, auth headers, cookies, session payloads, or provider responses.
+
+4. **Check database readiness**
+   - Identify whether the app uses Prisma, Drizzle, TypeORM, Sequelize, Rails migrations, Django migrations, Alembic, Knex, raw SQL, or another migration system.
+   - Confirm schema changes have matching migrations and that migrations are committed.
+   - Flag schema drift, missing deploy migration commands, destructive migrations without a backfill/rollback plan, seed data required in production, and raw SQL that is not parameterized.
+   - If a database-backed app has no ORM or migration tool, call that out as a launch risk unless the repository has a clear alternative migration process.
+
+5. **Check app correctness and security basics**
+   - Run or inspect available `lint`, `typecheck`, `test`, and `build` scripts when practical.
+   - Review auth boundaries, protected routes, admin-only actions, server/client separation, CORS, CSRF where relevant, rate limits, file upload validation, SSRF surfaces, open redirects, and unsafe eval/shell execution.
+   - Check error handling and observability: production errors should not leak stack traces, secrets, or internal IDs unnecessarily.
+
+6. **Check dead and legacy code**
+   - Search for unused routes, duplicate pages/components, abandoned API handlers, old feature flags, large commented blocks, stale TODO/FIXME/HACK notes, generated placeholders, console debugging, unused dependencies, and test/demo data paths.
+   - Prefer repository-aware tools when available: TypeScript compiler, ESLint, depcheck, framework route manifests, import graph tools, or existing CI checks.
+   - Treat dead code as lower severity unless it affects security, deploy size, routing, migrations, or user-visible behavior.
+
+7. **Check deployment shape**
+   - Inspect Dockerfiles, wrangler/vercel/netlify/cloudflare config, GitHub Actions, release scripts, cron configuration, and required runtime versions.
+   - Flag missing production build commands, wrong package manager commands, missing migration steps, secrets expected at build time vs runtime, cache directories mounted incorrectly, and local-only assumptions.
+
+## Useful Commands
+
+Adapt commands to the repository; do not run broad destructive commands.
+
+```bash
+git status --short
+git ls-files
+rg -n --hidden --glob '!node_modules' --glob '!.git' 'AKIA|BEGIN (RSA |OPENSSH |EC )?PRIVATE KEY|DATABASE_URL|JWT_SECRET|SECRET_KEY|API_KEY|ACCESS_TOKEN|REFRESH_TOKEN|WEBHOOK_SECRET|STRIPE_SECRET|OPENAI_API_KEY|ANTHROPIC_API_KEY|PASSWORD=' .
+rg -n --hidden --glob '!node_modules' --glob '!.git' 'TODO|FIXME|HACK|console\\.log|debugger|ts-ignore|eslint-disable' .
+```
+
+For JavaScript/TypeScript projects, inspect `package.json` scripts first, then run only relevant existing scripts such as `npm run lint`, `npm run typecheck`, `npm test`, or `npm run build`.
+
+## Severity
+
+- **P0 Blocker**: likely secret exposure, data loss, auth bypass, production deploy failure, broken migration, or user-data corruption.
+- **P1 High**: strong launch risk such as missing env documentation, unsafe database access, unprotected sensitive route, failing build/test, or tracked cache/build artifacts.
+- **P2 Medium**: maintainability or reliability issue likely to slow future work, such as stale duplicate code, missing focused tests, weak error handling, or unused dependencies.
+- **P3 Low**: cleanup or polish that is useful but not launch-blocking.
+
+## Host-Specific Review Output
+
+Detect host-specific review capabilities from active system/developer/app instructions, available tools, or local agent docs. Do not infer support from the model name alone, and do not invent pseudo-directives for a host.
+
+- **Codex App**: for findings tied to a specific file and line, emit one inline review comment directive per issue:
+
+  ```text
+  ::code-comment{title="[P1] Short issue title" body="Explain the concrete risk and the smallest practical fix. Redact any secret value." file="/absolute/path/to/file.ts" start=42 end=42 priority=1}
+  ```
+
+  Use absolute file paths, tight line ranges, and `priority` matching severity (`P0`/`P1` = `1`, `P2` = `2`, `P3` = `3`). Keep repo-level findings, missing-file findings, command failures, and residual risks in the normal findings list.
+
+- **Claude Code**: do not assume an inline review comment output directive. Use normal review findings with `file:line` references unless the current Claude Code environment explicitly provides a comment protocol or tool.
+- **Antigravity**: do not assume a portable text directive for artifact or inline comments. If the active environment exposes a native artifact/comment tool, use that tool; otherwise use normal review findings with `file:line` references.
+- **Zed**: do not assume a response-level inline comment directive. Zed may show agent edit review UI, but audit findings should stay in normal review format unless the active Zed environment explicitly provides a comment protocol or tool.
+
+## Output Format
+
+Lead with findings, ordered by severity. For each finding include:
+
+- Severity and short title.
+- Evidence: file path, line, command, or missing expected file.
+- Impact: what can break or leak.
+- Fix: the smallest practical next step.
+
+Then add:
+
+- **Verified**: commands actually run and their result.
+- **Not verified**: checks skipped and why.
+- **Residual risk**: anything the repository shape prevented you from proving.

package/resources/skills/skills/stripe/stripe-best-practices/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: stripe-best-practices
+description: >-
+  Use when user says "Stripe", "Stripe integration", or "payment flow". Checkout, webhooks, idempotency, security, testing.
+---
+
+# Stripe Best Practices
+Latest Stripe API version: **2026-04-22.dahlia**. Always use the latest API version and SDK unless the user specifies otherwise.
+
+## Integration routing
+
+| Building…                                                                | Recommended API                     | Details                  |
+| ------------------------------------------------------------------------ | ----------------------------------- | ------------------------ |
+| One-time payments                                                        | Checkout Sessions                   | <references/payments.md> |
+| Custom payment form with embedded UI                                     | Checkout Sessions + Payment Element | <references/payments.md> |
+| Saving a payment method for later                                        | Setup Intents                       | <references/payments.md> |
+| Connect platform or marketplace                                          | Accounts v2 (`/v2/core/accounts`)   | <references/connect.md>  |
+| Subscriptions or recurring billing                                       | Billing APIs + Checkout Sessions    | <references/billing.md>  |
+| Embedded financial accounts / banking                                    | v2 Financial Accounts               | <references/treasury.md> |
+| Security (key management, RAKs, webhooks, OAuth, 2FA, Connect liability) | See security reference              | <references/security.md> |
+
+Read the relevant reference file before answering any integration question or writing code.
+
+## Critical rules
+
+- *Never include `payment_method_types` in any Stripe API call*, with one exception: Terminal (in-person payments) integrations must pass `payment_method_types: ['card_present']` on the PaymentIntent. For all other integrations, omit this parameter entirely to enable dynamic payment methods, which enables you to configure payment method settings from the Dashboard and dynamically display the most relevant eligible payment methods to each customer to maximize conversion. To customize which payment methods you accept, use [`payment_method_configurations`](https://docs.stripe.com/payments/payment-method-configurations.md) or `excluded_payment_method_types` instead of `payment_method_types`.
+
+## Key documentation
+
+When the user’s request does not clearly fit a single domain above, consult:
+
+- [Integration Options](https://docs.stripe.com/payments/payment-methods/integration-options.md) — Start here when designing any 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 launching.

package/resources/skills/skills/stripe/stripe-best-practices/references/billing.md

@@ -0,0 +1,36 @@
+# 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).
+
+## 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.
+- *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/resources/skills/skills/stripe/stripe-best-practices/references/connect.md

@@ -0,0 +1,48 @@
+# Connect / platforms
+
+## Table of contents
+
+- Accounts v2 API
+- Controller properties
+- Charge types
+- Integration guides
+
+## Accounts v2 API
+
+For new Connect platforms, ALWAYS use the [Accounts v2 API](https://docs.stripe.com/connect/accounts-v2.md) (`POST /v2/core/accounts`). This is Stripe’s actively invested path and ensures long-term support.
+
+**Traps to avoid:** Don’t use the legacy `type` parameter (`type: 'express'`, `type: 'custom'`, `type: 'standard'`) in `POST /v1/accounts` for new platforms unless the user has explicitly requested v1.
+
+## Controller properties
+
+Configure connected accounts using `controller` properties instead of legacy account types:
+
+| 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         |
+
+Use `defaults.responsibilities`, `dashboard`, and `configuration` as described in [connected account configuration](https://docs.stripe.com/connect/accounts-v2/connected-account-configuration.md).
+
+Always describe accounts in terms of their responsibility settings, dashboard access, and [capabilities](https://docs.stripe.com/connect/account-capabilities.md) to describe what connected accounts can do.
+
+**Traps to avoid:** Don’t use the terms “Standard”, “Express”, or “Custom” as account types. These are legacy categories that bundle together responsibility, dashboard, and requirement decisions into opaque labels. Controller properties give explicit control over each dimension.
+
+## Charge types
+
+Choose one charge type per integration — don’t mix them. For most platforms, start with destination charges:
+
+- **Destination charges** — Use when the platform accepts liability for negative balances. Funds route to the connected account via `transfer_data.destination`.
+- **Direct charges** — Use when the platform wants Stripe to take risk on the connected account. The charge is created on the connected account directly.
+
+Use `on_behalf_of` to control the merchant of record, but only after reading [how charges work in Connect](https://docs.stripe.com/connect/charges.md).
+
+**Traps to avoid:** Don’t use the Charges API for Connect fund flows — use PaymentIntents or Checkout Sessions with `transfer_data` or `on_behalf_of`. Don’t mix charge types within a single integration.
+
+## Integration guides
+
+- [SaaS platforms and marketplaces guide](https://docs.stripe.com/connect/saas-platforms-and-marketplaces.md) — Choosing the right integration shape.
+- [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.

package/resources/skills/skills/stripe/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.
+1. **Checkout** ([docs](https://docs.stripe.com/payments/checkout.md)) — Stripe-hosted or embedded form. Best for most web apps.
+1. **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).