diff --git a/.prettierignore b/.prettierignore
index b7c3a88..1fcbaed 100644
--- a/.prettierignore
+++ b/.prettierignore
@@ -10,5 +10,4 @@ proto
 
 # Документы, которые форматируются в отдельных задачах / вручную
 AGENTS.md
-README.md
 docker-compose.yml
diff --git a/README.md b/README.md
index 97a42e4..e298494 100644
--- a/README.md
+++ b/README.md
@@ -1,39 +1,100 @@
-# evening_detective_client
+# Вечерний детектив
 
-This template should help get you started developing with Vue 3 in Vite.
+Онлайн-детективная игра: команды проходят «дело» — сценарий из точек, дверей, ключей и улик.
+Фронтенд в стиле «кабинета сыщика»: тёмная тема, «бумажные листы дел» с текстурой и шрифтом печатной машинки.
 
-## Recommended IDE Setup
+## Стек
 
-[VSCode](https://code.visualstudio.com/) + [Volar](https://marketplace.visualstudio.com/items?itemName=Vue.volar) (and disable Vetur).
+- **Vue 3.5** (`<script setup lang="ts">`) + **TypeScript**
+- **Vite 8** (сборка, dev-сервер)
+- **Pinia 3** (состояние), **Vue Router 5** (роутинг, ленивая загрузка страниц)
+- **Naive UI** (тёмная тема) + **@vicons** (иконки)
+- **axios** — HTTP-клиент; API-клиенты генерируются из `proto/main.proto` (см. «API-клиенты»)
 
-## Type Support for `.vue` Imports in TS
+## Требования
 
-TypeScript cannot handle type information for `.vue` imports by default, so we replace the `tsc` CLI with `vue-tsc` for type checking. In editors, we need [Volar](https://marketplace.visualstudio.com/items?itemName=Vue.volar) to make the TypeScript language service aware of `.vue` types.
+- Node.js 20.19+ или 22.12+ (требование Vite 8)
+- npm
 
-## Customize configuration
-
-See [Vite Configuration Reference](https://vite.dev/config/).
-
-## Project Setup
+## Быстрый старт
 
 ```sh
 npm install
-```
-
-### Compile and Hot-Reload for Development
-
-```sh
+cp .env.example .env # при необходимости (см. «Переменные окружения»)
 npm run dev
 ```
 
-### Type-Check, Compile and Minify for Production
+Dev-сервер поднимется с `--host`, порт по умолчанию — 5173.
+
+> Для работы с данными нужен запущенный бэкенд: API-клиент обращается к `VITE_API_URL`
+> (см. `.env.example`; при отсутствии переменной используется `http://localhost:8090`).
+> Без бэкенда страницы откроются, но данные не загрузятся.
+
+## Команды
+
+| Команда              | Назначение                                                                  |
+| -------------------- | --------------------------------------------------------------------------- |
+| `npm run dev`        | dev-сервер (Vite, `--host`)                                                 |
+| `npm run build`      | type-check + сборка продакшена (через `run-p`)                              |
+| `npm run build-only` | только сборка (`vite build`)                                                |
+| `npm run preview`    | локальный предпросмотр собранного `dist` (после `npm run build`)            |
+| `npm run type-check` | проверка типов (`vue-tsc --build`)                                          |
+| `npm run lint`       | ESLint по всему проекту с автофиксами                                       |
+| `npm run lint:css`   | Stylelint по `src/**/*.{css,scss,vue}` с автофиксами (свойства по алфавиту) |
+| `npm run format`     | Prettier по всему проекту (`prettier --write .`, см. `.prettierignore`)     |
+| `npm run proto:gen`  | генерация API-клиентов из proto (нужен установленный `protoc` + плагин)     |
+
+## Переменные окружения
+
+Скопируйте `.env.example` в `.env` и при необходимости измените:
+
+| Переменная       | Назначение                                                                            |
+| ---------------- | ------------------------------------------------------------------------------------- |
+| `VITE_API_URL`   | базовый URL бэкенда (пример: `http://localhost:8080`)                                 |
+| `VITE_APP_TITLE` | резервируется под название приложения (сейчас заголовок вкладки задан в `index.html`) |
+
+## Структура проекта
+
+```
+src/
+├── views/          — тонкие обёртки страниц (*View.vue → <Page />)
+├── components/     — страницы (*Page.vue) и переиспользуемые блоки
+├── router/         — маршруты (ленивая загрузка страниц)
+├── api/            — клиенты API + generated/ (сгенерированный код)
+├── stores/         — Pinia-стора
+├── composables/    — переиспользуемая логика (например, useSimplePolling)
+├── utils/          — утилиты
+├── types/          — типы
+└── assets/         — css, шрифты, изображения
+```
+
+Алиас `@/` → `src/`. Импорты: `@/components/...` для общих блоков, относительные для соседних файлов.
+
+## API-клиенты
+
+Клиенты генерируются из `proto/main.proto` (grpc-gateway) в `src/api/generated/**`:
+
+```sh
+npm run proto:gen
+```
+
+**Сгенерированный код руками не редактировать** — обновляется только через `npm run proto:gen`.
+Использовать клиенты только через обёртки (`getAuthClient()` и т.п. из `src/api/`).
+
+## Деплой
+
+`docker-compose.yml` поднимает статический HTTP-сервер, который отдаёт собранный `dist` (SPA-режим) на порту 8100:
 
 ```sh
 npm run build
+docker-compose up -d
+# приложение: http://localhost:8100
 ```
 
-### Lint with [ESLint](https://eslint.org/)
+## Конвенции
 
-```sh
-npm run lint
-```
+Подробные правила работы с кодом (структура, импорты, дизайн-канон «бумажного детектива», палитра) — в [`AGENTS.md`](AGENTS.md).
+
+## Рекомендуемые расширения VSCode
+
+См. `.vscode/extensions.json`: Volar, ESLint, EditorConfig, Prettier.