Add a generated gRPC API reference
Open
@Sanskarzz is already working on this.
Since Sep 17, 2026.
documentation
good first issue
- Dominant language
- Go
- Stars
- 152
- Forks
- 16
- Avg merge
- 14h 48m
- Merged PRs (30d)
- 536
Description
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 intask 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.mdanduser-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-refdeterministically regeneratesuser-docs/reference/grpc-schema.mdfrom 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 docsandtask site:buildpass.
Non-goals
- HTTP, OpenAPI, or SSE documentation; see #1706.
- Replacing or substantially rewriting the existing handwritten gRPC guide.
- Changing protobuf or runtime behavior.
- Generating client bindings.
- Documenting the privileged
LocalSessionContextServiceor the driver protocol undercontracts/proto/mecatl/driver/v1. - Generating authentication rules or exhaustive status-code behavior that is not represented in the protobuf descriptors.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Assessment
This issue has not been assessed yet.