diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..6e4381b
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,60 @@
+# Repository Guidelines
+
+Luma is an XMPP client for iOS, iPadOS, macOS, and watchOS, built with SwiftUI
+and the Martin / MartinOMEMO libraries. The Xcode project is generated from
+`project.yml` by XcodeGen — never edit `Luma.xcodeproj` directly.
+
+## Project Structure
+
+- `Sources/App/` — iOS/macOS app entry point (`LumaApp.swift`).
+- `Sources/Shared/` — shared code:
+  - `Models/` — value types and pure policy enums (`ChatMessage`,
+    `ArchiveSyncPagination`, `ChatTypingPolicy`, …).
+  - `UI/` — SwiftUI views and components.
+  - `XMPP/` — `XMPPService` (MAM/OMEMO/MUC), `LumaCallEngine`, OMEMO store.
+  - `Persistence/` — `ChatArchive` (JSON snapshot), preferences.
+  - `Services/`, `Security/` — media, notifications, credentials.
+- `Sources/Watch/` — single-target watchOS app.
+- `Tests/` — XCTest unit tests.
+- `Resources/`, `Config/`, `Brand/`, `Docs/` — assets, plists/entitlements,
+  icons, architecture/security docs.
+
+## Build, Test & Development
+
+- `make project` — regenerate `Luma.xcodeproj` from `project.yml`
+  (requires `brew install xcodegen`).
+- `make open` — regenerate and open Xcode.
+- `make verify` — run `Scripts/verify.sh`: grep-based structural invariants
+  plus an optional simulator build.
+- `make clean` — remove the generated project and DerivedData.
+- `xcodebuild test -project Luma.xcodeproj -scheme Luma \
+  -destination 'platform=iOS Simulator,name=iPhone 17 Pro Max'` — build and
+  run the test suite.
+
+## Coding Style
+
+- Swift 5.9; 4-space indentation (set in `project.yml`).
+- UI-facing state is `@MainActor` (`AppModel`, `XMPPService`); keep heavy work
+  (OMEMO decryption, media, persistence) off the main actor.
+- Prefer small, pure value types and unit-testable policy enums over inline
+  branching.
+- UI strings are Russian; identifiers and code comments are English.
+- No formatter/linter; `Scripts/verify.sh` is the guard — keep its greps in
+  sync when you change constants or symbols.
+
+## Testing
+
+- XCTest with `@testable import Luma`; one file per model/policy
+  (e.g., `ArchiveSyncPaginationTests.swift`), methods named `test...`.
+- Unit-test pure logic (policies, pagination, checkpoints); network/UI flows
+  are verified manually.
+- When a policy constant changes, update the matching `Tests/*` assertions and
+  the `Scripts/verify.sh` guard in the same commit.
+
+## Commit & Pull Request
+
+- Short, imperative, English subject lines (see `git log`: "mam fixes",
+  "fix errors and warnings").
+- CI (`.github/workflows/ios.yml`) runs `xcodebuild test` on push to
+  `main`/`develop` and on PRs to `main`; PRs must keep it green.
+- Update `README.md` / `Docs/*` whenever behaviour or architecture changes.