Fill gaps in next steps, fix dashes, improve cross-section flow

danbarr · claude · danbarr · commit dc2aaa2ea3b1 · 2026-03-27T11:14:52.000-04:00
- Add "Next steps" to 13 pages that were missing them across CLI,
  K8s, vMCP, Registry, and UI sections
- Replace em dashes and en dashes with hyphens in list items
- Add cross-section links from CLI and vMCP terminal pages to
  K8s, vMCP, and Registry sections
- Fix backward-pointing next steps (CLI auth → run-mcp-servers)
- Restore skills link dropped from Registry intro and telemetry
- Clean up hedging language in Registry deployment next steps

Co-Authored-By: Claude Opus 4.6 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/docs/toolhive/faq.mdx b/docs/toolhive/faq.mdx
@@ -62,13 +62,13 @@ from the web using the
 [GoFetch MCP server](https://github.com/StacklokLabs/gofetch), and for popular
 services and platforms like:
 
-- **Atlassian** – Access Jira and Confluence
-- **AWS Documentation** – Query AWS service documentation
-- **GitHub** – Access repositories, issues, and pull requests
-- **Kubernetes** – Interact with Kubernetes clusters via the
+- **Atlassian** - Access Jira and Confluence
+- **AWS Documentation** - Query AWS service documentation
+- **GitHub** - Access repositories, issues, and pull requests
+- **Kubernetes** - Interact with Kubernetes clusters via the
   [MKP MCP server](https://github.com/StacklokLabs/mkp)
-- **MongoDB**, **PostgreSQL**, **Redis** – Connect to databases
-- **Notion** – Connect to Notion workspaces
+- **MongoDB**, **PostgreSQL**, **Redis** - Connect to databases
+- **Notion** - Connect to Notion workspaces
 - And many more
 
 ### Can I run MCP servers that aren't in the registry?
@@ -158,8 +158,8 @@ ToolHive provides secure secrets management:
 
 Yes. ToolHive uses permission profiles to control:
 
-- **File system access** – Which directories the server can read or write
-- **Network access** – Which hosts and ports the server can connect to
+- **File system access** - Which directories the server can read or write
+- **Network access** - Which hosts and ports the server can connect to
 
 You can use built-in profiles or create custom ones for specific security
 requirements.
@@ -213,21 +213,21 @@ Yes. ToolHive supports corporate environments with:
 
 ### Where can I get help if I'm stuck?
 
-- **Documentation** – Check the comprehensive guides and reference documentation
-- **GitHub Issues** – Report bugs or request features on the
+- **Documentation** - Check the comprehensive guides and reference documentation
+- **GitHub Issues** - Report bugs or request features on the
   [ToolHive GitHub repository](https://github.com/stacklok/toolhive/issues)
-- **Discord Community** – Join the
+- **Discord Community** - Join the
   [Stacklok Discord](https://discord.gg/stacklok) for community support
-- **Troubleshooting sections** – Each guide includes troubleshooting tips for
+- **Troubleshooting sections** - Each guide includes troubleshooting tips for
   common issues
 
 ### How do I report a bug or request a feature?
 
 Open an issue in the appropriate GitHub repository:
 
-- [**ToolHive UI**](https://github.com/stacklok/toolhive-studio/issues) – For
+- [**ToolHive UI**](https://github.com/stacklok/toolhive-studio/issues) - For
   issues specific to the graphical desktop app
-- [**ToolHive CLI & Kubernetes**](https://github.com/stacklok/toolhive/issues) –
+- [**ToolHive CLI & Kubernetes**](https://github.com/stacklok/toolhive/issues) -
   For issues related to the CLI tool or Kubernetes operator
 
 ### Is there a community I can join?
diff --git a/docs/toolhive/guides-cli/advanced-cicd.mdx b/docs/toolhive/guides-cli/advanced-cicd.mdx
@@ -310,9 +310,15 @@ When implementing advanced CI/CD patterns:
 6. **Implement change detection** to avoid unnecessary builds
 7. **Store sensitive data** in CI/CD secrets, not in code
 
+## Next steps
+
+- [Deploy to Kubernetes](../guides-k8s/run-mcp-k8s.mdx) to run your CI/CD-built
+  servers in production
+- [Aggregate multiple servers](../guides-vmcp/index.mdx) into a single endpoint
+  with Virtual MCP Server
+
 ## Related information
 
 - [Build MCP server containers](./build-containers.mdx)
-- [Run MCP servers in Kubernetes](../guides-k8s/run-mcp-k8s.mdx)
 - [`thv build` command reference](../reference/cli/thv_build.md)
 - [Secrets management](./secrets-management.mdx)
diff --git a/docs/toolhive/guides-cli/auth.mdx b/docs/toolhive/guides-cli/auth.mdx
@@ -147,7 +147,8 @@ denied with a 403 Forbidden response.
 
 - [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
+- [Enable telemetry and metrics](./telemetry-and-metrics.mdx) to gain
+  observability into MCP server interactions
 - [Learn about the auth framework](../concepts/auth-framework.mdx) for a deeper
   understanding of ToolHive's authentication and authorization model
 
diff --git a/docs/toolhive/guides-cli/client-configuration.mdx b/docs/toolhive/guides-cli/client-configuration.mdx
@@ -148,6 +148,12 @@ Example output:
 Configure your client or library to connect to the MCP server using the URL
 ToolHive provides.
 
+## Next steps
+
+- [Set up custom permissions](./custom-permissions.mdx) to control filesystem
+  and network access for your servers
+- [Secure your servers](./auth.mdx) with OIDC authentication and Cedar policies
+
 ## Related information
 
 - [`thv client` command reference](../reference/cli/thv_client.md)
diff --git a/docs/toolhive/guides-cli/filesystem-access.mdx b/docs/toolhive/guides-cli/filesystem-access.mdx
@@ -217,6 +217,13 @@ container, use the server's `--db` flag to specify the new path:
 thv run --volume ~/my-database.db:/data/my-database.db sqlite -- --db /data/my-database.db
 ```
 
+## Next steps
+
+- [Exclude sensitive files](./thvignore.mdx) from MCP server access with
+  `.thvignore`
+- [Restrict network access](./network-isolation.mdx) to control outbound
+  connections
+
 ## Related information
 
 - [`thv run` command reference](../reference/cli/thv_run.md)
diff --git a/docs/toolhive/guides-cli/group-management.mdx b/docs/toolhive/guides-cli/group-management.mdx
@@ -120,9 +120,14 @@ Using `--with-workloads` permanently deletes all servers in the group.
 
 :::
 
+## Next steps
+
+- [Configure your AI client](./client-configuration.mdx) to connect to your
+  server groups
+- [Manage secrets](./secrets-management.mdx) for the MCP servers in your groups
+
 ## Related information
 
-- [Client configuration](client-configuration.mdx)
 - [Run MCP servers](run-mcp-servers.mdx)
 - [`thv group` command reference](../reference/cli/thv_group.md)
 - [`thv client` command reference](../reference/cli/thv_client.md)
diff --git a/docs/toolhive/guides-cli/network-isolation.mdx b/docs/toolhive/guides-cli/network-isolation.mdx
@@ -318,6 +318,11 @@ default behavior of allowing traffic only from the container's own hostname,
 
 :::
 
+## 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/secrets-management.mdx b/docs/toolhive/guides-cli/secrets-management.mdx
@@ -267,10 +267,17 @@ This command retrieves the `token` and `team_id` fields from the `slackbot` item
 in the `MCPVault` vault and passes them to the `slack` MCP server as the
 `SLACK_BOT_TOKEN` and `SLACK_TEAM_ID` environment variables.
 
+## Next steps
+
+- [Configure your AI client](./client-configuration.mdx) to connect to your
+  servers
+- [Set up custom permissions](./custom-permissions.mdx) to control filesystem
+  and network access
+
 ## Related information
 
 - [`thv secret` command reference](../reference/cli/thv_secret.md)
-- [Run MCP servers](../guides-cli/run-mcp-servers.mdx)
+- [Run MCP servers](./run-mcp-servers.mdx)
 
 ## Troubleshooting
 
diff --git a/docs/toolhive/guides-cli/thvignore.mdx b/docs/toolhive/guides-cli/thvignore.mdx
@@ -128,6 +128,11 @@ example, `.env*`, build artifacts) in your project's local `.thvignore`.
 
 </details>
 
+## Next steps
+
+- [Restrict network access](./network-isolation.mdx) to control outbound
+  connections from MCP servers
+
 ## Related information
 
 - [File system access](./filesystem-access.mdx)
diff --git a/docs/toolhive/guides-cli/token-exchange.mdx b/docs/toolhive/guides-cli/token-exchange.mdx
@@ -208,9 +208,9 @@ Key points in this example:
 
 ## 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
@@ -476,7 +476,7 @@ kubectl apply -f embedded-auth-config.yaml
 
 The MCPServer needs two configuration references: `externalAuthConfigRef`
 enables the embedded authorization server, and `oidcConfig` validates the JWTs
-that the embedded authorization server issues. Unlike approaches 1–3 where
+that the embedded authorization server issues. Unlike approaches 1-3 where
 `oidcConfig` points to an external identity provider, here it points to the
 embedded authorization server itself—the `oidcConfig` issuer must match the
 `issuer` in your `MCPExternalAuthConfig`.
diff --git a/docs/toolhive/guides-k8s/redis-session-storage.mdx b/docs/toolhive/guides-k8s/redis-session-storage.mdx
@@ -595,6 +595,13 @@ session storage is working correctly.
 
 </details>
 
+## Next steps
+
+- [Configure token exchange](./token-exchange-k8s.mdx) to let MCP servers
+  authenticate to backend services
+- [Monitor server activity](./telemetry-and-metrics.mdx) with OpenTelemetry and
+  Prometheus
+
 ## Related information
 
 - [Set up embedded authorization server authentication](./auth-k8s.mdx#set-up-embedded-authorization-server-authentication)
diff --git a/docs/toolhive/guides-k8s/telemetry-and-metrics.mdx b/docs/toolhive/guides-k8s/telemetry-and-metrics.mdx
@@ -284,9 +284,9 @@ Telemetry adds minimal overhead when properly configured:
 ## Related information
 
 - Tutorial:
-  [Collect telemetry for MCP workloads](../integrations/opentelemetry.mdx) —
+  [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
+- [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
@@ -260,7 +260,7 @@ Key points in this example:
 
 ## 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/deploy-manual.mdx b/docs/toolhive/guides-registry/deploy-manual.mdx
@@ -360,3 +360,11 @@ each instance to avoid leader election lease conflicts. The Helm chart handles
 this automatically.
 
 :::
+
+## Next steps
+
+- [Configure registry sources](./configuration.mdx) to set up your data sources
+  and sync policies
+- [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/deployment.mdx b/docs/toolhive/guides-registry/deployment.mdx
@@ -35,8 +35,8 @@ 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
+- [Configure registry sources](./configuration.mdx) to set up your data sources
+  and sync policies
 - [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
@@ -118,5 +118,6 @@ The server supports five registry source types:
   sync policies, and server filtering
 - [Set up authentication](./authentication.mdx) to secure access to your
   registry
+- [Manage skills](./skills.mdx) to publish and discover reusable skills
 - [View the API reference](../reference/registry-api.mdx) for endpoint
   documentation
diff --git a/docs/toolhive/guides-registry/skills.mdx b/docs/toolhive/guides-registry/skills.mdx
@@ -189,14 +189,18 @@ The API returns standard HTTP status codes:
 | 409  | Version already exists                                        |
 | 500  | Internal server error                                         |
 
-## What's next
+## Next steps
 
 Skill installation via agent clients (such as the ToolHive CLI or IDE
 extensions) is planned for a future release. For now, the registry serves as a
 discovery and distribution layer.
 
-- [Understanding skills](../concepts/skills.mdx) for background on the skills
+- [Configure telemetry](./telemetry-metrics.mdx) to monitor your registry
+  deployment
+
+## Related information
+
+- [Understanding skills](../concepts/skills.mdx) - background on the skills
   model
-- [Registry server introduction](./intro.mdx) for an overview of the Registry
-  server
-- [Authentication](./authentication.mdx) for configuring API access
+- [Registry server introduction](./intro.mdx)
+- [Authentication](./authentication.mdx) - configuring API access
diff --git a/docs/toolhive/guides-registry/telemetry-metrics.mdx b/docs/toolhive/guides-registry/telemetry-metrics.mdx
@@ -181,3 +181,5 @@ metrics still capture latency and error rates for these endpoints.
 ## Next steps
 
 - [Deploy the server](./deployment.mdx) to your Kubernetes environment
+- [Manage skills](./skills.mdx) to publish and discover reusable skills in your
+  registry
diff --git a/docs/toolhive/guides-ui/mcp-optimizer.mdx b/docs/toolhive/guides-ui/mcp-optimizer.mdx
@@ -114,8 +114,15 @@ If you encounter issues while using the MCP Optimizer, check the logs for
 debugging information. On the **MCP Optimizer** page, click the **Advanced**
 menu and select **MCP Optimizer logs**.
 
+## Next steps
+
+- Try the [Playground](./playground.mdx) to test your optimized tool set
+- [Organize MCP servers into groups](./group-management.mdx) to control which
+  servers the optimizer includes
+
 ## Related information
 
 - Tutorial:
   [Reduce token usage with MCP Optimizer](../tutorials/mcp-optimizer.mdx)
-- [Organize MCP servers into groups](./group-management.mdx)
+- [Optimizing LLM context](../concepts/tool-optimization.mdx) - background on
+  tool filtering and context pollution
diff --git a/docs/toolhive/guides-vmcp/audit-logging.mdx b/docs/toolhive/guides-vmcp/audit-logging.mdx
@@ -407,9 +407,9 @@ collection with Fluentd, Filebeat, Splunk, and other systems, see the
 
 ## Related information
 
-- [Authentication](./authentication.mdx) — configure client and backend
+- [Authentication](./authentication.mdx) - configure client and backend
   authentication for user identity in audit logs
-- [Telemetry and metrics](./telemetry-and-metrics.mdx) — monitor vMCP
+- [Telemetry and metrics](./telemetry-and-metrics.mdx) - monitor vMCP
   performance with OpenTelemetry
-- [Kubernetes logging guide](../guides-k8s/logging.mdx) — configure logging for
+- [Kubernetes logging guide](../guides-k8s/logging.mdx) - configure logging for
   MCP servers in Kubernetes
diff --git a/docs/toolhive/guides-vmcp/failure-handling.mdx b/docs/toolhive/guides-vmcp/failure-handling.mdx
@@ -417,7 +417,7 @@ operational:
 
 ## Related information
 
-- [Backend discovery modes](./backend-discovery.mdx) — backend health status and
+- [Backend discovery modes](./backend-discovery.mdx) - backend health status and
   `/status` endpoint
 - [Configuration guide](./configuration.mdx)
 - [VirtualMCPServer CRD specification](../reference/crd-spec.md#apiv1alpha1virtualmcpserver)
diff --git a/docs/toolhive/guides-vmcp/optimizer.mdx b/docs/toolhive/guides-vmcp/optimizer.mdx
@@ -305,13 +305,20 @@ spec:
         audience: vmcp-example
 ```
 
+## Next steps
+
+- [Configure failure handling](./failure-handling.mdx) for circuit breakers and
+  partial failure modes
+- [Monitor vMCP activity](./telemetry-and-metrics.mdx) with OpenTelemetry
+  tracing and metrics
+
 ## Related information
 
-- [MCP Optimizer tutorial](../tutorials/mcp-optimizer.mdx) — desktop/CLI setup
-- [Optimizing LLM context](../concepts/tool-optimization.mdx) — background on
+- [MCP Optimizer tutorial](../tutorials/mcp-optimizer.mdx) - desktop/CLI setup
+- [Optimizing LLM context](../concepts/tool-optimization.mdx) - background on
   tool filtering and context pollution
 - [Configure vMCP servers](./configuration.mdx)
 - [EmbeddingServer CRD specification](../reference/crd-spec.md#apiv1alpha1embeddingserver)
-- [Virtual MCP Server overview](../concepts/vmcp.mdx) — conceptual overview of
+- [Virtual MCP Server overview](../concepts/vmcp.mdx) - conceptual overview of
   vMCP
 - [VirtualMCPServer CRD specification](../reference/crd-spec.md#apiv1alpha1virtualmcpserver)
diff --git a/docs/toolhive/guides-vmcp/scaling-and-performance.mdx b/docs/toolhive/guides-vmcp/scaling-and-performance.mdx
@@ -80,6 +80,13 @@ spec:
 For stateful backends, vertical scaling or dedicated vMCP instances per team/use
 case are recommended instead of horizontal scaling.
 
+## Next steps
+
+- [Explore Kubernetes operator guides](../guides-k8s/index.mdx) for managing MCP
+  servers alongside vMCP
+- [Curate a server catalog](../guides-registry/index.mdx) for your team with the
+  Registry Server
+
 ## Related information
 
 - [Introduction to vMCP](./intro.mdx)
diff --git a/docs/toolhive/guides-vmcp/telemetry-and-metrics.mdx b/docs/toolhive/guides-vmcp/telemetry-and-metrics.mdx
@@ -174,9 +174,9 @@ Each span includes attributes for the target backend (`target.workload_id`,
 
 ## Related information
 
-- [Observability concepts](../concepts/observability.mdx) — overview of
+- [Observability concepts](../concepts/observability.mdx) - overview of
   ToolHive's observability architecture
-- [Kubernetes telemetry guide](../guides-k8s/telemetry-and-metrics.mdx) —
+- [Kubernetes telemetry guide](../guides-k8s/telemetry-and-metrics.mdx) -
   telemetry for MCPServer resources
-- [OpenTelemetry tutorial](../integrations/opentelemetry.mdx) — set up a local
+- [OpenTelemetry tutorial](../integrations/opentelemetry.mdx) - set up a local
   observability stack
diff --git a/docs/toolhive/tutorials/mcp-optimizer.mdx b/docs/toolhive/tutorials/mcp-optimizer.mdx
@@ -328,6 +328,6 @@ Now that you've set up MCP Optimizer, consider exploring these next steps:
 ## Related information
 
 - [MCP Optimizer UI guide](../guides-ui/mcp-optimizer.mdx)
-- [Optimize tool discovery in vMCP](../guides-vmcp/optimizer.mdx) — Kubernetes
+- [Optimize tool discovery in vMCP](../guides-vmcp/optimizer.mdx) - Kubernetes
   operator approach
 - [Organize MCP servers into groups](../guides-ui/group-management.mdx)
