Add next steps and cross-links across all doc sections

danbarr · claude · danbarr · commit bbc28a329bae · 2026-03-27T10:52:19.000-04:00
Co-Authored-By: Claude Opus 4.6 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/.husky/pre-commit b/.husky/pre-commit
diff --git a/docs/toolhive/concepts/vmcp.mdx b/docs/toolhive/concepts/vmcp.mdx
@@ -161,9 +161,15 @@ MCPRemoteProxy backends into a single endpoint. The use cases range from simple
 aggregation to complex workflows with approval gates, making it valuable for
 teams managing multiple MCP servers.
 
+## Next steps
+
+- [Try the Quickstart](../guides-vmcp/quickstart.mdx) to deploy your first vMCP
+  on a Kubernetes cluster
+- [Learn how to deploy vMCP](../guides-vmcp/intro.mdx) for a full overview of
+  configuration and architecture
+
 ## Related information
 
-- [Deploy vMCP](../guides-vmcp/intro.mdx)
 - [Configure authentication](../guides-vmcp/authentication.mdx)
 - [Tool aggregation and conflict resolution](../guides-vmcp/tool-aggregation.mdx)
 - [Composite tools and workflows](../guides-vmcp/composite-tools.mdx)
diff --git a/docs/toolhive/guides-cli/api-server.mdx b/docs/toolhive/guides-cli/api-server.mdx
@@ -83,6 +83,12 @@ Open a browser to `http://localhost:8080/api/doc` to view the API documentation.
 The OpenAPI specification is also available at
 `http://localhost:8080/api/openapi.json`.
 
+## Next steps
+
+- [Secure your servers](./auth.mdx) with authentication and authorization
+- [Monitor server activity](./telemetry-and-metrics.mdx) with OpenTelemetry and
+  Prometheus
+
 ## Related information
 
 - [ToolHive API documentation](../reference/api.mdx)
diff --git a/docs/toolhive/guides-cli/auth.mdx b/docs/toolhive/guides-cli/auth.mdx
@@ -143,13 +143,21 @@ to perform an action, ToolHive will evaluate the request against the policies.
 If the request is permitted, the action will proceed; otherwise, it will be
 denied with a 403 Forbidden response.
 
+## Next steps
+
+- [Configure token exchange](./token-exchange.mdx) to let MCP servers
+  authenticate to backend services
+- [Run MCP servers](./run-mcp-servers.mdx) with your auth configuration
+- [Learn about the auth framework](../concepts/auth-framework.mdx) for a deeper
+  understanding of ToolHive's authentication and authorization model
+
 ## Related information
 
-- For conceptual understanding, see
-  [Authentication and authorization framework](../concepts/auth-framework.mdx)
-- For detailed Cedar policy syntax, see
-  [Cedar policies](../concepts/cedar-policies.mdx) and the
-  [Cedar documentation](https://docs.cedarpolicy.com/)
+- [Authentication and authorization framework](../concepts/auth-framework.mdx)
+  for conceptual understanding
+- [Cedar policies](../concepts/cedar-policies.mdx) and the
+  [Cedar documentation](https://docs.cedarpolicy.com/) for detailed policy
+  syntax
 
 ## Troubleshooting
 
diff --git a/docs/toolhive/guides-cli/custom-permissions.mdx b/docs/toolhive/guides-cli/custom-permissions.mdx
@@ -229,6 +229,11 @@ When creating and using permission profiles:
 - Keep permission profiles in version control to track changes and share them
   with your team
 
+## Next steps
+
+- [Set up authentication](./auth.mdx) for user-level access control with OIDC
+  and Cedar policies
+
 ## Related information
 
 - [`thv run` command reference](../reference/cli/thv_run.md)
diff --git a/docs/toolhive/guides-cli/manage-mcp-servers.mdx b/docs/toolhive/guides-cli/manage-mcp-servers.mdx
@@ -151,11 +151,19 @@ thv start <REMOTE_SERVER_NAME>
 
 This will always prompt for re-authentication, even if valid tokens exist.
 
+## Next steps
+
+- [Organize servers into groups](./group-management.mdx) to manage related
+  servers together
+- [Monitor server activity](./telemetry-and-metrics.mdx) with OpenTelemetry and
+  Prometheus
+- [Configure your AI client](./client-configuration.mdx) to connect to your
+  servers
+
 ## Related information
 
 - [`thv list` command reference](../reference/cli/thv_list.md)
 - [`thv logs` command reference](../reference/cli/thv_logs.md)
 - [`thv stop` command reference](../reference/cli/thv_stop.md)
 - [`thv start` command reference](../reference/cli/thv_start.md)
 - [`thv rm` command reference](../reference/cli/thv_rm.md)
-- [Monitor with OpenTelemetry](../guides-cli/telemetry-and-metrics.mdx)
diff --git a/docs/toolhive/guides-cli/run-mcp-servers.mdx b/docs/toolhive/guides-cli/run-mcp-servers.mdx
@@ -888,11 +888,14 @@ The configuration file must contain all server settings.
 
 ## Next steps
 
-See [Monitor and manage MCP servers](./manage-mcp-servers.mdx) to monitor and
-control your servers.
-
-[Test your MCP server](./test-mcp-servers.mdx) using the MCP Inspector or
-`thv mcp` commands.
+- [Monitor and manage MCP servers](./manage-mcp-servers.mdx) to control your
+  running servers
+- [Test your MCP servers](./test-mcp-servers.mdx) using the MCP Inspector or
+  `thv mcp` commands
+- [Secure your servers](./auth.mdx) with OIDC authentication and Cedar policies
+- [Enable telemetry and metrics](./telemetry-and-metrics.mdx) to gain
+  observability into MCP server interactions
+- [Run the API server](./api-server.mdx) for programmatic access to ToolHive
 
 ## Related information
 
diff --git a/docs/toolhive/guides-cli/telemetry-and-metrics.mdx b/docs/toolhive/guides-cli/telemetry-and-metrics.mdx
@@ -406,6 +406,15 @@ Telemetry adds minimal overhead when properly configured:
 - Use appropriate sampling rates for your traffic volume
 - Monitor your observability backend costs and adjust sampling accordingly
 
+## Next steps
+
+- [Learn about ToolHive's observability model](../concepts/observability.mdx)
+  for a deeper understanding of the telemetry architecture
+- [Monitor and manage MCP servers](./manage-mcp-servers.mdx) for server
+  lifecycle management including logs and status monitoring
+- [Collect telemetry for MCP workloads](../integrations/opentelemetry.mdx) for a
+  hands-on tutorial with an OpenTelemetry Collector
+
 ## Related information
 
 - Tutorial:
diff --git a/docs/toolhive/guides-cli/test-mcp-servers.mdx b/docs/toolhive/guides-cli/test-mcp-servers.mdx
@@ -89,6 +89,14 @@ and see how your MCP server responds to various prompts.
 See [Test MCP servers in the ToolHive UI](../guides-ui/playground.mdx) to learn
 about the playground's features and how to get started.
 
+## Next steps
+
+- [Build MCP containers](./build-containers.mdx) to package your tested servers
+  for deployment
+- [Set up CI/CD patterns](./advanced-cicd.mdx) to automate testing in your
+  pipeline
+- [Secure your servers](./auth.mdx) with authentication and authorization
+
 ## Related information
 
 - [`thv inspector` command reference](../reference/cli/thv_inspector.md)
diff --git a/docs/toolhive/guides-cli/token-exchange.mdx b/docs/toolhive/guides-cli/token-exchange.mdx
@@ -200,11 +200,17 @@ Key points in this example:
   (`api:read`, `api:write`). The user's identity is preserved, but the
   permissions are transformed for the target service.
 
+## Next steps
+
+- [Monitor server activity](./telemetry-and-metrics.mdx) with OpenTelemetry and
+  Prometheus
+- [Test your MCP servers](./test-mcp-servers.mdx) to validate your configuration
+
 ## Related information
 
-- [Backend authentication](../concepts/backend-auth.mdx) - conceptual overview
+- [Backend authentication](../concepts/backend-auth.mdx) — conceptual overview
   of token exchange and federation
-- [Authentication and authorization](./auth.mdx) - basic auth setup for MCP
+- [Authentication and authorization](./auth.mdx) — basic auth setup for MCP
   servers
-- [CLI reference for `thv run`](../reference/cli/thv_run.md) - complete list of
+- [CLI reference for `thv run`](../reference/cli/thv_run.md) — complete list of
   flags
diff --git a/docs/toolhive/guides-k8s/auth-k8s.mdx b/docs/toolhive/guides-k8s/auth-k8s.mdx
@@ -760,6 +760,13 @@ kubectl logs -n toolhive-system -l app.kubernetes.io/name=weather-server-k8s
 2. Make requests that should be denied
 3. Check the proxy logs to see authorization decisions
 
+## Next steps
+
+- [Configure token exchange](./token-exchange-k8s.mdx) to let MCP servers
+  authenticate to backend services
+- [Set up audit logging](./logging.mdx) to track authentication decisions and
+  MCP server activity
+
 ## Related information
 
 - For conceptual understanding, see
diff --git a/docs/toolhive/guides-k8s/customize-tools.mdx b/docs/toolhive/guides-k8s/customize-tools.mdx
@@ -234,6 +234,12 @@ kubectl -n toolhive-system get mcpserver github -o yaml
 - If an MCPServer references a missing MCPToolConfig, the server enters Failed
   and the controller logs include the missing name and namespace.
 
+## Next steps
+
+- [Secure your servers](./auth-k8s.mdx) with authentication and authorization
+- [Monitor server activity](./telemetry-and-metrics.mdx) with OpenTelemetry and
+  Prometheus
+
 ## Related information
 
 - See the
diff --git a/docs/toolhive/guides-k8s/deploy-operator.mdx b/docs/toolhive/guides-k8s/deploy-operator.mdx
@@ -440,10 +440,9 @@ kubectl delete namespace toolhive-system
 
 ## Next steps
 
-See [Run MCP servers in Kubernetes](./run-mcp-k8s.mdx) to learn how to create
-and manage MCP servers using the ToolHive operator in your Kubernetes cluster.
-The operator supports deploying MCPServer resources based on the deployment mode
-configured during installation.
+- [Run MCP servers in Kubernetes](./run-mcp-k8s.mdx) to create and manage MCP
+  servers using the ToolHive operator
+- [Configure authentication](./auth-k8s.mdx) before exposing servers externally
 
 ## Related information
 
diff --git a/docs/toolhive/guides-k8s/run-mcp-k8s.mdx b/docs/toolhive/guides-k8s/run-mcp-k8s.mdx
@@ -441,22 +441,15 @@ kubectl -n <NAMESPACE> describe mcpserver <NAME>
 
 ## Next steps
 
-Learn how to [connect clients to your MCP servers](./connect-clients.mdx) from
-outside the cluster using Ingress or Gateway API, or from applications running
-within the cluster. See the
-[Client compatibility](../reference/client-compatibility.mdx) reference for
-information about supported MCP clients.
-
-Learn how to customize MCP tools using
-[filters and overrides](./customize-tools.mdx).
-
-Collect telemetry data from your MCP servers by following the
-[Telemetry and metrics](./telemetry-and-metrics.mdx) guide. Configure audit
-logging by following the [Set up logging](./logging.mdx) guide.
-
-Discover your deployed MCP servers automatically using the
-[Kubernetes registry](../guides-registry/configuration.mdx#kubernetes-registry)
-feature in the ToolHive Registry Server.
+- [Connect clients to your MCP servers](./connect-clients.mdx) from outside the
+  cluster using Ingress or Gateway API, or from within the cluster
+- [Secure your servers](./auth-k8s.mdx) with OIDC authentication and Cedar
+  policies
+- [Customize MCP tools](./customize-tools.mdx) with filters and overrides
+- [Aggregate multiple servers](../guides-vmcp/index.mdx) into a single endpoint
+  with Virtual MCP Server
+- [Curate a server catalog](../guides-registry/index.mdx) for your team with the
+  Registry Server
 
 ## Related information
 
diff --git a/docs/toolhive/guides-k8s/telemetry-and-metrics.mdx b/docs/toolhive/guides-k8s/telemetry-and-metrics.mdx
@@ -275,12 +275,18 @@ Telemetry adds minimal overhead when properly configured:
 - Use appropriate sampling rates for your traffic volume
 - Monitor your observability backend costs and adjust sampling accordingly
 
+## Next steps
+
+- [Set up audit logging](./logging.mdx) for structured request and authorization
+  event tracking
+- [Secure your servers](./auth-k8s.mdx) with authentication and authorization
+
 ## Related information
 
 - Tutorial:
-  [Collect telemetry for MCP workloads](../integrations/opentelemetry.mdx) -
-  Step-by-step guide to set up a local observability stack
-- [Telemetry and monitoring concepts](../concepts/observability.mdx) - Overview
+  [Collect telemetry for MCP workloads](../integrations/opentelemetry.mdx) —
+  step-by-step guide to set up a local observability stack
+- [Telemetry and monitoring concepts](../concepts/observability.mdx) — overview
   of ToolHive's observability architecture
 - [Kubernetes CRD reference](../reference/crd-spec.md#apiv1alpha1mcpserver) -
   Reference for the `MCPServer` Custom Resource Definition (CRD)
diff --git a/docs/toolhive/guides-k8s/token-exchange-k8s.mdx b/docs/toolhive/guides-k8s/token-exchange-k8s.mdx
@@ -251,9 +251,16 @@ Key points in this example:
   user's identity is preserved, but the permissions are transformed for the
   target service.
 
+## Next steps
+
+- [Monitor server activity](./telemetry-and-metrics.mdx) with OpenTelemetry and
+  Prometheus
+- [Set up audit logging](./logging.mdx) to track requests and authentication
+  decisions
+
 ## Related information
 
-- [Backend authentication](../concepts/backend-auth.mdx) - conceptual overview
+- [Backend authentication](../concepts/backend-auth.mdx) — conceptual overview
   of token exchange and federation
 - [Configure token exchange (CLI)](../guides-cli/token-exchange.mdx) - CLI-based
   setup
diff --git a/docs/toolhive/guides-registry/authentication.mdx b/docs/toolhive/guides-registry/authentication.mdx
@@ -547,6 +547,6 @@ If tokens from some providers work but others don't:
 
 ## Next steps
 
-- [Configure database storage](./database.mdx) for production deployments
-- [Deploy the server](./deployment.mdx) with authentication enabled
-- [Configure registry sources](./configuration.mdx) for your environment
+- [Set up the database](./database.mdx) for production storage and migrations
+- [Configure telemetry](./telemetry-metrics.mdx) for distributed tracing and
+  metrics collection
diff --git a/docs/toolhive/guides-registry/configuration.mdx b/docs/toolhive/guides-registry/configuration.mdx
@@ -522,7 +522,6 @@ distributed tracing and metrics collection. See the
 
 ## Next steps
 
-- [Configure authentication](./authentication.mdx) for secure access
-- [Configure telemetry](./telemetry-metrics.mdx) for metrics and tracing
-- [Deploy the server](./deployment.mdx) with your configuration
-- [Configure database storage](./database.mdx)
+- [Configure authentication](./authentication.mdx) to secure access to your
+  registry
+- [Set up the database](./database.mdx) for production storage
diff --git a/docs/toolhive/guides-registry/database.mdx b/docs/toolhive/guides-registry/database.mdx
@@ -306,5 +306,6 @@ If you see permission errors during normal operations:
 
 ## Next steps
 
-- [Deploy the server](./deployment.mdx) with database configuration
-- [Configure data sources](./configuration.mdx) to populate the registry
+- [Configure telemetry](./telemetry-metrics.mdx) for distributed tracing and
+  metrics collection
+- [Deploy the server](./deployment.mdx) to your Kubernetes environment
diff --git a/docs/toolhive/guides-registry/deployment.mdx b/docs/toolhive/guides-registry/deployment.mdx
@@ -32,3 +32,11 @@ Deploy the Registry Server directly using raw Kubernetes manifests. This
 approach gives you full control over the deployment configuration.
 
 See [Deploy manually](./deploy-manual.mdx) for instructions.
+
+## Next steps
+
+- [Configure registry sources](./configuration.mdx) if you haven't already set
+  up your data sources
+- [Set up authentication](./authentication.mdx) to secure access to your
+  registry
+- [Configure telemetry](./telemetry-metrics.mdx) to monitor your deployment
diff --git a/docs/toolhive/guides-registry/intro.mdx b/docs/toolhive/guides-registry/intro.mdx
@@ -114,8 +114,9 @@ The server supports five registry source types:
 
 ## Next steps
 
-- [Configure registry sources](./configuration.mdx) to set up your registry
-- [Deploy the server](./deployment.mdx) in your environment
-- [Manage skills](./skills.mdx) to publish and discover reusable skills
+- [Configure registry sources](./configuration.mdx) to set up your data sources,
+  sync policies, and server filtering
+- [Set up authentication](./authentication.mdx) to secure access to your
+  registry
 - [View the API reference](../reference/registry-api.mdx) for endpoint
   documentation
diff --git a/docs/toolhive/guides-registry/telemetry-metrics.mdx b/docs/toolhive/guides-registry/telemetry-metrics.mdx
@@ -180,6 +180,4 @@ metrics still capture latency and error rates for these endpoints.
 
 ## Next steps
 
-- [Configure the Registry Server](./configuration.mdx) with your registries
-- [Deploy the server](./deployment.mdx) to your environment
-- [Configure authentication](./authentication.mdx) for secure access
+- [Deploy the server](./deployment.mdx) to your Kubernetes environment
diff --git a/docs/toolhive/guides-ui/cli-access.mdx b/docs/toolhive/guides-ui/cli-access.mdx
@@ -133,6 +133,12 @@ the error message and resolution steps.
 
 </details>
 
+## Next steps
+
+- [Run MCP servers](./run-mcp-servers.mdx) from the ToolHive UI
+- Explore the full [CLI guides](../guides-cli/index.mdx) for terminal-based
+  workflows
+
 ## Related information
 
 - [CLI guides](../guides-cli/index.mdx)
diff --git a/docs/toolhive/guides-ui/client-configuration.mdx b/docs/toolhive/guides-ui/client-configuration.mdx
@@ -78,6 +78,12 @@ your client or library, so refer to its documentation for details. See the
 [client configuration reference](../reference/client-compatibility.mdx#manual-configuration)
 for some common examples.
 
+## Next steps
+
+- Test your setup in the [Playground](./playground.mdx)
+- [Customize which tools](./customize-tools.mdx) each server exposes to your AI
+  clients
+
 ## Related information
 
 - [Client compatibility](../reference/client-compatibility.mdx)
diff --git a/docs/toolhive/guides-ui/customize-tools.mdx b/docs/toolhive/guides-ui/customize-tools.mdx
@@ -194,6 +194,12 @@ icon is removed.
 1. Manually enable all tools using the toggle switches.
 1. Click **Apply** to save your changes.
 
+## Next steps
+
+- Try out your customized tools in the [Playground](./playground.mdx)
+- [Configure client access](./client-configuration.mdx) to connect your AI
+  clients to ToolHive
+
 ## Related information
 
 - [Run MCP servers](./run-mcp-servers.mdx)
diff --git a/docs/toolhive/guides-ui/group-management.mdx b/docs/toolhive/guides-ui/group-management.mdx
@@ -151,6 +151,14 @@ environments:
 3. Configure different AI clients or workspaces to access the appropriate groups
    for each project.
 
+## Next steps
+
+- [Manage secrets](./secrets-management.mdx) for the MCP servers in your groups
+- [Customize which tools](./customize-tools.mdx) each server exposes to your AI
+  clients
+- [Configure client access](./client-configuration.mdx) to connect your AI
+  clients to ToolHive
+
 ## Related information
 
 - [Run MCP servers](./run-mcp-servers.mdx)
diff --git a/docs/toolhive/guides-ui/network-isolation.mdx b/docs/toolhive/guides-ui/network-isolation.mdx
diff --git a/docs/toolhive/guides-ui/secrets-management.mdx b/docs/toolhive/guides-ui/secrets-management.mdx
diff --git a/docs/toolhive/guides-vmcp/audit-logging.mdx b/docs/toolhive/guides-vmcp/audit-logging.mdx
diff --git a/docs/toolhive/guides-vmcp/authentication.mdx b/docs/toolhive/guides-vmcp/authentication.mdx
diff --git a/docs/toolhive/guides-vmcp/backend-discovery.mdx b/docs/toolhive/guides-vmcp/backend-discovery.mdx
diff --git a/docs/toolhive/guides-vmcp/composite-tools.mdx b/docs/toolhive/guides-vmcp/composite-tools.mdx
diff --git a/docs/toolhive/guides-vmcp/configuration.mdx b/docs/toolhive/guides-vmcp/configuration.mdx
diff --git a/docs/toolhive/guides-vmcp/failure-handling.mdx b/docs/toolhive/guides-vmcp/failure-handling.mdx
diff --git a/docs/toolhive/guides-vmcp/intro.mdx b/docs/toolhive/guides-vmcp/intro.mdx
diff --git a/docs/toolhive/guides-vmcp/telemetry-and-metrics.mdx b/docs/toolhive/guides-vmcp/telemetry-and-metrics.mdx
diff --git a/docs/toolhive/guides-vmcp/tool-aggregation.mdx b/docs/toolhive/guides-vmcp/tool-aggregation.mdx
