Initial commit: VMware vSphere API simulator scaffold.

Add the FastAPI app, PostgreSQL migrations, Docker/Helm packaging, API
contracts, docs, client examples, and the unit/integration/compatibility
test suite for local client and tooling labs without a real vCenter.

docs/ru/troubleshooting.md

@@ -0,0 +1,75 @@
+**Language / Язык:** [English](../troubleshooting.md) | [Русский](troubleshooting.md)
+
+# Устранение неполадок
+
+## Ready остаётся недоступным
+
+1. Проверьте Postgres: `make logs` / health в Compose.
+2. Выполните `make db-migrate`.
+3. Снова вызовите `/health/ready`.
+
+Task workers могут повторять попытки, пока миграции не догонят после позднего migrate.
+
+## Неожиданный HTTP 501
+
+У каждого зарегистрированного маршрута должен быть реальный обработчик или
+DB-backed стаб — 501 не должен появляться для известного пути. Если вы его видите:
+
+- Убедитесь, что вызываете точный зарегистрированный path/verb (проверьте
+  `app/vsphere/rest/coverage.py` или `/docs`).
+- 501 от опционального legacy-стаба (`ENABLE_PVE_STUB=true`) ожидается для
+  необъявленных методов в стиле PVE, когда `CONTRACT_FALLBACK=error`; это
+  не относится к native vSphere-поверхности.
+- Сообщите о регрессии — на native vSphere-плоскости ожидается полное
+  покрытие реестра.
+
+## 401 / 403
+
+- Сессия истекла (скользящий TTL 2 часа) или заголовок/cookie
+  `vmware-api-session-id` не отправлен.
+- Некорректный Basic auth на `/api/session` (отсутствует заголовок, неверный
+  base64 от `user:password`).
+- Отказ по правам — попробуйте сравнить `administrator@vsphere.local` и
+  `readonly@vsphere.local` (см. [Авторизация](domains/authz.md)).
+
+## Задача никогда не завершается
+
+- Изучите `/api/cis/tasks/{task}`.
+- Проверьте логи worker/симулятора (`make logs`).
+- Убедитесь, что `TASK_WORKER_CONCURRENCY` > 0 и аренды в базе данных можно
+  забрать (claim).
+- Очень высокий `SIMULATION_TIME_SCALE` даёт необычные замедления (больше =
+  быстрее симуляция); чаще виноваты неверно заданные worker-аренды.
+
+## Сбои TLS / gateway
+
+- Используйте порт хоста **443** (gateway) для TLS-клиентов — pyvmomi,
+  govmomi, провайдер Terraform `hashicorp/vsphere`, Pulumi.
+- Устанавливайте `verify_ssl=False` / `allow_unverified_ssl=true` **только**
+  для локального self-signed development-сертификата.
+- Внутри Compose обращайтесь напрямую к `simulator:8080` (обычный HTTP, без
+  gateway).
+- Seeded-имена ВМ для `small` — `web-01`, `web-02`, `db-01`, `app-01`,
+  `jumpbox`, а не Proxmox-style `pve01`/VMID.
+
+## Drift Terraform / Pulumi / Ansible после reseed
+
+Reseed заменяет инвентарь в PostgreSQL (MOID-ы и имена ВМ могут измениться);
+состояние внешних инструментов автоматически не обновляется. Выполните
+refresh, import или пересоберите стеки после `make seed`.
+
+## Hot-swap «ничего не сделал»
+
+- Просмотр каталога ≠ apply. Используйте **Apply as runtime** или
+  `POST /ui/api/contract/apply?major=N`.
+- Применение мажора меняет **каталог Web UI / представление evidence**, а не
+  живую таблицу маршрутов — runtime всегда обслуживает полную
+  зарегистрированную поверхность. См. [Версии API](api-versions.md).
+- Apply локален для процесса; перезапуск Compose возвращает к значению по
+  умолчанию (мажор 9).
+
+## Demo unload удивил
+
+`POST /ui/api/demo/unload` очищает состояние, созданное через API, и
+загружает `small`. Повторите `make seed` (или снова загрузите
+`demo-cluster`), чтобы восстановить более богатую фикстуру.