# AI Context

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

Этот набор документов фиксирует стабильный, подтвержденный репозиторием контекст
HomeLab. Он дополняет краткий рабочий контракт в [`AGENTS.md`](../../AGENTS.md) и
не заменяет канонические Ansible inventory/vars или операционные заметки Obsidian.

HomeLab управляется как Ansible-first control plane: Proxmox VE/LXC, сетевой
транспорт, сервисы, резервное копирование, обновления и мониторинг описываются в
`ansible/`. Прямые изменения на серверах допустимы только для read-only диагностики
или break-glass восстановления с последующим переносом желаемого состояния в Ansible.

## Возможности

- создание и настройка LXC через Proxmox API или `pct` по SSH;
- управление сервисами через Docker/systemd и Docker Compose/systemd;
- OpenVPN-транспорт и SSH ProxyJump через `ru-vps`;
- Caddy reverse proxy для публичных сервисов;
- PBS и offsite restic backups с аудитом свежести;
- управляемые обновления по схеме backup/audit -> update -> health check;
- активный Uptime Kuma и сохраненный, но замороженный Prometheus stack;
- локальный Grimmory MCP с ручной синхронизацией книг в Obsidian.

## Форма системы

- `ansible/Makefile` является основной ручной точкой входа.
- `ansible/inventory/hosts.yml` задает хосты, группы и индивидуальные адреса.
- `ansible/inventory/group_vars/all/services.yml` содержит сводный реестр сервисов,
  но пока программно управляет только генерацией reverse proxy.
- `ansible/playbooks/` содержит операционные entry points, `ansible/roles/` - роли.
- `tools/grimmory-mcp/` является отдельным Node.js stdio MCP-процессом.
- Obsidian vault хранит решения, текущую эксплуатационную картину и журнал работ.

## Карта репозитория

| Путь | Назначение |
|---|---|
| `ansible/Makefile` | Проверки, deploy, update и защищенные операции |
| `ansible/inventory/` | Канонические хосты, группы, общие и host-specific vars |
| `ansible/playbooks/` | Операционные Ansible entry points |
| `ansible/roles/` | Переиспользуемые роли и сохраненный monitoring stack |
| `ansible/ssh_config` | SSH users, keys, ports и ProxyJump |
| `.opencode/agents/` | Read-only специализированные агенты HomeLab |
| `tools/grimmory-mcp/` | Grimmory API и Obsidian sync integration |
| `archive/2026-07-proxmox-migration/` | История до Ansible control plane, не active source |

## Ключевые ограничения

- Не хранить secrets в Git или Obsidian.
- Не считать `--check --diff` полной симуляцией Proxmox provisioning.
- Не запускать замороженный Prometheus stack без отдельного решения.
- Не считать generic roles `lxc_docker_host` и `compose_service` подключенными к
  production: активные service playbooks пока остаются источником поведения.
- Не исправлять обнаруженный технический долг в рамках несвязанной задачи.
- Не редактировать archive, generated files, installed Galaxy collections или
  `node_modules` как active implementation.

## Документы

- [`architecture.md`](architecture.md) - observed architecture и data/control flows.
- [`tech-stack.md`](tech-stack.md) - runtimes, dependencies и команды.
- [`edge-cases.md`](edge-cases.md) - failure modes, safety gaps и coverage.
- [`plan.md`](plan.md) - только подтвержденная активная работа.
- [`migration-tofu.md`](migration-tofu.md) - пошаговый план перехода provisioning
  LXC на OpenTofu по схеме blue-green.
- [`legacy-warning.md`](legacy-warning.md) - границы legacy/frozen/prototype кода.
- [`links.md`](links.md) - официальные version-relevant references.