Clarify ToolHive onboarding and navigation (#800)

* Clarify ToolHive platform overview

* Refine docs navigation

* Tighten onboarding quickstarts

* Strengthen platform positioning

* Address review feedback

* Polish onboarding copy

* Rename platform capabilities section

* Shorten reference nav labels

* Add authorization policies doc card

---------

Co-authored-by: Dan Barr <6922515+danbarr@users.noreply.github.com>

Author: danbarr

.agents/skills

@@ -0,0 +1 @@
+../.claude/skills

docs/toolhive/guides-cli/index.mdx

@@ -9,13 +9,19 @@ import DocCardList from '@theme/DocCardList';
 
 ## Introduction
 
-The ToolHive CLI (`thv`) is a command-line tool that allows you to deploy and
-manage MCP servers on your local machine or in development environments. It
-provides quick deployment of MCP servers and supports advanced features like
-custom permissions, network access filtering, and telemetry.
+The ToolHive CLI (`thv`) gives you a fast, repeatable way to run and manage MCP
+servers from the terminal. Use it when you want to script server setup, control
+permissions precisely, work in development environments, or automate ToolHive
+workflows in shell scripts and CI.
 
-It's designed for developers who prefer working in a terminal or need to
-integrate MCP server management into scripts or automation workflows.
+Within the ToolHive platform, the CLI gives you direct access to the same local
+runtime, built-in registry, and client-configuration workflows that power the
+UI. If you want a terminal-first way to run ToolHive locally or embed it in
+automation, start here.
+
+The CLI can also connect your local workflows and AI clients to the broader
+ToolHive platform. You can use it with MCP servers or gateways managed by the
+Kubernetes Operator, and point local workflows at a ToolHive Registry Server.
 
 :::info[Using ToolHive UI?]
 
@@ -32,6 +38,8 @@ both installed.
   `thv` and run your first MCP server in minutes.
 - **Already installed?** Jump to [Run MCP servers](./run-mcp-servers.mdx) to
   start managing servers from the command line.
+- **Want to browse the default catalog?** See
+  [Use the registry](./registry.mdx).
 - **Managing agent skills?** See [Manage agent skills](./skills-management.mdx)
   to install and publish reusable skills.
 - **Building or automating?** See advanced workflows for [auth](./auth.mdx),

docs/toolhive/guides-cli/install.mdx

@@ -389,7 +389,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.mdx) and
+MCP servers. See [Use the registry](./registry.mdx) and
 [Run MCP servers](./run-mcp-servers.mdx) to get started.
 
 ## Related information

docs/toolhive/guides-cli/quickstart.mdx

@@ -25,8 +25,9 @@ Before starting this tutorial, make sure you have:
 - [Docker](https://docs.docker.com/get-docker/) or
   [Podman](https://podman-desktop.io/downloads) or
   [Colima](https://github.com/abiosoft/colima) installed and running
-- A [supported MCP client](../reference/client-compatibility.mdx) like GitHub
-  Copilot in VS Code, Cursor, Claude Code, and more
+- _(Optional)_ A [supported MCP client](../reference/client-compatibility.mdx)
+  such as GitHub Copilot in VS Code, Cursor, or Claude Code. Needed only if you
+  want to test end-to-end client integration.
 
 ## Step 1: Install ToolHive
 
@@ -92,44 +93,7 @@ Platform: darwin/arm64
 
 This confirms ToolHive is installed and ready to use.
 
-## Step 2: Register your client
-
-Next, run the ToolHive client setup command to register your MCP client:
-
-```bash
-thv client setup
-```
-
-Select one or more clients from the list using the spacebar to toggle selection.
-Press Enter to confirm your selection.
-
-:::info[What's happening?]
-
-When you run the setup command, ToolHive automatically finds
-[supported clients](../reference/client-compatibility.mdx) on your system. When
-you register a client, ToolHive automatically configures it to use MCP servers
-that you run. This means you don't have to manually configure the client to
-connect to the MCP server.
-
-:::
-
-Confirm that your client is registered successfully:
-
-```bash
-thv client status
-```
-
-You should see output similar to this:
-
-```text
-┌────────────────┬───────────┬────────────┐
-│ CLIENT TYPE    │ INSTALLED │ REGISTERED │
-├────────────────┼───────────┼────────────┤
-│ vscode         │ ✅ Yes    │ ❌ No      │
-└────────────────┴───────────┴────────────┘
-```
-
-## Step 3: Find an MCP server to run
+## Step 2: Find an MCP server to run
 
 See what MCP servers are available in the registry:
 
@@ -153,8 +117,8 @@ This shows all the MCP servers available in the ToolHive registry.
 :::info[What's happening?]
 
 ToolHive maintains a curated registry of MCP servers that have been verified to
-work correctly. The registry includes information about what each server does
-and how to use it.
+work correctly. This built-in registry is the default catalog that the CLI uses
+to help you find and launch servers.
 
 :::
 
@@ -169,7 +133,7 @@ thv registry info fetch
 This shows you detailed information about the server, including what tools it
 provides and any configuration options.
 
-## Step 4: Run the Fetch MCP server
+## Step 3: Run the Fetch MCP server
 
 Now, run the Fetch server:
 
@@ -208,7 +172,7 @@ When you run an MCP server, ToolHive:
 
 :::
 
-## Step 5: Verify the server is running
+## Step 4: Verify the server is running
 
 Check that the server is running:
 
@@ -233,9 +197,46 @@ running and how they're configured.
 
 :::
 
+## Step 5: Connect an AI client
+
+To see the full payoff of the tutorial, have ToolHive configure a supported MCP
+client for you now:
+
+```bash
+thv client setup
+```
+
+Select one or more clients from the list using the spacebar to toggle selection.
+Press Enter to confirm your selection.
+
+Confirm that your client is registered successfully:
+
+```bash
+thv client status
+```
+
+You should see output similar to this:
+
+```text
+┌────────────────┬───────────┬────────────┐
+│ CLIENT TYPE    │ INSTALLED │ REGISTERED │
+├────────────────┼───────────┼────────────┤
+│ vscode         │ ✅ Yes    │ ✅ Yes     │
+└────────────────┴───────────┴────────────┘
+```
+
+:::info[What's happening?]
+
+When you run the setup command, ToolHive automatically finds
+[supported clients](../reference/client-compatibility.mdx) on your system. When
+you register a client, ToolHive automatically configures it to use MCP servers
+that you run.
+
+:::
+
 ## Step 6: Use the MCP server with your AI client
 
-Now that your MCP server is running, you can use it with your AI client
+If you completed Step 5, you can now use the MCP server with your AI client
 application. Open your supported client (VS Code, Cursor, etc.) and ask the AI
 to fetch content from a website. Note that you might need to restart your client
 for the changes to take effect.
@@ -279,12 +280,12 @@ the container, freeing up resources.
 
 :::
 
-## What's next?
+## Next steps
 
 Congratulations! You've successfully installed ToolHive and run your first MCP
 server. Here are some next steps to explore:
 
-- Try running other MCP servers from the registry with
+- Try running other MCP servers from the built-in registry with
   [`thv registry list`](../reference/cli/thv_registry_list.md) and
   [`thv run`](../reference/cli/thv_run.md)
 - Learn about [secrets management](../guides-cli/secrets-management.mdx) for MCP
@@ -309,6 +310,11 @@ production-ready MCP servers, that's where Stacklok Enterprise comes in.
 
 :::
 
+## Related information
+
+- [Use the registry](../guides-cli/registry.mdx)
+- [Client compatibility](../reference/client-compatibility.mdx)
+
 ## Troubleshooting
 
 <details>
@@ -333,7 +339,7 @@ thv run --proxy-port 8081 fetch
 
 If your AI client application can't use the server:
 
-- Make sure your client is registered with ToolHive (see Step 2)
+- Make sure your client is registered with ToolHive (see Step 5)
 - Check that your client is supported
 - Restart your client to pick up the new configuration
 - Verify the server is running with [`thv list`](../reference/cli/thv_list.md)

docs/toolhive/guides-cli/registry.mdx

@@ -1,5 +1,5 @@
 ---
-title: Explore the registry
+title: Use the registry
 description:
   Search the built-in registry to find, inspect, and run MCP servers with one
   command.

docs/toolhive/guides-k8s/index.mdx

@@ -9,8 +9,16 @@ import DocCardList from '@theme/DocCardList';
 
 ## Introduction
 
-The ToolHive Kubernetes Operator manages MCP servers in Kubernetes clusters. You
-define MCP servers as Kubernetes custom resources and the operator automates
+The ToolHive Kubernetes Operator brings MCP servers into a shared, governable
+Kubernetes environment. It solves the gap between trying MCP locally and running
+it for teams, with standard deployment workflows, centralized policy control,
+and platform-managed connectivity.
+
+Within the ToolHive platform, the operator is the foundation for multi-user and
+production-style deployments. It runs MCP workloads in the cluster and unlocks
+capabilities like Virtual MCP Server (vMCP) and Registry Server integrations.
+
+You define MCP servers as Kubernetes custom resources and the operator automates
 their deployment, proxying, and lifecycle management. The operator supports
 several primary resource types:
 
@@ -21,10 +29,8 @@ several primary resource types:
 - **VirtualMCPServer**: aggregate and optimize multiple servers behind a single
   endpoint
 
-Beyond managing MCP servers, the operator can deploy
-[ToolHive Registry Server](../guides-registry/index.mdx) instances via
-MCPRegistry resources, enabling automatic discovery of cluster-hosted MCP
-servers.
+This is the best starting point when you need ToolHive in a shared, multi-user,
+or production-style Kubernetes environment.
 
 ## Where to start
 

docs/toolhive/guides-k8s/quickstart.mdx

@@ -426,7 +426,7 @@ This will fully remove the kind cluster and clean up all associated resources.
 
 :::
 
-## What's next?
+## Next steps
 
 Congratulations! You've successfully deployed the ToolHive operator and created
 your first MCP server using Kubernetes resources. You now have a working
@@ -454,6 +454,11 @@ support - built for teams taking MCP from proof of concept to production.
 
 :::
 
+## Related information
+
+- [Connect clients to MCP servers](../guides-k8s/connect-clients.mdx)
+- [Run MCP servers in Kubernetes](../guides-k8s/run-mcp-k8s.mdx)
+
 ## Troubleshooting
 
 <details>

docs/toolhive/guides-registry/index.mdx

@@ -9,21 +9,28 @@ import DocCardList from '@theme/DocCardList';
 
 ## Introduction
 
-The ToolHive Registry Server is an implementation of the official
-[Model Context Protocol (MCP) Registry API specification](https://github.com/modelcontextprotocol/registry/blob/main/docs/reference/api/generic-registry-api.md).
-It provides a standardized REST API for discovering and accessing MCP servers
-from multiple backend sources, including Kubernetes clusters, Git repositories,
-API endpoints, and local files.
+The ToolHive Registry Server helps you publish and govern a catalog of MCP
+servers or skills for your team. Use it when you want a trusted catalog that
+improves discoverability, supports publishing workflows, and gives you more
+control over what different users can access.
+
+It can aggregate entries from Kubernetes clusters, Git repositories, API
+endpoints, and local files, then expose them through a standard MCP Registry API
+for ToolHive and other clients.
 
 :::note
 
 This section covers the **Registry Server**, a standalone service you deploy
 yourself. Looking for the built-in registry instead? See
-[Explore the registry](../guides-cli/registry.mdx) (CLI) or
-[Explore the registry](../guides-ui/registry.mdx) (UI).
+[Use the registry](../guides-cli/registry.mdx) (CLI) or
+[Use the registry](../guides-ui/registry.mdx) (UI).
 
 :::
 
+If you want to host and operate your own catalog, use the Registry Server. If
+you only need to browse the default ToolHive catalog from the UI or CLI, you do
+not need to deploy it.
+
 ## Where to start
 
 - **New to the Registry Server?** Follow the

docs/toolhive/guides-registry/intro.mdx

@@ -5,22 +5,37 @@ description:
   Server
 ---
 
-The ToolHive Registry Server is a standards-compliant implementation of the MCP
-Registry API specification. It provides a REST API for discovering and accessing
-MCP servers from multiple backend sources.
+The ToolHive Registry Server gives you a way to publish, curate, and control a
+catalog of MCP servers and skills for your organization. Use it when you want a
+trusted catalog for discoverability, team-scoped access, publishing, or
+multi-source aggregation.
+
+It pulls entries from multiple sources, stores them centrally, and exposes them
+through a standard MCP Registry API that ToolHive and other clients can consume.
 
 :::note[Registry Server vs. built-in registry]
 
-This section covers the **Registry Server**, a standalone service you deploy
-yourself for hosting and curating your own MCP server catalog.
+This section covers the **Registry Server** for hosting and curating your own
+MCP server and skills catalog.
 
 ToolHive also ships with a **built-in registry** for browsing and discovering
 MCP servers from the default catalog. That's a different feature: see
-[Explore the registry](../guides-cli/registry.mdx) (CLI) or
-[Explore the registry](../guides-ui/registry.mdx) (UI).
+[Use the registry](../guides-cli/registry.mdx) (CLI) or
+[Use the registry](../guides-ui/registry.mdx) (UI).
 
 :::
 
+## Why use the Registry Server?
+
+Use the Registry Server when you need to:
+
+- Curate a private or team-specific catalog instead of relying only on the
+  default public catalog
+- Publish MCP servers or [skills](../concepts/skills.mdx) for internal use
+- Aggregate entries from multiple sources behind one registry API
+- Apply authentication and authorization policies to registry access
+- Surface cluster-hosted workloads to users through a managed catalog
+
 ## Key concepts
 
 The Registry Server is built around three core concepts:
@@ -38,8 +53,9 @@ The Registry Server is built around three core concepts:
 
 ## How the Registry Server works
 
-The Registry server aggregates MCP server metadata from various sources and
-exposes it through a standardized API. When you start the server, it:
+The Registry Server aggregates MCP server and skills metadata from various
+sources and exposes it through a standardized API. When you start the server,
+it:
 
 1. Loads configuration from a YAML file
 2. Runs database migrations automatically
@@ -129,9 +145,9 @@ The server supports five source types:
 
 ## Registry Server and the rest of ToolHive
 
-The Registry Server is a standalone service. It is separate from the built-in
-catalog that the ToolHive CLI and UI ship with for browsing public MCP servers.
-The pieces work together:
+The Registry Server is one part of the broader ToolHive platform. It is
+different from the built-in catalog that the ToolHive CLI and UI ship with for
+browsing public MCP servers, but the pieces work together:
 
 - The CLI's [`thv search`](../reference/cli/thv_search.md) and
   [`thv registry`](../guides-cli/registry.mdx) commands query the built-in