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
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;
 }