diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 000000000..9788d9212
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,35 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+- Code: `app/` (Rails MVC, services, jobs, mailers, components), JS in `app/javascript/`, styles/assets in `app/assets/` (Tailwind, images, fonts).
+- Config: `config/`, environment examples in `.env.local.example` and `.env.test.example`.
+- Data: `db/` (migrations, seeds), fixtures in `test/fixtures/`.
+- Tests: `test/` mirroring `app/` (e.g., `test/models/*_test.rb`).
+- Tooling: `bin/` (project scripts), `docs/` (guides), `public/` (static), `lib/` (shared libs).
+
+## Build, Test, and Development Commands
+- Setup: `cp .env.local.example .env.local && bin/setup` — install deps, set DB, prepare app.
+- Run app: `bin/dev` — starts Rails server and asset/watchers via `Procfile.dev`.
+- Test suite: `bin/rails test` — run all Minitest tests; add `TEST=test/models/user_test.rb` to target a file.
+- Lint Ruby: `bin/rubocop` — style checks; add `-A` to auto-correct safe cops.
+- Lint/format JS/CSS: `npm run lint` and `npm run format` — uses Biome.
+- Security scan: `bin/brakeman` — static analysis for common Rails issues.
+
+## Coding Style & Naming Conventions
+- Ruby: 2-space indent, `snake_case` for methods/vars, `CamelCase` for classes/modules. Follow Rails conventions for folders and file names.
+- Views: ERB checked by `erb-lint` (see `.erb_lint.yml`). Avoid heavy logic in views; prefer helpers/components.
+- JavaScript: `lowerCamelCase` for vars/functions, `PascalCase` for classes/components. Let Biome format code.
+- Commit small, cohesive changes; keep diffs focused.
+
+## Testing Guidelines
+- Framework: Minitest (Rails). Name files `*_test.rb` and mirror `app/` structure.
+- Run: `bin/rails test` locally and ensure green before pushing.
+- Fixtures/VCR: Use `test/fixtures` and existing VCR cassettes for HTTP. Prefer unit tests plus focused integration tests.
+
+## Commit & Pull Request Guidelines
+- Commits: Imperative subject ≤ 72 chars (e.g., "Add account balance validation"). Include rationale in body and reference issues (`#123`).
+- PRs: Clear description, linked issues, screenshots for UI changes, and migration notes if applicable. Ensure CI passes, tests added/updated, and `rubocop`/Biome are clean.
+
+## Security & Configuration Tips
+- Never commit secrets. Start from `.env.local.example`; use `.env.local` for development only.
+- Run `bin/brakeman` before major PRs. Prefer environment variables over hard-coded values.