Next.js + Supabase + shadcn rules for AI coding agents

# AGENTS.md - this project

Instructions for AI coding agents working in this repository.

## Project

A Next.js (App Router) + Tailwind CSS v4 + shadcn/ui + Supabase + Zod validation project.

Stack: Next.js (App Router), Tailwind CSS v4, shadcn/ui, Supabase, Zod validation.

## Commands

- Dev server: `npm run dev`
- Production build (also type-checks): `npm run build`
- Lint: `npm run lint`
- Add a component: `npx shadcn@latest add <component>`
- New migration: `npx supabase migration new <name>`
- Generate TS types: `npx supabase gen types typescript --local > types/supabase.ts`

## Project structure

- `app/` holds routes: `page.tsx`, `layout.tsx`, `loading.tsx`, `error.tsx`, `route.ts` for API handlers.
- Shared UI in `components/`, server-only helpers in `lib/` (mark them with `import "server-only"`).

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

## Next.js (App Router)

- Check the Next.js major version in `package.json` before using an API; follow the docs for that version.
- Components are Server Components by default. Add `"use client"` only to the smallest leaf component that needs state, effects, or browser APIs.
- Fetch data in Server Components or Server Actions, not in `useEffect`.
- In Next.js 15+, `params`, `searchParams`, `cookies()` and `headers()` are async: always `await` them.
- Mutations go through Server Actions (`"use server"`) or `route.ts` handlers. Validate every input on the server and re-check auth inside the action.
- After a mutation, call `revalidatePath()` or `revalidateTag()` instead of forcing the whole route dynamic.
- Use `next/image` for images, `next/font` for fonts and `next/link` for internal links.
- Export `metadata` or `generateMetadata` from every page for title, description and Open Graph tags.
- Only variables prefixed `NEXT_PUBLIC_` reach the browser. Never put secrets in them.
- In Next.js 16, `middleware.ts` is renamed `proxy.ts`. Use whichever file the project already has.

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

## shadcn/ui

- Before building a UI primitive, check whether a shadcn/ui component exists and add it with `npx shadcn@latest add <component>`.
- Components live in `components/ui/` and are owned code: customize them there rather than wrapping them in more layers.
- Merge class names with the `cn()` helper from `lib/utils`.
- Keep accessibility props from Radix (labels, `aria-*`, focus handling) intact.

## Supabase

- Enable Row Level Security on every table and write explicit policies. No table ships without RLS.
- The anon/publishable key is public. The `service_role`/secret key bypasses RLS: use it only in trusted server code, never in the client.
- Change the schema with migration files in `supabase/migrations/`, not by clicking in the dashboard.
- On the server, verify the user with `supabase.auth.getUser()` (or `getClaims()`); do not trust `getSession()` alone for authorization.
- In SSR frameworks use `@supabase/ssr` (`createServerClient` / `createBrowserClient`), not the deprecated auth-helpers packages.
- Regenerate database types after each migration and type the client with them.

## Zod validation

- Validate all untrusted input (request bodies, form data, env vars, third-party API responses) with a Zod schema at the boundary.
- Derive TypeScript types from schemas with `z.infer<typeof schema>`; do not hand-write duplicate types.
- Use `safeParse` where you need to return validation errors to the user.

## Avoid

- Do not add `"use client"` to layouts or pages just to silence an error; move the interactive part into a child component.
- Do not use the Pages Router (`pages/`) APIs such as `getServerSideProps` in an App Router project.

## Reference docs

- [Next.js docs](https://nextjs.org/docs)
- [Tailwind CSS docs](https://tailwindcss.com/docs)
- [shadcn/ui docs](https://ui.shadcn.com/docs)
- [Supabase docs](https://supabase.com/docs)
- [Zod docs](https://zod.dev)

# CLAUDE.md - this project

Project instructions for Claude Code.

## Project

A Next.js (App Router) + Tailwind CSS v4 + shadcn/ui + Supabase + Zod validation project.

Stack: Next.js (App Router), Tailwind CSS v4, shadcn/ui, Supabase, Zod validation.

## Commands

- Dev server: `npm run dev`
- Production build (also type-checks): `npm run build`
- Lint: `npm run lint`
- Add a component: `npx shadcn@latest add <component>`
- New migration: `npx supabase migration new <name>`
- Generate TS types: `npx supabase gen types typescript --local > types/supabase.ts`

## Project structure

- `app/` holds routes: `page.tsx`, `layout.tsx`, `loading.tsx`, `error.tsx`, `route.ts` for API handlers.
- Shared UI in `components/`, server-only helpers in `lib/` (mark them with `import "server-only"`).

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

## Next.js (App Router)

- Check the Next.js major version in `package.json` before using an API; follow the docs for that version.
- Components are Server Components by default. Add `"use client"` only to the smallest leaf component that needs state, effects, or browser APIs.
- Fetch data in Server Components or Server Actions, not in `useEffect`.
- In Next.js 15+, `params`, `searchParams`, `cookies()` and `headers()` are async: always `await` them.
- Mutations go through Server Actions (`"use server"`) or `route.ts` handlers. Validate every input on the server and re-check auth inside the action.
- After a mutation, call `revalidatePath()` or `revalidateTag()` instead of forcing the whole route dynamic.
- Use `next/image` for images, `next/font` for fonts and `next/link` for internal links.
- Export `metadata` or `generateMetadata` from every page for title, description and Open Graph tags.
- Only variables prefixed `NEXT_PUBLIC_` reach the browser. Never put secrets in them.
- In Next.js 16, `middleware.ts` is renamed `proxy.ts`. Use whichever file the project already has.

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

## shadcn/ui

- Before building a UI primitive, check whether a shadcn/ui component exists and add it with `npx shadcn@latest add <component>`.
- Components live in `components/ui/` and are owned code: customize them there rather than wrapping them in more layers.
- Merge class names with the `cn()` helper from `lib/utils`.
- Keep accessibility props from Radix (labels, `aria-*`, focus handling) intact.

## Supabase

- Enable Row Level Security on every table and write explicit policies. No table ships without RLS.
- The anon/publishable key is public. The `service_role`/secret key bypasses RLS: use it only in trusted server code, never in the client.
- Change the schema with migration files in `supabase/migrations/`, not by clicking in the dashboard.
- On the server, verify the user with `supabase.auth.getUser()` (or `getClaims()`); do not trust `getSession()` alone for authorization.
- In SSR frameworks use `@supabase/ssr` (`createServerClient` / `createBrowserClient`), not the deprecated auth-helpers packages.
- Regenerate database types after each migration and type the client with them.

## Zod validation

- Validate all untrusted input (request bodies, form data, env vars, third-party API responses) with a Zod schema at the boundary.
- Derive TypeScript types from schemas with `z.infer<typeof schema>`; do not hand-write duplicate types.
- Use `safeParse` where you need to return validation errors to the user.

## Avoid

- Do not add `"use client"` to layouts or pages just to silence an error; move the interactive part into a child component.
- Do not use the Pages Router (`pages/`) APIs such as `getServerSideProps` in an App Router project.

## Reference docs

- [Next.js docs](https://nextjs.org/docs)
- [Tailwind CSS docs](https://tailwindcss.com/docs)
- [shadcn/ui docs](https://ui.shadcn.com/docs)
- [Supabase docs](https://supabase.com/docs)
- [Zod docs](https://zod.dev)

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

# this project

A Next.js (App Router) + Tailwind CSS v4 + shadcn/ui + Supabase + Zod validation project.

Stack: Next.js (App Router), Tailwind CSS v4, shadcn/ui, Supabase, Zod validation.

## Commands

- Dev server: `npm run dev`
- Production build (also type-checks): `npm run build`
- Lint: `npm run lint`
- Add a component: `npx shadcn@latest add <component>`
- New migration: `npx supabase migration new <name>`
- Generate TS types: `npx supabase gen types typescript --local > types/supabase.ts`

## 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: "Next.js (App Router) conventions: Next.js App Router with React Server Components and TypeScript."
globs: app/**/*.tsx, app/**/*.ts, src/**/*.tsx, src/**/*.ts
alwaysApply: false
---

# Next.js (App Router)

- Check the Next.js major version in `package.json` before using an API; follow the docs for that version.
- Components are Server Components by default. Add `"use client"` only to the smallest leaf component that needs state, effects, or browser APIs.
- Fetch data in Server Components or Server Actions, not in `useEffect`.
- In Next.js 15+, `params`, `searchParams`, `cookies()` and `headers()` are async: always `await` them.
- Mutations go through Server Actions (`"use server"`) or `route.ts` handlers. Validate every input on the server and re-check auth inside the action.
- After a mutation, call `revalidatePath()` or `revalidateTag()` instead of forcing the whole route dynamic.
- Use `next/image` for images, `next/font` for fonts and `next/link` for internal links.
- Export `metadata` or `generateMetadata` from every page for title, description and Open Graph tags.
- Only variables prefixed `NEXT_PUBLIC_` reach the browser. Never put secrets in them.
- In Next.js 16, `middleware.ts` is renamed `proxy.ts`. Use whichever file the project already has.

## Avoid

- Do not add `"use client"` to layouts or pages just to silence an error; move the interactive part into a child component.
- Do not use the Pages Router (`pages/`) APIs such as `getServerSideProps` in an App Router project.

Docs: https://nextjs.org/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: "shadcn/ui conventions: Copy-in React components built on Radix and Tailwind."
globs: components/ui/**/*.tsx, src/components/ui/**/*.tsx
alwaysApply: false
---

# shadcn/ui

- Before building a UI primitive, check whether a shadcn/ui component exists and add it with `npx shadcn@latest add <component>`.
- Components live in `components/ui/` and are owned code: customize them there rather than wrapping them in more layers.
- Merge class names with the `cn()` helper from `lib/utils`.
- Keep accessibility props from Radix (labels, `aria-*`, focus handling) intact.

Docs: https://ui.shadcn.com/docs

---
description: "Supabase conventions: Postgres, auth and storage from Supabase."
globs: supabase/**, **/supabase/**/*.ts, lib/supabase/**
alwaysApply: false
---

# Supabase

- Enable Row Level Security on every table and write explicit policies. No table ships without RLS.
- The anon/publishable key is public. The `service_role`/secret key bypasses RLS: use it only in trusted server code, never in the client.
- Change the schema with migration files in `supabase/migrations/`, not by clicking in the dashboard.
- On the server, verify the user with `supabase.auth.getUser()` (or `getClaims()`); do not trust `getSession()` alone for authorization.
- In SSR frameworks use `@supabase/ssr` (`createServerClient` / `createBrowserClient`), not the deprecated auth-helpers packages.
- Regenerate database types after each migration and type the client with them.

Docs: https://supabase.com/docs

---
description: "Zod validation conventions: Runtime schema validation with Zod."
globs: **/*.ts, **/*.tsx
alwaysApply: false
---

# Zod validation

- Validate all untrusted input (request bodies, form data, env vars, third-party API responses) with a Zod schema at the boundary.
- Derive TypeScript types from schemas with `z.infer<typeof schema>`; do not hand-write duplicate types.
- Use `safeParse` where you need to return validation errors to the user.

Docs: https://zod.dev

# Cursor rules - this project

You are an expert Next.js (App Router), Tailwind CSS v4, shadcn/ui, Supabase, Zod validation engineer working on this codebase. Follow these rules.

## Project

A Next.js (App Router) + Tailwind CSS v4 + shadcn/ui + Supabase + Zod validation project.

Stack: Next.js (App Router), Tailwind CSS v4, shadcn/ui, Supabase, Zod validation.

## Commands

- Dev server: `npm run dev`
- Production build (also type-checks): `npm run build`
- Lint: `npm run lint`
- Add a component: `npx shadcn@latest add <component>`
- New migration: `npx supabase migration new <name>`
- Generate TS types: `npx supabase gen types typescript --local > types/supabase.ts`

## Project structure

- `app/` holds routes: `page.tsx`, `layout.tsx`, `loading.tsx`, `error.tsx`, `route.ts` for API handlers.
- Shared UI in `components/`, server-only helpers in `lib/` (mark them with `import "server-only"`).

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

## Next.js (App Router)

- Check the Next.js major version in `package.json` before using an API; follow the docs for that version.
- Components are Server Components by default. Add `"use client"` only to the smallest leaf component that needs state, effects, or browser APIs.
- Fetch data in Server Components or Server Actions, not in `useEffect`.
- In Next.js 15+, `params`, `searchParams`, `cookies()` and `headers()` are async: always `await` them.
- Mutations go through Server Actions (`"use server"`) or `route.ts` handlers. Validate every input on the server and re-check auth inside the action.
- After a mutation, call `revalidatePath()` or `revalidateTag()` instead of forcing the whole route dynamic.
- Use `next/image` for images, `next/font` for fonts and `next/link` for internal links.
- Export `metadata` or `generateMetadata` from every page for title, description and Open Graph tags.
- Only variables prefixed `NEXT_PUBLIC_` reach the browser. Never put secrets in them.
- In Next.js 16, `middleware.ts` is renamed `proxy.ts`. Use whichever file the project already has.

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

## shadcn/ui

- Before building a UI primitive, check whether a shadcn/ui component exists and add it with `npx shadcn@latest add <component>`.
- Components live in `components/ui/` and are owned code: customize them there rather than wrapping them in more layers.
- Merge class names with the `cn()` helper from `lib/utils`.
- Keep accessibility props from Radix (labels, `aria-*`, focus handling) intact.

## Supabase

- Enable Row Level Security on every table and write explicit policies. No table ships without RLS.
- The anon/publishable key is public. The `service_role`/secret key bypasses RLS: use it only in trusted server code, never in the client.
- Change the schema with migration files in `supabase/migrations/`, not by clicking in the dashboard.
- On the server, verify the user with `supabase.auth.getUser()` (or `getClaims()`); do not trust `getSession()` alone for authorization.
- In SSR frameworks use `@supabase/ssr` (`createServerClient` / `createBrowserClient`), not the deprecated auth-helpers packages.
- Regenerate database types after each migration and type the client with them.

## Zod validation

- Validate all untrusted input (request bodies, form data, env vars, third-party API responses) with a Zod schema at the boundary.
- Derive TypeScript types from schemas with `z.infer<typeof schema>`; do not hand-write duplicate types.
- Use `safeParse` where you need to return validation errors to the user.

## Avoid

- Do not add `"use client"` to layouts or pages just to silence an error; move the interactive part into a child component.
- Do not use the Pages Router (`pages/`) APIs such as `getServerSideProps` in an App Router project.

## Reference docs

- [Next.js docs](https://nextjs.org/docs)
- [Tailwind CSS docs](https://tailwindcss.com/docs)
- [shadcn/ui docs](https://ui.shadcn.com/docs)
- [Supabase docs](https://supabase.com/docs)
- [Zod docs](https://zod.dev)

# Copilot instructions - this project

A Next.js (App Router) + Tailwind CSS v4 + shadcn/ui + Supabase + Zod validation project.

Stack: Next.js (App Router), Tailwind CSS v4, shadcn/ui, Supabase, Zod validation.

## Commands

- Dev server: `npm run dev`
- Production build (also type-checks): `npm run build`
- Lint: `npm run lint`
- Add a component: `npx shadcn@latest add <component>`
- New migration: `npx supabase migration new <name>`
- Generate TS types: `npx supabase gen types typescript --local > types/supabase.ts`

## 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/**/*.tsx,app/**/*.ts,src/**/*.tsx,src/**/*.ts"
---

# Next.js (App Router)

- Check the Next.js major version in `package.json` before using an API; follow the docs for that version.
- Components are Server Components by default. Add `"use client"` only to the smallest leaf component that needs state, effects, or browser APIs.
- Fetch data in Server Components or Server Actions, not in `useEffect`.
- In Next.js 15+, `params`, `searchParams`, `cookies()` and `headers()` are async: always `await` them.
- Mutations go through Server Actions (`"use server"`) or `route.ts` handlers. Validate every input on the server and re-check auth inside the action.
- After a mutation, call `revalidatePath()` or `revalidateTag()` instead of forcing the whole route dynamic.
- Use `next/image` for images, `next/font` for fonts and `next/link` for internal links.
- Export `metadata` or `generateMetadata` from every page for title, description and Open Graph tags.
- Only variables prefixed `NEXT_PUBLIC_` reach the browser. Never put secrets in them.
- In Next.js 16, `middleware.ts` is renamed `proxy.ts`. Use whichever file the project already has.

---
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: "components/ui/**/*.tsx,src/components/ui/**/*.tsx"
---

# shadcn/ui

- Before building a UI primitive, check whether a shadcn/ui component exists and add it with `npx shadcn@latest add <component>`.
- Components live in `components/ui/` and are owned code: customize them there rather than wrapping them in more layers.
- Merge class names with the `cn()` helper from `lib/utils`.
- Keep accessibility props from Radix (labels, `aria-*`, focus handling) intact.

---
applyTo: "supabase/**,**/supabase/**/*.ts,lib/supabase/**"
---

# Supabase

- Enable Row Level Security on every table and write explicit policies. No table ships without RLS.
- The anon/publishable key is public. The `service_role`/secret key bypasses RLS: use it only in trusted server code, never in the client.
- Change the schema with migration files in `supabase/migrations/`, not by clicking in the dashboard.
- On the server, verify the user with `supabase.auth.getUser()` (or `getClaims()`); do not trust `getSession()` alone for authorization.
- In SSR frameworks use `@supabase/ssr` (`createServerClient` / `createBrowserClient`), not the deprecated auth-helpers packages.
- Regenerate database types after each migration and type the client with them.

---
applyTo: "**/*.ts,**/*.tsx"
---

# Zod validation

- Validate all untrusted input (request bodies, form data, env vars, third-party API responses) with a Zod schema at the boundary.
- Derive TypeScript types from schemas with `z.infer<typeof schema>`; do not hand-write duplicate types.
- Use `safeParse` where you need to return validation errors to the user.

---
trigger: always_on
---

# this project

A Next.js (App Router) + Tailwind CSS v4 + shadcn/ui + Supabase + Zod validation project.

Stack: Next.js (App Router), Tailwind CSS v4, shadcn/ui, Supabase, Zod validation.

## Commands

- Dev server: `npm run dev`
- Production build (also type-checks): `npm run build`
- Lint: `npm run lint`
- Add a component: `npx shadcn@latest add <component>`
- New migration: `npx supabase migration new <name>`
- Generate TS types: `npx supabase gen types typescript --local > types/supabase.ts`

## 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/**/*.tsx, app/**/*.ts, src/**/*.tsx, src/**/*.ts
---

# Next.js (App Router)

- Check the Next.js major version in `package.json` before using an API; follow the docs for that version.
- Components are Server Components by default. Add `"use client"` only to the smallest leaf component that needs state, effects, or browser APIs.
- Fetch data in Server Components or Server Actions, not in `useEffect`.
- In Next.js 15+, `params`, `searchParams`, `cookies()` and `headers()` are async: always `await` them.
- Mutations go through Server Actions (`"use server"`) or `route.ts` handlers. Validate every input on the server and re-check auth inside the action.
- After a mutation, call `revalidatePath()` or `revalidateTag()` instead of forcing the whole route dynamic.
- Use `next/image` for images, `next/font` for fonts and `next/link` for internal links.
- Export `metadata` or `generateMetadata` from every page for title, description and Open Graph tags.
- Only variables prefixed `NEXT_PUBLIC_` reach the browser. Never put secrets in them.
- In Next.js 16, `middleware.ts` is renamed `proxy.ts`. Use whichever file the project already has.

---
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: components/ui/**/*.tsx, src/components/ui/**/*.tsx
---

# shadcn/ui

- Before building a UI primitive, check whether a shadcn/ui component exists and add it with `npx shadcn@latest add <component>`.
- Components live in `components/ui/` and are owned code: customize them there rather than wrapping them in more layers.
- Merge class names with the `cn()` helper from `lib/utils`.
- Keep accessibility props from Radix (labels, `aria-*`, focus handling) intact.

---
trigger: glob
globs: supabase/**, **/supabase/**/*.ts, lib/supabase/**
---

# Supabase

- Enable Row Level Security on every table and write explicit policies. No table ships without RLS.
- The anon/publishable key is public. The `service_role`/secret key bypasses RLS: use it only in trusted server code, never in the client.
- Change the schema with migration files in `supabase/migrations/`, not by clicking in the dashboard.
- On the server, verify the user with `supabase.auth.getUser()` (or `getClaims()`); do not trust `getSession()` alone for authorization.
- In SSR frameworks use `@supabase/ssr` (`createServerClient` / `createBrowserClient`), not the deprecated auth-helpers packages.
- Regenerate database types after each migration and type the client with them.

---
trigger: glob
globs: **/*.ts, **/*.tsx
---

# Zod validation

- Validate all untrusted input (request bodies, form data, env vars, third-party API responses) with a Zod schema at the boundary.
- Derive TypeScript types from schemas with `z.infer<typeof schema>`; do not hand-write duplicate types.
- Use `safeParse` where you need to return validation errors to the user.

# GEMINI.md - this project

Project context for Gemini CLI.

## Project

A Next.js (App Router) + Tailwind CSS v4 + shadcn/ui + Supabase + Zod validation project.

Stack: Next.js (App Router), Tailwind CSS v4, shadcn/ui, Supabase, Zod validation.

## Commands

- Dev server: `npm run dev`
- Production build (also type-checks): `npm run build`
- Lint: `npm run lint`
- Add a component: `npx shadcn@latest add <component>`
- New migration: `npx supabase migration new <name>`
- Generate TS types: `npx supabase gen types typescript --local > types/supabase.ts`

## Project structure

- `app/` holds routes: `page.tsx`, `layout.tsx`, `loading.tsx`, `error.tsx`, `route.ts` for API handlers.
- Shared UI in `components/`, server-only helpers in `lib/` (mark them with `import "server-only"`).

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

## Next.js (App Router)

- Check the Next.js major version in `package.json` before using an API; follow the docs for that version.
- Components are Server Components by default. Add `"use client"` only to the smallest leaf component that needs state, effects, or browser APIs.
- Fetch data in Server Components or Server Actions, not in `useEffect`.
- In Next.js 15+, `params`, `searchParams`, `cookies()` and `headers()` are async: always `await` them.
- Mutations go through Server Actions (`"use server"`) or `route.ts` handlers. Validate every input on the server and re-check auth inside the action.
- After a mutation, call `revalidatePath()` or `revalidateTag()` instead of forcing the whole route dynamic.
- Use `next/image` for images, `next/font` for fonts and `next/link` for internal links.
- Export `metadata` or `generateMetadata` from every page for title, description and Open Graph tags.
- Only variables prefixed `NEXT_PUBLIC_` reach the browser. Never put secrets in them.
- In Next.js 16, `middleware.ts` is renamed `proxy.ts`. Use whichever file the project already has.

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

## shadcn/ui

- Before building a UI primitive, check whether a shadcn/ui component exists and add it with `npx shadcn@latest add <component>`.
- Components live in `components/ui/` and are owned code: customize them there rather than wrapping them in more layers.
- Merge class names with the `cn()` helper from `lib/utils`.
- Keep accessibility props from Radix (labels, `aria-*`, focus handling) intact.

## Supabase

- Enable Row Level Security on every table and write explicit policies. No table ships without RLS.
- The anon/publishable key is public. The `service_role`/secret key bypasses RLS: use it only in trusted server code, never in the client.
- Change the schema with migration files in `supabase/migrations/`, not by clicking in the dashboard.
- On the server, verify the user with `supabase.auth.getUser()` (or `getClaims()`); do not trust `getSession()` alone for authorization.
- In SSR frameworks use `@supabase/ssr` (`createServerClient` / `createBrowserClient`), not the deprecated auth-helpers packages.
- Regenerate database types after each migration and type the client with them.

## Zod validation

- Validate all untrusted input (request bodies, form data, env vars, third-party API responses) with a Zod schema at the boundary.
- Derive TypeScript types from schemas with `z.infer<typeof schema>`; do not hand-write duplicate types.
- Use `safeParse` where you need to return validation errors to the user.

## Avoid

- Do not add `"use client"` to layouts or pages just to silence an error; move the interactive part into a child component.
- Do not use the Pages Router (`pages/`) APIs such as `getServerSideProps` in an App Router project.

## Reference docs

- [Next.js docs](https://nextjs.org/docs)
- [Tailwind CSS docs](https://tailwindcss.com/docs)
- [shadcn/ui docs](https://ui.shadcn.com/docs)
- [Supabase docs](https://supabase.com/docs)
- [Zod docs](https://zod.dev)