diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..1187914
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,44 @@
+# Repository Guidelines
+
+This document summarizes how to work effectively in this repo.
+
+## Project Structure & Module Organization
+- `src/app`: Next.js App Router (Next 14). Localized routes under `src/app/[locale]`. Global styles in `src/app/globals.css`.
+- `src/components`: Reusable UI in PascalCase (e.g., `Header.tsx`).
+- `src/servers`: Server-side data and actions (DB, search, works APIs).
+- `src/libs`: Integrations and utilities (Stripe, Replicate, R2, DB helpers).
+- `src/configs`: App/third‑party config (e.g., `stripeConfig.ts`, `openaiConfig.ts`).
+- `src/i18n`, `src/context`: Localization and React context.
+- `public`: Static assets. `sql/tables`: PostgreSQL DDL.
+- Path alias: import app modules via `~/*` (see `tsconfig.json`).
+
+## Build, Test, and Development Commands
+- `npm run dev` / `yarn dev`: Start local dev server on port 3000.
+- `npm run build`: Production build (`.next`).
+- `npm start`: Serve the built app.
+- `npx next lint`: Run ESLint checks.
+
+Environment: copy `.env.example` → `.env.local` and fill required keys (Stripe, Replicate webhook URL, Google OAuth, R2, Postgres). For first run, create tables from `sql/tables/*` in your database.
+
+## Coding Style & Naming Conventions
+- TypeScript, React, Next.js App Router.
+- Indentation: 2 spaces; prefer explicit types for public APIs.
+- Components: PascalCase (`MyComponent.tsx`). Hooks: `useX.ts`.
+- Modules/utilities: camelCase (`helpers.ts`), server modules under `src/servers`.
+- Imports: prefer `~/...` alias for internal paths.
+- Linting: ESLint (`extends: next/core-web-vitals`); run `npx next lint --fix` before pushing.
+- Styles: TailwindCSS in components; keep class lists readable and deduplicated.
+
+## Testing Guidelines
+- No formal test framework is configured yet. Perform manual QA for:
+  - Auth flows, payment (Stripe test mode), image generation webhooks (use ngrok for local Replicate webhook), and locale pages.
+- If adding automated tests, prefer Playwright for E2E and React Testing Library for components; place tests adjacent to sources.
+
+## Commit & Pull Request Guidelines
+- Commits: short, imperative subject (e.g., "fix r2 region", "add stripe config"). Group related changes.
+- PRs: clear description, linked issue, steps to validate (commands, URLs), and screenshots for UI changes.
+- Keep changes scoped; update README and configs when behavior or env vars change. Never commit secrets.
+
+## Security & Configuration Tips
+- Store secrets only in `.env.*`. Rotate keys used for local testing. Verify webhook and cron/automation settings if deploying to Vercel.
+