# AGENTS.md

Инструкции для AI-агентов и автоматизации, работающих с этим репозиторием.

## Форма проекта

Это Docker Compose инфраструктурный репозиторий. Основные source-файлы:

- `docker-compose.yml`
- `.env.example`
- `.gitignore`
- `.gitea/workflows/*.yaml`
- `.gitea/actions/*`
- `README.md`
- `AGENTS.md`

Текущие service aliases в Compose:

```text
prx
pwd
mon
mon-agent
cld
git
git-runner
sup-hbbs
sup-hbbr
```

Сохраняйте эти короткие aliases, если пользователь явно не попросил переименовать сервисы и не подтвердил учет deploy-impact.

## Секреты и runtime-данные

Не читайте, не выводите, не пересказывайте, не копируйте и не коммитьте реальные секреты или runtime-данные.

Считайте эти пути sensitive или local-only:

- `.env`
- `secrets/`
- `data/`
- database-файлы вроде `*.sqlite3`, `*.sqlite3-shm`, `*.sqlite3-wal`
- private keys и сгенерированные service credentials
- certificates и letsencrypt data

Используйте `.env.example`, `docker-compose.yml` и workflow-файлы как source of truth для имен переменных и секретов. Если задача требует просмотра реальных secret values или runtime-данных, остановитесь и запросите явное разрешение пользователя.

## Правила изменений

- Держите изменения узко привязанными к запрошенному infrastructure-поведению.
- Не выполняйте destructive-операции против `data/`, `secrets/`, Docker volumes или корня проекта без явного разрешения пользователя.
- Не запускайте `docker compose down -v`, volume pruning, recursive deletion, database migrations или service resets, если пользователь не запросил именно это.
- При добавлении или изменении Compose-переменной обновляйте `.env.example`, `README.md` и Gitea deploy workflow, если значение нужно при деплое.
- При добавлении или изменении Compose-секрета обновляйте блок `secrets:`, создание секретов в deploy workflow, `README.md` и соответствующий service environment.
- Сохраняйте стиль YAML: короткие service aliases, single quotes там, где они уже используются, и существующую indentation-схему.
- Избегайте unrelated formatting churn в workflow и Compose-файлах.

## Валидация

Для Compose-изменений запускайте:

```sh
docker compose config
```

Для изменений deploy workflow проверяйте затронутые `.gitea/workflows/*.yaml` и подтверждайте, что нужные variables/secrets описаны в `README.md`.

Для documentation-only изменений проверьте, что:

- service names совпадают с `docker-compose.yml`;
- environment variables совпадают с `.env.example`;
- secret filenames совпадают с Compose-блоком `secrets:`;
- реальные secret values и runtime-данные не попали в документацию.

## Операционный контекст

Деплой запускается вручную через Gitea Actions. Deploy workflow подключается к серверу по SSH, записывает `.env` и `secrets/*.txt`, опционально делает backup удаленного `data/` и стартует контейнеры командой:

```sh
docker compose -f docker-compose-<ref>.yml up -d --remove-orphans
```

Workflow может отправлять Telegram-уведомления и прикладывать deploy logs. Изменения deploy-поведения должны учитывать и remote shell commands, и documented Gitea variables/secrets.