diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 000000000..f63b2c9ec
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,59 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+
+The repository contains three main modules:
+- **`surfsense_web/`**: Next.js 15 frontend with TypeScript
+  - `app/`: App router pages and layouts
+  - `components/`: React components organized by feature
+  - `atoms/`: Jotai atoms for state management
+  - `lib/apis/`: API service layer with Zod validation
+  - `hooks/`: Custom React hooks (being migrated to jotai+tanstack)
+  - `contracts/types/`: Zod schemas and TypeScript types
+- **`surfsense_backend/`**: FastAPI Python backend
+- **`surfsense_browser_extension/`**: Browser extension
+
+## Build, Test, and Development Commands
+
+**Web Frontend** (from `surfsense_web/`):
+```bash
+pnpm install        # Install dependencies
+pnpm dev           # Start development server
+pnpm build         # Production build
+pnpm format        # Format code with Biome
+```
+
+## Coding Style & Naming Conventions
+
+- **TypeScript**: Use tabs for indentation, arrow functions preferred
+- **Files**: kebab-case (e.g., `llm-config-api.service.ts`)
+- **Types**: PascalCase with Zod schemas, infer types at end of file
+- **Atoms**: Descriptive names with "Atom" suffix (e.g., `documentsAtom`, `createDocumentMutationAtom`)
+- **Formatting**: Biome for linting and formatting
+
+## Migration Pattern (Imperative to Jotai+TanStack Query)
+
+When migrating from imperative hooks to jotai+tanstack:
+1. Create Zod schemas in `contracts/types/`
+2. Create API service in `lib/apis/`
+3. Add cache keys to `lib/query-client/cache-keys.ts`
+4. Create query/mutation atoms in `atoms/`
+5. Replace hook usage in components (maintain backward compatibility)
+6. Delete old hook after all usages migrated
+
+**Important**: For queries needing dynamic inputs, use `useQuery` directly in components instead of atoms.
+
+## Commit Guidelines
+
+- **Format**: `type: description` (e.g., `feat: add user API service`, `fix: resolve type error`)
+- **Types**: `feat`, `fix`, `refactor`, `docs`, `chore`
+- **Scope**: One logical change per commit
+- **Build**: Always run `pnpm build` before committing
+
+## Agent-Specific Instructions
+
+- Work incrementally - one function/component at a time
+- Never commit without explicit approval
+- Remove obvious comments that state what code clearly does
+- Follow existing patterns from previous migrations
+- Maintain backward compatibility during migrations