Laravel + Stripe + Tailwind rules for AI coding agents

# AGENTS.md - this project

Instructions for AI coding agents working in this repository.

## Project

A PHP + Laravel + Tailwind CSS v4 + Stripe payments project.

Stack: PHP + Laravel, Tailwind CSS v4, Stripe payments.

## Commands

- Dev server: `composer run dev`
- Migrate: `php artisan migrate`
- Tests: `php artisan test`
- Format: `vendor/bin/pint`
- Forward webhooks locally: `stripe listen --forward-to localhost:3000/api/webhooks/stripe`

## How to work in this repo

- Read the relevant files before editing. Follow the patterns already in the codebase over these generic rules.
- Make the smallest change that solves the task. Do not refactor or reformat unrelated code.
- Before saying a task is done, run the type-check, lint and tests listed under Commands and fix what you broke.
- If requirements are ambiguous, ask one clear question instead of guessing.
- Never commit secrets, API keys or `.env` files. Use env vars and keep `.env.example` up to date.
- Do not add a new dependency when the standard library or an existing dependency already covers it.
- Ask before adding, removing or upgrading any dependency.
- Ask before changing database schemas, auth, payments or CI configuration.
- Never delete files, drop data or run destructive commands (`rm -rf`, `git push --force`, `DROP TABLE`) without explicit approval.
- Keep each change under ~200 changed lines where possible; split larger work into steps.

## PHP + Laravel

- Use `php artisan make:*` generators so files land in the conventional place.
- Validate input with Form Request classes, not inline in controllers.
- Use Eloquent relationships and eager load with `with()` to avoid N+1 queries.
- Protect mass assignment with `$fillable` on every model.
- Authorize with Policies and Gates.
- Read config through `config()`; only `config/*.php` files call `env()`.
- Queue slow work (emails, webhooks) with jobs.

## Tailwind CSS v4

- Tailwind v4 is configured in CSS: `@import "tailwindcss";` plus `@theme { ... }` for design tokens. Do not create a `tailwind.config.js` unless the project already has one.
- Use theme tokens (colors, spacing) instead of arbitrary values like `w-[37px]`.
- Build responsive layouts mobile-first with `sm:`, `md:`, `lg:` prefixes.
- Extract repeated class lists into components, not `@apply` chains.
- Support dark mode with the `dark:` variant when the project uses it.

## Stripe payments

- Never trust prices or amounts from the client. Look up Price IDs and amounts on the server.
- Prefer Stripe Checkout or Payment Elements over custom card forms.
- Verify every webhook signature with the raw request body and the endpoint secret.
- Fulfil orders and update subscription status from webhooks, not from the success redirect.
- Make webhook handlers idempotent (store processed event IDs) and use idempotency keys on create calls.
- Use test-mode keys in development. The secret key is server-only.

## Reference docs

- [Laravel docs](https://laravel.com/docs)
- [Tailwind CSS docs](https://tailwindcss.com/docs)
- [Stripe docs](https://docs.stripe.com)

# CLAUDE.md - this project

Project instructions for Claude Code.

## Project

A PHP + Laravel + Tailwind CSS v4 + Stripe payments project.

Stack: PHP + Laravel, Tailwind CSS v4, Stripe payments.

## Commands

- Dev server: `composer run dev`
- Migrate: `php artisan migrate`
- Tests: `php artisan test`
- Format: `vendor/bin/pint`
- Forward webhooks locally: `stripe listen --forward-to localhost:3000/api/webhooks/stripe`

## How to work in this repo

- Read the relevant files before editing. Follow the patterns already in the codebase over these generic rules.
- Make the smallest change that solves the task. Do not refactor or reformat unrelated code.
- Before saying a task is done, run the type-check, lint and tests listed under Commands and fix what you broke.
- If requirements are ambiguous, ask one clear question instead of guessing.
- Never commit secrets, API keys or `.env` files. Use env vars and keep `.env.example` up to date.
- Do not add a new dependency when the standard library or an existing dependency already covers it.
- Ask before adding, removing or upgrading any dependency.
- Ask before changing database schemas, auth, payments or CI configuration.
- Never delete files, drop data or run destructive commands (`rm -rf`, `git push --force`, `DROP TABLE`) without explicit approval.
- Keep each change under ~200 changed lines where possible; split larger work into steps.

## PHP + Laravel

- Use `php artisan make:*` generators so files land in the conventional place.
- Validate input with Form Request classes, not inline in controllers.
- Use Eloquent relationships and eager load with `with()` to avoid N+1 queries.
- Protect mass assignment with `$fillable` on every model.
- Authorize with Policies and Gates.
- Read config through `config()`; only `config/*.php` files call `env()`.
- Queue slow work (emails, webhooks) with jobs.

## Tailwind CSS v4

- Tailwind v4 is configured in CSS: `@import "tailwindcss";` plus `@theme { ... }` for design tokens. Do not create a `tailwind.config.js` unless the project already has one.
- Use theme tokens (colors, spacing) instead of arbitrary values like `w-[37px]`.
- Build responsive layouts mobile-first with `sm:`, `md:`, `lg:` prefixes.
- Extract repeated class lists into components, not `@apply` chains.
- Support dark mode with the `dark:` variant when the project uses it.

## Stripe payments

- Never trust prices or amounts from the client. Look up Price IDs and amounts on the server.
- Prefer Stripe Checkout or Payment Elements over custom card forms.
- Verify every webhook signature with the raw request body and the endpoint secret.
- Fulfil orders and update subscription status from webhooks, not from the success redirect.
- Make webhook handlers idempotent (store processed event IDs) and use idempotency keys on create calls.
- Use test-mode keys in development. The secret key is server-only.

## Reference docs

- [Laravel docs](https://laravel.com/docs)
- [Tailwind CSS docs](https://tailwindcss.com/docs)
- [Stripe docs](https://docs.stripe.com)

---
description: "Core rules for this project"
alwaysApply: true
---

# this project

A PHP + Laravel + Tailwind CSS v4 + Stripe payments project.

Stack: PHP + Laravel, Tailwind CSS v4, Stripe payments.

## Commands

- Dev server: `composer run dev`
- Migrate: `php artisan migrate`
- Tests: `php artisan test`
- Format: `vendor/bin/pint`
- Forward webhooks locally: `stripe listen --forward-to localhost:3000/api/webhooks/stripe`

## How to work in this repo

- Read the relevant files before editing. Follow the patterns already in the codebase over these generic rules.
- Make the smallest change that solves the task. Do not refactor or reformat unrelated code.
- Before saying a task is done, run the type-check, lint and tests listed under Commands and fix what you broke.
- If requirements are ambiguous, ask one clear question instead of guessing.
- Never commit secrets, API keys or `.env` files. Use env vars and keep `.env.example` up to date.
- Do not add a new dependency when the standard library or an existing dependency already covers it.
- Ask before adding, removing or upgrading any dependency.
- Ask before changing database schemas, auth, payments or CI configuration.
- Never delete files, drop data or run destructive commands (`rm -rf`, `git push --force`, `DROP TABLE`) without explicit approval.
- Keep each change under ~200 changed lines where possible; split larger work into steps.

---
description: "PHP + Laravel conventions: Laravel app with Eloquent."
globs: app/**/*.php, routes/**/*.php, database/**/*.php, resources/views/**/*.blade.php
alwaysApply: false
---

# PHP + Laravel

- Use `php artisan make:*` generators so files land in the conventional place.
- Validate input with Form Request classes, not inline in controllers.
- Use Eloquent relationships and eager load with `with()` to avoid N+1 queries.
- Protect mass assignment with `$fillable` on every model.
- Authorize with Policies and Gates.
- Read config through `config()`; only `config/*.php` files call `env()`.
- Queue slow work (emails, webhooks) with jobs.

Docs: https://laravel.com/docs

---
description: "Tailwind CSS v4 conventions: Utility-first styling with Tailwind CSS v4."
globs: **/*.css, **/*.tsx, **/*.vue, **/*.svelte, **/*.astro, **/*.html, **/*.blade.php, **/*.erb
alwaysApply: false
---

# Tailwind CSS v4

- Tailwind v4 is configured in CSS: `@import "tailwindcss";` plus `@theme { ... }` for design tokens. Do not create a `tailwind.config.js` unless the project already has one.
- Use theme tokens (colors, spacing) instead of arbitrary values like `w-[37px]`.
- Build responsive layouts mobile-first with `sm:`, `md:`, `lg:` prefixes.
- Extract repeated class lists into components, not `@apply` chains.
- Support dark mode with the `dark:` variant when the project uses it.

Docs: https://tailwindcss.com/docs

---
description: "Stripe payments conventions: Payments and subscriptions with Stripe."
globs: **/stripe/**, **/webhooks/**, **/billing/**
alwaysApply: false
---

# Stripe payments

- Never trust prices or amounts from the client. Look up Price IDs and amounts on the server.
- Prefer Stripe Checkout or Payment Elements over custom card forms.
- Verify every webhook signature with the raw request body and the endpoint secret.
- Fulfil orders and update subscription status from webhooks, not from the success redirect.
- Make webhook handlers idempotent (store processed event IDs) and use idempotency keys on create calls.
- Use test-mode keys in development. The secret key is server-only.

Docs: https://docs.stripe.com

# Cursor rules - this project

You are an expert PHP + Laravel, Tailwind CSS v4, Stripe payments engineer working on this codebase. Follow these rules.

## Project

A PHP + Laravel + Tailwind CSS v4 + Stripe payments project.

Stack: PHP + Laravel, Tailwind CSS v4, Stripe payments.

## Commands

- Dev server: `composer run dev`
- Migrate: `php artisan migrate`
- Tests: `php artisan test`
- Format: `vendor/bin/pint`
- Forward webhooks locally: `stripe listen --forward-to localhost:3000/api/webhooks/stripe`

## How to work in this repo

- Read the relevant files before editing. Follow the patterns already in the codebase over these generic rules.
- Make the smallest change that solves the task. Do not refactor or reformat unrelated code.
- Before saying a task is done, run the type-check, lint and tests listed under Commands and fix what you broke.
- If requirements are ambiguous, ask one clear question instead of guessing.
- Never commit secrets, API keys or `.env` files. Use env vars and keep `.env.example` up to date.
- Do not add a new dependency when the standard library or an existing dependency already covers it.
- Ask before adding, removing or upgrading any dependency.
- Ask before changing database schemas, auth, payments or CI configuration.
- Never delete files, drop data or run destructive commands (`rm -rf`, `git push --force`, `DROP TABLE`) without explicit approval.
- Keep each change under ~200 changed lines where possible; split larger work into steps.

## PHP + Laravel

- Use `php artisan make:*` generators so files land in the conventional place.
- Validate input with Form Request classes, not inline in controllers.
- Use Eloquent relationships and eager load with `with()` to avoid N+1 queries.
- Protect mass assignment with `$fillable` on every model.
- Authorize with Policies and Gates.
- Read config through `config()`; only `config/*.php` files call `env()`.
- Queue slow work (emails, webhooks) with jobs.

## Tailwind CSS v4

- Tailwind v4 is configured in CSS: `@import "tailwindcss";` plus `@theme { ... }` for design tokens. Do not create a `tailwind.config.js` unless the project already has one.
- Use theme tokens (colors, spacing) instead of arbitrary values like `w-[37px]`.
- Build responsive layouts mobile-first with `sm:`, `md:`, `lg:` prefixes.
- Extract repeated class lists into components, not `@apply` chains.
- Support dark mode with the `dark:` variant when the project uses it.

## Stripe payments

- Never trust prices or amounts from the client. Look up Price IDs and amounts on the server.
- Prefer Stripe Checkout or Payment Elements over custom card forms.
- Verify every webhook signature with the raw request body and the endpoint secret.
- Fulfil orders and update subscription status from webhooks, not from the success redirect.
- Make webhook handlers idempotent (store processed event IDs) and use idempotency keys on create calls.
- Use test-mode keys in development. The secret key is server-only.

## Reference docs

- [Laravel docs](https://laravel.com/docs)
- [Tailwind CSS docs](https://tailwindcss.com/docs)
- [Stripe docs](https://docs.stripe.com)

# Copilot instructions - this project

A PHP + Laravel + Tailwind CSS v4 + Stripe payments project.

Stack: PHP + Laravel, Tailwind CSS v4, Stripe payments.

## Commands

- Dev server: `composer run dev`
- Migrate: `php artisan migrate`
- Tests: `php artisan test`
- Format: `vendor/bin/pint`
- Forward webhooks locally: `stripe listen --forward-to localhost:3000/api/webhooks/stripe`

## How to work in this repo

- Read the relevant files before editing. Follow the patterns already in the codebase over these generic rules.
- Make the smallest change that solves the task. Do not refactor or reformat unrelated code.
- Before saying a task is done, run the type-check, lint and tests listed under Commands and fix what you broke.
- If requirements are ambiguous, ask one clear question instead of guessing.
- Never commit secrets, API keys or `.env` files. Use env vars and keep `.env.example` up to date.
- Do not add a new dependency when the standard library or an existing dependency already covers it.
- Ask before adding, removing or upgrading any dependency.
- Ask before changing database schemas, auth, payments or CI configuration.
- Never delete files, drop data or run destructive commands (`rm -rf`, `git push --force`, `DROP TABLE`) without explicit approval.
- Keep each change under ~200 changed lines where possible; split larger work into steps.

---
applyTo: "app/**/*.php,routes/**/*.php,database/**/*.php,resources/views/**/*.blade.php"
---

# PHP + Laravel

- Use `php artisan make:*` generators so files land in the conventional place.
- Validate input with Form Request classes, not inline in controllers.
- Use Eloquent relationships and eager load with `with()` to avoid N+1 queries.
- Protect mass assignment with `$fillable` on every model.
- Authorize with Policies and Gates.
- Read config through `config()`; only `config/*.php` files call `env()`.
- Queue slow work (emails, webhooks) with jobs.

---
applyTo: "**/*.css,**/*.tsx,**/*.vue,**/*.svelte,**/*.astro,**/*.html,**/*.blade.php,**/*.erb"
---

# Tailwind CSS v4

- Tailwind v4 is configured in CSS: `@import "tailwindcss";` plus `@theme { ... }` for design tokens. Do not create a `tailwind.config.js` unless the project already has one.
- Use theme tokens (colors, spacing) instead of arbitrary values like `w-[37px]`.
- Build responsive layouts mobile-first with `sm:`, `md:`, `lg:` prefixes.
- Extract repeated class lists into components, not `@apply` chains.
- Support dark mode with the `dark:` variant when the project uses it.

---
applyTo: "**/stripe/**,**/webhooks/**,**/billing/**"
---

# Stripe payments

- Never trust prices or amounts from the client. Look up Price IDs and amounts on the server.
- Prefer Stripe Checkout or Payment Elements over custom card forms.
- Verify every webhook signature with the raw request body and the endpoint secret.
- Fulfil orders and update subscription status from webhooks, not from the success redirect.
- Make webhook handlers idempotent (store processed event IDs) and use idempotency keys on create calls.
- Use test-mode keys in development. The secret key is server-only.

---
trigger: always_on
---

# this project

A PHP + Laravel + Tailwind CSS v4 + Stripe payments project.

Stack: PHP + Laravel, Tailwind CSS v4, Stripe payments.

## Commands

- Dev server: `composer run dev`
- Migrate: `php artisan migrate`
- Tests: `php artisan test`
- Format: `vendor/bin/pint`
- Forward webhooks locally: `stripe listen --forward-to localhost:3000/api/webhooks/stripe`

## How to work in this repo

- Read the relevant files before editing. Follow the patterns already in the codebase over these generic rules.
- Make the smallest change that solves the task. Do not refactor or reformat unrelated code.
- Before saying a task is done, run the type-check, lint and tests listed under Commands and fix what you broke.
- If requirements are ambiguous, ask one clear question instead of guessing.
- Never commit secrets, API keys or `.env` files. Use env vars and keep `.env.example` up to date.
- Do not add a new dependency when the standard library or an existing dependency already covers it.
- Ask before adding, removing or upgrading any dependency.
- Ask before changing database schemas, auth, payments or CI configuration.
- Never delete files, drop data or run destructive commands (`rm -rf`, `git push --force`, `DROP TABLE`) without explicit approval.
- Keep each change under ~200 changed lines where possible; split larger work into steps.

---
trigger: glob
globs: app/**/*.php, routes/**/*.php, database/**/*.php, resources/views/**/*.blade.php
---

# PHP + Laravel

- Use `php artisan make:*` generators so files land in the conventional place.
- Validate input with Form Request classes, not inline in controllers.
- Use Eloquent relationships and eager load with `with()` to avoid N+1 queries.
- Protect mass assignment with `$fillable` on every model.
- Authorize with Policies and Gates.
- Read config through `config()`; only `config/*.php` files call `env()`.
- Queue slow work (emails, webhooks) with jobs.

---
trigger: glob
globs: **/*.css, **/*.tsx, **/*.vue, **/*.svelte, **/*.astro, **/*.html, **/*.blade.php, **/*.erb
---

# Tailwind CSS v4

- Tailwind v4 is configured in CSS: `@import "tailwindcss";` plus `@theme { ... }` for design tokens. Do not create a `tailwind.config.js` unless the project already has one.
- Use theme tokens (colors, spacing) instead of arbitrary values like `w-[37px]`.
- Build responsive layouts mobile-first with `sm:`, `md:`, `lg:` prefixes.
- Extract repeated class lists into components, not `@apply` chains.
- Support dark mode with the `dark:` variant when the project uses it.

---
trigger: glob
globs: **/stripe/**, **/webhooks/**, **/billing/**
---

# Stripe payments

- Never trust prices or amounts from the client. Look up Price IDs and amounts on the server.
- Prefer Stripe Checkout or Payment Elements over custom card forms.
- Verify every webhook signature with the raw request body and the endpoint secret.
- Fulfil orders and update subscription status from webhooks, not from the success redirect.
- Make webhook handlers idempotent (store processed event IDs) and use idempotency keys on create calls.
- Use test-mode keys in development. The secret key is server-only.

# GEMINI.md - this project

Project context for Gemini CLI.

## Project

A PHP + Laravel + Tailwind CSS v4 + Stripe payments project.

Stack: PHP + Laravel, Tailwind CSS v4, Stripe payments.

## Commands

- Dev server: `composer run dev`
- Migrate: `php artisan migrate`
- Tests: `php artisan test`
- Format: `vendor/bin/pint`
- Forward webhooks locally: `stripe listen --forward-to localhost:3000/api/webhooks/stripe`

## How to work in this repo

- Read the relevant files before editing. Follow the patterns already in the codebase over these generic rules.
- Make the smallest change that solves the task. Do not refactor or reformat unrelated code.
- Before saying a task is done, run the type-check, lint and tests listed under Commands and fix what you broke.
- If requirements are ambiguous, ask one clear question instead of guessing.
- Never commit secrets, API keys or `.env` files. Use env vars and keep `.env.example` up to date.
- Do not add a new dependency when the standard library or an existing dependency already covers it.
- Ask before adding, removing or upgrading any dependency.
- Ask before changing database schemas, auth, payments or CI configuration.
- Never delete files, drop data or run destructive commands (`rm -rf`, `git push --force`, `DROP TABLE`) without explicit approval.
- Keep each change under ~200 changed lines where possible; split larger work into steps.

## PHP + Laravel

- Use `php artisan make:*` generators so files land in the conventional place.
- Validate input with Form Request classes, not inline in controllers.
- Use Eloquent relationships and eager load with `with()` to avoid N+1 queries.
- Protect mass assignment with `$fillable` on every model.
- Authorize with Policies and Gates.
- Read config through `config()`; only `config/*.php` files call `env()`.
- Queue slow work (emails, webhooks) with jobs.

## Tailwind CSS v4

- Tailwind v4 is configured in CSS: `@import "tailwindcss";` plus `@theme { ... }` for design tokens. Do not create a `tailwind.config.js` unless the project already has one.
- Use theme tokens (colors, spacing) instead of arbitrary values like `w-[37px]`.
- Build responsive layouts mobile-first with `sm:`, `md:`, `lg:` prefixes.
- Extract repeated class lists into components, not `@apply` chains.
- Support dark mode with the `dark:` variant when the project uses it.

## Stripe payments

- Never trust prices or amounts from the client. Look up Price IDs and amounts on the server.
- Prefer Stripe Checkout or Payment Elements over custom card forms.
- Verify every webhook signature with the raw request body and the endpoint secret.
- Fulfil orders and update subscription status from webhooks, not from the success redirect.
- Make webhook handlers idempotent (store processed event IDs) and use idempotency keys on create calls.
- Use test-mode keys in development. The secret key is server-only.

## Reference docs

- [Laravel docs](https://laravel.com/docs)
- [Tailwind CSS docs](https://tailwindcss.com/docs)
- [Stripe docs](https://docs.stripe.com)