Generate an OpenAPI-backed HTTP API reference

Summary

Generate an OpenAPI-compatible reference for Mecatl's public HTTP JSON API while keeping the existing HTTP/SSE guide focused on behavior, streaming, and lifecycle semantics.

This work was split from #712 after the TypeScript SDK introduced a complete RPC catalog and mechanical parity checks against the server router and protobuf descriptors.

Current state

• internal/adapter/server/http.go is the HTTP wire source of truth, as recorded in ADR 0321.
• sdk/typescript/src/rpc-catalog.ts contains route and codec metadata used by the SDK.
• internal/adapter/server/sdk_typescript_http_routes_test.go checks the SDK catalog against the registered routes and protobuf descriptors.
• user-docs/reference/http-sse-api.md is the canonical curated HTTP/SSE guide.

The generated reference must build on these existing boundaries rather than introduce another independently maintained route table.

Scope

• Define and document how an OpenAPI-compatible artifact is generated from, or mechanically checked against, the server router and existing descriptor-backed route metadata.
• Cover every public HTTP JSON endpoint, including methods, route and query parameters, request and response schemas, authentication expectations, and status/problem responses.
• Render or link the generated endpoint reference from user-docs/reference/.
• Keep SSE framing, reconnect behavior, cursor handling, and stream lifecycle explanations in the curated HTTP/SSE guide, with links in both directions.
• Add deterministic regeneration and CI drift checks.
• Reconcile ownership with the SDK RPC catalog so adding a route does not require maintaining two unchecked contract descriptions.

Acceptance criteria

• The HTTP router remains the authoritative wire surface; no independent route table becomes a competing source of truth.
• A documented command produces a deterministic OpenAPI-compatible artifact and rendered endpoint reference.
• Every registered public JSON route is represented with its method, parameters, request and response schemas, authentication expectations, and status/problem responses.
• HTTP/SSE routes link to the curated streaming and lifecycle documentation.
• The generated reference is linked from the canonical transport and reference pages.
• CI fails when generated artifacts or checked route metadata drift from the implementation.
• task docs and task site:build pass.

Non-goals

• Generating the gRPC reference; that remains in #712.
• Replacing curated SSE lifecycle documentation with generated output.
• Changing HTTP or gRPC behavior.
• Adding a new API version.

Start by reading internal/adapter/server/http.go and ADR 0321, then compare the route metadata in sdk/typescript/src/rpc-catalog.ts with internal/adapter/server/sdk_typescript_http_routes_test.go. Use user-docs/reference/http-sse-api.md, task docs, and task site:build to trace the documentation boundaries; done means deterministic generation, complete route coverage, linked references, and CI drift checks.