docs: add repository contributor guide

AGENTS.md

@@ -0,0 +1,34 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+
+This repository contains the Next.js application for the Chadebebe wishlist site. App Router routes live in `app/`, including public wishlist pages in `app/[slug]/`, admin screens in `app/admin/`, and API handlers in `app/api/`. Shared UI belongs in `components/`, while server utilities, auth, database access, and scraping helpers live in `lib/`. Drizzle and SQLite data are under `lib/db/` and `data/db/`. Static assets are in `public/`; uploaded runtime assets are stored in `data/uploads/`. Deployment configuration is in the parent project root at `/home/adriano/chadebebe/docker-compose.yaml`, which builds this `src/` directory.
+
+## Build, Test, and Development Commands
+
+Run commands from `src/` unless noted.
+
+- `npm install`: install local dependencies.
+- `npm run dev`: start Next.js locally on port `3000`.
+- `npm run build`: create the production Next.js standalone build.
+- `npm run lint`: run the configured Next.js ESLint command.
+- `npm run db:migrate`: apply Drizzle migrations.
+- `npm run db:studio`: open Drizzle Studio for database inspection.
+- `npm run guest:create -- --name="Name"`: create a guest access token.
+- From `/home/adriano/chadebebe`, `docker compose up -d --build`: rebuild and redeploy the production container.
+
+## Coding Style & Naming Conventions
+
+Use TypeScript, React function components, and the App Router conventions already present in `app/`. Keep indentation at two spaces. Prefer descriptive camelCase for variables/functions, PascalCase for components, and lowercase route directory names. Keep UI copy in Portuguese for user-facing screens. Use Tailwind CSS utility classes for styling and follow existing component patterns before introducing new abstractions.
+
+## Testing Guidelines
+
+There is currently no dedicated test framework or `npm test` script. For changes, run `npm run build` at minimum; use `npm run lint` when dependencies are available. For database or reservation changes, manually exercise the relevant public wishlist and admin flows, including quantity limits, claim/unclaim behavior, and guest-token access.
+
+## Commit & Pull Request Guidelines
+
+Recent history mostly uses Conventional Commit prefixes, such as `feat:`, `fix:`, `docs:`, and `chore:`. Use concise imperative messages, for example `fix: hide disabled reservation action`. Pull requests should include a short summary, verification steps, linked issue if applicable, and screenshots for UI changes. Note any database snapshot or migration changes explicitly.
+
+## Security & Configuration Tips
+
+Do not commit real admin tokens or secrets. Admin access is controlled by `ADMIN_TOKEN`; production deployment also depends on Traefik labels and the external `web` Docker network. Treat `data/db/wishlist.db` as a snapshot and checkpoint SQLite before committing database updates.