Sync documentation with the actual infrastructure

The host table listed 9 hosts against 16 in the inventory, the role tree
did not match roles/, and the documented setup path used a venv that no
longer works.

Describe the current entry points instead: nix develop, make, and the
ssh_config include that makes `ssh gitea` work by hand. Point at
`make docs` as the way to regenerate the host table rather than editing
it, since that is what drifted.

Also record what is deliberately incomplete: lxc_docker_host and
compose_service exist but are not wired into any playbook, and LXC
creation is still split between direct pct create over SSH and the
pve_lxc API role.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GTocXkGUUazHdKKd3r9k71

README.md

@@ -1,34 +1,60 @@
 # HomeLab Infrastructure
 
-Active HomeLab infrastructure is managed through Ansible.
+Активная инфраструктура домашней лаборатории управляется через Ansible.
+Каноничные инструкции для людей и агентов — в [AGENTS.md](./AGENTS.md).
 
-## Active Files
+## Быстрый старт
 
-- `ansible/` — current control plane.
-- `ansible/inventory/hosts.yml` — inventory and host facts.
-- `ansible/playbooks/check.yml` — safe connectivity/facts check.
+Окружение собрано в Nix, venv не нужен:
 
-## Archive
+```bash
+nix develop                 # или один раз: direnv allow
 
-Historical pre-Proxmox material is kept under:
-
-```text
-archive/2026-07-proxmox-migration/
+# Один раз на клон
+ansible-galaxy collection install -r ansible/requirements.yml -p ansible/collections
 ```
 
-It contains old NixOS configs, Docker Compose service definitions, Gitea workflows, deploy scripts and old Ansible bootstrap playbooks.
-
-## Basic Check
+Всё управление — через `make` из `ansible/`:
 
 ```bash
 cd ansible
-ansible-playbook playbooks/check.yml
+make help                   # список целей, начинать отсюда
+make check                  # связность и ожидаемые IP
+make status                 # read-only сводка по всей инфраструктуре
+make lint                   # ansible-lint + yamllint
 ```
 
+Деплой и обновления:
+
+```bash
+make dry-gitea              # предпросмотр (--check --diff)
+make deploy-gitea           # применить
+make update-gitea           # бэкап -> обновление -> health-check
+```
+
+`.env` с Proxmox-токенами подхватывается автоматически. Опасные цели требуют `CONFIRM=1`.
+
+## SSH руками
+
+`ansible/ssh_config` — единый источник правды по SSH и для Ansible, и для терминала.
+Добавь в `~/.ssh/config`, чтобы заработал `ssh gitea`:
+
+```
+Include /home/ada/Documents/Projects/HomeLab/infras/ansible/ssh_config
+```
+
+## Структура
+
+- `ansible/` — control plane: `Makefile`, `inventory/`, `playbooks/`, `roles/`, `ssh_config`
+- `ansible/inventory/group_vars/all/services.yml` — реестр сервисов (VMID, IP, порты, домены, образы)
+- `flake.nix` — dev-окружение
+- `.gitea/workflows/lint.yml` — CI: yamllint, ansible-lint, syntax-check
+- `archive/2026-07-proxmox-migration/` — исторические NixOS/Docker конфиги, только как справка
+
 ## Grimmory MCP
 
-`tools/grimmory-mcp/` contains the read-only Grimmory API integration for
-OpenCode and the explicitly invoked Obsidian synchronization tools.
+`tools/grimmory-mcp/` содержит read-only интеграцию с Grimmory API для OpenCode
+и явно вызываемые инструменты синхронизации с Obsidian.
 
 ```bash
 npm install --prefix tools/grimmory-mcp
@@ -36,6 +62,6 @@ npm run configure --prefix tools/grimmory-mcp
 npm test --prefix tools/grimmory-mcp
 ```
 
-OpenCode registers the server globally. After restarting OpenCode, use
-`/grimmory-sync` to update individual book notes under `90 Library/Books` and
-covers under `99 System/Export/Grimmory/Covers`.
+OpenCode регистрирует сервер глобально. После перезапуска OpenCode используй
+`/grimmory-sync` для обновления заметок книг в `90 Library/Books` и обложек
+в `99 System/Export/Grimmory/Covers`.