add readme

AGENTS.md

@@ -12,7 +12,7 @@
 1. Сначала изучай существующий поток и используй текущие паттерны проекта.
 2. Делай минимальный целевой diff; не добавляй зависимости и абстракции без необходимости.
 3. Не трогай вложенные `.git` и не смешивай историю двух дочерних репозиториев.
-4. Не коммить и не отправляй изменения без явного запроса пользователя.
+4. Коммиты и push выполняет только пользователь. Агент никогда не коммитит и не отправляет изменения.
 5. Не добавляй `.env`, ключи, пароли, сертификаты и локальные артефакты в Git.
 6. После нетривиальных изменений запускай краткую релевантную проверку и сообщай результат.
 

README.md

@@ -0,0 +1,107 @@
+# Вечерний детектив
+
+Онлайн-детективная игра: команды проходят дело из точек, дверей, ключей и улик.
+
+## Структура workspace
+
+Корневой репозиторий `agents` хранит рабочие инструкции и документацию. Код живёт
+в двух отдельных репозиториях:
+
+- [`evening_detective_server/`](evening_detective_server/) — Go-бэкенд;
+- [`evening_detective_frontend/`](evening_detective_frontend/) — Vue/TypeScript-фронтенд;
+- [`email_server/`](email_server/) — старый собственный почтовый сервер, не нужен для локального запуска.
+
+У каждого из двух основных проектов своя история Git и свой remote. Не удаляйте
+вложенные `.git` и не смешивайте коммиты между репозиториями.
+
+## Локальный запуск
+
+Требования: Go, Docker Compose, Node.js 20.19+ или 22.12+, npm.
+
+### 1. Зависимости сервера
+
+```sh
+cd evening_detective_server
+docker compose -f docker-compose-db.yml up -d
+cp .env.example .env
+make run
+```
+
+Сервис запускает:
+
+- gRPC на `http://localhost:8080`;
+- REST gateway и Swagger на `http://localhost:8090`.
+
+Для локального фронтенда в `evening_detective_frontend/.env` укажите:
+
+```dotenv
+VITE_API_URL=http://localhost:8090
+```
+
+### 2. Фронтенд
+
+В другом терминале:
+
+```sh
+cd evening_detective_frontend
+npm install
+cp .env.example .env
+npm run dev
+```
+
+Фронтенд будет доступен на `http://localhost:5173`.
+
+### 3. Локальный пользователь
+
+```sh
+cd evening_detective_server
+make dev-user
+```
+
+По умолчанию создаётся пользователь `dev@example.com` с паролем `dev123456`.
+Для изменения используйте `DEV_USER_EMAIL` и `DEV_USER_PASSWORD`.
+
+## Проверки перед изменениями
+
+Сервер:
+
+```sh
+cd evening_detective_server
+make test
+```
+
+Фронтенд:
+
+```sh
+cd evening_detective_frontend
+npm run type-check
+npm run lint
+npm run lint:css
+```
+
+При изменении protobuf сначала обновляйте сгенерированный код существующими
+командами `make generate` на сервере и `npm run proto:gen` на фронтенде.
+Сгенерированные файлы руками не редактируйте.
+
+## Окружение и секреты
+
+Файлы `.env` предназначены только для локальных значений и не коммитятся.
+Начинайте настройку с `.env.example`. Секреты SMTP, JWT, S3, webhook и внешних
+API храните только в окружении или секрет-хранилище.
+
+Публичный адрес приложения задаётся через `APP_BASE_URL`; он используется в
+ссылках из писем и QR-кодах команд.
+
+## Рабочий процесс
+
+1. Перед изменением прочитайте корневой [`AGENTS.md`](AGENTS.md) и инструкции
+   целевого проекта.
+2. Делайте минимальное изменение в одном дочернем репозитории.
+3. Запускайте релевантные проверки.
+4. Коммиты и push выполняет только пользователь; агент никогда не коммитит и не отправляет изменения.
+
+Текущие подробные инструкции:
+
+- [`AGENTS.md`](AGENTS.md) — правила workspace;
+- [`evening_detective_frontend/AGENTS.md`](evening_detective_frontend/AGENTS.md) — правила фронтенда;
+- [`evening_detective_server/README.md`](evening_detective_server/README.md) — детали бэкенда.