docs: generate gRPC schema reference

.github/workflows/ci.yml

@@ -1408,6 +1408,11 @@ jobs:
       - name: Acceptance-proof traceability gate
         run: task ac-trace-strict
 
+      - uses: bufbuild/buf-setup-action@a47c93e0b1648d5651a065437926377d060baa99 # v1.50.0
+        with:
+          version: '1.72.0'
+          github_token: ${{ github.token }}
+
       # Documentation-only changes still run the repository's Go-backed structural
       # checks (ADR numbering/shape, citations, lifecycle, and reading-map checks).
       - name: go test ./docs/lint
@@ -1440,6 +1445,23 @@ jobs:
             exit 1
           fi
 
+      # Regenerate into RUNNER_TEMP so the freshness check never modifies the
+      # checkout. The checked-in page is the exact output developers get from
+      # `task docs:grpc-ref`.
+      - name: gRPC schema reference is up to date
+        shell: bash
+        run: |
+          set -euo pipefail
+          buf generate --template buf.gen.grpc-docs.yaml \
+            --output "$RUNNER_TEMP/grpc-reference" \
+            --path contracts/proto/mecatl/v1/harness.proto \
+            --path contracts/proto/mecatl/v1/schedule.proto
+          generated="$RUNNER_TEMP/grpc-reference/user-docs/reference/grpc-schema.md"
+          if ! diff -u user-docs/reference/grpc-schema.md "$generated"; then
+            echo "::error file=user-docs/reference/grpc-schema.md::gRPC schema reference is out of date — run 'task docs:grpc-ref' and commit the result."
+            exit 1
+          fi
+
       # matlatl's composite action builds the gate from ITS OWN checkout, so
       # there is no binary step and no extra credentials here — only org Actions
       # access to stacklok/matlatl (granted org-wide). strict also fails on

Taskfile.yml

@@ -7,7 +7,7 @@
 #                               official release binary into .tools/bin)
 #   - goimports     (only for `task fmt`)
 #                               go install golang.org/x/tools/cmd/goimports@latest
-#   - buf           (only for `task generate`)
+#   - buf           (for `task generate` and `task docs:grpc-ref`)
 #                               https://buf.build/docs/installation
 #   - helm unittest (only for `task deploy:helm-unittest`)
 #                               task deploy:helm-unittest installs the pinned
@@ -976,6 +976,16 @@ tasks:
       # fails on drift. Never hand-edit either output.
       - go run ./internal/configgen/cmd/configref --skeleton internal/configgen/settings.skeleton.yaml --reference user-docs/reference/configuration.md
 
+  docs:grpc-ref:
+    desc: Regenerate the committed gRPC schema reference from the public Harness and Schedule protobuf contracts
+    cmds:
+      - cmd: |
+          command -v buf >/dev/null 2>&1 || { echo "buf not found; install: https://buf.build/docs/installation"; exit 1; }
+          buf generate --template buf.gen.grpc-docs.yaml \
+            --path contracts/proto/mecatl/v1/harness.proto \
+            --path contracts/proto/mecatl/v1/schedule.proto
+        silent: true
+
   docs:check:
     desc: Gate acceptance-plan checker fixtures, Go-backed document structure, executable operations examples, and doc link health with matlatl (strict — broken links/anchors, orphans, unreachable)
     cmds:
@@ -998,6 +1008,7 @@ tasks:
     desc: Refresh generated references and gate doc links (matlatl) — run before committing doc changes
     cmds:
       - task: docs:configref
+      - task: docs:grpc-ref
       - task: sdk:docs
       - task: docs:check
 

buf.gen.grpc-docs.yaml

@@ -0,0 +1,12 @@
+version: v2
+plugins:
+  # Keep the generator version explicit and run it through Buf's protoc-plugin
+  # protocol. A local invocation lets the plugin read the repository-owned
+  # Docusaurus template without introducing a custom protobuf parser.
+  - local:
+      - go
+      - run
+      - github.com/pseudomuto/protoc-gen-doc/cmd/protoc-gen-doc@v1.5.1
+    out: user-docs/reference
+    opt:
+      - scripts/grpc-schema.md.tmpl,grpc-schema.md

scripts/grpc-schema.md.tmpl

@@ -0,0 +1,74 @@
+{{- define "safe" -}}
+{{- . | html | replace "{" "{" | replace "}" "}" -}}
+{{- end -}}
+{{- define "table-safe" -}}
+{{- . | nobr | replace "\r" " " | replace "\n" " " | html | replace "|" "|" | replace "{" "{" | replace "}" "}" -}}
+{{- end -}}
+---
+title: gRPC schema reference
+description: Look up Mecatl gRPC services, RPCs, messages, enums, and fields.
+sidebar_position: 3
+---
+
+# gRPC schema reference
+
+{{"{"}}/* GENERATED FILE. DO NOT EDIT. Run `task docs:grpc-ref` after changing the source protobuf files. */{{"}"}}
+
+This reference is generated from
+[`contracts/proto/mecatl/v1/harness.proto`](https://github.com/stacklok/mecatl/blob/main/contracts/proto/mecatl/v1/harness.proto)
+and
+[`contracts/proto/mecatl/v1/schedule.proto`](https://github.com/stacklok/mecatl/blob/main/contracts/proto/mecatl/v1/schedule.proto).
+For behavior, authentication, status codes, and operational guidance, see the
+[gRPC API reference](/reference/grpc-api.md). For help choosing between gRPC and
+HTTP/SSE, see [Connect with gRPC or HTTP](/building/deployment/grpc-http.md).
+
+## Services
+
+{{range .Files -}}
+{{range .Services}}
+### `{{.FullName}}`
+
+{{template "safe" .Description}}
+
+| RPC | Request | Response | Client streaming | Server streaming | Description |
+|---|---|---|---|---|---|
+{{range .Methods -}}
+| `{{.Name}}` | `{{.RequestLongType}}` | `{{.ResponseLongType}}` | {{if .RequestStreaming}}Yes{{else}}No{{end}} | {{if .ResponseStreaming}}Yes{{else}}No{{end}} | {{template "table-safe" .Description}} |
+{{end}}
+{{end -}}
+{{end}}
+## Messages and enums
+
+{{range .Files}}
+### `{{.Name}}`
+
+{{template "safe" .Description}}
+
+{{range .Messages}}
+#### `{{.FullName}}`
+
+{{template "safe" .Description}}
+
+{{if .HasFields -}}
+| Field | Type | Label | Oneof | Description |
+|---|---|---|---|---|
+{{range .Fields -}}
+| `{{.Name}}` | `{{.LongType}}` | {{.Label}} | {{if and .IsOneof (ne .Label "optional")}}`{{.OneofDecl}}`{{end}} | {{if (index .Options "deprecated" | default false)}}**Deprecated.** {{end}}{{template "table-safe" .Description}}{{if .DefaultValue}} Default: `{{.DefaultValue}}`.{{end}} |
+{{end}}
+{{else -}}
+This message has no fields.
+{{end}}
+
+{{end -}}
+{{range .Enums}}
+#### `{{.FullName}}`
+
+{{template "safe" .Description}}
+
+| Name | Number | Description |
+|---|---|---|
+{{range .Values -}}
+| `{{.Name}}` | `{{.Number}}` | {{template "table-safe" .Description}} |
+{{end -}}
+{{end -}}
+{{end -}}

user-docs/.prettierignore

@@ -1,5 +1,6 @@
 # Ignore autogenerated files
 reference/configuration.md
+reference/grpc-schema.md
 reference/typescript-sdk-api/core.md
 reference/typescript-sdk-api/node.md
 reference/typescript-sdk-api/deno.md

user-docs/_README.md

@@ -63,7 +63,8 @@ feature guide.
 |Skills, commands, soul, and user model|`features/skills-commands-and-soul.md` and `building/what-you-get/memory.md`|Extension-point pages document the importable interfaces.|
 |Hooks|`building/what-you-get/hooks.md`|`building/extension-points/hook-runner.md` owns host-integration details.|
 |Configuration schema|`reference/configuration.md`|`building/deployment/settings.md` explains which configuration plane to use.|
-|gRPC API|`reference/grpc-api.md`|`building/deployment/grpc-http.md` explains client integration and transport choice.|
+|gRPC API behavior|`reference/grpc-api.md`|`building/deployment/grpc-http.md` explains client integration and transport choice.|
+|gRPC schema|`reference/grpc-schema.md`|The generated page owns exact services, RPC signatures, messages, enums, fields, and proto comments; `reference/grpc-api.md` owns behavior and semantics.|
 |HTTP and SSE API|`reference/http-sse-api.md`|`building/deployment/grpc-http.md` explains client integration and transport choice.|
 |TypeScript SDK workflows|`building/getting-started/typescript-sdk.md` and `building/typescript-sdk/`|Deployment and feature pages link to the SDK guide that owns the application workflow.|
 |TypeScript SDK method reference|`reference/typescript-sdk-api/`|SDK guides link to the generated entry-point reference instead of copying signatures or option inventories.|
@@ -151,6 +152,8 @@ Generated reference pages are exceptions to direct editing:
 
 - For `reference/configuration.md`, change the configuration schema or
   generator, then run `task docs:configref`.
+- For `reference/grpc-schema.md`, change the public protobuf contracts or the
+  generator template, then run `task docs:grpc-ref`.
 - For `reference/typescript-sdk-api/core.md`, `node.md`, and `deno.md`, change the
   TSDoc in `sdk/typescript/src/` or the SDK documentation generator, then run
   `task sdk:docs`. Use `task sdk:docs:check` to verify that the committed output

user-docs/building/deployment/grpc-http.md

@@ -94,6 +94,8 @@ import mecatlv1 "github.com/stacklok/mecatl/contracts/gen/go/mecatl/v1"
 
 For RPC-by-RPC behavior, request fields, response semantics, and stream control
 frames, see the [gRPC API reference](/reference/grpc-api.md).
+For generated service signatures, streaming directions, message fields, and
+enum values, see the [gRPC schema reference](/reference/grpc-schema.md).
 
 One `Converse` stream drives one run. Start it with exactly one `Prompt` or
 `RetryStart`, then send only control frames while the run remains live. The

user-docs/reference/grpc-api.md

@@ -10,6 +10,10 @@ This is the detailed operator and wire reference. For the client-integration
 entry point, event lifecycle, and HTTP/SSE comparison, start with
 [Drive via gRPC / HTTP](/building/deployment/grpc-http.md).
 
+For generated RPC signatures, streaming directions, messages, enums, fields,
+and protobuf comments, see the
+[gRPC schema reference](/reference/grpc-schema.md).
+
 Service: `mecatl.v1.HarnessService` (`contracts/proto/mecatl/v1/harness.proto`).
 
 ## Server identity