Structure and title updates

docs/toolhive/concepts/observability.md → docs/toolhive/concepts/observability.mdx

@@ -420,7 +420,7 @@ Now that you understand how ToolHive's observability works, you can:
 2. **Follow the tutorial** to set up a local observability stack with
    [OpenTelemetry, Jaeger, Prometheus, and Grafana](../tutorials/opentelemetry.mdx)
 3. **Enable telemetry** when running your servers:
-   - [using the ToolHive CLI](../guides-cli/telemetry-and-metrics.md)
+   - [using the ToolHive CLI](../guides-cli/telemetry-and-metrics.mdx)
    - using the Kubernetes operator (not yet supported -
      [contributions welcome](https://github.com/stacklok/toolhive/releases/tag/v0.2.0))
 4. **Set up basic dashboards** to track request rates, error rates, and response

docs/toolhive/faq.md → docs/toolhive/faq.mdx

@@ -144,7 +144,7 @@ ToolHive supports:
 ### How do I get my MCP server added to the ToolHive registry?
 
 The ToolHive registry has specific
-[inclusion criteria](./concepts/registry-criteria.md), such as being open
+[inclusion criteria](./concepts/registry-criteria.mdx), such as being open
 source, following good security practices, and maintaining code quality. Review
 the criteria and
 [submit your server for consideration](https://github.com/stacklok/toolhive/issues/new?template=add-an-mcp-server.md).

docs/toolhive/guides-cli/advanced-cicd.mdx

@@ -1,5 +1,5 @@
 ---
-title: Advanced CI/CD with ToolHive
+title: Advanced CI/CD patterns
 description:
   Advanced CI/CD patterns for building and deploying MCP server containers with
   ToolHive.

docs/toolhive/guides-cli/build-containers.mdx

@@ -1,5 +1,5 @@
 ---
-title: Build MCP server containers
+title: Build MCP containers
 description:
   How to build MCP server containers without running them using the ToolHive
   CLI.

docs/toolhive/guides-cli/custom-permissions.mdx

@@ -19,7 +19,7 @@ in a single profile.
 Permission profiles control two types of access:
 
 - **Host file system access** specifies paths on your host that are mounted into
-  the MCP server container — see [file system access](./filesystem-access.md)
+  the MCP server container — see [file system access](./filesystem-access.mdx)
   for detailed examples
 - **Network access rules** let you restrict outbound HTTP(S) connectivity from
   the MCP server — see [network isolation](./network-isolation.mdx) for
@@ -189,7 +189,7 @@ This profile grants file system access without defining any network permissions.
 (Note, to actually block network access, use the `--isolate-network` flag when
 running the server.)
 
-See [file system access](./filesystem-access.md) for more details and specific
+See [file system access](./filesystem-access.mdx) for more details and specific
 examples.
 
 ## Apply a permission profile
@@ -233,5 +233,5 @@ When creating and using permission profiles:
 
 - [`thv run` command reference](../reference/cli/thv_run.md)
 - [Run MCP servers](./run-mcp-servers.mdx)
-- [File system access](./filesystem-access.md)
+- [File system access](./filesystem-access.mdx)
 - [Network isolation](./network-isolation.mdx)

docs/toolhive/guides-cli/group-management.md → docs/toolhive/guides-cli/group-management.mdx

@@ -1,5 +1,5 @@
 ---
-title: Group MCP servers
+title: Organize servers into groups
 description:
   How to organize MCP servers into logical groups and configure client access.
 ---

docs/toolhive/guides-cli/install.mdx

@@ -314,7 +314,7 @@ To uninstall ToolHive:
 ## Next steps
 
 Now that you have ToolHive installed, you can start using it to run and manage
-MCP servers. See [Explore the registry](./registry.md) and
+MCP servers. See [Explore the registry](./registry.mdx) and
 [Run MCP servers](./run-mcp-servers.mdx) to get started.
 
 ## Related information

docs/toolhive/guides-cli/manage-mcp-servers.md → docs/toolhive/guides-cli/manage-mcp-servers.mdx

@@ -1,5 +1,5 @@
 ---
-title: Monitor and manage MCP servers
+title: Manage servers
 description:
   How to monitor and manage the lifecycle of MCP servers using ToolHive.
 ---
@@ -146,4 +146,4 @@ This will always prompt for re-authentication, even if valid tokens exist.
 - [`thv stop` command reference](../reference/cli/thv_stop.md)
 - [`thv restart` command reference](../reference/cli/thv_restart.md)
 - [`thv rm` command reference](../reference/cli/thv_rm.md)
-- [Monitor with OpenTelemetry](../guides-cli/telemetry-and-metrics.md)
+- [Monitor with OpenTelemetry](../guides-cli/telemetry-and-metrics.mdx)

docs/toolhive/guides-cli/network-isolation.mdx

@@ -323,7 +323,7 @@ default behavior of allowing traffic only from the container's own hostname,
 - [`thv run` command reference](../reference/cli/thv_run.md)
 - [Run MCP servers](./run-mcp-servers.mdx)
 - [Custom permissions](./custom-permissions.mdx)
-- [File system access](./filesystem-access.md)
+- [File system access](./filesystem-access.mdx)
 
 ## Troubleshooting
 

docs/toolhive/guides-cli/registry.md → docs/toolhive/guides-cli/registry.mdx

@@ -5,7 +5,7 @@ description: How to use the built-in registry to find MCP servers.
 
 ToolHive includes a built-in registry of MCP servers with verified
 configurations that meet a
-[minimum quality standard](../concepts/registry-criteria.md), allowing you to
+[minimum quality standard](../concepts/registry-criteria.mdx), allowing you to
 discover and deploy high-quality tools effortlessly. Simply select one from the
 list and run it securely with a single command.
 
@@ -194,7 +194,7 @@ configurations.
 
 :::note
 
-Registry groups are different from [runtime groups](./group-management.md).
+Registry groups are different from [runtime groups](./group-management.mdx).
 Registry groups organize server definitions within registry files, while runtime
 groups organize running server instances for access control.
 

docs/toolhive/guides-cli/run-mcp-servers.mdx

@@ -9,7 +9,7 @@ server settings, and run custom servers using Docker images or protocol schemes.
 
 ## Run a server from the registry
 
-To run an MCP server from the [ToolHive registry](./registry.md), use the
+To run an MCP server from the [ToolHive registry](./registry.mdx), use the
 [`thv run`](../reference/cli/thv_run.md) command with the name of the server you
 want to run. The server name is the same as its name in the registry.
 
@@ -67,7 +67,7 @@ Use `thv search <NAME>` or `thv registry list` to discover available servers.
 
 ### Run registry groups
 
-If you use a [custom registry](./registry.md#use-a-custom-registry) that
+If you use a [custom registry](./registry.mdx#use-a-custom-registry) that
 includes groups, you can run multiple related servers together as a unit. This
 is useful when you need several servers for a specific workflow or project:
 
@@ -83,7 +83,7 @@ thv group run dev-toolkit
 
 Running a group starts all servers defined within that group simultaneously,
 saving you from running each server individually. See
-[Registry groups](./registry.md#organize-servers-with-registry-groups) for more
+[Registry groups](./registry.mdx#organize-servers-with-registry-groups) for more
 information about organizing servers into groups in your custom registry.
 
 :::info[What's happening?]
@@ -185,18 +185,18 @@ The group must exist before you can run a server in it.
 
 :::
 
-See [Group management](./group-management.md) for more details on organizing
-servers into groups and configuring client access.
+See [Organize servers with groups](./group-management.mdx) to learn more about
+organizing servers and configuring client access.
 
 ### Mount a local file or directory
 
 To enable file system access for an MCP server, you can either use the
 `--volume` flag to mount specific paths or create a custom permission profile
 that defines read and write permissions.
 
-See [File system access](./filesystem-access.md) for detailed examples. To
+See [File system access](./filesystem-access.mdx) for detailed examples. To
 prevent sensitive files from being exposed when mounting a project, use
-[.thvignore](./thvignore.md).
+[.thvignore](./thvignore.mdx).
 
 ### Restrict network access
 
@@ -451,6 +451,9 @@ When you use a protocol scheme, ToolHive:
 
 :::
 
+To build the image without running it, see
+[Build MCP containers](./build-containers.mdx).
+
 #### Examples
 
 <Tabs groupId='protocol' queryString='protocol'>
@@ -814,7 +817,7 @@ The configuration file must contain all server settings.
 
 ## Next steps
 
-See [Monitor and manage MCP servers](./manage-mcp-servers.md) to monitor and
+See [Monitor and manage MCP servers](./manage-mcp-servers.mdx) to monitor and
 control your servers.
 
 ## Related information
@@ -823,7 +826,7 @@ control your servers.
 - [Client configuration](./client-configuration.mdx)
 - [Secrets management](./secrets-management.mdx)
 - [Custom permissions](./custom-permissions.mdx)
-- [File system access](./filesystem-access.md)
+- [File system access](./filesystem-access.mdx)
 - [Network isolation](./network-isolation.mdx)
 
 ## Troubleshooting
@@ -887,7 +890,7 @@ If a server crashes or exits unexpectedly:
 If a remote MCP server authentication fails:
 
 1. Check the server logs for authentication errors (see
-   [View server logs](./manage-mcp-servers.md#view-server-logs) for the correct
+   [View server logs](./manage-mcp-servers.mdx#view-server-logs) for the correct
    log file path on your platform)
 
 2. Verify the issuer URL is correct and accessible

docs/toolhive/guides-cli/telemetry-and-metrics.md → docs/toolhive/guides-cli/telemetry-and-metrics.mdx

@@ -15,7 +15,7 @@ Datadog, and Grafana Cloud, or expose Prometheus metrics locally.
 ToolHive's telemetry captures detailed information about MCP interactions
 including traces, metrics, and performance data. For a comprehensive overview of
 the telemetry architecture, metrics collection, and monitoring capabilities, see
-the [observability overview](../concepts/observability.md).
+the [observability overview](../concepts/observability.mdx).
 
 ## Enable telemetry
 
@@ -324,7 +324,7 @@ Telemetry adds minimal overhead when properly configured:
 
 - Tutorial:
   [Collect telemetry for MCP workloads](../tutorials/opentelemetry.mdx)
-- [Telemetry and monitoring concepts](../concepts/observability.md)
+- [Telemetry and monitoring concepts](../concepts/observability.mdx)
 - [`thv run` command reference](../reference/cli/thv_run.md)
 - [Run MCP servers](run-mcp-servers.mdx)
 

docs/toolhive/guides-cli/thvignore.md → docs/toolhive/guides-cli/thvignore.mdx

@@ -1,5 +1,5 @@
 ---
-title: Hide sensitive files with .thvignore
+title: Hide sensitive files
 description:
   Use .thvignore to prevent secrets from leaking into MCP containers while
   keeping fast bind mounts for development.
@@ -130,7 +130,7 @@ example, `.env*`, build artifacts) in your project's local `.thvignore`.
 
 ## Related information
 
-- [File system access](./filesystem-access.md)
+- [File system access](./filesystem-access.mdx)
 - [Run MCP servers](./run-mcp-servers.mdx)
 - [Network isolation](./network-isolation.mdx)
 - [`thv run` command reference](../reference/cli/thv_run.md)

docs/toolhive/guides-k8s/tool-config.mdx → docs/toolhive/guides-k8s/customize-tools.mdx

@@ -1,5 +1,5 @@
 ---
-title: Configure tools for MCP servers on Kubernetes
+title: Customize tools
 description:
   Filter and rename MCP server tools using the MCPToolConfig CRD and
   toolConfigRef.
@@ -209,7 +209,7 @@ 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.
 
-## Related
+## Related information
 
 - See the [Kubernetes CRD reference](../reference/crd-spec.mdx) for the full
   MCPToolConfig and MCPServerSpec schemas.

docs/toolhive/guides-k8s/deploy-operator-helm.md → docs/toolhive/guides-k8s/deploy-operator-helm.mdx

@@ -71,7 +71,7 @@ kubectl logs -f -n toolhive-system <TOOLHIVE_OPERATOR_POD_NAME>
 
 This shows you the logs of the operator pod, which can help you debug any
 issues. For comprehensive logging and audit capabilities, see the
-[Logging infrastructure](./logging-infrastructure.md) guide.
+[Logging infrastructure](./logging.mdx) guide.
 
 ## Customize the operator
 
@@ -265,7 +265,7 @@ configured during installation.
 
 ## Related information
 
-- [Kubernetes introduction](./intro.md) - Overview of ToolHive's Kubernetes
+- [Kubernetes introduction](./intro.mdx) - Overview of ToolHive's Kubernetes
   integration
 - [ToolHive operator tutorial](../tutorials/quickstart-k8s.mdx) - Step-by-step
   tutorial for getting started using a local kind cluster

docs/toolhive/guides-k8s/index.mdx

@@ -15,12 +15,12 @@ environments. By defining MCP servers as Kubernetes resources, the operator
 automates their deployment and management, making it easier to run MCP servers
 in multi-user environments.
 
-:::info
+:::info[Experimental]
 
-Experimental The Kubernetes operator is still under active development and isn't
-recommended for production use cases yet. Specifically, the `MCPServer` Custom
-Resource Definition (CRD) is still in an alpha state so breaking changes to the
-spec and its capabilities are possible.
+The Kubernetes operator is still under active development and isn't recommended
+for production use cases yet. Specifically, the `MCPServer` Custom Resource
+Definition (CRD) is still in an alpha state so breaking changes to the spec and
+its capabilities are possible.
 
 :::
 

docs/toolhive/guides-k8s/intro.md → docs/toolhive/guides-k8s/intro.mdx

@@ -1,7 +1,6 @@
 ---
-title: Overview of the ToolHive Kubernetes Operator
+title: Overview
 description: How to manage MCP servers in Kubernetes with the ToolHive operator
-sidebar_label: Overview
 ---
 
 The ToolHive Kubernetes operator manages MCP servers in Kubernetes clusters. It
@@ -16,8 +15,8 @@ Definition (CRD) is still in an alpha state so breaking changes to the spec and
 its capabilities are possible.
 
 See the [ToolHive Operator quickstart tutorial](../tutorials/quickstart-k8s.mdx)
-to get started quickly using a local kind cluster. We'd love for you to try
-itout and send feedback!
+to get started quickly using a local kind cluster. We'd love for you to try it
+out and send feedback!
 
 :::
 
@@ -52,7 +51,7 @@ flowchart TB
 
 ## Installation
 
-[Use Helm to install the ToolHive operator](./deploy-operator-helm.md) in your
+[Use Helm to install the ToolHive operator](./deploy-operator-helm.mdx) in your
 Kubernetes cluster. Helm simplifies the installation process and lets you manage
 the operator using Helm charts.
 

docs/toolhive/guides-k8s/logging-infrastructure.md → docs/toolhive/guides-k8s/logging.mdx

@@ -1,8 +1,7 @@
 ---
-title: Logging infrastructure
+title: Set up logging
 description:
   Configure and manage logging for ToolHive in Kubernetes environments
-sidebar_label: Logging infrastructure
 ---
 
 The ToolHive Kubernetes operator provides comprehensive logging capabilities for