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/troubleshooting.md

@@ -0,0 +1,71 @@
+**Language / Язык:** [English](troubleshooting.md) | [Русский](ru/troubleshooting.md)
+
+# Troubleshooting
+
+## Ready stays unavailable
+
+1. Confirm Postgres: `make logs` / Compose health.
+2. Run `make db-migrate`.
+3. Hit `/health/ready` again.
+
+Task workers may retry until migrations catch up after a late migrate.
+
+## Unexpected HTTP 501
+
+Every registered route should have a real handler or DB-backed stub — 501
+should not appear for a known path. If you see it:
+
+- Confirm you are calling the exact registered path/verb (check
+  `app/vsphere/rest/coverage.py` or `/docs`).
+- 501 from the optional legacy stub (`ENABLE_PVE_STUB=true`) is expected for
+  undeclared PVE-style methods when `CONTRACT_FALLBACK=error`; it is
+  unrelated to the vSphere surface.
+- Report a regression — full registry coverage is expected on the native
+  vSphere plane.
+
+## 401 / 403
+
+- Session expired (2-hour sliding TTL) or `vmware-api-session-id` header/cookie
+  not sent.
+- Basic auth malformed on `/api/session` (missing header, wrong
+  `user:password` base64).
+- Privilege denial — try `administrator@vsphere.local` vs
+  `readonly@vsphere.local` to compare (see [Authorization](domains/authz.md)).
+
+## Task never finishes
+
+- Inspect `/api/cis/tasks/{task}`.
+- Check worker/simulator logs (`make logs`).
+- Verify `TASK_WORKER_CONCURRENCY` > 0 and database leases can be claimed.
+- Extremely high `SIMULATION_TIME_SCALE` slowdowns are unusual (higher =
+  faster simulation); mis-set worker leases are more common culprits.
+
+## TLS / gateway failures
+
+- Use host port **443** (gateway) for TLS clients — pyvmomi, govmomi,
+  Terraform's `hashicorp/vsphere` provider, Pulumi.
+- Set `verify_ssl=False` / `allow_unverified_ssl=true` **only** for the local
+  self-signed development certificate.
+- Inside Compose, target `simulator:8080` directly (plain HTTP, no gateway).
+- Seeded VM names for `small` are `web-01`, `web-02`, `db-01`, `app-01`,
+  `jumpbox` — not Proxmox-style `pve01`/VMIDs.
+
+## Terraform / Pulumi / Ansible drift after reseed
+
+Reseed replaces PostgreSQL inventory (MOIDs and VM names can change);
+external tool state does not update automatically. Refresh, import, or
+rebuild stacks after `make seed`.
+
+## Hot-swap "did nothing"
+
+- Catalog browse ≠ apply. Use **Apply as runtime** or
+  `POST /ui/api/contract/apply?major=N`.
+- Applying a major changes the **Web UI catalog / evidence view**, not the
+  live route table — the runtime always serves the full registered surface.
+  See [API versions](api-versions.md).
+- Apply is process-local; a Compose restart returns to the default (major 9).
+
+## Demo unload surprised you
+
+`POST /ui/api/demo/unload` clears API-created state and loads `small`. Re-run
+`make seed` (or load `demo-cluster` again) to restore a richer fixture.