# AGENTS.md — инструкции для агентов (Hermes и др.), работающих с /opt/md2vk

## О проекте

md2vk — сервис публикации Markdown на стену VK через официальный VK API (wall.post + format_data).
FastAPI + SQLAlchemy async + SQLite + Fernet. Документация — в `docs/`, начни с `docs/index.md` и `docs/access.md`.

## Правила работы

1. **Сначала читай доки проекта**: `docs/index.md`, `docs/access.md`, `docs/status.md`,
   `docs/deploy.md` и прошлые сессии (`session_search`), потом действуй.
2. **Не удаляй файлы и данные пользователя** без явного подтверждения (БД `data/md2vk.db`,
   `secrets/`, пользователи). Перезапись/миграция БД — только по явной команде.
3. **Секреты в git не коммитятся**: `secrets/token_encryption_key`,
   `secrets/estorozhenko_api_key.txt`, `.env` — в .gitignore. Токены gitverse/gitea — в
   `/opt/hermes/.hermes/secrets/git-tokens.env` (source его, не ищи по каталогам).
4. **Прод-порт 8420** (не 8000 — занят docker-search-api на bigbox). Контейнер слушает 127.0.0.1:8420.
5. **Изменения в прод-код** — через git: сначала commit/push в gitverse (истина), gitea подтянет pull mirror.
6. **Caddy/fail2ban живут на vps02** (ssh-алиас `vps02`, sudo по ключу):
   - Caddyfile: `/opt/caddy/Caddyfile`, reload: `docker exec caddy caddy reload --config /etc/caddy/Caddyfile`
   - fail2ban: jail `md2vk`, ban после 5 попыток, unban: `sudo fail2ban-client -c /etc/fail2ban unban <ip>`
   - Пароль basic auth — только bcrypt-хэш в Caddyfile; генерировать `docker exec caddy caddy hash-password`.
7. **Рестарт docker на bigbox** — локально (`docker compose up -d`), не на vps02.
8. **Наблюдаемость по умолчанию** (делать сразу, не спрашивать): лог авторизации +
   метрики доступности/успешности/активной сессии. Лог: `/opt/md2vk/logs/access.{date}.log` (JSONL).
9. **Хэштеги/теги — строчными буквами**; документация — с точными маппингами портов и доступов.
10. **Не запускать ручные бэкапы** — делает крон (homelab-backup, 2:45).

## Команды

```bash
cd /opt/md2vk
make docker-up        # собрать+поднять (или: docker compose up -d --build)
curl -s http://127.0.0.1:8420/api/v1/health              # {"status":"ok"}
docker logs md2vk     # логи контейнера
ls -t logs/           # аудит-лог (JSONL)
```

## Публикация через API (пример)

```bash
API_KEY=$(cat secrets/estorozhenko_api_key.txt)
curl -s http://127.0.0.1:8420/api/v1/publish \
  -H "Content-Type: application/json" \
  -d "{\"api_key\":\"$API_KEY\",\"vk_account_id\":1,\"message_md\":\"**Привет** из md2vk\"}"
```

Сначала добавить VK-аккаунт: `POST /api/v1/accounts` c `access_token` (VK OAuth-токен, scope wall).

## Git-схема

- Истина: gitverse.ru (kpa39l/md2vk) — push через `https://kpa39l:<PAT>@gitverse.ru/kpa39l/md2vk.git`
  (SSH-ключ ~/.ssh/gitverse также работает); PAT в `/opt/hermes/.hermes/secrets/git-tokens.env` ($GITVERSE_PAT)
- Зеркало: gitea.nixg.ru (estorozhenko/md2vk) — pull mirror, обновляется автоматически (8h)
- Ветки: main (default)

## Ключевые лица/доступы

- Владелец: estorozhenko (пользователь Hermes), kpa39l (gitverse-аккаунт, email kpa39l@yandex.ru)
- vps02: 87.242.100.206 (estorozhenko, sudo по ключу), Caddy + fail2ban
- bigbox: 10.8.0.2 (локальный хост), проект /opt/md2vk
- DNS: nixg.ru (Jino), A-запись md2vk → 87.242.100.206