# Участие в разработке Tasktopia

Предлагайте небольшие изменения с одной целью, проверкой результата и
обновлённой документацией. Начните с [локального запуска](README.md#быстрый-старт)
и создайте ветку от актуального `main`.

## Проверки

Нужны Node.js 24+, Docker Compose v2 и Python 3.12+ с `venv`.
Остановите dev-сервер перед E2E и освободите порт 5173. Playwright запускает
отдельный сервер с тестовой базой; при занятом порту он может переиспользовать
существующий сервер и его базу.

```bash
npm run assets:setup
npx playwright install --with-deps chromium firefox webkit
npm run test:db:start
npm run typecheck
npm run lint
npm test
npm run build
npm run test:e2e
npm run test:db:stop
```

Для изменений интерфейса добавьте или обновите проверку Playwright. После
изменений генерации мира отдельно запустите `npm run test:worldgen`:
тяжёлые проверки генерации и браузерные тесты не выполняются одновременно.

## Графика

Перед изменением графики прочитайте
[правила подготовки ресурсов](assets/pixel-city-pack/docs/GENERATION-SPEC.md).
Новый PNG должен иметь запись в манифесте, смысловой ключ, контрольную сумму
исходника и метаданные. Для здания нужны все пять стадий; для фоновой анимации —
полный набор кадров.

После изменения выполните `npm run assets:build` и `npm run assets:verify`.
Проверьте изображение в исходном масштабе, увеличенный вид без сглаживания и
карту приложения. Сохраняйте ракурс, палитру и происхождение исходников.
Генерация графики во время работы приложения и незарегистрированные подмены
ресурсов не допускаются.

## Контракты

- Изменение API или MCP требует проверки и обновления `docs/MCP.md` и `public/ai.md`.
- Миграции PostgreSQL добавляются новыми файлами; применённые миграции не переписываются.
- Событие, меняющее карту, содержит точный `affectedBounds`.
- Изменяющие операции MCP остаются идемпотентными.
- Карточки и отчёты служат для чтения и навигации. Изменение задач выполняется через MCP; подробнее — [правила интерфейса](docs/PRODUCT-UI-RULES.md).

## Перед отправкой

Опишите проблему, результат и выполненные проверки. Не добавляйте секреты,
копии рабочих баз, `node_modules`, отчёты покрытия и временные данные Playwright.

Предлагая изменения, вы соглашаетесь распространять их на условиях
[MIT](LICENSE). Сохраняйте авторские уведомления и лицензии сторонних материалов.