From 703ecd6140ac4d21cc9c126302cada10017c48c6 Mon Sep 17 00:00:00 2001
From: Daniil Okhlopkov <5613295+ohld@users.noreply.github.com>
Date: Thu, 2 Oct 2025 11:17:18 +0300
Subject: [PATCH] docs: add agent onboarding guide

---
 AGENTS.md | 28 ++++++++++++++++++++++++++++
 README.md |  4 +++-
 2 files changed, 31 insertions(+), 1 deletion(-)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 00000000..950e9472
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,28 @@
+# Agent Onboarding
+
+Welcome! The notes below summarize the key workflows pulled from `README.md` so you can get productive quickly.
+
+## Running the application locally
+1. `cp .env.example .env`
+2. `docker network create ffmemes_network`
+3. `docker compose up -d --build`
+4. Populate the new `.env` with the credentials you need before interacting with the services.
+
+## Test execution
+- All tests depend on the Alembic migrations that are automatically upgraded and downgraded by the `run_migrations` fixture in `tests/conftest.py`. No extra work is required when you call `pytest`, but keep the hook in mind if you introduce new migrations.
+- The canonical Docker workflow is `docker compose exec app pytest`.
+- When running tests outside Docker, export the environment variables seeded in `pytest.ini`:
+  - `SITE_URL`
+  - `DATABASE_URL`
+  - `REDIS_URL`
+  - `SITE_DOMAIN`
+  - `SECURE_COOKIES`
+  - `ENVIRONMENT`
+  - `CORS_HEADERS`
+  - `CORS_ORIGINS`
+
+## Formatting and linting
+Use Ruff for linting and formatting via Docker: `docker compose exec app format` (runs `ruff --fix` and `ruff format`).
+
+## Async testing pattern
+Follow the existing async pattern in `tests/recommendations/test_meme_queue.py` by decorating coroutine tests with `@pytest.mark.asyncio`.
diff --git a/README.md b/README.md
index 0581d9aa..688503a8 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,9 @@
-# Fast Food Memes 
+# Fast Food Memes
 
 ➡️ https://t.me/ffmemesbot ⬅️
 
+For a distilled onboarding guide, see [AGENTS.md](AGENTS.md).
+
 ## Local Development
 
 ### First Build Only