Add custom registry tutorial and JSON schema reference

.github/workflows/update-toolhive-reference.yml

@@ -70,7 +70,7 @@ jobs:
           title: |
             Update ToolHive reference docs for ${{ steps.imports.outputs.version }}
           body: |
-            This PR updates the ToolHive CLI and API reference documentation to the latest release: ${{ steps.imports.outputs.version }}.
+            This PR updates the ToolHive CLI and API reference documentation for release: ${{ steps.imports.outputs.version }}.
           commit-message: |
             Update ToolHive reference docs for ${{ steps.imports.outputs.version }}
           labels: |

docs/toolhive/guides-cli/registry.md

@@ -132,6 +132,15 @@ By default, ToolHive uses a built-in registry of verified MCP servers. You can
 configure ToolHive to use a custom registry instead. This is useful for
 organizations that want to maintain their own private registry of MCP servers.
 
+The registry is a JSON file that follows the
+[ToolHive registry schema](../reference/registry-schema.mdx). Once you configure
+a custom registry, ToolHive uses it for all commands that interact with the
+registry, such as `thv registry list`, `thv registry info`, and `thv run`.
+
+Refer to the
+[built-in registry file](https://github.com/stacklok/toolhive/blob/main/pkg/registry/data/registry.json)
+for examples of MCP server entries.
+
 ### Set a remote registry URL
 
 To configure ToolHive to use a remote registry, set the registry URL:
@@ -154,14 +163,6 @@ To configure ToolHive to use a local registry, set the registry file:
 thv config set-registry <PATH>
 ```
 
-The registry must be a JSON file that follows the same format as the
-[built-in registry](https://github.com/stacklok/toolhive/blob/main/pkg/registry/data/registry.json).
-Once you configure a remote registry, all registry commands
-([`thv registry list`](../reference/cli/thv_registry_list.md),
-[`thv registry info`](../reference/cli/thv_registry_info.md),
-[`thv search`](../reference/cli/thv_search.md)) will use the remote registry
-instead of the built-in one.
-
 ### Check the current registry location
 
 To see which registry (URL or path) is currently configured:
@@ -189,6 +190,8 @@ This restores the default behavior of using ToolHive's built-in registry.
 See [Run MCP servers](./run-mcp-servers.mdx) to run an MCP server from the
 registry.
 
+Learn how to [create a custom MCP registry](../tutorials/custom-registry.mdx).
+
 ## Related information
 
 - [`thv registry` command reference](../reference/cli/thv_registry.md)

docs/toolhive/reference/crd-spec.mdx

@@ -6,6 +6,6 @@ description:
 toc_max_heading_level: 4
 ---
 
-import CRDRef from '@site/static/api-specs/crd-api.md';
+import CRDRef from '@site/static/api-specs/toolhive-crd-api.md';
 
 <CRDRef />

docs/toolhive/reference/registry-schema.mdx

@@ -0,0 +1,24 @@
+---
+title: ToolHive registry JSON schema
+description: The JSON schema for the ToolHive registry.
+displayed_sidebar: toolhiveSidebar
+---
+
+import JSONSchemaViewer from '@theme/JSONSchemaViewer';
+import Schema from '@site/static/api-specs/toolhive-registry-schema.json';
+
+This is the JSON schema for the ToolHive registry. It defines the structure and
+constraints for the registry entries, ensuring that all entries conform to a
+consistent format.
+
+To use this schema in your own custom registry file, add a `$schema` property at
+the top of your JSON file:
+
+```json
+{
+  "$schema": "https://raw.githubusercontent.com/stacklok/toolhive/main/pkg/registry/data/schema.json",
+  ...
+}
+```
+
+<JSONSchemaViewer schema={Schema} />