docs: migration guide + mocks.json -> OpenAPI conversion script

[MaxMichel2]

Part of #72

Depends on #1 through #8 being at least functionally complete (this is the last 0.2.0 issue — it documents and tooling-supports the finished migration).

Summary

Write a migration guide for integrators upgrading from a pre-0.2.0 mocks.json-based setup, and ship a small conversion script so nobody has to hand-translate their mocks.json into OpenAPI.

Why this needs its own issue

This is a big-bang breaking change (per the epic's decision table) — there is no dual-format transition period. Every existing integrator's mocks.json stops working the moment they upgrade to 0.2.0. Without a migration guide and a conversion script, that upgrade is a hostile experience: a hand-written OpenAPI spec is significantly more effort than a mocks.json for anyone with more than a couple of endpoints.

What to build

docs/guides/migrating-to-openapi.md

Should cover, concretely:

• What changed and why (short version of the epic's rationale — link back to it, don't duplicate the whole writeup)
• Field-by-field mapping: old mocks.json field → new OpenAPI field (e.g. apiGroups[].id → filename/info.title per spec, endpoints[].id → operationId, environments[].url → servers[].url, endpointOverrides → just add another paths entry)
• What to do about environments specifically: staging/prod entries collapse to a single servers[] list (pick whichever URL(s) the mocking use case actually needs — see Feature/feature flip #2's rationale for why there's no equivalent to endpointOverrides needed anymore, since versions/variants are just additional paths entries in the same spec)
• How response files need to move/be referenced (declared examples.<name>.externalValue per Feature/analytics #4, vs. today's directory-tier + filename convention)
• Any DataStore-level consequence (previously-selected mocks reset once — link to API mocking module #6)
• A worked example, ideally using the sample app's before/after from ⬆️ Update kotlin #8 as the reference

Conversion script

A script (scripts/mocks-json-to-openapi.<kts|py> — pick whichever this repo's existing scripts/ directory conventions favor, check scripts/build_docs.sh and scripts/release.sh for the established language/style) that:

• Reads an existing mocks.json
• Emits one OpenAPI JSON (or YAML) file per apiGroups[] entry
• Merges each group's environments' endpoints into the single spec's paths, using endpointOverrides/additionalEndpoints (if present) to produce whatever path variants existed before
• Emits a warning for anything it can't automatically translate (e.g. if the mapping is genuinely ambiguous) rather than silently guessing

This does not need to be a polished, general-purpose tool — it's a one-time upgrade aid, not a permanently-supported feature. Keep it simple; a script that handles the common shapes well and clearly flags what it couldn't handle is more valuable than one that tries to be exhaustive.

Acceptance criteria

• docs/guides/migrating-to-openapi.md exists and covers every mapping listed above.
• The conversion script successfully converts the original (pre-migration) version of the sample app's mocks.json (recover it from git history if ⬆️ Update kotlin #8 has already replaced it) into a spec that the new parser (✨ Add initial DevView #1) accepts.
• The script is referenced from the migration guide with a usage example.
• CHANGELOG.md at the repo root documents the 0.2.0 breaking change with a pointer to the migration guide (per this repo's changelog convention — root file is the source of truth, docs/changelog.md is built from it automatically, do not edit the built copy directly).

Files likely touched

• docs/guides/migrating-to-openapi.md (new)
• scripts/mocks-json-to-openapi.<ext> (new)
• CHANGELOG.md

[github-actions]

This issue is stale because it has been open for 21 days with no activity.