Nuxt + Tailwind + Zod rules for AI coding agents

# AGENTS.md - this project

Instructions for AI coding agents working in this repository.

## Project

A Nuxt (Vue 3) + Tailwind CSS v4 + Zod validation project.

Stack: Nuxt (Vue 3), Tailwind CSS v4, Zod validation.

## Commands

- Dev server: `npm run dev`
- Build: `npm run build`
- Type check: `npx nuxi typecheck`

## Project structure

- Pages in `pages/`, components in `components/`, composables in `composables/`, API routes in `server/api/`.
- Nuxt 4 moves app code under `app/`; follow the layout the project already uses.

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

## Nuxt (Vue 3)

- Use `<script setup lang="ts">` and the Composition API.
- Rely on Nuxt auto-imports for Vue, composables and components; do not add manual imports for them.
- Fetch data with `useFetch` or `useAsyncData` so it works with SSR. Avoid raw `fetch` inside `onMounted` for page data.
- Server routes go in `server/api/` using `defineEventHandler`; validate bodies with `readValidatedBody`.
- Secrets go in `runtimeConfig` (server-only keys) and env vars. Only `runtimeConfig.public` reaches the browser.
- Use `useState` for SSR-safe shared state or Pinia for larger stores.

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

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

## Reference docs

- [Nuxt docs](https://nuxt.com/docs)
- [Tailwind CSS docs](https://tailwindcss.com/docs)
- [Zod docs](https://zod.dev)

# CLAUDE.md - this project

Project instructions for Claude Code.

## Project

A Nuxt (Vue 3) + Tailwind CSS v4 + Zod validation project.

Stack: Nuxt (Vue 3), Tailwind CSS v4, Zod validation.

## Commands

- Dev server: `npm run dev`
- Build: `npm run build`
- Type check: `npx nuxi typecheck`

## Project structure

- Pages in `pages/`, components in `components/`, composables in `composables/`, API routes in `server/api/`.
- Nuxt 4 moves app code under `app/`; follow the layout the project already uses.

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

## Nuxt (Vue 3)

- Use `<script setup lang="ts">` and the Composition API.
- Rely on Nuxt auto-imports for Vue, composables and components; do not add manual imports for them.
- Fetch data with `useFetch` or `useAsyncData` so it works with SSR. Avoid raw `fetch` inside `onMounted` for page data.
- Server routes go in `server/api/` using `defineEventHandler`; validate bodies with `readValidatedBody`.
- Secrets go in `runtimeConfig` (server-only keys) and env vars. Only `runtimeConfig.public` reaches the browser.
- Use `useState` for SSR-safe shared state or Pinia for larger stores.

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

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

## Reference docs

- [Nuxt docs](https://nuxt.com/docs)
- [Tailwind CSS docs](https://tailwindcss.com/docs)
- [Zod docs](https://zod.dev)

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

# this project

A Nuxt (Vue 3) + Tailwind CSS v4 + Zod validation project.

Stack: Nuxt (Vue 3), Tailwind CSS v4, Zod validation.

## Commands

- Dev server: `npm run dev`
- Build: `npm run build`
- Type check: `npx nuxi typecheck`

## 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: "Nuxt (Vue 3) conventions: Nuxt full-stack Vue 3 app with TypeScript."
globs: **/*.vue, server/**/*.ts, composables/**/*.ts, app/**/*.ts
alwaysApply: false
---

# Nuxt (Vue 3)

- Use `<script setup lang="ts">` and the Composition API.
- Rely on Nuxt auto-imports for Vue, composables and components; do not add manual imports for them.
- Fetch data with `useFetch` or `useAsyncData` so it works with SSR. Avoid raw `fetch` inside `onMounted` for page data.
- Server routes go in `server/api/` using `defineEventHandler`; validate bodies with `readValidatedBody`.
- Secrets go in `runtimeConfig` (server-only keys) and env vars. Only `runtimeConfig.public` reaches the browser.
- Use `useState` for SSR-safe shared state or Pinia for larger stores.

Docs: https://nuxt.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: "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 Nuxt (Vue 3), Tailwind CSS v4, Zod validation engineer working on this codebase. Follow these rules.

## Project

A Nuxt (Vue 3) + Tailwind CSS v4 + Zod validation project.

Stack: Nuxt (Vue 3), Tailwind CSS v4, Zod validation.

## Commands

- Dev server: `npm run dev`
- Build: `npm run build`
- Type check: `npx nuxi typecheck`

## Project structure

- Pages in `pages/`, components in `components/`, composables in `composables/`, API routes in `server/api/`.
- Nuxt 4 moves app code under `app/`; follow the layout the project already uses.

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

## Nuxt (Vue 3)

- Use `<script setup lang="ts">` and the Composition API.
- Rely on Nuxt auto-imports for Vue, composables and components; do not add manual imports for them.
- Fetch data with `useFetch` or `useAsyncData` so it works with SSR. Avoid raw `fetch` inside `onMounted` for page data.
- Server routes go in `server/api/` using `defineEventHandler`; validate bodies with `readValidatedBody`.
- Secrets go in `runtimeConfig` (server-only keys) and env vars. Only `runtimeConfig.public` reaches the browser.
- Use `useState` for SSR-safe shared state or Pinia for larger stores.

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

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

## Reference docs

- [Nuxt docs](https://nuxt.com/docs)
- [Tailwind CSS docs](https://tailwindcss.com/docs)
- [Zod docs](https://zod.dev)

# Copilot instructions - this project

A Nuxt (Vue 3) + Tailwind CSS v4 + Zod validation project.

Stack: Nuxt (Vue 3), Tailwind CSS v4, Zod validation.

## Commands

- Dev server: `npm run dev`
- Build: `npm run build`
- Type check: `npx nuxi typecheck`

## 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: "**/*.vue,server/**/*.ts,composables/**/*.ts,app/**/*.ts"
---

# Nuxt (Vue 3)

- Use `<script setup lang="ts">` and the Composition API.
- Rely on Nuxt auto-imports for Vue, composables and components; do not add manual imports for them.
- Fetch data with `useFetch` or `useAsyncData` so it works with SSR. Avoid raw `fetch` inside `onMounted` for page data.
- Server routes go in `server/api/` using `defineEventHandler`; validate bodies with `readValidatedBody`.
- Secrets go in `runtimeConfig` (server-only keys) and env vars. Only `runtimeConfig.public` reaches the browser.
- Use `useState` for SSR-safe shared state or Pinia for larger stores.

---
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: "**/*.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 Nuxt (Vue 3) + Tailwind CSS v4 + Zod validation project.

Stack: Nuxt (Vue 3), Tailwind CSS v4, Zod validation.

## Commands

- Dev server: `npm run dev`
- Build: `npm run build`
- Type check: `npx nuxi typecheck`

## 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: **/*.vue, server/**/*.ts, composables/**/*.ts, app/**/*.ts
---

# Nuxt (Vue 3)

- Use `<script setup lang="ts">` and the Composition API.
- Rely on Nuxt auto-imports for Vue, composables and components; do not add manual imports for them.
- Fetch data with `useFetch` or `useAsyncData` so it works with SSR. Avoid raw `fetch` inside `onMounted` for page data.
- Server routes go in `server/api/` using `defineEventHandler`; validate bodies with `readValidatedBody`.
- Secrets go in `runtimeConfig` (server-only keys) and env vars. Only `runtimeConfig.public` reaches the browser.
- Use `useState` for SSR-safe shared state or Pinia for larger stores.

---
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: **/*.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 Nuxt (Vue 3) + Tailwind CSS v4 + Zod validation project.

Stack: Nuxt (Vue 3), Tailwind CSS v4, Zod validation.

## Commands

- Dev server: `npm run dev`
- Build: `npm run build`
- Type check: `npx nuxi typecheck`

## Project structure

- Pages in `pages/`, components in `components/`, composables in `composables/`, API routes in `server/api/`.
- Nuxt 4 moves app code under `app/`; follow the layout the project already uses.

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

## Nuxt (Vue 3)

- Use `<script setup lang="ts">` and the Composition API.
- Rely on Nuxt auto-imports for Vue, composables and components; do not add manual imports for them.
- Fetch data with `useFetch` or `useAsyncData` so it works with SSR. Avoid raw `fetch` inside `onMounted` for page data.
- Server routes go in `server/api/` using `defineEventHandler`; validate bodies with `readValidatedBody`.
- Secrets go in `runtimeConfig` (server-only keys) and env vars. Only `runtimeConfig.public` reaches the browser.
- Use `useState` for SSR-safe shared state or Pinia for larger stores.

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

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

## Reference docs

- [Nuxt docs](https://nuxt.com/docs)
- [Tailwind CSS docs](https://tailwindcss.com/docs)
- [Zod docs](https://zod.dev)