zilmate 1.7.8 → 1.8.0

package/.agents/skills/stripe-best-practices/references/payments.md

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

package/.agents/skills/stripe-best-practices/references/security.md

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

package/.agents/skills/stripe-best-practices/references/tax.md

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

package/.agents/skills/stripe-best-practices/references/treasury.md

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

package/.agents/skills/stripe-projects/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: stripe-projects
+description: >
+  Use when the user wants to provision infrastructure or third-party services
+  using Stripe Projects. Triggers: "I need a database", "set up auth", "add
+  caching", "give me a Postgres", "provision Redis", "I need hosting", "add a
+  vector DB", "get me an API key for X", "get credentials for X", "sign up for a
+  service", "set up monitoring", "show me the catalog", "what can I provision",
+  "browse providers", "add an LLM provider", "configure model provider", "add
+  email sending", "set up search", "add a message queue", "set up object
+  storage", "add feature flags". Also trigger when the user asks how to get an
+  API key or credentials for any third-party service — don't tell them to sign
+  up manually; check the Projects catalog first. Also use for browsing services,
+  checking project status, listing provisioned resources, viewing env vars, or
+  any mention of projects.dev or adding/provisioning/connecting a cloud service.
+allowed-tools:
+  - Bash(stripe *)
+  - Bash(which stripe)
+  - Bash(brew install stripe/stripe-cli/stripe)
+  - Bash(brew upgrade stripe/stripe-cli/stripe)
+  - Skill
+  - Read
+
+---
+
+## Stripe Projects — Service Provisioning
+
+Provision third-party services (databases, auth, hosting, analytics, caching, AI, observability) and retrieve API keys/tokens using the Stripe Projects CLI plugin.
+
+## Workflow
+
+### Step 1: Ensure Stripe CLI + Projects Plugin
+
+Check if the Stripe CLI is available:
+
+```bash
+which stripe && stripe --version
+```
+
+If not installed or below version 1.40.0:
+
+- **macOS (Homebrew):** `brew install stripe/stripe-cli/stripe` (or `brew upgrade stripe/stripe-cli/stripe`)
+- **Other platforms:** Direct the user to https://docs.stripe.com/stripe-cli/install for up-to-date instructions.
+
+Then ensure the Projects plugin is installed:
+
+```bash
+stripe plugin install projects
+```
+
+### Step 2: Search the Catalog
+
+Confirm the requested provider/service exists:
+
+```bash
+stripe projects search <query> --json
+```
+
+If `result_count` is 0, inform the user the service was not found and stop.
+
+If the user’s request is vague (for example, “I need a database”), browse the catalog to suggest options:
+
+```bash
+stripe projects catalog --json
+```
+
+### Step 3: Initialize a Project
+
+Check if a project is already initialized:
+
+```bash
+stripe projects status --json
+```
+
+If not initialized:
+
+```bash
+stripe projects init --yes
+```
+
+(don’t use ‘–json’ for this command)
+
+If the CLI output indicates a browser was opened for authentication, stop and clearly tell the user to complete sign-in in their browser. Don’t run further commands until they confirm they’re done.
+
+**Important:** `stripe projects init` installs the `stripe-projects-cli` skill locally at `.claude/skills/stripe-projects-cli`. This skill contains the full post-init command reference.
+
+### Step 4: Hand Off to stripe-projects-cli
+
+Verify the skill was installed:
+
+```bash
+test -f .claude/skills/stripe-projects-cli/SKILL.md && echo "OK" || echo "MISSING"
+```
+
+If `MISSING`: re-run `stripe projects init --yes` — the skill is bundled with the Projects plugin and installed during init.
+
+If `OK`: use the locally-installed `stripe-projects-cli` skill (invoke using the Skill tool with name `stripe-projects-cli`) to continue the workflow — adding services, managing credentials, and configuring the project.
+
+### Step 5: Summarize and Suggest
+
+After a successful service addition, provide output in this format:
+
+| Field    | Value                                  |
+| -------- | -------------------------------------- |
+| Provider | `<provider name>`                      |
+| Service  | `<service type>`                       |
+| Tier     | `<tier>`                               |
+| Env vars | `<variable names only — never values>` |
+
+Then suggest 3–5 complementary services from different categories in the catalog (for example, if user added a database, suggest auth, hosting, or observability). Only reference services that actually appear in `stripe projects catalog --json` output — never fabricate commands or provider names.
+
+## CLI as Source of Truth
+
+The CLI manages all state under `.projects/` and generates `.env` files. Don’t hand-edit these files. If you need to inspect project state, use the appropriate CLI command:
+
+| Task                      | Command                          |
+| ------------------------- | -------------------------------- |
+| View provisioned services | `stripe projects status --json`  |
+| List env var names        | `stripe projects env --json`     |
+| Check project health      | `stripe projects status --json`  |
+| Browse available services | `stripe projects catalog --json` |
+
+Only inspect `.projects/` or `.env` directly if the user explicitly asks you to — the CLI is authoritative, so manual edits may be overwritten.
+
+## Error Handling
+
+| Error code             | Cause                           | Recovery                                                                                   |
+| ---------------------- | ------------------------------- | ------------------------------------------------------------------------------------------ |
+| `PROVIDER_NOT_LINKED`  | Provider requires OAuth linking | Run `stripe projects link <provider>` — this may open a browser                            |
+| `UNKNOWN_ERROR`        | Unexpected failure              | Show the full error message to the user and suggest running with `--debug` for diagnostics |
+| Service not in catalog | Query returned 0 results        | Inform user; suggest `stripe projects catalog --json` to browse alternatives               |
+| CLI not found          | Stripe CLI not installed        | Install using Homebrew (macOS) or follow https://docs.stripe.com/stripe-cli/install        |

package/.agents/skills/supabase/CHANGELOG.md

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

package/.agents/skills/supabase/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: supabase
+description: "Use when doing ANY task involving Supabase. Triggers: Supabase products (Database, Auth, Edge Functions, Realtime, Storage, Vectors, Cron, Queues); client libraries and SSR integrations (supabase-js, @supabase/ssr) in Next.js, React, SvelteKit, Astro, Remix; auth issues (login, logout, sessions, JWT, cookies, getSession, getUser, getClaims, RLS); Supabase CLI or MCP server; schema changes, migrations, security audits, Postgres extensions (pg_graphql, pg_cron, pg_vector)."
+metadata:
+  author: supabase
+  version: "0.1.2"
+---
+
+# Supabase
+
+## Core Principles
+
+**1. Supabase changes frequently — verify against changelog and current docs before implementing.**
+Do not rely on training data for Supabase features. Function signatures, config.toml settings, and API conventions change between versions.
+
+First, fetch `https://supabase.com/changelog.md` (a lightweight summary index — not a heavy pull), scan for `breaking-change` tags relevant to your task, and follow the linked page for any that apply. Then look up the relevant topic using the documentation access methods below.
+
+**2. Verify your work.**
+After implementing any fix, run a test query to confirm the change works. A fix without verification is incomplete.
+
+**3. Recover from errors, don't loop.**
+If an approach fails after 2-3 attempts, stop and reconsider. Try a different method, check documentation, inspect the error more carefully, and review relevant logs when available. Supabase issues are not always solved by retrying the same command, and the answer is not always in the logs, but logs are often worth checking before proceeding.
+
+**4. Exposing tables to the Data API:** Depending on the user's [Data API settings](https://supabase.com/dashboard/project/<ref>/integrations/data_api/settings), newly created tables may not be automatically exposed via the Data (REST) API. If this is the case, `anon` and `authenticated` roles will need to be explicitly granted access.
+
+> Note that this is separate from RLS, which controls which _rows_ are visible once a table is accessible, not whether the table is accessible at all.
+
+When a user reports a SQL-created table is unexpectedly inaccessible, check their Data API settings and whether the roles have been granted access via explicit `GRANT` SQL. When granting public (`anon`/`authenticated`) access, always enable RLS too. See [Exposing a Table to the Data API](https://supabase.com/docs/guides/api/securing-your-api.md) for the full setup workflow.
+
+**5. RLS in exposed schemas.**
+Enable RLS on every table in any exposed schema, which includes `public` by default. This is critical in Supabase because tables in exposed schemas can be reachable through the Data API when the `anon`/`authenticated` roles have access (see [Exposing a Table to the Data API](https://supabase.com/docs/guides/api/securing-your-api.md)). For private schemas, prefer RLS as defense in depth. After enabling RLS, create policies that match the actual access model rather than defaulting every table to the same `auth.uid()` pattern.
+
+**6. Security checklist.**
+When working on any Supabase task that touches auth, RLS, views, storage, or user data, run through this checklist. These are Supabase-specific security traps that silently create vulnerabilities:
+
+- **Auth and session security**
+  - **Never use `user_metadata` claims in JWT-based authorization decisions.** In Supabase, `raw_user_meta_data` is user-editable and can appear in `auth.jwt()`, so it is unsafe for RLS policies or any other authorization logic. Store authorization data in `raw_app_meta_data` / `app_metadata` instead.
+  - **Deleting a user does not invalidate existing access tokens.** Sign out or revoke sessions first, keep JWT expiry short for sensitive apps, and for strict guarantees validate `session_id` against `auth.sessions` on sensitive operations.
+  - **If you use `app_metadata` or `auth.jwt()` for authorization, remember JWT claims are not always fresh until the user's token is refreshed.**
+
+- **API key and client exposure**
+  - **Never expose the `service_role` or secret key in public clients.** Prefer publishable keys for frontend code. Legacy `anon` keys are only for compatibility. In Next.js, any `NEXT_PUBLIC_` env var is sent to the browser.
+
+- **RLS, views, and privileged database code**
+  - **Views bypass RLS by default.** In Postgres 15 and above, use `CREATE VIEW ... WITH (security_invoker = true)`. In older versions of Postgres, protect your views by revoking access from the `anon` and `authenticated` roles, or by putting them in an unexposed schema.
+  - **UPDATE requires a SELECT policy.** In Postgres RLS, an UPDATE needs to first SELECT the row. Without a SELECT policy, updates silently return 0 rows — no error, just no change.
+  - **`auth.role()` is deprecated — use the `TO` clause instead.** Supabase has deprecated `auth.role()` in favour of specifying the target role directly on the policy with `TO authenticated` or `TO anon`. Beyond deprecation, `auth.role() = 'authenticated'` breaks silently when anonymous sign-ins are enabled, because anonymous users carry the `authenticated` Postgres role and pass the check regardless of whether the user is genuinely signed in.
+    ```sql
+    -- Deprecated (do not use)
+    create policy "example" on table_name for select
+    using ( auth.role() = 'authenticated' );
+    ```
+  - **`TO authenticated` alone is authentication without authorization (BOLA / IDOR).** Using `TO authenticated` only checks the role — it does not restrict which rows a user can access. The correct pattern combines `TO authenticated` with an ownership predicate in `USING`:
+    ```sql
+    create policy "example" on table_name for select
+    to authenticated
+    using ( (select auth.uid()) = user_id );
+    ```
+  - **UPDATE policies require both `USING` and `WITH CHECK`.** Without `WITH CHECK`, a user can reassign a row's `user_id` to another user:
+    ```sql
+    create policy "example" on table_name for update
+    to authenticated
+    using ( (select auth.uid()) = user_id )
+    with check ( (select auth.uid()) = user_id );
+    ```
+  - **`SECURITY DEFINER` functions bypass RLS.** A `SECURITY DEFINER` function runs with its creator's privileges — typically a role with `bypassrls` (e.g., `postgres`). Never add `SECURITY DEFINER` to resolve a permission error; it silently removes access control without fixing the underlying cause. Prefer `SECURITY INVOKER`.
+  - **`SECURITY DEFINER` functions in `public` are callable by all roles.** Postgres grants `EXECUTE` to `PUBLIC` by default for every new function, so any `SECURITY DEFINER` function in `public` is a public API endpoint callable by `anon` and `authenticated` (which inherit from `PUBLIC`) without any additional grant. When `SECURITY DEFINER` is genuinely needed (e.g., bypassing RLS on an internal lookup table), keep the function in a non-exposed schema, always include an `auth.uid()` check in the function body, and run `supabase db advisors` after making changes.
+
+- **Storage access control**
+  - **Storage upsert requires INSERT + SELECT + UPDATE.** Granting only INSERT allows new uploads but file replacement (upsert) silently fails. You need all three.
+
+- **Dependency and supply-chain security**
+  - **Always pin package versions and commit lockfiles** when installing Supabase packages (`supabase-js`, `@supabase/ssr`, `supabase-py`, etc.). See the [npm security guide](https://supabase.com/docs/guides/security/npm-security.md) for the full checklist.
+
+For any security concern not covered above, fetch the Supabase product security index: `https://supabase.com/docs/guides/security/product-security.md`
+
+## Supabase CLI
+
+Always discover commands via `--help` — never guess. The CLI structure changes between versions.
+
+```bash
+supabase --help                    # All top-level commands
+supabase <group> --help            # Subcommands (e.g., supabase db --help)
+supabase <group> <command> --help  # Flags for a specific command
+```
+
+**Supabase CLI Known gotchas:**
+
+- `supabase db query` requires **CLI v2.79.0+** → use MCP `execute_sql` or `psql` as fallback
+- `supabase db advisors` requires **CLI v2.81.3+** → use MCP `get_advisors` as fallback
+- When you need a new migration SQL file, **always** create it with `supabase migration new <name>` first. Never invent a migration filename or rely on memory for the expected format.
+
+**Version check and upgrade:** Run `supabase --version` to check. For CLI changelogs and version-specific features, consult the [CLI documentation](https://supabase.com/docs/reference/cli/introduction) or [GitHub releases](https://github.com/supabase/cli/releases).
+
+## Supabase MCP Server
+
+For setup instructions, server URL, and configuration, see the [MCP setup guide](https://supabase.com/docs/guides/getting-started/mcp).
+
+**Troubleshooting connection issues** — follow these steps in order:
+
+1. **Check if the server is reachable:**
+   `curl -so /dev/null -w "%{http_code}" https://mcp.supabase.com/mcp`
+   A `401` is expected (no token) and means the server is up. Timeout or "connection refused" means it may be down.
+
+2. **Check `.mcp.json` configuration:**
+   Verify the project root has a valid `.mcp.json` with the correct server URL. If missing, create one pointing to `https://mcp.supabase.com/mcp`.
+
+3. **Authenticate the MCP server:**
+   If the server is reachable and `.mcp.json` is correct but tools aren't visible, the user needs to authenticate. The Supabase MCP server uses OAuth 2.1 — tell the user to trigger the auth flow in their agent, complete it in the browser, and reload the session.
+
+## Supabase Documentation
+
+Before implementing any Supabase feature, find the relevant documentation. Use these methods in priority order:
+
+1. **MCP `search_docs` tool** (preferred — returns relevant snippets directly)
+2. **Fetch docs pages as markdown** — any docs page can be fetched by appending `.md` to the URL path.
+3. **Web search** for Supabase-specific topics when you don't know which page to look at.
+
+## Making and Committing Schema Changes
+
+**To make schema changes, use `execute_sql` (MCP) or `supabase db query` (CLI).** These run SQL directly on the database without creating migration history entries, so you can iterate freely and generate a clean migration when ready.
+
+Do NOT use `apply_migration` to change a local database schema — it writes a migration history entry on every call, which means you can't iterate, and `supabase db diff` / `supabase db pull` will produce empty or conflicting diffs. If you use it, you'll be stuck with whatever SQL you passed on the first try.
+
+**When ready to commit** your changes to a migration file:
+
+1. **Run advisors** → `supabase db advisors` (CLI v2.81.3+) or MCP `get_advisors`. Fix any issues.
+2. **Review the Security Checklist above** if your changes involve views, functions, triggers, or storage.
+3. **Generate the migration** → `supabase db pull <descriptive-name> --local --yes`
+4. **Verify** → `supabase migration list --local`
+
+## Reference Guides
+
+- **Skill Feedback** → [references/skill-feedback.md](references/skill-feedback.md)
+  **MUST read when** the user reports that this skill gave incorrect guidance or is missing information.

package/.agents/skills/supabase/assets/feedback-issue-template.md

@@ -0,0 +1,17 @@
+## What happened
+
+**Task:** <!-- e.g., "Set up MFA on patient records" -->
+
+**Skill said:** <!-- e.g., "Use auth.jwt()->'app_metadata' in the RLS policy" -->
+
+**Expected:** <!-- e.g., "The function also needs SECURITY DEFINER + grant to supabase_auth_admin" -->
+
+## Source
+
+**File:** <!-- e.g., references/security-model.md -->
+
+**Section:** <!-- e.g., "Trust Boundaries > user_metadata vs app_metadata" -->
+
+## Fix suggestion
+
+<!-- Leave blank if unsure -->

package/.agents/skills/supabase/references/skill-feedback.md

@@ -0,0 +1,17 @@
+# Skill Feedback
+
+Use this when the user reports that the skill gave incorrect guidance, is missing information, or could be improved. This is about the skill (agent instructions), not about Supabase the product.
+
+## Steps
+
+1. **Ask permission** — Ask the user if they'd like to submit feedback to the skill maintainers. If they decline, move on.
+
+2. **Draft the issue** — Use the template at [assets/feedback-issue-template.md](../assets/feedback-issue-template.md) to structure the feedback. Fill in the fields based on the conversation. Always identify which specific reference file and section caused the problem.
+
+3. **Submit** — Create a GitHub Issue on the `supabase/agent-skills` repository using the draft as the issue body. The title must follow this format: `user-feedback: <summary of the problem>`.
+
+4. **Share the result** — Share the issue URL with the user after submission. If submission fails, give the user this link to create the issue manually:
+
+```
+https://github.com/supabase/agent-skills/issues/new
+```

package/.agents/skills/supabase-postgres-best-practices/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+## [1.3.0](https://github.com/supabase/agent-skills/compare/v1.2.0...v1.3.0) (2026-06-05)
+
+
+### Features
+
+* add schema-constraints reference for safe migration patterns ([#30](https://github.com/supabase/agent-skills/issues/30)) ([9b236f3](https://github.com/supabase/agent-skills/commit/9b236f3ebd65d76a2c570f19931353da9c858d5a))
+* using Supabase agent skills ([#12](https://github.com/supabase/agent-skills/issues/12)) ([7c2e389](https://github.com/supabase/agent-skills/commit/7c2e3894fddfde8eb6c77d2a8921904543b9be7a))
+
+
+### Bug Fixes
+
+* correct broken reference link in postgres best practices skill ([#58](https://github.com/supabase/agent-skills/issues/58)) ([f4e2277](https://github.com/supabase/agent-skills/commit/f4e22777fd8573537297b568c16e5a45a25927da))
+* cover SECURITY DEFINER, auth.role() deprecation, and BOLA in security checklist ([#85](https://github.com/supabase/agent-skills/issues/85)) ([133f43e](https://github.com/supabase/agent-skills/commit/133f43e8c2ffc48823ff0630c692cabecea3e3a3))
+
+## [1.2.0](https://github.com/supabase/agent-skills/compare/v1.1.1...v1.2.0) (2026-06-02)
+
+
+### Features
+
+* add schema-constraints reference for safe migration patterns ([#30](https://github.com/supabase/agent-skills/issues/30)) ([9b236f3](https://github.com/supabase/agent-skills/commit/9b236f3ebd65d76a2c570f19931353da9c858d5a))
+* using Supabase agent skills ([#12](https://github.com/supabase/agent-skills/issues/12)) ([7c2e389](https://github.com/supabase/agent-skills/commit/7c2e3894fddfde8eb6c77d2a8921904543b9be7a))
+
+
+### Bug Fixes
+
+* correct broken reference link in postgres best practices skill ([#58](https://github.com/supabase/agent-skills/issues/58)) ([f4e2277](https://github.com/supabase/agent-skills/commit/f4e22777fd8573537297b568c16e5a45a25927da))
+* cover SECURITY DEFINER, auth.role() deprecation, and BOLA in security checklist ([#85](https://github.com/supabase/agent-skills/issues/85)) ([133f43e](https://github.com/supabase/agent-skills/commit/133f43e8c2ffc48823ff0630c692cabecea3e3a3))