Prepare 0.1.0 for lab release: durable handlers, HTTP Compose, CI, and pulumi-tests.

- Harden DB-backed handlers and seed profiles; align client wire shapes for
  cluster resources, QEMU config, and node SSL fields
- Serve plain HTTP on Compose :8006; keep TLS optional (--profile tls) and
  terminate HTTPS at Kubernetes Ingress
- Add pulumi-tests (full contract surface majors 6–9 + BPG lifecycle) and
  make pulumi-tests
- Ship bilingual docs, CHANGELOG, SECURITY, CONTRIBUTING, and GitHub Actions
  (make ci + Compose/Helm validation)

docs/ru/examples/ansible.md

@@ -0,0 +1,14 @@
+**Language / Язык:** [English](../../examples/ansible.md) | [Русский](ansible.md)
+
+# Ansible
+
+Playbook использует модуль `uri` для HTTP `:8006` с аутентификацией по токену, затем
+ticket+CSRF для пути мутации.
+
+```bash
+cd examples/ansible
+ansible-playbook -i inventory.ini playbook.yml
+```
+
+Перед использованием фиксированных VMID из предыдущего запуска выполните повторный seed
+симулятора.

docs/ru/examples/go.md

@@ -0,0 +1,13 @@
+**Language / Язык:** [English](../../examples/go.md) | [Русский](go.md)
+
+# Go
+
+Использует стандартную библиотеку Go для `http://localhost:8006` с аутентификацией
+по API-токену.
+
+```bash
+cd examples/go
+go run .
+```
+
+См. `main.go` — там cookbook-поток и вспомогательная функция опроса UPID.

docs/ru/examples/java.md

@@ -0,0 +1,13 @@
+**Language / Язык:** [English](../../examples/java.md) | [Русский](java.md)
+
+# Java
+
+Cookbook на Java 11+ `HttpClient` с аутентификацией по API-токену через `:8006`.
+
+```bash
+cd examples/java
+javac Cookbook.java && java Cookbook
+```
+
+Сторонние JSON-библиотеки не нужны — ответы разбираются простыми строковыми
+вспомогательными функциями, достаточными для лабораторного smoke-теста.

docs/ru/examples/overview.md

@@ -0,0 +1,58 @@
+**Language / Язык:** [English](../../examples/overview.md) | [Русский](overview.md)
+
+# Обзор примеров клиентов
+
+## Чеклист запуска
+
+```bash
+make up
+curl -sf http://localhost:8006/health/ready
+make seed PROFILE=small
+curl -s http://localhost:8006/api2/json/version
+```
+
+Опционально — зафиксировать major 8 на время сессии:
+
+```bash
+curl -s -X POST 'http://localhost:8006/ui/api/contract/apply?major=8'
+```
+
+## Эндпоинты
+
+| URL | Когда использовать |
+|---|---|
+| `http://localhost:8006` | curl, Go, Java, Perl, Ansible, requests |
+| `http://localhost:8006` | proxmoxer, многие TLS-клиенты Terraform/Pulumi |
+
+## Краткая справка по аутентификации
+
+**Ticket**
+
+```bash
+RESP=$(curl -s -X POST -d 'username=root@pam&password=secret' \
+  http://localhost:8006/api2/json/access/ticket)
+TICKET=$(echo "$RESP" | jq -r .data.ticket)
+CSRF=$(echo "$RESP" | jq -r .data.CSRFPreventionToken)
+```
+
+**Заголовок токена**
+
+```text
+Authorization: PVEAPIToken=root@pam!automation=automation-secret
+```
+
+## Ожидание UPID
+
+Никогда не считайте, что ВМ уже запущена, только по HTTP-ответу мутации. Опрашивайте
+`/nodes/{node}/tasks/{upid}/status`, пока `data.status` не станет терминальным (обычно
+`stopped` с кодом выхода OK для завершённых задач — используйте поля Proxmox, которые
+ваш клиент уже понимает).
+
+## Предупреждение о повторном seed
+
+`make seed` заменяет гостей в PostgreSQL. После этого обновите состояние
+Terraform/Pulumi/Ansible.
+
+## Запускаемое дерево примеров
+
+См. [`examples/README.ru.md`](../../../examples/README.ru.md).

docs/ru/examples/perl.md

@@ -0,0 +1,11 @@
+**Language / Язык:** [English](../../examples/perl.md) | [Русский](perl.md)
+
+# Perl
+
+Cookbook на `HTTP::Tiny` + JSON с аутентификацией по API-токену.
+
+```bash
+cd examples/perl
+cpanm --installdeps .   # или установите HTTP::Tiny и JSON вручную
+perl cookbook.pl
+```

docs/ru/examples/pulumi.md

@@ -0,0 +1,15 @@
+**Language / Язык:** [English](../../examples/pulumi.md) | [Русский](pulumi.md)
+
+# Pulumi
+
+Python-программа Pulumi, управляющая симулятором по HTTPS с аутентификацией по токену
+через паттерны Pulumi Command/provider, описанные в `examples/pulumi`.
+
+```bash
+cd examples/pulumi
+pulumi stack init dev   # один раз
+pulumi up
+```
+
+Та же осторожность, что и с Terraform: состояние PostgreSQL симулятора и состояние Pulumi
+независимы. Зафиксируйте major API для воспроизводимого CI.

docs/ru/examples/python-proxmoxer.md

@@ -0,0 +1,23 @@
+**Language / Язык:** [English](../../examples/python-proxmoxer.md) | [Русский](python-proxmoxer.md)
+
+# Python — proxmoxer
+
+Канонический путь через библиотеку к HTTPS-шлюзу.
+
+## Запуск
+
+```bash
+make up && make seed PROFILE=small
+pip install -r examples/python/requirements.txt
+python examples/python/proxmoxer_cookbook.py
+```
+
+Переопределение через переменные окружения: `PVE_HOST` (по умолчанию `localhost`),
+`PVE_PORT` (по умолчанию `8007`), `PVE_USER`, `PVE_PASSWORD`, либо токен через
+`PVE_TOKEN_NAME` / `PVE_TOKEN_VALUE`.
+
+## Заметки
+
+- `verify_ssl=False` нужен только для одноразового локального сертификата.
+- Мутации по ticket, которые обрабатывает proxmoxer, автоматически включают CSRF.
+- Узел по умолчанию для профиля `small` — `pve01`.

docs/ru/examples/python-requests.md

@@ -0,0 +1,13 @@
+**Language / Язык:** [English](../../examples/python-requests.md) | [Русский](python-requests.md)
+
+# Python — requests
+
+Сырой HTTP к `:8006` без proxmoxer.
+
+```bash
+pip install -r examples/python/requirements.txt
+python examples/python/requests_cookbook.py
+```
+
+Скрипт демонстрирует аутентификацию по токену (без CSRF) и по ticket (с CSRF) для
+общего потока create → wait → start → stop → delete.

docs/ru/examples/terraform.md

@@ -0,0 +1,20 @@
+**Language / Язык:** [English](../../examples/terraform.md) | [Русский](terraform.md)
+
+# Terraform
+
+Пример использует провайдер Proxmox, направленный на локальный HTTPS-шлюз
+(`http://localhost:8006`) с `insecure = true` для разработческого сертификата.
+
+```bash
+cd examples/terraform
+terraform init
+terraform apply
+```
+
+Версии плагинов провайдера меняются быстро — зафиксируйте версии в `versions.tf` на
+те, что вы протестировали. После `make seed` обновите или пересоздайте state, чтобы
+предположения о VMID и узле оставались согласованными.
+
+Этот cookbook — отправная точка для лабораторного CI, а не сертификация каждого
+ресурса провайдера по всем четырём major API. Зафиксируйте major симулятора перед
+apply (`CONTRACT_SNAPSHOT` или hot-swap + проверка `/version`).

docs/ru/examples/troubleshooting-clients.md

@@ -0,0 +1,13 @@
+**Language / Язык:** [English](../../examples/troubleshooting-clients.md) | [Русский](troubleshooting-clients.md)
+
+# Устранение неполадок клиентов
+
+| Симптом | Решение |
+|---|---|
+| Ошибки TLS-сертификата | Используйте `http://localhost:8006` с отключённой проверкой **только** локально (`curl -sk`, `verify_ssl=False`, `insecure=true`) |
+| Ошибка CSRF | Передавайте `CSRFPreventionToken` при мутациях по ticket; в скриптах предпочитайте аутентификацию по токену |
+| Узел не найден | Профиль `small` использует `pve01` |
+| 403 на power | Возможно, используется `auditor@pve` / readonly-токен — переключитесь на root или operator |
+| Создание провайдером vs UPID | Опрашивайте задачи; многие провайдеры уже ждут — сырые HTTP-клиенты часто забывают |
+| Расхождение после reseed | Обновите/пересоздайте состояние Terraform/Pulumi/Ansible |
+| Неверные поля схемы | Hot-swap или cold-start нужного major; проверьте `/version` |