dticket.tootaio.com/AGENTS.md

Repository Guidelines

Project Structure & Module Organization

This is a Nuxt 4 dinner ticket system using Vue, Nitro, PostgreSQL, Redis, Tailwind CSS, and Nuxt UI. Frontend code lives under app/: pages, components, layouts, composables, middleware, and global styles. Server code lives under server/: API handlers in server/api, startup plugins in server/plugins, and database/auth/session helpers in server/utils. Shared TypeScript helpers live in shared/; static assets in public/.

Build, Test, and Development Commands

• pnpm install: install dependencies using the pinned pnpm version.
• pnpm dev: start the Nuxt development server.
• pnpm build: build the production Nitro app.
• pnpm preview or pnpm start: preview or run the built app.
• docker compose up --build: start the app with PostgreSQL and Redis.
• docker compose -f docker-compose.yml -f docker-compose.dev.yml up --build: run the Docker hot-reload stack.

Coding Style & Naming Conventions

Use TypeScript, Vue single-file components, and existing Nuxt conventions. Match the current style: 2-space indentation, single quotes, no semicolons, and explicit helpers. Name Nitro handlers by route and method, such as server/api/bookings.get.ts or server/api/public/bookings/[token]/confirm.post.ts. Keep server-only logic in server/utils, browser-facing logic in app/composables, and shared validation or formatting in shared/. Prefer Nuxt UI and Tailwind utilities over custom CSS unless styling is global.

Testing Guidelines

No dedicated unit test framework is configured yet. pnpm build is the current verification gate, but agents should not run tests or builds in WSL unless explicitly asked; the maintainer will run them and report failures. For PostgreSQL, Redis, sessions, WebAuthn, or WhatsApp changes, verify with Docker and GET /api/health. If tests are added later, place them near the covered feature and document the command.

Commit & Pull Request Guidelines

The Git history follows Conventional Commit-style messages, commonly feat(scope): summary, fix(scope): summary, refactor(scope): summary, and build: summary. Use scopes like bookings, auth, users, i18n, or receipt. Pull requests should include a concise description, verification steps, linked issues when applicable, and screenshots for UI changes. Note required .env changes, migrations, or Docker impacts.

Security & Configuration Tips

Create local configuration from .env.example. Do not commit secrets, session keys, database URLs with credentials, or WhatsApp tokens. Keep NUXT_PUBLIC_APP_URL aligned with the browser origin because WebAuthn requires a stable relying-party origin.

UI Safety Rules (CRITICAL)

User-facing UI must NEVER contain:

• prompts
• remarks
• planning notes
• debug messages
• explanations of what was changed
• internal field names like debug, meta, internal

Agent-Specific Instructions

Keep implementations concise and scoped to the requested behavior. Prefer the smallest code change that fits existing patterns, and avoid unrelated refactors, formatting churn, or broad rewrites.