docs: дополнить руководство для агентов (базовые понятия с нуля)

AGENTS.md

@@ -13,6 +13,60 @@
 
 ---
 
+## 0. Кому адресован этот файл
+
+Файл написан для **стороннего ИИ-агента, который не знает о предметной области ничего**.
+Если ты такой агент — прочитай файл целиком, прежде чем советовать. Ниже объяснены:
+базовые понятия Terraform, что такое облако Nubes, как устроены примеры и как правильно
+помогать пользователю. Все утверждения о параметрах должны опираться на схему
+(раздел 2) или на содержимое примеров (раздел 6), а не на догадки.
+
+## 0.1. Базовые понятия Terraform (с нуля)
+
+- **Terraform** — инструмент «инфраструктура как код» (Infrastructure as Code). Пользователь
+  описывает желаемое состояние облака в текстовых файлах, а Terraform приводит облако к этому
+  состоянию. Ничего не делается руками в интерфейсе — всё описано в коде.
+- **HCL** — язык этих файлов (расширение `.tf`). Пример блока ресурса:
+  ```hcl
+  resource "nubes_postgres" "main_pg" { … }   # тип ресурса — nubes_postgres, локальное имя — main_pg
+  ```
+- **Провайдер** — плагин, через который Terraform общается с конкретным облаком. Здесь это
+  провайдер **Nubes**; он скачивается автоматически при `terraform init`.
+- **Ресурс** — объект в облаке (кластер БД, виртуальная машина, бакет и т.п.).
+- **Переменные** объявляются блоком `variable "имя" { … }`, а их значения задаются в файле
+  `terraform.tfvars` — это то, что заполняет пользователь под свою организацию.
+- **Файл состояния** (`terraform.tfstate`) хранит соответствие «код ↔ реальные объекты».
+  Его **не редактируют вручную**.
+- **Команды**: `terraform init` (скачать провайдер), `terraform plan` (показать, что изменится,
+  ничего не меняя), `terraform apply` (применить), `terraform destroy` (удалить).
+- Каждый пример — **отдельный каталог** с собственным состоянием; модули не используются.
+
+## 0.2. Что такое Nubes
+
+**Nubes** — облачная платформа, предоставляющая услуги «как сервис»: базы данных
+(PostgreSQL, MongoDB, Redis, MariaDB, ClickHouse), очереди (Kafka, RabbitMQ), Kubernetes
+(«Штурвал»), виртуализацию VMware (vDC, Edge, виртуальные машины), объектное хранилище S3,
+готовые приложения (Node.js, Flask, Lucee и др.) и сеть (DNS, внешние IP, SNAT).
+
+- Управляется через **Личный кабинет (ЛК)** и **API**. Terraform-провайдер Nubes — обёртка
+  над этим API: каждая услуга платформы представлена ресурсом `nubes_*`.
+- Ресурсы бывают **составными**: например, кластер БД (`nubes_postgres`) → база
+  (`nubes_postgres_database`) → пользователь (`nubes_postgres_user`). Часть ресурсов —
+  **модификаторы** уже существующих услуг (внешние IP, SNAT).
+- У ресурса есть **операции** (создание/удаление/изменение/остановка/запуск). Провайдер сам
+  вызывает нужную операцию по командам Terraform.
+- Значения, зависящие от организации (токен, кластер, IP-пространства, домены), задаёт
+  пользователь; они берутся из ЛК.
+
+## 0.3. Зачем эти примеры и как их используют
+
+Пользователь клонирует репозиторий, копирует `terraform.tfvars.example` → `terraform.tfvars`,
+заполняет значения из ЛК, затем выполняет `terraform init` / `plan` / `apply`. Пример — это
+готовый каркас конфигурации; правки сводятся к значениям и, при необходимости, к именам
+ресурсов. Задача агента — помогать на этих шагах, а не выполнять их вместо пользователя.
+
+---
+
 ## 1. Что это за репозиторий
 
 Здесь лежат законченные сценарии развёртывания инфраструктуры в облаке Nubes через
@@ -304,4 +358,17 @@ provider "nubes" {
 | `vApp` | виртуальный каталог; контейнер для ВМ |
 | `suspend` | остановка ресурса с сохранением данных |
 | `adopt` | «усыновление» уже существующего ресурса по имени |
+| **ЛК** | Личный кабинет Nubes — веб-интерфейс управления услугами |
+| **услуга / инстанс** | конкретный объект в облаке, созданный по ресурсу |
+| **операция** | действие платформы над услугой: `create`/`delete`/`modify`/`suspend`/`resume` и др. |
+| `resource_name` | имя услуги в ЛК; по нему провайдер находит и усыновляет объект |
+| `startup_configuration` | параметры размещения (например `resource_realm` — кластер Kubernetes) |
+| `access_configuration` | сетевой доступ: IP-списки, внешний IP |
+| `backup_configuration` | резервное копирование: `schedule` (cron), `retain` (срок хранения) |
+| `json_env` | переменные окружения приложения (JSON) |
+| `git_revision` | версия кода приложения; смена значения → redeploy |
+| `domain` | доменное имя приложения (полный суффикс платформа добавляет сама) |
+| **HCL** | язык конфигурации Terraform (файлы `.tf`) |
+| `terraform.tfvars` | файл значений переменных; в этом репозитории — в `.gitignore` |
+| `terraform.tfstate` | файл состояния Terraform; хранит соответствие «код ↔ облако» |