Proposed work: document checked-in OpenAPI YAML export path for offline SDK generation

[yanyishuai]

Related bounty or source issue

Bounty #932
Related: #944 / PR #1175 (regenerated docs/openapi.yaml from FastAPI)

Problem

docs/api-examples.md points agents at $API_HOST/openapi.json, which is correct for live hosts, but contributors working offline or generating SDKs from a git checkout have no documented path to the checked-in OpenAPI YAML export once it lands. Without a short pointer, agents keep inventing divergent static specs (the failure mode that blocked early #1175 drafts).

Evidence

Current docs/api-examples.md mentions $API_HOST/openapi.json / /api/docs only. PR #1175 adds docs/openapi.yaml plus scripts/export_openapi.py and a path-alignment regression test. A docs-only follow-up would make the offline export discoverable after merge.

Proposed work

After #1175 (or equivalent) merges, add 2?4 lines to docs/api-examples.md (and optionally docs/agent-guide.md) describing:

• live contract: $API_HOST/openapi.json
• offline export: docs/openapi.yaml regenerated via python scripts/export_openapi.py
• rule: do not hand-author divergent path names

Include a docs-smoke phrase check so the pointer cannot silently disappear.

Expected value

Prevents divergent client specs and speeds SDK/agent onboarding from a cold checkout.

Reference tier

25-100 MRWK: small docs, typo, reproduction, triage

Acceptance or test notes

• Docs mention both live /openapi.json and checked-in docs/openapi.yaml export command
• docs_smoke asserts the new phrases
• No runtime API behavior change

Duplicate search

#944/#1175 implement the export; this proposal is documentation discoverability only. Open proposed-work search found no identical docs-pointer issue.

Out of scope

Changing OpenAPI schemas, adding new routes, or replacing the live /openapi.json source of truth.