From 1bf463de02c52c5304ca5c8c21a6ac273f979bff Mon Sep 17 00:00:00 2001
From: Fedorov Vladimir <vladimir.fodorow@gmail.com>
Date: Mon, 31 Aug 2026 01:33:24 +0700
Subject: [PATCH] update agents

---
 AGENTS.md | 104 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 104 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..49bb17c
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,104 @@
+# AGENTS.md — Вечерний детектив (фронтенд)
+
+Правила работы агента над этим репозиторием. Читай целиком перед началом любой задачи.
+Онлайн-детективная игра: команды проходят «дело» — сценарий из точек, дверей, ключей и улик.
+
+## 1. Стек и команды
+
+- **Стек:** Vue 3.5 (`<script setup lang="ts">`), Vite 8, Pinia 3, Vue Router 5, Naive UI (тёмная тема), @vicons, axios.
+- **API:** клиенты генерируются из `proto/main.proto` → `src/api/generated/`.
+
+| Команда | Назначение |
+|---|---|
+| `npm run dev` | dev-сервер (Vite, `--host`) |
+| `npm run type-check` | проверка типов (vue-tsc) |
+| `npm run lint` | ESLint с автофиксами |
+| `npm run lint:css` | Stylelint (алфавитный порядок свойств) |
+| `npm run format` | Prettier (`src/`) |
+| `npm run build` | type-check + сборка |
+| `npm run proto:gen` | генерация API-клиентов из proto (после изменения proto) |
+
+## 2. Структура и соглашения
+
+- `src/views/*View.vue` — тонкие обёртки над страницами (только импорт и `<Page />`).
+- `src/components/*Page.vue` — страницы (GamesPage, OfficePage, TeamStoryPage…).
+- `src/components/*.vue` — переиспользуемые блоки (HeaderMenu, MessagePaper, PlaceBlock, IntroBlock…).
+- `src/api/generated/**` — **сгенерированный код, руками не редактировать.** Обновляется только через `npm run proto:gen`.
+- `src/stores/`, `src/composables/`, `src/utils/`, `src/types/` — по назначению.
+- Алиас `@/` → `src/`. Импорты: `@/components/...` для общих блоков, относительные для соседних файлов.
+- UI-тексты — на русском.
+
+## 3. Правила выполнения задач
+
+1. **Сначала изучи.** Прочитай `package.json`, `tsconfig.app.json`, релевантные компоненты и существующие паттерны. Следуй им; не вводи новый стек, механизмы и зависимости без согласования с пользователем.
+2. **Код:** `defineProps` с типами (`Object as PropType<T>`), типизированные `emit`, производные значения через `computed`. Не дублируй логику — выноси в `composables/`/`utils/`.
+3. **Импорты:** сортируй (simple-import-sort): сторонние → `@/` → относительные. Удаляй неиспользуемые (unused-imports). Точки с запятой не ставим, одинарные кавычки, ширина 100 (Prettier).
+4. **API:** только через сгенерированные клиенты (`getAuthClient()` и т.п.). После вызова проверяй `res.error` и показывай `message.error(res.error!)`. Поля из proto необязательны — бери с `!` как в существующем коде.
+5. **Ошибки и состояния:** используй `useMessage()` из naive-ui; загрузку — простым `ref` + асинхронная функция (существующий паттерн), поллинг — `useSimplePolling`.
+6. **Стили:** `scoped`, свойства по алфавиту (stylelint). Не добавляй новые цвета хардкодом — только палитра из раздела 4.
+7. **Адаптивность:** мобильная вёрстка по умолчанию, брейкпоинт `@media (width >= 1024px)` (существующий паттерн). Скрывай скроллбары как `.center-block-custom`.
+8. **Проверки перед сдачей (всегда):** `npm run type-check` → `npm run lint` → `npm run lint:css`. При затрагивании сборки — `npm run build`. Сообщи в ответе, какие проверки прошли.
+9. **Запрещено:** `git commit` и `git push` (глобальное правило). Не переписывай чужой код без необходимости — минимальные целевые изменения.
+
+## 4. Правила дизайна (канон «бумажного детектива»)
+
+Стилистика проекта — тёмный «кабинет сыщика»: тёмный фон, «бумажные листы дел» с текстурой и шрифтом печатной машинки, бронзовые/золотые акценты, зелёный акцент интерактива.
+
+### 4.1 Палитра (использовать только эти значения)
+
+| Роль | Значение |
+|---|---|
+| Фон страницы | `#111` |
+| Панели / карточки / блоки | `#222` (border-radius: 10px) |
+| Основной текст | `#eee` |
+| Вторичный текст (подписи, служебное) | `#aaa`, `#777` |
+| Акцент hover/active | `#63e2b7` |
+| Бронза (заголовки на бумаге, PDF-ссылки) | `--second-color: rgb(97 74 22)` |
+| Золото (ключи, «требуемые ключи») | `gold` |
+| Кнопки-действия на бумаге | текст `#bfa07d`, фон — текстура `belt.png` |
+| Подписи улик/приложений | `burlywood` |
+| Текст на бумажном листе | `black` |
+
+### 4.2 Типографика
+
+- **UI (формы, панели, навигация):** системный стек из `base.css`, 15px.
+- **Бумажные листы дел:** `font-family: 'font_old_typer'` (шрифт подключён в `main.css`, файл `src/assets/fonts/a_OldTyper.ttf`). Контент — 18px, заголовок вступления — 26px с `letter-spacing: 3px`.
+- Никогда не используй `font_old_typer` для UI-элементов (кнопки, формы, меню).
+
+### 4.3 Бумажный лист (компонент MessagePaper)
+
+Контент дел (вступление, точки, приложения) оборачивается в `MessagePaper`:
+
+- Фон — текстура `paper.jpg` (`background-size: cover`), тень `0 0 5px black`, слои-подложки с поворотами `rotate(-3deg)` / `rotate(2deg)`.
+- Разделители — пунктирные `hr`: `border: dashed 1px` (на бумаге — `black`, в тёмных панелях — `#eee`).
+- **«Фотографии»** (картинка точки, картинки-улики): подложка с текстурой `paper_white.jpg`, паддинг 7px, `transform: rotate(-3deg)`, тень `0 3px 15px rgb(98 98 98)`, `cursor: zoom-in`, клик — просмотр в `n-modal` + `n-card`.
+- **Улики-картинки в потоке текста:** блок `float: right`, текст обтекает; контейнер — `display: flow-root` (BFC, чтобы не наезжало на двери).
+- **Кнопки действий («двери»):** фон `belt.png` (`background-size: cover`), текст `#bfa07d`, `border-radius: 5px`, inline-block, паддинг `5px 12px`.
+- **Сворачивание листа:** иконка `collapse.png` (45×28), развёрнутый лист — `rotate(-180deg)`.
+
+### 4.4 Компоненты и иконки
+
+- UI-контролы — только naive-ui (`n-*`): тёмная тема задана в `App.vue` (`NConfigProvider :theme="darkTheme"`). Не стилизуй нативные `<input>/<button>`.
+- Иконки — `@vicons` через обёртку `<Icon>` из `@vicons/utils`, размер через `size` (например `<Icon size="28"><MenuOutlined /></Icon>`).
+- Модальные окна просмотра — `n-modal` + `n-card`, ширина `min(94vw, 1200px)`, `role="dialog" aria-modal="true"`.
+
+### 4.5 Раскладка страниц
+
+- Фиксированный `HeaderMenu` сверху, высота 70px; контент — контейнер `.center-block-custom` (`margin-top: 70px`, высота `calc(100dvh - 70px)`, скрытый скроллбар).
+- Ширина контента: `.width700` — бумажные листы/дела, `.width1200` — списки и таблицы.
+- Карточки списков (игры, сценарии): фон `#222`, `border-radius: 10px`, hover — `color: #63e2b7` + `cursor: pointer`.
+- Интерактивные блоки-«листы» в редакторе: `.place-block-hover` — hover-рамка `1px solid #63e2b7`.
+
+### 4.6 Поведение и состояния
+
+- Hover интерактивных элементов — только `#63e2b7` (не изобретай новые цвета).
+- Заголовки и служебные подписи — вторичные цвета палитры (`#aaa`/`#777`), без ярких акцентов.
+- Новые цвета/токены добавлять только через `src/assets/base.css` в `:root` (существующие: `--main-color`, `--second-color`, `--main-back-color`, `--main-back-item-color`) — и только если без них нельзя обойтись палитрой.
+
+## 5. Чек-лист перед сдачей
+
+1. ✅ Соблюдены соглашения структуры и импортов (разделы 2–3).
+2. ✅ Использована только палитра и стилистика раздела 4.
+3. ✅ Адаптивность и скролл-контейнеры как в существующих страницах.
+4. ✅ `npm run type-check`, `npm run lint`, `npm run lint:css` — без ошибок (отчёт в ответе).
+5. ✅ Сгенерированный код не тронут; git commit/push не выполнялись.