docs: explain contexts and cluster coordination in known differences

Expand the terse "Contexts are single-tenant" bullet in the README with
a full explanation of what Confluent contexts are (multi-tenancy
namespaces for Schema Linking) and why we return only the default
context. Also clarify the cluster coordination difference. Update the
OpenAPI spec /contexts endpoint description and regenerate API docs.

Author: millerjp

README.md

@@ -206,8 +206,8 @@ AxonOps Schema Registry implements the Confluent Schema Registry REST API v1:
 
 **Known differences:**
 
-- Contexts are single-tenant only and always return `["."]`
-- Cluster coordination uses database constraints instead of Kafka
+- **Contexts** -- In Confluent Schema Registry, contexts are a multi-tenancy feature that allows multiple schemas with the same subject names and IDs to coexist in separate namespaces (e.g. `".team-a"`, `".team-b"`). Subjects are qualified with a context prefix (e.g. `:.mycontext:my-subject`), and schema IDs are unique within each context. This is primarily used for Schema Linking and enterprise multi-tenant deployments. AxonOps Schema Registry operates as a single-tenant registry -- the `GET /contexts` endpoint always returns `["."]` (the default context only), and context-qualified subject names are not supported.
+- **Cluster coordination** -- Confluent uses Kafka's group protocol for leader election between registry instances. AxonOps instances are fully stateless with no leader election -- database-level constraints (transactions, LWTs) handle coordination instead.
 
 ---
 

api/openapi.yaml

@@ -1634,9 +1634,20 @@ paths:
     get:
       summary: Get schema registry contexts
       description: >-
-        Returns the list of contexts defined in the registry. Contexts are namespace
-        prefixes extracted from subject names. The default context is `.` (a single dot).
-        This endpoint always includes the default context in the response.
+        Returns the list of contexts defined in the registry.
+
+
+        In Confluent Schema Registry, **contexts** are a multi-tenancy feature that
+        allows multiple schemas with the same subject names and IDs to coexist in
+        separate namespaces (e.g. `.team-a`, `.team-b`). Subjects are qualified with
+        a context prefix (e.g. `:.mycontext:my-subject`), and schema IDs are unique
+        within each context. This is primarily used for Schema Linking and enterprise
+        multi-tenant deployments.
+
+
+        AxonOps Schema Registry operates as a single-tenant registry. This endpoint
+        always returns `["."]` (the default context only). Context-qualified subject
+        names are not supported.
       operationId: getContexts
       tags:
         - Metadata

docs/api-reference.md

@@ -3740,7 +3740,11 @@ curl -X GET http://localhost:8081/contexts \
 
 `GET /contexts`
 
-Returns the list of contexts defined in the registry. Contexts are namespace prefixes extracted from subject names. The default context is `.` (a single dot). This endpoint always includes the default context in the response.
+Returns the list of contexts defined in the registry.
+
+In Confluent Schema Registry, **contexts** are a multi-tenancy feature that allows multiple schemas with the same subject names and IDs to coexist in separate namespaces (e.g. `.team-a`, `.team-b`). Subjects are qualified with a context prefix (e.g. `:.mycontext:my-subject`), and schema IDs are unique within each context. This is primarily used for Schema Linking and enterprise multi-tenant deployments.
+
+AxonOps Schema Registry operates as a single-tenant registry. This endpoint always returns `["."]` (the default context only). Context-qualified subject names are not supported.
 
 > Example responses