protocol-bunker

Imported from FHRha/protocol-bunker (AGENTS.md). Install upstream with npx skills add FHRha/protocol-bunker. Copyright stays with the author.

# AGENTS.md

О проекте

Protocol: Bunker — это монорепозиторий браузерной адаптации игры «Бункер».

Проект включает:

• клиентскую часть;
• серверную часть;
• общие типы и контракты;
• сценарии и игровой контент;
• стримерские и зрительские режимы;
• сборку релизов под разные платформы;
• документацию для игроков, хостов, стримеров и разработчиков.

Игровой сценарий для обычных участников происходит в браузере. Хост поднимает игру локально, на своём устройстве или на сервере, а остальные подключаются по ссылке.

Зачем нужен этот файл

Этот файл — обзорная карта репозитория.

Он нужен, чтобы быстро понять:

• как устроен проект;
• за что отвечают основные директории;
• куда вносить изменения;
• какие документы считаются каноническими;
• где проходит граница между кодом, контентом, локализацией, стримингом и документацией.

Этот файл не заменяет профильную документацию из docs/. Его задача — быстро дать общую картину проекта.

Карта папок

Ниже — обзорная карта верхнего уровня репозитория.

protocol-bunker/
├─ client/                  # браузерный клиент, UI, лобби, комната, карточки, overlay-related части
├─ server/                  # сервер, комнаты, websocket-логика, состояние матча
├─ shared/                  # общие типы, контракты, payload'ы, доменные сущности
├─ scenarios/               # сценарии, карты, игровые данные, special conditions
├─ tests/                   # интеграционные и другие автоматические проверки
├─ scripts/                 # сборка, упаковка, release/helper-скрипты
├─ docs/                    # документация по ролям и сценариям
│  ├─ user/                 # материалы для игроков
│  ├─ host/                 # self-host, deployment, Linux/nginx
│  ├─ streaming/            # OBS, overlay, streamer flow
│  ├─ dev/                  # архитектура, setup, testing, content system, releases
│  └─ internal/             # QA checklist, заметки, миграции, служебные материалы
├─ locales/                 # UI-локализация, переводы, интерфейсные тексты
├─ package.json             # корневые скрипты и workspace-конфигурация
├─ install.sh               # Linux-установщик и сценарий обновления
├─ README.md                # главный вход в репозиторий
├─ MANUAL.md                # общий пользовательский мануал
└─ AGENTS.md                # обзорная карта проекта и репозитория

## Общая структура репозитория

Ниже перечислены основные верхнеуровневые части проекта и их назначение.

### `client/`

Браузерный интерфейс игры.

Здесь находится всё, что связано с отображением:
- входа;
- лобби;
- игровой комнаты;
- игроков;
- карточек;
- голосования;
- состояний игры;
- мобильного и адаптивного поведения;
- UI для стримерских и зрительских сценариев.

Если меняется визуальная часть, пользовательский интерфейс или отображение состояния матча, основная точка входа обычно находится здесь.

### `server/`

Серверная часть проекта.

Здесь находится логика:
- создания и жизненного цикла комнат;
- подключений;
- websocket-взаимодействия;
- синхронизации состояния;
- хода партии;
- обработки игровых действий;
- ролей хоста, игроков, spectator / control и служебных соединений.

Если меняется серверная логика, сетевое поведение или поведение комнаты, основная точка входа обычно находится здесь.

### `shared/`

Общие типы, контракты и структуры данных.

Это слой, который связывает клиент и сервер между собой.

Здесь обычно находятся:
- типы сообщений;
- payload’ы событий;
- общие доменные сущности;
- перечисления;
- контракты состояния;
- общие утилиты без привязки к конкретной стороне приложения.

Если меняется формат данных между клиентом и сервером, почти всегда затрагивается `shared/`.

### `scenarios/`

Сценарии и игровой контент.

Здесь находятся:
- сценарии;
- наборы карт;
- игровые данные;
- special conditions;
- контентные сущности и связанная с ними логика.

Это слой, который отвечает за содержимое партии и сценарные правила.

Если меняются карты, сценарные данные, специальные условия или контентная модель — основная точка входа обычно находится здесь.

### `tests/`

Автоматические проверки проекта.

Здесь хранятся тесты, связанные с:
- критичными игровыми сценариями;
- websocket-flow;
- комнатами;
- подключениями;
- host transfer;
- установкой и обновлением, если это входит в текущий набор тестов.

Если нужно понять, что уже проверяется автоматически, или добавить новую важную проверку, начинать стоит здесь.

### `scripts/`

Служебные скрипты.

Здесь находятся скрипты для:
- сборки;
- упаковки;
- подготовки релизов;
- platform-specific сценариев;
- вспомогательных технических операций.

Если меняется packaging, release-flow или build-helper логика, точка входа обычно здесь.

### `docs/`

Документация проекта.

Она разделена по аудиториям:
- `docs/user/` — документы для игроков;
- `docs/host/` — документы для хостинга и развёртывания;
- `docs/streaming/` — документы для стриминга, OBS и оверлеев;
- `docs/dev/` — документы для разработки;
- `docs/internal/` — внутренние checklist’ы, заметки, миграции и служебные материалы.

### `locales/`

Локализация интерфейса и связанные с ней данные.

Здесь находятся UI-строки и связанные локализационные материалы.

Важно различать:
- локализацию интерфейса, которая нужна приложению;
- человекочитаемую документацию в `docs/`, которая нужна людям.

Если меняются тексты интерфейса, переводы и UI-ключи, начинать нужно здесь и в соответствующих клиентских местах.

### Прочие верхнеуровневые файлы

#### `README.md`
Главный вход в репозиторий. Это короткий роутер по основным сценариям:
- играть;
- хостить;
- стримить;
- разрабатывать.

#### `MANUAL.md`
Общий пользовательский мануал. Более длинный и человекочитаемый документ, чем `README.md`.

#### `AGENTS.md`
Этот файл. Обзорная карта проекта и структуры репозитория.

#### `package.json`
Корневые скрипты проекта, включая:
- `dev`
- `build`
- `typecheck`
- `test:integration`
- `pack:*`
- `locale:*`

#### `install.sh`
Linux-установщик и сценарий быстрой установки / обновления для готового self-host / server deployment.

## Как части проекта связаны между собой

В упрощённом виде структура проекта работает так:

- `server/` поднимает игру, управляет комнатой и держит состояние матча;
- `client/` подключается к серверу и отображает интерфейс игрокам, хосту, зрителям и стримеру;
- `shared/` задаёт общие контракты между клиентом и сервером;
- `scenarios/` поставляет игровые данные и сценарную логику;
- `tests/` проверяет, что критичные части системы корректно работают вместе;
- `scripts/` собирает и упаковывает релизные артефакты;
- `docs/` объясняет всё это разным аудиториям;
- `locales/` обеспечивает локализацию интерфейса и связанных UI-текстов.

## Куда вносить изменения

Ниже — простой ориентир по типам задач.

### Если меняется интерфейс
Смотри:
- `client/`
- `locales/`, если затронуты тексты интерфейса

### Если меняется серверная логика
Смотри:
- `server/`

### Если меняются события, payload’ы или общие типы
Смотри:
- `shared/`
- затем соответствующие места в `client/` и `server/`

### Если меняются карты, сценарии, special conditions или игровые данные
Смотри:
- `scenarios/`

### Если меняется стримерский режим, overlay или viewer / control flow
Смотри:
- `client/`
- `server/`
- `docs/streaming/`, если меняется пользовательская логика или инструкция

### Если меняется локализация
Смотри:
- `locales/`
- `client/`
- при необходимости `docs/user/`, если меняется человекочитаемая версия правил или объяснений

### Если меняется сборка, упаковка или release-flow
Смотри:
- `scripts/`
- `package.json`
- `docs/dev/release-process.md`

### Если меняется установка или Linux deployment
Смотри:
- `install.sh`
- `docs/host/self-hosting.md`
- `docs/host/linux-nginx.md`
- `docs/host/deployment.md`

### Если меняется документация
Смотри:
- `README.md`
- `MANUAL.md`
- соответствующий раздел в `docs/`

## Канонические документы

Ниже перечислены основные документы, которые считаются актуальной основной документацией проекта.

### Корневые документы
- `README.md`
- `MANUAL.md`
- `AGENTS.md`

### Документы для разработки
- `docs/dev/setup.md`
- `docs/dev/architecture.md`
- `docs/dev/testing.md`
- `docs/dev/content-system.md`
- `docs/dev/release-process.md`

### Документы для стриминга
- `docs/streaming/streamer-quick-start.md`
- `docs/streaming/overlay-guide.md`
- `docs/streaming/overlay-presets.md`

### Документы для игроков
- `docs/user/getting-started.md`
- `docs/user/game-rules.md`
- `docs/user/faq.md`

### Документы для хостов
- `docs/host/self-hosting.md`
- `docs/host/linux-nginx.md`
- `docs/host/deployment.md`

### Внутренние документы
- `docs/internal/qa-checklist.md`

## Документы переходного периода и legacy-материалы

В репозитории могут оставаться старые документы, временные заметки, технические миграции и файлы переходного периода.

К ним стоит относиться так:
- если документ не входит в список канонических выше, он не должен считаться основной точкой правды без отдельной проверки;
- временные и одноразовые материалы должны постепенно переезжать в `docs/internal/notes/` и `docs/internal/migrations/`;
- устаревшие документы не должны дублировать новую структуру документации.

Если старый документ противоречит новому разделу `docs/`, ориентироваться нужно на актуальные канонические документы.

## Документация и уровень детализации

Важно различать уровни документации:

### `README.md`
Короткий вход в проект.

### `MANUAL.md`
Общий пользовательский мануал и единая понятная инструкция.

### `docs/*`
Профильные документы по ролям и сценариям.

### `AGENTS.md`
Обзорная карта репозитория и структуры проекта.

## Практический принцип работы с репозиторием

Перед изменением чего-либо полезно сначала определить тип задачи:

- визуальная правка;
- серверная правка;
- изменение контракта;
- изменение контента;
- изменение локализации;
- изменение стримерского сценария;
- изменение установки или deployment;
- изменение документации.

После этого уже выбирать нужную часть проекта, а не искать вслепую по всему репозиторию.