infra/AGENTS.md

# AGENTS.md

## Назначение

HomeLab infras - Ansible-first control plane для домашней инфраструктуры на
Proxmox VE. Желаемое состояние хранится в inventory, vars, roles и playbooks;
прямые изменения на серверах допустимы только для read-only диагностики или
break-glass восстановления и затем должны быть отражены в Ansible.

Стабильный контекст проекта находится в [`docs/ai/`](docs/ai/README.md). Не
загружай весь набор по умолчанию: читай только документы, относящиеся к задаче.

## Что читать

| Задача | Контекст |
|---|---|
| Любое изменение | `README.md`, [`docs/ai/README.md`](docs/ai/README.md), релевантная секция [`architecture.md`](docs/ai/architecture.md) |
| Inventory или новый service | `ansible/inventory/hosts.yml`, `ansible/inventory/group_vars/all/services.yml`, [`architecture.md`](docs/ai/architecture.md), [`edge-cases.md`](docs/ai/edge-cases.md) |
| Provisioning или update | `ansible/README.md`, relevant playbook/role, [`edge-cases.md`](docs/ai/edge-cases.md), [`legacy-warning.md`](docs/ai/legacy-warning.md) |
| Network, SSH, OpenVPN, Caddy | `ansible/ssh_config`, `ansible/inventory/group_vars/all/main.yml`, [`architecture.md`](docs/ai/architecture.md), [`links.md`](docs/ai/links.md) |
| Backups и recovery | `ansible/playbooks/pve-backup-jobs.yml`, `ansible/roles/backup_audit/`, [`architecture.md`](docs/ai/architecture.md), [`edge-cases.md`](docs/ai/edge-cases.md) |
| Grimmory MCP | `tools/grimmory-mcp/README.md`, [`tech-stack.md`](docs/ai/tech-stack.md), [`edge-cases.md`](docs/ai/edge-cases.md) |
| Legacy/frozen code | [`legacy-warning.md`](docs/ai/legacy-warning.md) |
| Переезд на OpenTofu | [`migration-tofu.md`](docs/ai/migration-tofu.md), `tofu/README.md`, `tofu/*.tf` |
| Текущая работа | [`plan.md`](docs/ai/plan.md); `current-task.md` является историческим планом |

Перед инфраструктурными изменениями прочитай релевантные заметки в Obsidian:

`/home/ada/Documents/Vaults/SecondBrain/02 Projects/HomeLab/`

Основные заметки: `HomeLab.md`,
`Notes/Текущее состояние HomeLab после миграции на Proxmox.md`, `Log.md`.
После изменения обнови соответствующую заметку, если изменились topology,
операционная процедура, решение или неочевидное ограничение.

## Источники правды

- Hosts и groups: `ansible/inventory/hosts.yml`.
- Shared network/access vars: `ansible/inventory/group_vars/all/main.yml`.
- Service facts: `ansible/inventory/group_vars/all/services.yml`.
- SSH users, keys, ports и ProxyJump: `ansible/ssh_config`.
- Manual operations и safety gates: `ansible/Makefile`.
- Secrets: ignored `.env` в КОРНЕ репозитория; его читают и Make/Ansible, и OpenTofu.
- Human decisions и operations log: HomeLab Obsidian vault.

Программные потребители реестра:

- `playbooks/reverse-proxy.yml` — сборка Caddyfile;
- `playbooks/ru-vps-base.yml` — стек Caddy и его закреплённый образ;
- `playbooks/pve-backup-jobs.yml` — списки VMID заданий PBS (поле `backup.job`);
- `roles/backup_audit` — VMID для аудита (флаг `monitoring.backup_audit_vmid`);
- `playbooks/validate.yml` — сверка реестра с фактическим состоянием Proxmox.

Остальное (`pve-*.yml`, `status.yml`, monitoring, SSH config) по-прежнему
дублирует значения и должно меняться согласованно.

`make validate` — read-only gate, проверяющий это расхождение.

## Границы

- Active control plane находится в `ansible/`.
- `archive/2026-07-proxmox-migration/` - только историческая справка; не редактировать
  и не возвращать из него конфигурацию как active implementation.
- Не редактировать generated artifacts, `ansible/collections/`, `.venv/`,
  `node_modules/`, `.direnv/` и secret-bearing ignored files.
- `roles/compose_service` подключён в `playbooks/ru-vps-base.yml` (стек Caddy).
  `roles/lxc_docker_host` не подключён нигде.
  Не считать active service playbooks устаревшими до отдельной миграции.
- Не исправлять найденный technical debt в несвязанной задаче без отдельного решения.
- Для новой VM/LXC/managed host по умолчанию provision public SSH key пользователя,
  если пользователь явно не указал иное.

## Setup и команды

Предпочтительное окружение - Nix:

```bash
nix develop                    # или один раз: direnv allow
ansible-galaxy collection install \
  -r ansible/requirements.yml \
  -p ansible/collections       # один раз на clone
```

Работай через Make из `ansible/` или с `make -C ansible` из root:

```bash
make -C ansible help
make -C ansible check
make -C ansible status EXTRA="--limit '!gyro'"
make -C ansible inventory
make -C ansible docs
make -C ansible lint
```

Локальный syntax-check всех playbooks, соответствующий CI:

```bash
nix develop -c sh -c \
  'cd ansible && for f in playbooks/*.yml; do ansible-playbook --syntax-check "$f"; done'
```

Grimmory MCP требует отдельный Node.js `>=22` runtime:

```bash
npm install --prefix tools/grimmory-mcp
npm test --prefix tools/grimmory-mcp
```

## Safety Contract

- Сначала выполняй smallest safe local validation, затем bounded live check только
  когда он нужен задаче.
- `make dry-<service>` использует `--check --diff`, но не является полной симуляцией
  Proxmox API или command-heavy `pct` playbooks.
- `make status` read-only, но его exit code не является health gate.
- `update-all`, `mihomo-harden` и frozen `monitoring` требуют `CONFIRM=1`.
- `gyro` требует Vault password; не обходи `make gyro` без явной причины.
- Service update order: fresh backup/audit -> update -> health check. Backup не
  означает automatic rollback.
- Uptime Kuma активен. Prometheus/Alertmanager/Grafana stack заморожен; не запускать
  его параллельно без отдельного architecture decision.
- Active remote images обычно pin по `tag@sha256:digest`; frozen Prometheus images
  tag-only. Floating auto-updaters не используются.
- Не включать cluster-wide PVE firewall без аудита всех guests с `firewall=1`.
- Не останавливать production services для fault injection без согласованного
  maintenance window.

## Secrets

- Никогда не коммить и не цитировать реальные passwords, tokens, private keys,
  `.env`, Vault plaintext, PBS/restic credentials или TLS keys.
- Используй ignored `.env` в корне репозитория, Ansible Vault, runtime prompt или
  external local secret file.
- `PROXMOX_ROOT_PASSWORD` (root@pam) нужен ТОЛЬКО целям `tofu-*` и только для
  привилегированных полей LXC. Ansible им не пользуется. Не логировать и не
  передавать в playbook vars.
- В Git допустимы только sanitized `.env.example` и encrypted Vault content.
- Secret-bearing tasks должны использовать `no_log: true`, а files - минимальные
  permissions.

## Рабочий процесс

1. Прочитай минимальный релевантный context и Obsidian notes.
2. Проверь active inventory, vars, playbook/role и связанные consumers.
3. Внеси smallest correct declarative change; не используй ad-hoc server edits.
4. Запусти минимальные local checks, затем только необходимые bounded live checks.
5. Проверь diff на broad targeting, secrets, destructive behavior и docs drift.
6. Обнови repository/Obsidian documentation для изменившихся решений и процедур.
7. В отчете перечисли changed files, проверки, неисполненные live checks и unknowns.

Для read-only reconnaissance, Ansible safety review, syntax validation, network/log
diagnostics, backup audit и Obsidian context используй специализированные агенты из
`.opencode/agents/`. Большие logs и command outputs передавай соответствующему
read-only summarizer и всегда ограничивай `--since`, `-n` или `--tail`.