From 2d3cdf45c726581a7887a5e4b4b43d996e3a361e Mon Sep 17 00:00:00 2001
From: Kevin Rajan <7121943+kvnloo@users.noreply.github.com>
Date: Sun, 11 Oct 2026 02:55:25 -0500
Subject: [PATCH 1/2] docs(extensibility): name extension family base
 capabilities

Adapt dot's verified documentation slice for NVIDIA/OpenShell#4378. Credit SoniaMehta14 for the report and Seth Jennings for negotiation design. AI-assisted preparation; no DCO attestation on behalf of Kevin.
---
 docs/extensibility/overview.mdx | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/docs/extensibility/overview.mdx b/docs/extensibility/overview.mdx
index 149df13d96..d1e97767c8 100644
--- a/docs/extensibility/overview.mdx
+++ b/docs/extensibility/overview.mdx
@@ -97,6 +97,22 @@ or supervisor middleware service, both peers exchange
 implementation versions, supported capabilities, and capabilities required
 from the other peer. Family-specific features remain in their typed protocols.
 
+Use protocol version `1.0` and advertise the base capability for your
+extension family in `supported_capabilities`:
+
+| Extension family | Base capability |
+| --- | --- |
+| Compute driver | `openshell.compute.contract` |
+| Credential driver | `openshell.credentials.contract` |
+| Gateway interceptor | `openshell.gateway-interceptor.contract` |
+| Supervisor middleware | `openshell.supervisor-middleware.contract` |
+
+For example, a supervisor middleware's `MiddlewareManifest.extension` can use
+`protocol_version` with `major: 1` and `minor: 0`, and include
+`openshell.supervisor-middleware.contract` in both `supported_capabilities` and
+`required_capabilities`. The gateway also advertises that capability. Set
+`implementation_name` and `implementation_version` to identify your service.
+
 OpenShell accepts compatible minor versions when both capability requirements
 are satisfied. It rejects different major versions, missing metadata, or an
 unmet required capability during startup. Built-in and external service

From 5e0ca4c82904c094db42243a0b44d10ec5331881 Mon Sep 17 00:00:00 2001
From: Kevin Rajan <7121943+kvnloo@users.noreply.github.com>
Date: Sun, 11 Oct 2026 02:55:27 -0500
Subject: [PATCH 2/2] docs(proto): explain middleware base capability
 negotiation

Clarify the existing 1.0 middleware metadata contract without changing any field or token; from dot's scoped docs proposal.
---
 proto/supervisor_middleware.proto | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/proto/supervisor_middleware.proto b/proto/supervisor_middleware.proto
index 52793d905f..20b8357b68 100644
--- a/proto/supervisor_middleware.proto
+++ b/proto/supervisor_middleware.proto
@@ -67,6 +67,10 @@ message MiddlewareManifest {
   // this post-authentication consistency check.
   string expected_audience = 4;
   // Supervisor-middleware protocol metadata. Required for negotiation.
+  // Set protocol_version to 1.0 and advertise
+  // "openshell.supervisor-middleware.contract" in supported_capabilities.
+  // The gateway advertises the same capability; include it in
+  // required_capabilities when the middleware requires that contract.
   openshell.extension.v1.PeerMetadata extension = 5;
 }