AGENTS.md generator

# AGENTS.md

Guidance for AI coding agents (Cursor, Codex, Claude Code and others) working on this project.

Keep this file short. If something here is wrong, fix the file in the same change.

## Stack

- Next.js App Router + TypeScript (strict). React Server Components by default.
- Tailwind CSS v4 + shadcn/ui.
- Supabase (Postgres) via `@supabase/ssr`.
- Auth: Supabase Auth.
- Stripe (Checkout, Customer Portal, webhooks).
- Zod for input validation.

## Commands

- Install: `npm install`
- Dev server: `npm run dev`
- Lint: `npm run lint`
- Build: `npm run build`
- After schema changes: `supabase migration new <name>`, then regenerate types with `supabase gen types typescript`

## Project map

- `src/app/`: routes, layouts, route handlers (`route.ts`).
- `src/components/`: shared UI (`src/components/ui/` is shadcn/ui, generated).
- `src/lib/`: server utilities and clients (`src/lib/supabase/` for the browser and server clients).
- `supabase/migrations/`: SQL migrations (source of truth for the schema).
- Update this map when you add a top-level folder.

## Conventions

- Server Components by default. Add `"use client"` only for state, effects or browser APIs, and keep client components small.
- Fetch data on the server. Don't call your own route handlers from Server Components.
- Secrets live in env vars on the server. Only `NEXT_PUBLIC_` vars reach the browser, so never put a secret in one.
- Document every new env var in `.env.example`.
- Validate every external input (form data, route params, request bodies, webhook payloads) with Zod on the server.
- Style with Tailwind utility classes. Reuse shadcn/ui components before writing new ones; add them with the shadcn CLI instead of copying code by hand.

## Auth and data access

- Use `createServerClient` (server) and `createBrowserClient` (client) from `@supabase/ssr`. Create a new server client per request.
- On the server, authorize with `supabase.auth.getUser()` or `getClaims()`. Never trust `getSession()` on the server.
- Every table in an exposed schema has Row Level Security enabled with explicit policies. The `service_role` / secret key is server-only and never used for requests made on behalf of a user.
- Middleware/proxy checks are optimistic only. The real authorization check happens next to the data access.
- Check ownership on every read and write of user data (filter by the current user's id).

## Stripe

- Verify webhooks with `stripe.webhooks.constructEvent` on the raw body (`await req.text()`), never parsed JSON.
- Webhooks can arrive twice and out of order: make handlers idempotent and re-fetch the subscription from Stripe before writing.
- Grant access from the database state the webhook writes, not from the Checkout success redirect.
- Never create the Stripe client at module top level with a missing key; builds run without secrets.
- Use test mode keys and the Stripe CLI (`stripe listen`) locally.

## Working rules for agents

- Plan before large changes and list the files you will touch.
- Keep diffs minimal. Don't reformat or rename unrelated code.
- Ask before adding a dependency (`npm install <pkg>`).
- Don't edit generated files, lockfiles or applied migrations by hand.
- Before you finish: `npm run lint` and `npm run build` pass.

## Landmines

- <Add things that broke before, e.g. "the billing page must stay dynamic".>

<!-- Generated with the free AGENTS.md generator at https://vibeboot.dev/tools/agents-md-generator -->

70 lines · generated in your browser, nothing is sent anywhere.