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/api-versions.md

@@ -0,0 +1,77 @@
+**Language / Язык:** [English](api-versions.md) | [Русский](ru/api-versions.md)
+
+# API versions (vSphere catalog majors 6–9)
+
+The Web UI and evidence/compatibility reports browse four integer **catalog
+majors** that map onto vSphere Automation API label floors:
+
+| Major | vSphere label | Contract version string |
+|---|---|---|
+| 6 | 7.0 | `7.0.0` |
+| 7 | 7.0 U3 | `7.0.3` |
+| 8 | 8.0 | `8.0.0` |
+| 9 | 8.0 U2 (Automation 9.1 surface) | `8.0.2` |
+
+Definitions live in [`app/vsphere/contracts/matrix.py`](../app/vsphere/contracts/matrix.py)
+(`VERSIONS`, `PATH_FLOOR`). Each registered REST path has a **floor** — the
+lowest major at which it appears in the catalog — sourced from the same
+module. Undated paths default to the highest major (9) until catalogued.
+
+## Runtime vs catalog
+
+This is the most important distinction in the project:
+
+- **Catalog major** — controls what the Web UI endpoint tree, `/ui/api/catalog`,
+  and compatibility/evidence reports show for a given major.
+- **Runtime surface** — the simulator always serves the **full registered
+  route table** with deep handlers or DB-backed stubs, independent of the
+  active catalog major. A known path is never returned as HTTP 501 because of
+  a version floor.
+
+Hot-swapping the catalog major is therefore a **documentation/browse**
+switch, not a compatibility gate on live traffic. See
+[`available_for_request()`](../app/vsphere/contracts/matrix.py) for the exact
+policy.
+
+## Cold start
+
+`GET /api/appliance/system/version` reports the version string of the
+currently selected runtime source (defaults to `8.0.2` / major 9 unless the
+process overrides `app.state.runtime_source_version`).
+
+## Hot-swap (catalog browse)
+
+Browse any major in the Web UI catalog, or call:
+
+```http
+POST /ui/api/contract/apply?major=7
+```
+
+Effects:
+
+- The Web UI catalog, `/ui/api/compatibility`, and evidence reports switch to
+  major 7's floor and ledger (`evidence/vsphere-7.0.3.json`).
+- The change is **process-local** and **not persisted**; a restart returns to
+  the default (major 9).
+- REST/SOAP routes already registered continue to answer with their real
+  handlers regardless of the applied major.
+
+### Client guidance
+
+- Most clients (pyvmomi, govmomi, Terraform, Pulumi, Ansible `uri`) do not
+  need to pin a catalog major — the runtime surface does not change shape
+  based on it.
+- Use catalog majors when you specifically want the Web UI / evidence view to
+  reflect an older vSphere label for documentation or screenshots.
+- After apply, re-check `/ui/api/compatibility?major=N` for the active
+  catalog state.
+
+## Regenerating catalog artifacts
+
+```bash
+make vsphere-bundles     # stub OpenAPI matrices + evidence ledgers
+make vsphere-universe    # regenerate universe.json from the Broadcom operations index
+make evidence            # regenerate per-major verified surface evidence ledgers
+```
+
+See [API surface](api-surface.md) and [Compatibility](compatibility.md).