Add a generated gRPC API reference

[jhrozek]

Summary

Add a deterministic, generated gRPC schema reference for Mecatl's ordinary public API while keeping the existing handwritten guide focused on behavior and operational semantics.

This issue was narrowed after the recent TypeScript SDK and documentation work. The HTTP/OpenAPI portion is now tracked separately in #1706.

Scope

• Generate a Docusaurus-compatible Markdown reference from:
  • contracts/proto/mecatl/v1/harness.proto (HarnessService)
  • contracts/proto/mecatl/v1/schedule.proto (ScheduleService)
• Use a pinned Buf-compatible documentation plugin rather than a custom protobuf parser.
• Write the committed generated page to user-docs/reference/grpc-schema.md.
• Cover both services, every RPC, the messages and enums used by them, field comments, and unary/server-streaming/bidirectional-streaming directions.
• Add a dedicated regeneration command, task docs:grpc-ref, and include it in task docs.
• Add a non-mutating CI freshness check that fails when the committed page differs from regenerated output.
• Link the generated schema reference from user-docs/reference/grpc-api.md and user-docs/building/deployment/grpc-http.md.
• Clearly mark the page as generated and identify the proto files as its source.

Acceptance criteria

• task docs:grpc-ref deterministically regenerates user-docs/reference/grpc-schema.md from the two protobuf contracts.
• The generated page includes HarnessService, ScheduleService, every RPC, their streaming directions, and the messages/enums they use.
• The existing handwritten gRPC guide remains the canonical home for authentication, error behavior, lifecycle guidance, and other semantics not encoded in protobuf descriptors.
• The handwritten gRPC and transport pages link to the generated schema reference.
• CI fails with a clear message when the generated page is stale.
• task docs and task site:build pass.

Non-goals

• HTTP, OpenAPI, or SSE documentation; see Generate an OpenAPI-backed HTTP API reference #1706.
• Replacing or substantially rewriting the existing handwritten gRPC guide.
• Changing protobuf or runtime behavior.
• Generating client bindings.
• Documenting the privileged LocalSessionContextService or the driver protocol under contracts/proto/mecatl/driver/v1.
• Generating authentication rules or exhaustive status-code behavior that is not represented in the protobuf descriptors.

[Sanskarzz]

Hi @jhrozek
I want to work on this issue. Please assign this to me

[jhrozek]

Hi @jhrozek I want to work on this issue. Please assign this to me

Done. Checking in with @samuv and @kantord - is the issue as written still valid after the month given your SDK work?

[samuv]

Hi @jhrozek I want to work on this issue. Please assign this to me

Done. Checking in with @samuv and @kantord - is the issue as written still valid after the month given your SDK work?

Thanks for checking! The underlying need is still there, but the recent SDK and docs work has changed the scope a bit.

Since @Sanskarzz has already volunteered, perhaps we can narrow this issue to the gRPC reference for HarnessService and ScheduleService, including the documentation link and drift check. We can track the more involved HTTP/OpenAPI work separately. That should keep this a clear and useful contribution.

[samuv]

Thanks again for volunteering, @Sanskarzz! Following the discussion above, I've narrowed this issue to the generated gRPC reference and updated the acceptance criteria so the task has clear boundaries. The HTTP/OpenAPI work is now tracked separately in #1706.

Please let us know if anything in the updated scope is unclear before you get started.

[Sanskarzz]

Thanks, @samuv and @jhrozek, for assigning this and narrowing the scope. The updated scope is clear to me.

My understanding is that #712 is limited to generating a deterministic, Docusaurus-compatible gRPC schema reference from harness.proto and schedule.proto, using a pinned Buf-compatible documentation plugin. I’ll add task docs:grpc-ref, include it in task docs, add a non-mutating CI freshness check, and link the generated reference from the existing gRPC and transport guides. I’ll keep HTTP/OpenAPI/SSE work and any protobuf or runtime changes out of this PR, that work remains in #1706

Mecatl is new to me, so I’m currently familiarizing myself with the repository structure and its documentation and code-generation workflows. I’ll follow the existing Buf, Taskfile, generated-document, and CI patterns while implementing this.

Unless you have a preferred documentation plugin or template, I’ll select a well-supported Buf-compatible plugin, pin its version, and document the choice in the PR. I’ll confirm here first if I encounter any scope ambiguity.