Add project documentation

2026-08-22 23:42:47 +03:00
parent 4fe1bb44e4
commit 30f7dc0ce2
2 changed files with 240 additions and 0 deletions
@@ -0,0 +1,83 @@
+# 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.