feat(docs): publish the gRPC API as a supported public integration contract #1613

Problem Statement

OpenShell exposes a full gRPC service (`openshell.v1.OpenShell` in `proto/openshell.proto`) covering sandbox lifecycle, policy lifecycle (including the agent-driven proposal loop landing in #1097 / #1528), provider management, and inference routing. The CLI and TUI are both clients of this contract.

Field signal from partner / customer teams shows the gRPC surface is being perceived as "no API" because:

• There is no `docs/reference/api.mdx` or equivalent published reference. The proto file is the contract source but is not packaged or discoverable for integrators.
• There is no published OpenAPI / Connect / grpc-gateway export, so HTTP-only consumers cannot integrate without writing their own bridge.
• There is no documented stability / versioning policy on the service, so partners do not know whether they can safely build on it.
• There is no documented RBAC mapping for the RPCs (`config:read`, `sandbox:read`, admin role) outside of source.

Concrete impact: partners attempting to build web approval UIs on top of the agent-driven policy loop are currently considering wrapping CLI commands instead of using gRPC directly, because the gRPC contract is not packaged as a supported partner surface.

Proposed Design

Publish the existing gRPC service as a supported public integration contract. Three deliverables:

1. docs/reference/api.mdx — canonical reference page covering: the gRPC service, auth (mTLS + JWT/OIDC), RBAC role mapping per RPC, error model, and the stability policy (additive-first, deprecation window, no breaking changes within a minor version).
2. Generated reference for each RPC — message shapes, RBAC requirements, and short examples. Generate from `proto/openshell.proto` rather than handwriting to keep it in sync. Cover at minimum: sandbox CRUD, policy lifecycle (`GetDraftPolicy`, `ApproveDraftChunk`, `RejectDraftChunk`, `ApproveAllDraftChunks`, `EditDraftChunk`, `UndoDraftChunk`, `ClearDraftChunks`, `GetDraftHistory`, `SubmitPolicyAnalysis`), provider RPCs, inference routing.
3. Decide and document the HTTP path. Pick one of: (a) Connect / grpc-gateway export at a documented endpoint, (b) "use the SDKs from Python and TypeScript SDK Support #1044," or (c) defer with an explicit "gRPC-only for now" stance. The choice is the spike — this issue tracks documenting whatever we choose so the partner story stops being implicit.

Out of scope: shipping the SDKs themselves (#1044), writing partner integration tutorials beyond a single end-to-end example, or building a web/HTTP shim before the spike concludes.

Alternatives Considered

• Leave the proto as the contract. Status quo; produces the "no API" misperception we are already seeing in the field.
• Skip the reference and ship SDKs only via Python and TypeScript SDK Support #1044. SDKs are the right primary path, but SDK consumers still need a stable contract document to reason about RBAC, versioning, and what is supported vs. internal. Without a reference doc the SDKs ship without a spec.
• Auto-publish proto via Buf Schema Registry only. Useful for engineers but not sufficient as a partner-facing contract — does not cover auth, RBAC, stability policy, or HTTP access pattern.

Agent Investigation

• `proto/openshell.proto` is the contract source today. RBAC enforcement lives in `crates/openshell-server/src/auth/authz.rs`.
• Existing user docs (`docs/`) cover CLI and TUI workflows, not the gRPC surface as an integration contract.
• The CLI and TUI both consume the same service definitions, demonstrating the contract is already stable enough for first-party clients — making it a small lift to publish it as a supported partner surface.

Related

• SDK consumers of this contract: Python and TypeScript SDK Support #1044
• The proposal-loop RPCs are the highest-near-term-value consumer: OpenShell Agent-Driven Policy Management #1062, feat(gateway): persist and validate agent policy proposal operations #1097, feat(policy): add agentic approval loop #1528